runtime

Documentation

Index

• func OutputPathComponent(id string) string
• func SafeTaskPathComponent(input string) string
• func ValidateTaskID(id string) error
• type RuntimeLifecycle
  • func NewRuntimeLifecycle(projectRoot string) *RuntimeLifecycle
  • func NewRuntimeLifecycleAt(projectRoot, storageRoot string) *RuntimeLifecycle
  • func NewRuntimeLifecycleForSession(projectRoot, sessionID string) *RuntimeLifecycle
  • func (l *RuntimeLifecycle) ActiveState() ([]RuntimeLifecycleEvent, error)
  • func (l *RuntimeLifecycle) Events() ([]RuntimeLifecycleEvent, error)
  • func (l *RuntimeLifecycle) Publish(ctx context.Context, event RuntimeLifecycleEvent) error
  • func (l *RuntimeLifecycle) Root() string
  • func (l *RuntimeLifecycle) StorageRoot() string
  • func (l *RuntimeLifecycle) Subscribe(sink RuntimeLifecycleSink)
• type RuntimeLifecycleEvent
• type RuntimeLifecycleEventType
• type RuntimeLifecycleSink
• type RuntimeTaskRecord
• type RuntimeTaskStore
  • func NewRuntimeTaskStore(projectRoot string) *RuntimeTaskStore
  • func NewRuntimeTaskStoreAt(projectRoot, storageRoot string) *RuntimeTaskStore
  • func NewRuntimeTaskStoreForSession(projectRoot, sessionID string) *RuntimeTaskStore
  • func (s *RuntimeTaskStore) Exists(id string) bool
  • func (s *RuntimeTaskStore) FindLocalAgentByAlias(alias string) (RuntimeTaskRecord, bool)
  • func (s *RuntimeTaskStore) Get(id string) (RuntimeTaskRecord, bool)
  • func (s *RuntimeTaskStore) List() []RuntimeTaskRecord
  • func (s *RuntimeTaskStore) Save(record RuntimeTaskRecord) error
  • func (s *RuntimeTaskStore) StorageRoot() string

Functions

func OutputPathComponent

func OutputPathComponent(id string) string

OutputPathComponent returns the canonical collision-resistant artifact name component for a runtime task identity.

func SafeTaskPathComponent

func SafeTaskPathComponent(input string) string

SafeTaskPathComponent projects a runtime task identity onto the canonical single-component storage form shared by task records and their artifacts.

func ValidateTaskID

func ValidateTaskID(id string) error

ValidateTaskID rejects identities that cannot safely own one runtime-task record and its adjacent artifacts.

Types

type RuntimeLifecycle

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

RuntimeLifecycle persists events before dispatching them to side-effect sinks. A process crash can therefore reconstruct state from disk without relying on an in-memory callback having completed.

func NewRuntimeLifecycle

func NewRuntimeLifecycle(projectRoot string) *RuntimeLifecycle

func NewRuntimeLifecycleAt

func NewRuntimeLifecycleAt(projectRoot, storageRoot string) *RuntimeLifecycle

NewRuntimeLifecycleAt creates a journal with an explicitly injected storage root. This is the only constructor tests need: projectRoot remains logical while all persistence stays under the supplied temporary directory.

func NewRuntimeLifecycleForSession

func NewRuntimeLifecycleForSession(projectRoot, sessionID string) *RuntimeLifecycle

NewRuntimeLifecycleForSession creates a lifecycle journal isolated to one conversation. An empty session ID selects the process-private namespace.

func (*RuntimeLifecycle) ActiveState

func (l *RuntimeLifecycle) ActiveState() ([]RuntimeLifecycleEvent, error)

ActiveState folds the durable event history into the state that must survive session resume and compaction. Instantaneous cron/MCP events are history-only.

func (*RuntimeLifecycle) Events

func (l *RuntimeLifecycle) Events() ([]RuntimeLifecycleEvent, error)

func (*RuntimeLifecycle) Publish

func (l *RuntimeLifecycle) Publish(ctx context.Context, event RuntimeLifecycleEvent) error

Publish durably appends event, then fans the same event identity out to all subscribers. Sink failures are returned only after the event is persisted.

func (*RuntimeLifecycle) Root

func (l *RuntimeLifecycle) Root() string

Root returns the immutable project root owned by this lifecycle journal.

func (*RuntimeLifecycle) StorageRoot

func (l *RuntimeLifecycle) StorageRoot() string

StorageRoot returns the external, private persistence directory. Root() remains the logical project identity used in lifecycle payloads and routing.

func (*RuntimeLifecycle) Subscribe

func (l *RuntimeLifecycle) Subscribe(sink RuntimeLifecycleSink)

type RuntimeLifecycleEvent

type RuntimeLifecycleEvent struct {
	ID        string                    `json:"id"`
	Type      RuntimeLifecycleEventType `json:"type"`
	SessionID string                    `json:"session_id,omitempty"`
	EntityID  string                    `json:"entity_id,omitempty"`
	ToolName  string                    `json:"tool_name,omitempty"`
	Status    string                    `json:"status,omitempty"`
	Payload   map[string]any            `json:"payload,omitempty"`
	CreatedAt time.Time                 `json:"created_at"`
}

RuntimeLifecycleEvent is the durable, TS-compatible lifecycle envelope. Payload remains intentionally open so dependent tools can add state without forcing a schema change in this foundation layer.

type RuntimeLifecycleEventType

type RuntimeLifecycleEventType string

RuntimeLifecycleEventType is the stable event vocabulary shared by tool, task, cron, worktree, team, and MCP lifecycle integrations.

