rpc

package
v0.54.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 2, 2026 License: MIT Imports: 35 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	OpPing        = "ping"
	OpStatus      = "status"
	OpHealth      = "health"
	OpMetrics     = "metrics"
	OpCreate      = "create"
	OpUpdate      = "update"
	OpClose       = "close"
	OpList        = "list"
	OpCount       = "count"
	OpShow        = "show"
	OpReady       = "ready"
	OpBlocked     = "blocked"
	OpStale       = "stale"
	OpStats       = "stats"
	OpDepAdd      = "dep_add"
	OpDepRemove   = "dep_remove"
	OpDepTree     = "dep_tree"
	OpLabelAdd    = "label_add"
	OpLabelRemove = "label_remove"
	OpCommentList = "comment_list"
	OpCommentAdd  = "comment_add"
	OpBatch       = "batch"
	OpResolveID   = "resolve_id"

	OpCompact             = "compact"
	OpCompactStats        = "compact_stats"
	OpExport              = "export"
	OpImport              = "import"
	OpEpicStatus          = "epic_status"
	OpGetMutations        = "get_mutations"
	OpGetMoleculeProgress = "get_molecule_progress"
	OpShutdown            = "shutdown"
	OpDelete              = "delete"
	OpGetWorkerStatus     = "get_worker_status"
	OpGetConfig           = "get_config"
	OpMolStale            = "mol_stale"
	OpGetEnrichmentStats  = "get_enrichment_stats"

	// Gate operations
	OpGateCreate = "gate_create"
	OpGateList   = "gate_list"
	OpGateShow   = "gate_show"
	OpGateClose  = "gate_close"
	OpGateWait   = "gate_wait"
)

Operation constants for all bd commands

View Source 
const (
	MutationCreate  = "create"
	MutationUpdate  = "update"
	MutationDelete  = "delete"
	MutationComment = "comment"
	// Molecule-specific event types for activity feed
	MutationBonded   = "bonded"   // Molecule bonded to parent (dynamic bond)
	MutationSquashed = "squashed" // Wisp squashed to digest
	MutationBurned   = "burned"   // Wisp discarded without digest
	MutationStatus   = "status"   // Status change (in_progress, completed, failed)
)

Mutation event types

View Source 
const MaxUnixSocketPath = 103

MaxUnixSocketPath is the maximum length for Unix socket paths. macOS has a 104-byte limit (including null terminator), Linux has 108. We use 103 to be safe across platforms.

Variables

View Source 
var ClientVersion = "0.0.0" // Placeholder; overridden at startup

ClientVersion is the version of this RPC client This should match the bd CLI version for proper compatibility checks It's set dynamically by main.go from cmd/bd/version.go before making RPC calls

View Source 
var ServerVersion = "0.0.0" // Placeholder; overridden by daemon startup

ServerVersion is the version of this RPC server This should match the bd CLI version for proper compatibility checks It's set dynamically by daemon.go from cmd/bd/version.go before starting the server

Functions

func CleanupSocketDir 

func CleanupSocketDir(socketPath string) error

CleanupSocketDir removes the socket directory if it's in /tmp/beads-*. This should be called when the daemon shuts down.

func EnsureSocketDir 

func EnsureSocketDir(socketPath string) (string, error)

EnsureSocketDir creates the socket directory if it doesn't exist. Returns the socket path (unchanged) and any error. This should be called by the daemon before listening.

func NeedsShortPath 

func NeedsShortPath(workspacePath string) bool

NeedsShortPath returns true if the workspace path would result in a socket path exceeding Unix limits.

func ShortSocketPath 

func ShortSocketPath(workspacePath string) string

ShortSocketPath returns a short socket path suitable for Unix sockets. On Unix systems with socket path length limits (macOS: 104 chars, Linux: 108), this function returns a path in /tmp/beads-{hash}/ to avoid exceeding limits.

The hash is derived from the canonicalized workspace path, ensuring: - Different workspaces get different socket directories - The same workspace always gets the same hash (deterministic) - Symlinks and case differences resolve to the same hash

If the computed .beads/bd.sock path is short enough, it returns that directly. This preserves backwards compatibility for workspaces with short paths.

Types

type BatchArgs 

type BatchArgs struct {
	Operations []BatchOperation `json:"operations"`
}

BatchArgs represents arguments for batch operations

type BatchOperation 

type BatchOperation struct {
	Operation string          `json:"operation"`
	Args      json.RawMessage `json:"args"`
}

BatchOperation represents a single operation in a batch

type BatchResponse 

type BatchResponse struct {
	Results []BatchResult `json:"results"`
}

BatchResponse contains the results of a batch operation

type BatchResult 

type BatchResult struct {
	Success bool            `json:"success"`
	Data    json.RawMessage `json:"data,omitempty"`
	Error   string          `json:"error,omitempty"`
}

BatchResult represents the result of a single operation in a batch

type BlockedArgs 

type BlockedArgs struct {
	ParentID string `json:"parent_id,omitempty"` // Filter to descendants of this bead/epic
}

BlockedArgs represents arguments for the blocked operation

type Client 

type Client struct {
	// contains filtered or unexported fields
}

Client represents an RPC client that connects to the daemon

func TryConnect 

func TryConnect(socketPath string) (*Client, error)

TryConnect attempts to connect to the daemon socket Returns nil if no daemon is running or unhealthy

func TryConnectWithTimeout 

func TryConnectWithTimeout(socketPath string, dialTimeout time.Duration) (*Client, error)

TryConnectWithTimeout attempts to connect to the daemon socket using the provided dial timeout. Returns nil if no daemon is running or unhealthy.

