toolruntime

Documentation

Overview

Package toolruntime tracks long-running tool subprocess ownership and scoped interrupts.

Index

• Variables
• type BootReconcileReport
• type Handle
  • func (h *Handle) Checkpoint(ctx context.Context, checkpoint ProcessCheckpoint) error
  • func (h *Handle) Complete(ctx context.Context, completion ProcessCompletion) error
  • func (h *Handle) ID() string
• type InterruptFunc
• type InterruptReport
• type InterruptScope
  • func (s InterruptScope) IsZero() bool
  • func (s InterruptScope) Normalize() InterruptScope
• type Interrupter
• type MemoryStore
  • func NewMemoryStore() *MemoryStore
  • func (s *MemoryStore) ListProcessRecords(_ context.Context, query ProcessQuery) ([]ProcessRecord, error)
  • func (s *MemoryStore) UpdateProcessRecordState(_ context.Context, update ProcessStateUpdate) error
  • func (s *MemoryStore) UpsertProcessRecord(_ context.Context, record ProcessRecord) error
• type Option
  • func WithDaemonPID(pid int) Option
  • func WithInterrupter(interrupter Interrupter) Option
  • func WithLogger(logger *slog.Logger) Option
  • func WithNow(now func() time.Time) Option
  • func WithVerifier(verifier Verifier) Option
• type ProcessCheckpoint
• type ProcessCompletion
• type ProcessOwner
• type ProcessQuery
• type ProcessRecord
• type ProcessSource
  • func (s ProcessSource) Validate() error
• type ProcessState
  • func (s ProcessState) Validate() error
• type ProcessStateUpdate
• type RegisterConfig
• type Registry
  • func NewRegistry(store Store, opts ...Option) *Registry
  • func (r *Registry) Interrupt(ctx context.Context, scope InterruptScope) (InterruptReport, error)
  • func (r *Registry) ReconcileBoot(ctx context.Context) (BootReconcileReport, error)
  • func (r *Registry) Register(ctx context.Context, cfg RegisterConfig) (*Handle, error)
• type Store
• type Verifier

Variables

var (
	// ErrProcessNotFound reports that an interrupt scope matched no active process records.
	ErrProcessNotFound = errors.New("toolruntime: process not found")
	// ErrOwnershipValidationFailed reports that a recovered PID no longer matches
	// the stored process ownership evidence.
	ErrOwnershipValidationFailed = errors.New("toolruntime: process ownership validation failed")
)

Types

type BootReconcileReport

type BootReconcileReport struct {
	Checked   int
	Recovered int
	Stale     int
}

BootReconcileReport summarizes restart reconciliation.

type Handle

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

Handle represents a registered process checkpoint handle.

func (*Handle) Checkpoint

func (h *Handle) Checkpoint(ctx context.Context, checkpoint ProcessCheckpoint) error

Checkpoint persists a state or owner update for the process.

func (*Handle) Complete

func (h *Handle) Complete(ctx context.Context, completion ProcessCompletion) error

Complete records the terminal process state exactly once.

func (*Handle) ID

func (h *Handle) ID() string

ID returns the durable process record ID.

type InterruptFunc

type InterruptFunc func(context.Context, ProcessRecord) error

InterruptFunc interrupts a live process record owned by the current daemon.

type InterruptReport

type InterruptReport struct {
	Matched     int
	Signaled    int
	Stale       int
	Unavailable int
}

InterruptReport summarizes one scoped interrupt request.

type InterruptScope

type InterruptScope struct {
	ProcessID     string
	SessionID     string
	TurnID        string
	ToolCallID    string
	TerminalID    string
	ExtensionName string
	HookName      string
	Source        ProcessSource
	Reason        string
}

InterruptScope targets one process, tool call, turn, session, hook, or extension.

func (InterruptScope) IsZero

func (s InterruptScope) IsZero() bool

IsZero reports whether the scope carries any selector.

func (InterruptScope) Normalize

func (s InterruptScope) Normalize() InterruptScope

Normalize trims every string selector in the scope.

type Interrupter

type Interrupter interface {
	InterruptProcess(ctx context.Context, record ProcessRecord) error
}

Interrupter signals a recovered process after ownership validation.

type MemoryStore

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

MemoryStore is an in-memory Store implementation used by tests and fakes.

func NewMemoryStore

func NewMemoryStore() *MemoryStore

NewMemoryStore constructs an empty in-memory process store.

func (*MemoryStore) ListProcessRecords

func (s *MemoryStore) ListProcessRecords(_ context.Context, query ProcessQuery) ([]ProcessRecord, error)

ListProcessRecords returns records matching the query.

func (*MemoryStore) UpdateProcessRecordState

func (s *MemoryStore) UpdateProcessRecordState(_ context.Context, update ProcessStateUpdate) error

UpdateProcessRecordState updates lifecycle fields for an existing record.

func (*MemoryStore) UpsertProcessRecord

func (s *MemoryStore) UpsertProcessRecord(_ context.Context, record ProcessRecord) error

UpsertProcessRecord inserts or replaces a record.

type Option

type Option func(*Registry)

Option customizes a Registry.

func WithDaemonPID