const (
	LifecycleToolStart           RuntimeLifecycleEventType = "tool_start"
	LifecycleToolComplete        RuntimeLifecycleEventType = "tool_complete"
	LifecycleTaskCreated         RuntimeLifecycleEventType = "task_created"
	LifecycleTaskCompleted       RuntimeLifecycleEventType = "task_completed"
	LifecycleCronFire            RuntimeLifecycleEventType = "cron_fire"
	LifecycleWorktreeEnter       RuntimeLifecycleEventType = "worktree_enter"
	LifecycleWorktreeExit        RuntimeLifecycleEventType = "worktree_exit"
	LifecycleTeamCreate          RuntimeLifecycleEventType = "team_create"
	LifecycleTeamDelete          RuntimeLifecycleEventType = "team_delete"
	LifecycleMCPResourcesChanged RuntimeLifecycleEventType = "mcp_resources_changed"
)

type RuntimeLifecycleSink

type RuntimeLifecycleSink interface {
	HandleLifecycleEvent(context.Context, RuntimeLifecycleEvent) error
}

RuntimeLifecycleSink is the single side-effect boundary for notifications, mailbox delivery, task refresh, analytics, and other event consumers.

type RuntimeTaskRecord

type RuntimeTaskRecord struct {
	ID                     string                              `json:"id"`
	Type                   string                              `json:"type"`
	Status                 string                              `json:"status"`
	Description            string                              `json:"description,omitempty"`
	Command                string                              `json:"command,omitempty"`
	Prompt                 string                              `json:"prompt,omitempty"`
	OutputPath             string                              `json:"output_path,omitempty"`
	ExitCode               *int                                `json:"exit_code,omitempty"`
	Error                  string                              `json:"error,omitempty"`
	Result                 string                              `json:"result,omitempty"`
	StartedAt              time.Time                           `json:"started_at"`
	FinishedAt             *time.Time                          `json:"finished_at,omitempty"`
	UpdatedAt              time.Time                           `json:"updated_at"`
	OutputOffset           int64                               `json:"output_offset,omitempty"`
	AgentAlias             string                              `json:"agent_alias,omitempty"`
	AgentInput             *agentcontract.Input                `json:"agent_input,omitempty"`
	Detached               bool                                `json:"detached,omitempty"`
	AgentMetadata          *agentcontract.SessionMetadata      `json:"agent_metadata,omitempty"`
	AgentMessages          []types.Message                     `json:"agent_messages,omitempty"`
	OwnerSessionID         string                              `json:"owner_session_id,omitempty"`
	OwnerSessionProjectDir string                              `json:"owner_session_project_dir,omitempty"`
	OwnerProjectRoot       string                              `json:"owner_project_root,omitempty"`
	OwnerAgentID           string                              `json:"owner_agent_id,omitempty"`
	OwnerPID               int                                 `json:"owner_pid,omitempty"`
	CurrentRunID           string                              `json:"current_run_id,omitempty"`
	Attempt                int                                 `json:"attempt,omitempty"`
	BatchID                string                              `json:"batch_id,omitempty"`
	ParentRunID            string                              `json:"parent_run_id,omitempty"`
	AgentPath              string                              `json:"agent_path,omitempty"`
	QueuedPrompts          int                                 `json:"queued_prompts,omitempty"`
	QueueReason            string                              `json:"queue_reason,omitempty"`
	Runs                   []agentcontract.RunRecord           `json:"runs,omitempty"`
	LatestProgress         *agentcontract.ProgressEvent        `json:"latest_progress,omitempty"`
	TranscriptPath         string                              `json:"transcript_path,omitempty"`
	DurationMs             *int64                              `json:"duration_ms,omitempty"`
	TotalTokens            *int                                `json:"total_tokens,omitempty"`
	Usage                  *types.Usage                        `json:"usage,omitempty"`
	Outcome                agentcontract.RunOutcome            `json:"outcome,omitempty"`
	TerminalReason         string                              `json:"terminal_reason,omitempty"`
	TimeoutNanos           int64                               `json:"timeout_nanos,omitempty"`
	ArtifactRefs           []string                            `json:"artifact_refs,omitempty"`
	VerificationRefs       []string                            `json:"verification_refs,omitempty"`
	Notification           *agentcontract.RuntimeNotification  `json:"notification,omitempty"`
	Notifications          []agentcontract.RuntimeNotification `json:"notifications,omitempty"`
}

type RuntimeTaskStore

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

func NewRuntimeTaskStore

func NewRuntimeTaskStore(projectRoot string) *RuntimeTaskStore

func NewRuntimeTaskStoreAt

func NewRuntimeTaskStoreAt(projectRoot, storageRoot string) *RuntimeTaskStore

NewRuntimeTaskStoreAt injects an external runtime root for hermetic tests and embedded runtimes. projectRoot remains the logical owner of every record.

func NewRuntimeTaskStoreForSession

func NewRuntimeTaskStoreForSession(projectRoot, sessionID string) *RuntimeTaskStore

NewRuntimeTaskStoreForSession creates task state and output paths isolated to one conversation. An empty session ID selects the process namespace.

func (*RuntimeTaskStore) Exists

func (s *RuntimeTaskStore) Exists(id string) bool

func (*RuntimeTaskStore) FindLocalAgentByAlias

func (s *RuntimeTaskStore) FindLocalAgentByAlias(alias string) (RuntimeTaskRecord, bool)

func (*RuntimeTaskStore) Get

func (s *RuntimeTaskStore) Get(id string) (RuntimeTaskRecord, bool)

func (*RuntimeTaskStore) List

func (s *RuntimeTaskStore) List() []RuntimeTaskRecord

func (*RuntimeTaskStore) Save

func (s *RuntimeTaskStore) Save(record RuntimeTaskRecord) error

func (*RuntimeTaskStore) StorageRoot

func (s *RuntimeTaskStore) StorageRoot() string

StorageRoot returns the external private namespace used by this store.