func (*Client) AddComment 

func (c *Client) AddComment(args *CommentAddArgs) (*Response, error)

AddComment adds a comment to an issue via the daemon

func (*Client) AddDependency 

func (c *Client) AddDependency(args *DepAddArgs) (*Response, error)

AddDependency adds a dependency via the daemon

func (*Client) AddLabel 

func (c *Client) AddLabel(args *LabelAddArgs) (*Response, error)

AddLabel adds a label via the daemon

func (*Client) Batch 

func (c *Client) Batch(args *BatchArgs) (*Response, error)

Batch executes multiple operations atomically

func (*Client) Blocked 

func (c *Client) Blocked(args *BlockedArgs) (*Response, error)

Blocked gets blocked issues via the daemon

func (*Client) Call 

func (c *Client) Call(operation string, args interface{}) (*Response, error)

Call executes a generic RPC operation

func (*Client) Close 

func (c *Client) Close() error

Close closes the connection to the daemon

func (*Client) CloseIssue 

func (c *Client) CloseIssue(args *CloseArgs) (*Response, error)

CloseIssue marks an issue as closed via the daemon.

func (*Client) Count 

func (c *Client) Count(args *CountArgs) (*Response, error)

Count counts issues via the daemon

func (*Client) Create 

func (c *Client) Create(args *CreateArgs) (*Response, error)

Create creates a new issue via the daemon

func (*Client) Delete 

func (c *Client) Delete(args *DeleteArgs) (*Response, error)

Delete deletes one or more issues via the daemon.

func (*Client) EpicStatus 

func (c *Client) EpicStatus(args *EpicStatusArgs) (*Response, error)

EpicStatus gets epic completion status via the daemon

func (*Client) Execute 

func (c *Client) Execute(operation string, args interface{}) (*Response, error)

Execute sends an RPC request and waits for a response

func (*Client) ExecuteWithCwd 

func (c *Client) ExecuteWithCwd(operation string, args interface{}, cwd string) (*Response, error)

ExecuteWithCwd sends an RPC request with an explicit cwd (or current dir if empty string)

func (*Client) Export 

func (c *Client) Export(args *ExportArgs) (*Response, error)

Export exports the database to JSONL format

func (*Client) GateClose 

func (c *Client) GateClose(args *GateCloseArgs) (*Response, error)

GateClose closes a gate via the daemon

func (*Client) GateCreate 

func (c *Client) GateCreate(args *GateCreateArgs) (*Response, error)

GateCreate creates a gate via the daemon

func (*Client) GateList 

func (c *Client) GateList(args *GateListArgs) (*Response, error)

GateList lists gates via the daemon

func (*Client) GateShow 

func (c *Client) GateShow(args *GateShowArgs) (*Response, error)

GateShow shows a gate via the daemon

func (*Client) GateWait 

func (c *Client) GateWait(args *GateWaitArgs) (*Response, error)

GateWait adds waiters to a gate via the daemon

func (*Client) GetConfig 

func (c *Client) GetConfig(args *GetConfigArgs) (*GetConfigResponse, error)

GetConfig retrieves a config value from the daemon's database

func (*Client) GetEnrichmentStats 

func (c *Client) GetEnrichmentStats() (*EnrichmentStatsResponse, error)

GetEnrichmentStats retrieves background AI enrichment status from the daemon

func (*Client) GetMutations 

func (c *Client) GetMutations(args *GetMutationsArgs) (*Response, error)

GetMutations retrieves recent mutations from the daemon

func (*Client) GetWorkerStatus 

func (c *Client) GetWorkerStatus(args *GetWorkerStatusArgs) (*GetWorkerStatusResponse, error)

GetWorkerStatus retrieves worker status via the daemon

func (*Client) Health 

func (c *Client) Health() (*HealthResponse, error)

Health sends a health check request to verify the daemon is healthy

func (*Client) List 

func (c *Client) List(args *ListArgs) (*Response, error)

List lists issues via the daemon

func (*Client) ListComments 

func (c *Client) ListComments(args *CommentListArgs) (*Response, error)

ListComments retrieves comments for an issue via the daemon

func (*Client) Metrics 

func (c *Client) Metrics() (*MetricsSnapshot, error)

Metrics retrieves daemon metrics

func (*Client) MolStale 

func (c *Client) MolStale(args *MolStaleArgs) (*MolStaleResponse, error)

MolStale retrieves stale molecules (complete-but-unclosed) via the daemon

func (*Client) Ping 

func (c *Client) Ping() error

Ping sends a ping request to verify the daemon is alive

func (*Client) Ready 

func (c *Client) Ready(args *ReadyArgs) (*Response, error)

Ready gets ready work via the daemon

func (*Client) RemoveDependency 

func (c *Client) RemoveDependency(args *DepRemoveArgs) (*Response, error)

RemoveDependency removes a dependency via the daemon

func (*Client) RemoveLabel 

func (c *Client) RemoveLabel(args *LabelRemoveArgs) (*Response, error)

RemoveLabel removes a label via the daemon

func (*Client) ResolveID 

func (c *Client) ResolveID(args *ResolveIDArgs) (*Response, error)

ResolveID resolves a partial issue ID to a full ID via the daemon

func (*Client) SetActor 

func (c *Client) SetActor(actor string)

SetActor sets the actor for audit trail (who is performing operations)

func (*Client) SetDatabasePath 

func (c *Client) SetDatabasePath(dbPath string)

SetDatabasePath sets the expected database path for validation

func (*Client) SetTimeout 