func WithDaemonPID(pid int) Option

WithDaemonPID records the owning daemon PID in new checkpoints.

func WithInterrupter

func WithInterrupter(interrupter Interrupter) Option

WithInterrupter overrides recovered-process signaling.

func WithLogger

func WithLogger(logger *slog.Logger) Option

WithLogger injects a diagnostic logger.

func WithNow

func WithNow(now func() time.Time) Option

WithNow overrides the registry clock.

func WithVerifier

func WithVerifier(verifier Verifier) Option

WithVerifier overrides PID/start-time validation.

type ProcessCheckpoint

type ProcessCheckpoint struct {
	Owner          *ProcessOwner
	PID            *int
	ProcessGroupID *int
	StartedAt      *time.Time
	State          ProcessState
	Error          string
	UpdatedAt      time.Time
}

ProcessCheckpoint mutates checkpointable fields for a tracked record.

type ProcessCompletion

type ProcessCompletion struct {
	ExitCode *int
	Err      error
	Error    string
}

ProcessCompletion captures the terminal outcome for a tracked process.

type ProcessOwner

type ProcessOwner struct {
	SessionID     string
	TurnID        string
	ToolCallID    string
	TerminalID    string
	ExtensionName string
	HookName      string
	SandboxID     string
}

ProcessOwner captures stable owner IDs used for scoped interrupts.

type ProcessQuery

type ProcessQuery struct {
	IDs    []string
	States []ProcessState
	Scope  InterruptScope
	Limit  int
}

ProcessQuery filters persisted process records.

type ProcessRecord

type ProcessRecord struct {
	ID             string
	Source         ProcessSource
	Owner          ProcessOwner
	PID            int
	ProcessGroupID int
	Command        string
	Args           []string
	Cwd            string
	StartedAt      time.Time
	StartedByPID   int
	State          ProcessState
	ExitCode       *int
	Error          string
	CreatedAt      time.Time
	UpdatedAt      time.Time
	CompletedAt    *time.Time
}

ProcessRecord is the checkpointed process ownership record.

type ProcessSource

type ProcessSource string

ProcessSource identifies the AGH subsystem that launched a process.

const (
	ProcessSourceACPAgent        ProcessSource = "acp_agent"
	ProcessSourceACPTerminal     ProcessSource = "acp_terminal"
	ProcessSourceSandboxTerminal ProcessSource = "sandbox_terminal"
	ProcessSourceHook            ProcessSource = "hook"
	ProcessSourceExtension       ProcessSource = "extension"
	ProcessSourceSubprocess      ProcessSource = "subprocess"
)

func (ProcessSource) Validate

func (s ProcessSource) Validate() error

Validate ensures the source is known.

type ProcessState

type ProcessState string

ProcessState is the durable lifecycle state for a tracked process.

const (
	ProcessStateRunning      ProcessState = "running"
	ProcessStateInterrupting ProcessState = "interrupting"
	ProcessStateInterrupted  ProcessState = "interrupted"
	ProcessStateCompleted    ProcessState = "completed"
	ProcessStateFailed       ProcessState = "failed"
	ProcessStateStale        ProcessState = "stale"
)

func (ProcessState) Validate

func (s ProcessState) Validate() error

Validate ensures the state is known.

type ProcessStateUpdate

type ProcessStateUpdate struct {
	ID          string
	State       ProcessState
	ExitCode    *int
	Error       string
	UpdatedAt   time.Time
	CompletedAt *time.Time
}

ProcessStateUpdate is the storage-level state mutation for a record.

type RegisterConfig

type RegisterConfig struct {
	ID             string
	Source         ProcessSource
	Owner          ProcessOwner
	PID            int
	ProcessGroupID int
	Command        string
	Args           []string
	Cwd            string
	StartedAt      time.Time
	Interrupt      InterruptFunc
}

RegisterConfig describes one process registration.

type Registry

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

Registry owns in-memory process handles and durable checkpointing.

func NewRegistry

func NewRegistry(store Store, opts ...Option) *Registry

NewRegistry constructs a process registry. A nil store keeps live scoped interrupts working but skips durable checkpoints.

func (*Registry) Interrupt

func (r *Registry) Interrupt(ctx context.Context, scope InterruptScope) (InterruptReport, error)

Interrupt signals only processes matching the supplied scope.

func (*Registry) ReconcileBoot

func (r *Registry) ReconcileBoot(ctx context.Context) (BootReconcileReport, error)

ReconcileBoot validates durable active records after daemon restart.

func (*Registry) Register

func (r *Registry) Register(ctx context.Context, cfg RegisterConfig) (*Handle, error)

Register checkpoints a running process and returns a handle for later updates.

type Store

type Store interface {
	UpsertProcessRecord(ctx context.Context, record ProcessRecord) error
	UpdateProcessRecordState(ctx context.Context, update ProcessStateUpdate) error
	ListProcessRecords(ctx context.Context, query ProcessQuery) ([]ProcessRecord, error)
}

Store is the durable persistence boundary consumed by Registry.

type Verifier

type Verifier func(pid int, startedAt time.Time) bool

Verifier validates that a PID still belongs to the stored start-time evidence.