func (c *Client) SetTimeout(timeout time.Duration)

SetTimeout sets the request timeout duration

func (*Client) Show 

func (c *Client) Show(args *ShowArgs) (*Response, error)

Show shows an issue via the daemon

func (*Client) Shutdown 

func (c *Client) Shutdown() error

Shutdown sends a graceful shutdown request to the daemon

func (*Client) Stale 

func (c *Client) Stale(args *StaleArgs) (*Response, error)

Stale gets stale issues via the daemon

func (*Client) Stats 

func (c *Client) Stats() (*Response, error)

Stats gets statistics via the daemon

func (*Client) Status 

func (c *Client) Status() (*StatusResponse, error)

Status retrieves daemon status metadata

func (*Client) Update 

func (c *Client) Update(args *UpdateArgs) (*Response, error)

Update updates an issue via the daemon

type CloseArgs 

type CloseArgs struct {
	ID          string `json:"id"`
	Reason      string `json:"reason,omitempty"`
	Session     string `json:"session,omitempty"`      // Claude Code session ID that closed this issue
	SuggestNext bool   `json:"suggest_next,omitempty"` // Return newly unblocked issues (GH#679)
	Force       bool   `json:"force,omitempty"`        // Force close even with open blockers (GH#962)
}

CloseArgs represents arguments for the close operation

type CloseResult 

type CloseResult struct {
	Closed    *types.Issue   `json:"closed"`              // The issue that was closed
	Unblocked []*types.Issue `json:"unblocked,omitempty"` // Issues newly unblocked by closing
}

CloseResult is returned when SuggestNext is true (GH#679) When SuggestNext is false, just the closed issue is returned for backward compatibility

type CommentAddArgs 

type CommentAddArgs struct {
	ID     string `json:"id"`
	Author string `json:"author"`
	Text   string `json:"text"`
}

CommentAddArgs represents arguments for adding a comment to an issue

type CommentListArgs 

type CommentListArgs struct {
	ID string `json:"id"`
}

CommentListArgs represents arguments for listing comments on an issue

type CompactArgs 

type CompactArgs struct {
	IssueID   string `json:"issue_id,omitempty"` // Empty for --all
	Tier      int    `json:"tier"`               // 1 or 2
	DryRun    bool   `json:"dry_run"`
	Force     bool   `json:"force"`
	All       bool   `json:"all"`
	APIKey    string `json:"api_key,omitempty"`
	Workers   int    `json:"workers,omitempty"`
	BatchSize int    `json:"batch_size,omitempty"`
}

CompactArgs represents arguments for the compact operation

type CompactResponse 

type CompactResponse struct {
	Success       bool              `json:"success"`
	IssueID       string            `json:"issue_id,omitempty"`
	Results       []CompactResult   `json:"results,omitempty"` // For batch operations
	Stats         *CompactStatsData `json:"stats,omitempty"`   // For stats operation
	OriginalSize  int               `json:"original_size,omitempty"`
	CompactedSize int               `json:"compacted_size,omitempty"`
	Reduction     string            `json:"reduction,omitempty"`
	Duration      string            `json:"duration,omitempty"`
	DryRun        bool              `json:"dry_run,omitempty"`
}

CompactResponse represents the response from a compact operation

type CompactResult 

type CompactResult struct {
	IssueID       string `json:"issue_id"`
	Success       bool   `json:"success"`
	Error         string `json:"error,omitempty"`
	OriginalSize  int    `json:"original_size,omitempty"`
	CompactedSize int    `json:"compacted_size,omitempty"`
	Reduction     string `json:"reduction,omitempty"`
}

CompactResult represents the result of compacting a single issue

type CompactStatsArgs 

type CompactStatsArgs struct {
	Tier int `json:"tier,omitempty"`
}

CompactStatsArgs represents arguments for compact stats operation

type CompactStatsData 

type CompactStatsData struct {
	Tier1Candidates  int    `json:"tier1_candidates"`
	Tier2Candidates  int    `json:"tier2_candidates"`
	TotalClosed      int    `json:"total_closed"`
	Tier1MinAge      string `json:"tier1_min_age"`
	Tier2MinAge      string `json:"tier2_min_age"`
	EstimatedSavings string `json:"estimated_savings,omitempty"`
}

CompactStatsData represents compaction statistics

type CountArgs 

type CountArgs struct {
	// Supports all the same filters as ListArgs
	Query     string   `json:"query,omitempty"`
	Status    string   `json:"status,omitempty"`
	Priority  *int     `json:"priority,omitempty"`
	IssueType string   `json:"issue_type,omitempty"`
	Assignee  string   `json:"assignee,omitempty"`
	Labels    []string `json:"labels,omitempty"`
	LabelsAny []string `json:"labels_any,omitempty"`
	IDs       []string `json:"ids,omitempty"`

	// Pattern matching
	TitleContains       string `json:"title_contains,omitempty"`
	DescriptionContains string `json:"description_contains,omitempty"`
	NotesContains       string `json:"notes_contains,omitempty"`

	// Date ranges
	CreatedAfter  string `json:"created_after,omitempty"`
	CreatedBefore string `json:"created_before,omitempty"`
	UpdatedAfter  string `json:"updated_after,omitempty"`
	UpdatedBefore string `json:"updated_before,omitempty"`
	ClosedAfter   string `json:"closed_after,omitempty"`
	ClosedBefore  string `json:"closed_before,omitempty"`

	// Empty/null checks
	EmptyDescription bool `json:"empty_description,omitempty"`
	NoAssignee       bool `json:"no_assignee,omitempty"`
	NoLabels         bool `json:"no_labels,omitempty"`

	// Priority range
	PriorityMin *int `json:"priority_min,omitempty"`
	PriorityMax *int `json:"priority_max,omitempty"`

	// Grouping option (only one can be specified)
	GroupBy string `json:"group_by,omitempty"` // "status", "priority", "type", "assignee", "label"
}

CountArgs represents arguments for the count operation

type CreateArgs 

type CreateArgs struct {
	ID                 string   `json:"id,omitempty"`
	Parent             string   `json:"parent,omitempty"` // Parent ID for hierarchical issues
	Title              string   `json:"title"`
	Description        string   `json:"description,omitempty"`
	IssueType          string   `json:"issue_type"`
	Priority           int      `json:"priority"`
	Design             string   `json:"design,omitempty"`
	AcceptanceCriteria string   `json:"acceptance_criteria,omitempty"`
	Notes              string   `json:"notes,omitempty"`
	Assignee           string   `json:"assignee,omitempty"`
	ExternalRef        string   `json:"external_ref,omitempty"`      // Link to external issue trackers
	EstimatedMinutes   *int     `json:"estimated_minutes,omitempty"` // Time estimate in minutes
	Labels             []string `json:"labels,omitempty"`
	Dependencies       []string `json:"dependencies,omitempty"`
	// Waits-for dependencies
	WaitsFor     string `json:"waits_for,omitempty"`      // Spawner issue ID to wait for
	WaitsForGate string `json:"waits_for_gate,omitempty"` // Gate type: all-children or any-children
	// Messaging fields
	Sender    string `json:"sender,omitempty"`     // Who sent this (for messages)
	Ephemeral bool   `json:"ephemeral,omitempty"`  // If true, not exported to JSONL; bulk-deleted when closed
	RepliesTo string `json:"replies_to,omitempty"` // Issue ID for conversation threading
	// ID generation
	IDPrefix  string `json:"id_prefix,omitempty"`  // Override prefix for ID generation (mol, eph, etc.)
	CreatedBy string `json:"created_by,omitempty"` // Who created the issue
	Owner     string `json:"owner,omitempty"`      // Human owner for CV attribution (git author email)
	// Molecule type (for swarm coordination)
	MolType string `json:"mol_type,omitempty"` // swarm, patrol, or work (default)
	// Agent identity fields (only valid when IssueType == "agent")
	RoleType string `json:"role_type,omitempty"` // polecat|crew|witness|refinery|mayor|deacon
	Rig      string `json:"rig,omitempty"`       // Rig name (empty for town-level agents)
	// Event fields (only valid when IssueType == "event")
	EventCategory string `json:"event_category,omitempty"` // Namespaced category (e.g., patrol.muted, agent.started)
	EventActor    string `json:"event_actor,omitempty"`    // Entity URI who caused this event
	EventTarget   string `json:"event_target,omitempty"`   // Entity URI or bead ID affected
	EventPayload  string `json:"event_payload,omitempty"`  // Event-specific JSON data
	// Time-based scheduling fields (GH#820)
	DueAt      string `json:"due_at,omitempty"`      // Relative or ISO format due date
	DeferUntil string `json:"defer_until,omitempty"` // Relative or ISO format defer date
}

CreateArgs represents arguments for the create operation

type DeleteArgs 

type DeleteArgs struct {
	IDs     []string `json:"ids"`               // Issue IDs to delete
	Force   bool     `json:"force,omitempty"`   // Force deletion without confirmation
	DryRun  bool     `json:"dry_run,omitempty"` // Preview mode
	Cascade bool     `json:"cascade,omitempty"` // Recursively delete dependents
	Reason  string   `json:"reason,omitempty"`  // Reason for deletion
}

DeleteArgs represents arguments for the delete operation

type DepAddArgs 

type DepAddArgs struct {
	FromID  string `json:"from_id"`
	ToID    string `json:"to_id"`
	DepType string `json:"dep_type"`
}

DepAddArgs represents arguments for adding a dependency

type DepRemoveArgs 

type DepRemoveArgs struct {
	FromID  string `json:"from_id"`
	ToID    string `json:"to_id"`
	DepType string `json:"dep_type,omitempty"`
}

DepRemoveArgs represents arguments for removing a dependency

type DepTreeArgs 

type DepTreeArgs struct {
	ID       string `json:"id"`
	MaxDepth int    `json:"max_depth,omitempty"`
}

DepTreeArgs represents arguments for the dep tree operation

type EnrichmentStatsResponse 

type EnrichmentStatsResponse struct {
	Enabled      bool `json:"enabled"`
	QueueLength  int  `json:"queue_length"`
	Processed    int  `json:"processed_count"`
	Failed       int  `json:"failed_count"`
	OllamaActive bool `json:"ollama_active"`
}

EnrichmentStatsResponse represents the background AI enrichment status

type EpicStatusArgs 

type EpicStatusArgs struct {
	EligibleOnly bool `json:"eligible_only,omitempty"`
}

EpicStatusArgs represents arguments for the epic status operation

type ExportArgs 

type ExportArgs struct {
	JSONLPath string `json:"jsonl_path"` // Path to export JSONL file
}

ExportArgs represents arguments for the export operation

type GateCloseArgs 

type GateCloseArgs struct {
	ID     string `json:"id"`               // Gate ID (partial or full)
	Reason string `json:"reason,omitempty"` // Close reason
}

GateCloseArgs represents arguments for closing a gate

type GateCreateArgs 

type GateCreateArgs struct {
	Title     string        `json:"title"`
	AwaitType string        `json:"await_type"` // gh:run, gh:pr, timer, human, mail
	AwaitID   string        `json:"await_id"`   // ID/value for the await type
	Timeout   time.Duration `json:"timeout"`    // Timeout duration
	Waiters   []string      `json:"waiters"`    // Mail addresses to notify when gate clears
}

GateCreateArgs represents arguments for creating a gate

type GateCreateResult 

type GateCreateResult struct {
	ID string `json:"id"` // Created gate ID
}

GateCreateResult represents the result of creating a gate

type GateListArgs 

type GateListArgs struct {
	All bool `json:"all"` // Include closed gates
}

GateListArgs represents arguments for listing gates

type GateShowArgs 

type GateShowArgs struct {
	ID string `json:"id"` // Gate ID (partial or full)
}

GateShowArgs represents arguments for showing a gate

type GateWaitArgs 

type GateWaitArgs struct {
	ID      string   `json:"id"`      // Gate ID (partial or full)
	Waiters []string `json:"waiters"` // Additional waiters to add
}

GateWaitArgs represents arguments for adding waiters to a gate

type GateWaitResult 

type GateWaitResult struct {
	AddedCount int `json:"added_count"` // Number of new waiters added
}

GateWaitResult represents the result of adding waiters

type GetConfigArgs 

type GetConfigArgs struct {
	Key string `json:"key"` // Config key to retrieve (e.g., "issue_prefix")
}

GetConfigArgs represents arguments for getting daemon config

type GetConfigResponse 

type GetConfigResponse struct {
	Key   string `json:"key"`
	Value string `json:"value"`
}

GetConfigResponse represents the response from get_config operation

type GetMoleculeProgressArgs 

type GetMoleculeProgressArgs struct {
	MoleculeID string `json:"molecule_id"` // The ID of the molecule (parent issue)
}

GetMoleculeProgressArgs represents arguments for the get_molecule_progress operation

type GetMutationsArgs 

type GetMutationsArgs struct {
	Since int64 `json:"since"` // Unix timestamp in milliseconds (0 for all recent)
}

GetMutationsArgs represents arguments for retrieving recent mutations

type GetWorkerStatusArgs 

type GetWorkerStatusArgs struct {
	// Assignee filters to a specific worker (optional, empty = all workers)
	Assignee string `json:"assignee,omitempty"`
}

GetWorkerStatusArgs represents arguments for retrieving worker status

type GetWorkerStatusResponse 

type GetWorkerStatusResponse struct {
	Workers []WorkerStatus `json:"workers"`
}

GetWorkerStatusResponse is the response for get_worker_status operation

type HealthResponse 

type HealthResponse struct {
	Status         string  `json:"status"`                   // "healthy", "degraded", "unhealthy"
	Version        string  `json:"version"`                  // Server/daemon version
	ClientVersion  string  `json:"client_version,omitempty"` // Client version from request
	Compatible     bool    `json:"compatible"`               // Whether versions are compatible
	Uptime         float64 `json:"uptime_seconds"`
	DBResponseTime float64 `json:"db_response_ms"`
	ActiveConns    int32   `json:"active_connections"`
	MaxConns       int     `json:"max_connections"`
	MemoryAllocMB  uint64  `json:"memory_alloc_mb"`
	Error          string  `json:"error,omitempty"`
}

HealthResponse is the response for a health check operation

type ImportArgs 

type ImportArgs struct {
	JSONLPath string `json:"jsonl_path"` // Path to import JSONL file
}

ImportArgs represents arguments for the import operation

type LabelAddArgs 

type LabelAddArgs struct {
	ID    string `json:"id"`
	Label string `json:"label"`
}

LabelAddArgs represents arguments for adding a label

type LabelRemoveArgs 

type LabelRemoveArgs struct {
	ID    string `json:"id"`
	Label string `json:"label"`
}

LabelRemoveArgs represents arguments for removing a label

type LatencyStats 

type LatencyStats struct {
	MinMS float64 `json:"min_ms"`
	P50MS float64 `json:"p50_ms"`
	P95MS float64 `json:"p95_ms"`
	P99MS float64 `json:"p99_ms"`
	MaxMS float64 `json:"max_ms"`
	AvgMS float64 `json:"avg_ms"`
}

LatencyStats holds latency percentile data in milliseconds

type ListArgs 

type ListArgs struct {
	Query     string   `json:"query,omitempty"`
	Status    string   `json:"status,omitempty"`
	Priority  *int     `json:"priority,omitempty"`
	IssueType string   `json:"issue_type,omitempty"`
	Assignee  string   `json:"assignee,omitempty"`
	Label     string   `json:"label,omitempty"`      // Deprecated: use Labels
	Labels    []string `json:"labels,omitempty"`     // AND semantics
	LabelsAny []string `json:"labels_any,omitempty"` // OR semantics
	IDs       []string `json:"ids,omitempty"`        // Filter by specific issue IDs
	Limit     int      `json:"limit,omitempty"`

	// Pattern matching
	TitleContains       string `json:"title_contains,omitempty"`
	DescriptionContains string `json:"description_contains,omitempty"`
	NotesContains       string `json:"notes_contains,omitempty"`

	// Date ranges (ISO 8601 format)
	CreatedAfter  string `json:"created_after,omitempty"`
	CreatedBefore string `json:"created_before,omitempty"`
	UpdatedAfter  string `json:"updated_after,omitempty"`
	UpdatedBefore string `json:"updated_before,omitempty"`
	ClosedAfter   string `json:"closed_after,omitempty"`
	ClosedBefore  string `json:"closed_before,omitempty"`

	// Empty/null checks
	EmptyDescription bool `json:"empty_description,omitempty"`
	NoAssignee       bool `json:"no_assignee,omitempty"`
	NoLabels         bool `json:"no_labels,omitempty"`

	// Priority range
	PriorityMin *int `json:"priority_min,omitempty"`
	PriorityMax *int `json:"priority_max,omitempty"`

	// Pinned filtering
	Pinned *bool `json:"pinned,omitempty"`

	// Template filtering
	IncludeTemplates bool `json:"include_templates,omitempty"`

	// Parent filtering
	ParentID string `json:"parent_id,omitempty"`

	// Ephemeral filtering
	Ephemeral *bool `json:"ephemeral,omitempty"`

	// Molecule type filtering
	MolType string `json:"mol_type,omitempty"`

	// Status exclusion (for default non-closed behavior, GH#788)
	ExcludeStatus []string `json:"exclude_status,omitempty"`

	// Type exclusion (for hiding internal types like gates, bd-7zka.2)
	ExcludeTypes []string `json:"exclude_types,omitempty"`

	// Time-based scheduling filters (GH#820)
	Deferred    bool   `json:"deferred,omitempty"`     // Filter issues with defer_until set
	DeferAfter  string `json:"defer_after,omitempty"`  // ISO 8601 format
	DeferBefore string `json:"defer_before,omitempty"` // ISO 8601 format
	DueAfter    string `json:"due_after,omitempty"`    // ISO 8601 format
	DueBefore   string `json:"due_before,omitempty"`   // ISO 8601 format
	Overdue     bool   `json:"overdue,omitempty"`      // Filter issues where due_at < now

	// Staleness control (bd-dpkdm)
	AllowStale bool `json:"allow_stale,omitempty"` // Skip staleness check, return potentially stale data
}

ListArgs represents arguments for the list operation

type Metrics 

type Metrics struct {
	// contains filtered or unexported fields
}

Metrics holds all telemetry data for the daemon

func NewMetrics 

func NewMetrics() *Metrics

NewMetrics creates a new metrics collector

func (*Metrics) RecordConnection 

func (m *Metrics) RecordConnection()

RecordConnection records a new connection

func (*Metrics) RecordError 

func (m *Metrics) RecordError(operation string)

RecordError records a failed request

func (*Metrics) RecordRejectedConnection 

func (m *Metrics) RecordRejectedConnection()

RecordRejectedConnection records a rejected connection (max conns reached)

func (*Metrics) RecordRequest 

func (m *Metrics) RecordRequest(operation string, latency time.Duration)

RecordRequest records a request (successful or failed)

func (*Metrics) Snapshot 

func (m *Metrics) Snapshot(activeConns int) MetricsSnapshot

Snapshot returns a point-in-time snapshot of all metrics

type MetricsSnapshot 

type MetricsSnapshot struct {
	Timestamp      time.Time          `json:"timestamp"`
	UptimeSeconds  float64            `json:"uptime_seconds"`
	Operations     []OperationMetrics `json:"operations"`
	TotalConns     int64              `json:"total_connections"`
	ActiveConns    int                `json:"active_connections"`
	RejectedConns  int64              `json:"rejected_connections"`
	MemoryAllocMB  uint64             `json:"memory_alloc_mb"`
	MemorySysMB    uint64             `json:"memory_sys_mb"`
	GoroutineCount int                `json:"goroutine_count"`
}

MetricsSnapshot is a point-in-time view of all metrics

type MolStaleArgs 

type MolStaleArgs struct {
	BlockingOnly   bool `json:"blocking_only"`   // Only show molecules blocking other work
	UnassignedOnly bool `json:"unassigned_only"` // Only show unassigned molecules
	ShowAll        bool `json:"show_all"`        // Include molecules with 0 children
}

MolStaleArgs represents arguments for the mol stale operation

type MolStaleResponse 

type MolStaleResponse struct {
	StaleMolecules []*StaleMolecule `json:"stale_molecules"`
	TotalCount     int              `json:"total_count"`
	BlockingCount  int              `json:"blocking_count"`
}

MolStaleResponse holds the result of the mol stale operation

type MoleculeProgress 

type MoleculeProgress struct {
	MoleculeID string         `json:"molecule_id"`
	Title      string         `json:"title"`
	Assignee   string         `json:"assignee"`
	Steps      []MoleculeStep `json:"steps"`
}

MoleculeProgress represents the progress of a molecule (parent issue with steps)

type MoleculeStep 

type MoleculeStep struct {
	ID        string  `json:"id"`
	Title     string  `json:"title"`
	Status    string  `json:"status"`     // "done", "current", "ready", "blocked"
	StartTime *string `json:"start_time"` // ISO 8601 timestamp when step was created
	CloseTime *string `json:"close_time"` // ISO 8601 timestamp when step was closed (if done)
}

MoleculeStep represents a single step within a molecule

type MutationEvent 

type MutationEvent struct {
	Type      string // One of the Mutation* constants
	IssueID   string // e.g., "bd-42"
	Title     string // Issue title for display context (may be empty for some operations)
	Assignee  string // Issue assignee for display context (may be empty)
	Actor     string // Who performed the action (may differ from assignee)
	Timestamp time.Time
	// Optional metadata for richer events (used by status, bonded, etc.)
	OldStatus string `json:"old_status,omitempty"` // Previous status (for status events)
	NewStatus string `json:"new_status,omitempty"` // New status (for status events)
	ParentID  string `json:"parent_id,omitempty"`  // Parent molecule (for bonded events)
	StepCount int    `json:"step_count,omitempty"` // Number of steps (for bonded events)
}

MutationEvent represents a database mutation for event-driven sync

type OperationMetrics 

type OperationMetrics struct {
	Operation    string       `json:"operation"`
	TotalCount   int64        `json:"total_count"`
	SuccessCount int64        `json:"success_count"`
	ErrorCount   int64        `json:"error_count"`
	Latency      LatencyStats `json:"latency,omitempty"`
}

OperationMetrics holds metrics for a single operation type

type PingResponse 

type PingResponse struct {
	Message string `json:"message"`
	Version string `json:"version"`
}

PingResponse is the response for a ping operation

type ReadyArgs 

type ReadyArgs struct {
	Assignee        string   `json:"assignee,omitempty"`
	Unassigned      bool     `json:"unassigned,omitempty"`
	Priority        *int     `json:"priority,omitempty"`
	Type            string   `json:"type,omitempty"`
	Limit           int      `json:"limit,omitempty"`
	SortPolicy      string   `json:"sort_policy,omitempty"`
	Labels          []string `json:"labels,omitempty"`
	LabelsAny       []string `json:"labels_any,omitempty"`
	ParentID        string   `json:"parent_id,omitempty"`        // Filter to descendants of this bead/epic
	MolType         string   `json:"mol_type,omitempty"`         // Filter by molecule type: swarm, patrol, or work
	IncludeDeferred bool     `json:"include_deferred,omitempty"` // Include issues with future defer_until (GH#820)
}

ReadyArgs represents arguments for the ready operation

type Request 

type Request struct {
	Operation     string          `json:"operation"`
	Args          json.RawMessage `json:"args"`
	Actor         string          `json:"actor,omitempty"`
	RequestID     string          `json:"request_id,omitempty"`
	Cwd           string          `json:"cwd,omitempty"`            // Working directory for database discovery
	ClientVersion string          `json:"client_version,omitempty"` // Client version for compatibility checks
	ExpectedDB    string          `json:"expected_db,omitempty"`    // Expected database path for validation (absolute)
}

Request represents an RPC request from client to daemon

type ResolveIDArgs 

type ResolveIDArgs struct {
	ID string `json:"id"`
}

ResolveIDArgs represents arguments for the resolve_id operation

type Response 

type Response struct {
	Success bool            `json:"success"`
	Data    json.RawMessage `json:"data,omitempty"`
	Error   string          `json:"error,omitempty"`
}

Response represents an RPC response from daemon to client

type Server 

type Server struct {
	// contains filtered or unexported fields
}

Server represents the RPC server that runs in the daemon

func NewServer 

func NewServer(socketPath string, store storage.Storage, workspacePath string, dbPath string) *Server

NewServer creates a new RPC server

func (*Server) GetEnrichmentQueueLength 

func (s *Server) GetEnrichmentQueueLength(ctx context.Context) int

GetEnrichmentQueueLength returns the number of sessions pending AI enrichment

func (*Server) GetRecentMutations 

func (s *Server) GetRecentMutations(sinceMillis int64) []MutationEvent

GetRecentMutations returns mutations since the given timestamp

func (*Server) MutationChan 

func (s *Server) MutationChan() <-chan MutationEvent

MutationChan returns the mutation event channel for the daemon to consume

func (*Server) ResetDroppedEventsCount 

func (s *Server) ResetDroppedEventsCount() int64

ResetDroppedEventsCount resets the dropped events counter and returns the previous value

func (*Server) SetConfig 

func (s *Server) SetConfig(autoCommit, autoPush, autoPull, localMode bool, syncInterval, daemonMode string)

SetConfig sets the daemon configuration for status reporting

func (*Server) Start 

func (s *Server) Start(_ context.Context) error

Start starts the RPC server and listens for connections

func (*Server) Stop 

func (s *Server) Stop() error

Stop stops the RPC server and cleans up resources

func (*Server) WaitReady 

func (s *Server) WaitReady() <-chan struct{}

WaitReady waits for the server to be ready to accept connections

type ShowArgs 

type ShowArgs struct {
	ID string `json:"id"`
}

ShowArgs represents arguments for the show operation

type StaleArgs 

type StaleArgs struct {
	Days   int    `json:"days,omitempty"`
	Status string `json:"status,omitempty"`
	Limit  int    `json:"limit,omitempty"`
}

StaleArgs represents arguments for the stale command

type StaleMolecule 

type StaleMolecule struct {
	ID             string   `json:"id"`
	Title          string   `json:"title"`
	TotalChildren  int      `json:"total_children"`
	ClosedChildren int      `json:"closed_children"`
	Assignee       string   `json:"assignee,omitempty"`
	BlockingIssues []string `json:"blocking_issues,omitempty"`
	BlockingCount  int      `json:"blocking_count"`
}

StaleMolecule holds info about a stale molecule (for RPC response)

type StatusResponse 

type StatusResponse struct {
	Version             string  `json:"version"`                         // Server/daemon version
	WorkspacePath       string  `json:"workspace_path"`                  // Absolute path to workspace root
	DatabasePath        string  `json:"database_path"`                   // Absolute path to database file
	SocketPath          string  `json:"socket_path"`                     // Path to Unix socket
	PID                 int     `json:"pid"`                             // Process ID
	UptimeSeconds       float64 `json:"uptime_seconds"`                  // Time since daemon started
	LastActivityTime    string  `json:"last_activity_time"`              // ISO 8601 timestamp of last request
	ExclusiveLockActive bool    `json:"exclusive_lock_active"`           // Whether an exclusive lock is held
	ExclusiveLockHolder string  `json:"exclusive_lock_holder,omitempty"` // Lock holder name if active
	// Daemon configuration
	AutoCommit   bool   `json:"auto_commit"`   // Whether auto-commit is enabled
	AutoPush     bool   `json:"auto_push"`     // Whether auto-push is enabled
	AutoPull     bool   `json:"auto_pull"`     // Whether auto-pull is enabled (periodic remote sync)
	LocalMode    bool   `json:"local_mode"`    // Whether running in local-only mode (no git)
	SyncInterval string `json:"sync_interval"` // Sync interval (e.g., "5s")
	DaemonMode   string `json:"daemon_mode"`   // Sync mode: "poll" or "events"
}

StatusResponse represents the daemon status metadata

type UpdateArgs 

type UpdateArgs struct {
	ID                 string   `json:"id"`
	Title              *string  `json:"title,omitempty"`
	Description        *string  `json:"description,omitempty"`
	Status             *string  `json:"status,omitempty"`
	Priority           *int     `json:"priority,omitempty"`
	Design             *string  `json:"design,omitempty"`
	AcceptanceCriteria *string  `json:"acceptance_criteria,omitempty"`
	Notes              *string  `json:"notes,omitempty"`
	Assignee           *string  `json:"assignee,omitempty"`
	ExternalRef        *string  `json:"external_ref,omitempty"`      // Link to external issue trackers
	EstimatedMinutes   *int     `json:"estimated_minutes,omitempty"` // Time estimate in minutes
	IssueType          *string  `json:"issue_type,omitempty"`        // Issue type (bug|feature|task|epic|chore)
	AddLabels          []string `json:"add_labels,omitempty"`
	RemoveLabels       []string `json:"remove_labels,omitempty"`
	SetLabels          []string `json:"set_labels,omitempty"`
	// Messaging fields
	Sender    *string `json:"sender,omitempty"`     // Who sent this (for messages)
	Ephemeral *bool   `json:"ephemeral,omitempty"`  // If true, not exported to JSONL; bulk-deleted when closed
	RepliesTo *string `json:"replies_to,omitempty"` // Issue ID for conversation threading
	// Graph link fields
	RelatesTo    *string `json:"relates_to,omitempty"`    // JSON array of related issue IDs
	DuplicateOf  *string `json:"duplicate_of,omitempty"`  // Canonical issue ID if duplicate
	SupersededBy *string `json:"superseded_by,omitempty"` // Replacement issue ID if obsolete
	// Pinned field
	Pinned *bool `json:"pinned,omitempty"` // If true, issue is a persistent context marker
	// Reparenting field
	Parent *string `json:"parent,omitempty"` // New parent issue ID (reparents the issue)
	// Agent slot fields
	HookBead *string `json:"hook_bead,omitempty"` // Current work on agent's hook (0..1)
	RoleBead *string `json:"role_bead,omitempty"` // Role definition bead for agent
	// Agent state fields
	AgentState   *string `json:"agent_state,omitempty"`   // Agent state (idle|running|stuck|stopped|dead)
	LastActivity *bool   `json:"last_activity,omitempty"` // If true, update last_activity to now
	// Agent identity fields
	RoleType *string `json:"role_type,omitempty"` // polecat|crew|witness|refinery|mayor|deacon
	Rig      *string `json:"rig,omitempty"`       // Rig name (empty for town-level agents)
	// Event fields (only valid when IssueType == "event")
	EventCategory *string `json:"event_category,omitempty"` // Namespaced category (e.g., patrol.muted, agent.started)
	EventActor    *string `json:"event_actor,omitempty"`    // Entity URI who caused this event
	EventTarget   *string `json:"event_target,omitempty"`   // Entity URI or bead ID affected
	EventPayload  *string `json:"event_payload,omitempty"`  // Event-specific JSON data
	// Work queue claim operation
	Claim bool `json:"claim,omitempty"` // If true, atomically claim issue (set assignee+status, fail if already claimed)
	// Time-based scheduling fields (GH#820)
	DueAt      *string `json:"due_at,omitempty"`      // Relative or ISO format due date
	DeferUntil *string `json:"defer_until,omitempty"` // Relative or ISO format defer date
	// Gate fields
	AwaitID *string  `json:"await_id,omitempty"` // Condition identifier for gates (run ID, PR number, etc.)
	Waiters []string `json:"waiters,omitempty"`  // Mail addresses to notify when gate clears
	// Slot fields
	Holder *string `json:"holder,omitempty"` // Who currently holds the slot (for type=slot beads)
}

UpdateArgs represents arguments for the update operation

type WorkerStatus 

type WorkerStatus struct {
	Assignee      string `json:"assignee"`                 // Worker identifier
	MoleculeID    string `json:"molecule_id,omitempty"`    // Parent molecule/epic ID (if working on a step)
	MoleculeTitle string `json:"molecule_title,omitempty"` // Parent molecule/epic title
	CurrentStep   int    `json:"current_step,omitempty"`   // Current step number (1-indexed)
	TotalSteps    int    `json:"total_steps,omitempty"`    // Total number of steps in molecule
	StepID        string `json:"step_id,omitempty"`        // Current step issue ID
	StepTitle     string `json:"step_title,omitempty"`     // Current step issue title
	LastActivity  string `json:"last_activity"`            // ISO 8601 timestamp of last update
	Status        string `json:"status"`                   // Current work status (in_progress, blocked, etc.)
}

WorkerStatus represents the status of a single worker and their current work

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.