Documentation
¶
Overview ¶
Package subagent owns durable, read-only specialist executions for the Coding application. It deliberately does not expand the generic agent API.
Index ¶
- Constants
- Variables
- func BuiltinPrompt(id string, structured, nativeStructuredOutput bool) (string, error)
- func BuiltinResultSchema(id string) (json.RawMessage, bool)
- func FormatResultText(result Result) string
- func InstructionsDigest(value string) string
- func IsDirectory(value string) bool
- func IsNotSentinel(value string) bool
- func IsParentMessageID(id string) bool
- func NormalizeIsolation(value string) (string, bool)
- func Reconcile(ctx context.Context, repository *session.Repository, parent *session.Handle) error
- func SanitizeCwd(value string) string
- func ValidateCwdDirectory(value string) error
- func ValidateExecutionPlan(plan ExecutionPlan) error
- func ValidateIdentity(identity AgentIdentity) error
- func WorktreeIsolation(value string) bool
- type Activity
- type ActivityAction
- type ActivityPhase
- type ActivitySummary
- type AdmissionEvent
- type AdmissionObserver
- type AdmissionOutcome
- type AdmissionReason
- type AgentEvent
- type AgentEventObserver
- type AgentIdentity
- type AgentKind
- type Config
- type Delivery
- type Detail
- type DispatchInput
- type Dispatcher
- type EffectiveCapability
- type Event
- type Evidence
- type Execution
- type ExecutionOptions
- type ExecutionPlan
- type ExploreResult
- type Lifecycle
- type LifecycleStart
- type LifecycleStop
- type LifecycleStopDecision
- type LimitBehavior
- type Limits
- type Manager
- func (m *Manager) Cancel(ctx context.Context, childSessionID string) error
- func (m *Manager) CancelRoot(rootInteractionID string) int
- func (m *Manager) Close(ctx context.Context) error
- func (m *Manager) Inspect(ctx context.Context, childSessionID string) (Detail, error)
- func (m *Manager) List(ctx context.Context) ([]Summary, error)
- func (m *Manager) MaxAutoFollowUps() int
- func (m *Manager) MessageCoordinator() *MessageCoordinator
- func (m *Manager) SpawnToolFor(owner Ownership, observer Observer) agent.Tool
- func (m *Manager) SpawnToolForDispatcher(owner Ownership, observer Observer, dispatcher Dispatcher) agent.Tool
- func (m *Manager) Start(ctx context.Context, request Request, observer Observer) (*Execution, error)
- func (m *Manager) StartWithDispatcher(ctx context.Context, request Request, observer Observer, dispatcher Dispatcher) (*Execution, error)
- func (m *Manager) Wait(ctx context.Context, childSessionID string) (Result, error)
- type MessageBinding
- type MessageCall
- type MessageCoordinator
- type MessageDelivery
- type MessageDisposition
- type MessageOutcome
- type MessageOutcomeKind
- type MessagePorts
- type MessageQuotaKind
- type MessageSender
- type MessageSenderIdentity
- type MessageSink
- type Notification
- type NotificationInbox
- func (i *NotificationInbox) Acknowledge(ids ...string) error
- func (i *NotificationInbox) Contains(id string) (bool, error)
- func (i *NotificationInbox) Enqueue(value Notification) error
- func (i *NotificationInbox) EnqueueCompletion(event Event) error
- func (i *NotificationInbox) EnqueueMessage(value ParentMessage) error
- func (i *NotificationInbox) EnqueueRecovered(summary Summary, result any) error
- func (i *NotificationInbox) Pending() ([]Notification, error)
- func (i *NotificationInbox) PendingMessages() ([]ParentMessage, error)
- type Observer
- type Outcome
- type OutputContract
- type OutputFormat
- type OutputValidator
- type Ownership
- type ParentMessage
- type ParentMessageKind
- type PlanResult
- type PlanStep
- type PrivateBinding
- type Request
- type Result
- type ResumeSource
- type ReviewFinding
- type ReviewResult
- type Role
- type Runner
- type RunnerResult
- type State
- type Summary
- type ToolActivity
- type ToolStatus
- type WakePort
- type WakeTarget
Constants ¶
const ( // AgentIdentitySchema identifies the durable, non-secret child identity // snapshot written by the Coding subagent protocol. AgentIdentitySchema = "pips.coding.subagent.identity/v1alpha1" // ExecutionPlanSchema identifies the immutable execution snapshot consumed // by Manager. A plan is compiled by Coding; a definition is never executed // directly by this package. ExecutionPlanSchema = "pips.coding.subagent.plan/v1alpha1" // MaxDelegationDepth is the product hard bound for recursive custom Agent // edges below a root child. MaxDelegationDepth = 3 // IsolationWorktree is the resolved plan isolation value that selects a // child-owned, preserved Git worktree. IsolationWorktree = "worktree" )
const ( // MaxMessageBytes bounds one message's UTF-8 text. MaxMessageBytes = 32 << 10 // MaxSenderAttemptOutbound bounds the messages one sender attempt may emit. MaxSenderAttemptOutbound = 32 // MaxSenderTargetInFlight bounds the messages from one sender attempt to one // target incarnation that the target has not consumed yet. MaxSenderTargetInFlight = 4 // MaxChildMessageAdmissions bounds the concurrent messages one child // retains. MaxChildMessageAdmissions = 8 // MaxMessageAdmissions bounds the concurrent messages of one execution // tree. MaxMessageAdmissions = 64 // DefaultMessageAdmissionTimeout bounds one live admission handshake. DefaultMessageAdmissionTimeout = 5 * time.Second // DefaultMessageFinalizationTimeout bounds the drain of a finalizing // child's unconsumed admissions before they are revoked. DefaultMessageFinalizationTimeout = 6 * time.Second // DefaultMessageSpawnReadyTimeout bounds a message parked for a child that // has a durable record but no live execution yet. DefaultMessageSpawnReadyTimeout = 120 * time.Second // ParentMessageTarget is the literal target that names a sender's direct // spawner instead of a child session id. ParentMessageTarget = "parent" // DirectAgentRunPrefix marks the synthetic run identity of a user-authored // direct Agent invocation. Such an invocation is not a delegation of the // conversation's own work, so it is never a message target. DirectAgentRunPrefix = "user-direct-" )
Bounds and timeouts of the child messaging surface. Every bound is a named constant so the refusal a caller sees names the limit that produced it.
const ( // ToolName is the stable main-agent delegation protocol name. ToolName = "spawn_subagent" // ResultSchema identifies the bounded foreground Tool result envelope. ResultSchema = "pips.coding.subagent.result/v1alpha1" // SpawnResultSchema identifies the immediate background admission result. SpawnResultSchema = "pips.coding.agent.spawn/v1alpha1" )
const ( // DefaultForegroundBudget bounds how long a foreground queued spawn waits // before it is handed off to the background. DefaultForegroundBudget = 10 * time.Minute )
const IsolationNone = "none"
IsolationNone is the caller spelling that selects the shared parent workspace. It normalizes to the empty plan value.
const ParentMessagePrefix = "bg-"
ParentMessagePrefix marks every generated parent message id. The prefix keeps the shared queue's id spaces disjoint, so an acknowledgement can tell a completion id from a message id.
const StopCauseNoProgress = "no_progress"
StopCauseNoProgress is the RunnerResult.StopCause a child runner reports when its own progress guard ended the run. The agent runtime can only report agent.StopWhen for it, so the Manager maps this to the no_progress code.
Variables ¶
var ( // ErrInvalid means configuration, request, or durable data is invalid. ErrInvalid = errors.New("coding subagent: invalid input") // ErrCapacity means the Runtime's concurrent child limit is exhausted. It // is the compatibility alias of ErrConcurrentLimit. ErrCapacity = ErrConcurrentLimit // ErrSpawnLimit means one root interaction exhausted its child budget. ErrSpawnLimit = errors.New("coding subagent: spawn limit exhausted") // ErrClosed means the manager no longer accepts executions. ErrClosed = errors.New("coding subagent: closed") // ErrInvalidResult means a specialist returned malformed or unsafe output. ErrInvalidResult = errors.New("coding subagent: invalid result") )
var ErrConcurrentLimit = errors.New("coding subagent: concurrent limit reached")
ErrConcurrentLimit means the concurrent child cap refused a spawn.
var ErrMessageClosed = errors.New("coding subagent: message channel is closed")
ErrMessageClosed reports that a child no longer accepts messages because its channel is closed.
var ErrMessageFinalizing = errors.New("coding subagent: child is finalizing")
ErrMessageFinalizing reports that a child is finishing and no longer accepts messages.
var ErrMessageSaturated = errors.New("coding subagent: child message admissions are saturated")
ErrMessageSaturated reports that one child already retains its maximum number of unconsumed messages.
var ErrMessageWakeUnsupported = errors.New("coding subagent: message wake is unsupported")
ErrMessageWakeUnsupported reports that a sender binding cannot start a wake.
var ErrQueueTimeout = errors.New("coding subagent: queue wait exceeded")
ErrQueueTimeout means a foreground spawn waited out its budget while queued.
Functions ¶
func BuiltinPrompt ¶ added in v0.1.9
BuiltinPrompt returns the rendered child prompt for one builtin agent type. When structured is true it asks for the typed JSON result contract that BuiltinResultSchema describes; general-purpose has no typed schema and keeps the plain-text contract.
func BuiltinResultSchema ¶ added in v0.1.9
func BuiltinResultSchema(id string) (json.RawMessage, bool)
BuiltinResultSchema returns the JSON Schema for one builtin agent's optional structured result contract. ok is false for a builtin without a typed schema, such as general-purpose.
func FormatResultText ¶ added in v0.1.9
FormatResultText renders the model-facing completion text for one child result. It is the one rendering a finished child's answer uses, so the spawn result and a read of the same child through the task-output Tool cannot drift. An interrupted child carries no resume pointer: reconciliation closed it, and the resume path refuses that state, so the line would name a call that cannot succeed.
func InstructionsDigest ¶
InstructionsDigest returns the durable digest used to prove a compiled execution plan still carries its exact rendered instruction text.
func IsDirectory ¶ added in v0.1.9
IsDirectory reports whether a sanitized path names an existing directory.
func IsNotSentinel ¶ added in v0.1.9
IsNotSentinel reports whether a caller-supplied optional string is a real value. The source treats "", "null", "none", "undefined", and blank as absent.
func IsParentMessageID ¶ added in v0.1.9
IsParentMessageID reports whether one queue id names a rendered parent message rather than a background child's completion.
func NormalizeIsolation ¶ added in v0.1.9
NormalizeIsolation validates a caller-supplied isolation spelling and returns the canonical plan value. ok is false for an unknown spelling. The empty value and "none" both select the shared parent workspace.
func Reconcile ¶
Reconcile repairs the current parent's bounded descendant tree from authoritative child Sessions, deepest first, and converts incomplete executions to interrupted.
func SanitizeCwd ¶ added in v0.1.9
SanitizeCwd cleans one model-emitted cwd argument. It trims whitespace, strips any surrounding quote or backtick characters whether or not they are matched, drops a sentinel placeholder, and expands one leading "~". The empty result means the argument is absent.
func ValidateCwdDirectory ¶ added in v0.1.9
ValidateCwdDirectory re-checks that one sanitized caller-supplied path is an existing directory and returns the caller-facing error text when it is not. The admission boundary and the child binding both apply it, so a directory that disappears between the two is still caught. It is skipped for a child that runs in a Worktree or that resumes a sibling.
func ValidateExecutionPlan ¶
func ValidateExecutionPlan(plan ExecutionPlan) error
ValidateExecutionPlan validates a non-legacy plan at the Coding composition boundary. Legacy snapshots remain readable through journal inspection but cannot be dispatched through this API.
func ValidateIdentity ¶
func ValidateIdentity(identity AgentIdentity) error
ValidateIdentity validates the bounded, non-secret identity contract.
func WorktreeIsolation ¶ added in v0.1.9
WorktreeIsolation reports whether one canonical isolation value selects a preserved child Worktree.
Types ¶
type Activity ¶
type Activity struct {
Revision uint64
Phase ActivityPhase
StartedAt time.Time
UpdatedAt time.Time
RunID string
Turn int
Tools []ToolActivity
}
Activity is an immutable point-in-time view of an active child execution. It is presentation state and is not persisted in the parent lifecycle.
type ActivityAction ¶
type ActivityAction string
ActivityAction is one sanitized semantic action suitable for parent UI projection. It deliberately excludes raw Tool arguments and results.
const ( // ActivityActionRead means the child is reading a workspace file. ActivityActionRead ActivityAction = "read" // ActivityActionSearch means the child is searching workspace text. ActivityActionSearch ActivityAction = "search" // ActivityActionGlob means the child is matching workspace paths. ActivityActionGlob ActivityAction = "glob" // ActivityActionList means the child is listing a workspace directory. ActivityActionList ActivityAction = "list" )
type ActivityPhase ¶
type ActivityPhase string
ActivityPhase describes the currently observable child execution phase.
const ( // ActivityPhaseUnknown means live phase data is unavailable. ActivityPhaseUnknown ActivityPhase = "" // ActivityPhaseStarting means the child run is being initialized. ActivityPhaseStarting ActivityPhase = "starting" // ActivityPhaseThinking means the child is between observable Tool calls. ActivityPhaseThinking ActivityPhase = "thinking" // ActivityPhaseWorking means the child is executing an observable Tool. ActivityPhaseWorking ActivityPhase = "working" // ActivityPhaseFinalizing means the child is validating its final result. ActivityPhaseFinalizing ActivityPhase = "finalizing" )
type ActivitySummary ¶
type ActivitySummary struct {
Action ActivityAction `json:"action"`
Target string `json:"target"`
}
ActivitySummary is a bounded, content-safe description of the child's latest observable action. Target is a workspace-relative path or pattern.
type AdmissionEvent ¶
type AdmissionEvent struct {
Outcome AdmissionOutcome
Reason AdmissionReason
Delivery Delivery
DelegationDepth int
}
AdmissionEvent is one content-free shared-budget decision. It deliberately excludes Agent, Session, run, Tool-call, task, and root-interaction identity.
type AdmissionObserver ¶
type AdmissionObserver func(context.Context, AdmissionEvent)
AdmissionObserver receives a synchronous, non-authoritative budget signal. Manager isolates observer panics and never lets observation change admission.
type AdmissionOutcome ¶
type AdmissionOutcome string
AdmissionOutcome is the bounded result of one shared-budget reservation.
const ( // AdmissionOutcomeAccepted means the request reserved an active slot. AdmissionOutcomeAccepted AdmissionOutcome = "accepted" // AdmissionOutcomeQueued means the request waited in arrival order for a slot. AdmissionOutcomeQueued AdmissionOutcome = "queued" // AdmissionOutcomeRejected means the shared budget refused the request. AdmissionOutcomeRejected AdmissionOutcome = "rejected" )
type AdmissionReason ¶
type AdmissionReason string
AdmissionReason is a low-cardinality classification.
const ( // AdmissionReasonCapacity means the concurrent tree limit was exhausted. AdmissionReasonCapacity AdmissionReason = "capacity" // AdmissionReasonQueueTimeout means a foreground spawn waited out its budget. AdmissionReasonQueueTimeout AdmissionReason = "queue_timeout" // AdmissionReasonSpawnLimit means the root cumulative limit was exhausted. AdmissionReasonSpawnLimit AdmissionReason = "spawn_limit" // AdmissionReasonClosed means the Manager no longer accepts work. AdmissionReasonClosed AdmissionReason = "closed" // AdmissionReasonInvalid means the reservation input was malformed. AdmissionReasonInvalid AdmissionReason = "invalid" )
type AgentEvent ¶
AgentEvent associates one raw child Agent event with its stable child Session and immutable ownership.
type AgentEventObserver ¶
type AgentEventObserver func(context.Context, AgentEvent) error
AgentEventObserver receives raw child events for ordinary Session-state projection. Returning an error cancels that child execution.
type AgentIdentity ¶
type AgentIdentity struct {
Schema string `json:"schema"`
ID string `json:"id"`
Kind AgentKind `json:"kind"`
Name string `json:"name"`
DefinitionSchema string `json:"definition_schema"`
DefinitionDigest string `json:"definition_digest"`
DefinitionSource string `json:"definition_source"`
}
AgentIdentity is the stable, non-secret identity of an execution. ID is canonical and must never be reconstructed from Name. Definition fields are a snapshot, so inspecting an old child does not depend on its source file still existing.
func BuiltinIdentity ¶
func BuiltinIdentity(role Role) (AgentIdentity, error)
BuiltinIdentity returns the registry-equivalent identity for one legacy specialist role.
func IdentityFromDefinition ¶
func IdentityFromDefinition(definition agentprofile.Definition) (AgentIdentity, error)
IdentityFromDefinition converts one validated registry definition into the durable identity used by a compiled execution plan.
func (AgentIdentity) IsZero ¶
func (i AgentIdentity) IsZero() bool
IsZero reports whether no identity was supplied. It exists only for legacy journal and event decoding; new execution admission never accepts it.
func (AgentIdentity) LegacyRole ¶
func (i AgentIdentity) LegacyRole() Role
LegacyRole returns the builtin role projection for this identity. Custom and ephemeral identities intentionally have no synthetic role.
type AgentKind ¶
type AgentKind string
AgentKind identifies the durable source class of one child agent.
const ( // AgentKindBuiltin identifies a program-owned compatibility agent. AgentKindBuiltin AgentKind = "builtin" // AgentKindCustom identifies a loaded user or trusted-project definition. AgentKindCustom AgentKind = "custom" // AgentKindEphemeral identifies an explicit, non-persisted one-shot // definition. AgentKindEphemeral AgentKind = "ephemeral" )
type Config ¶
type Config struct {
Context context.Context
Repository *session.Repository
Parent *session.Handle
Tree *workspace.Tree
Model ai.LanguageModel
// GenerationID identifies the immutable Coding integration snapshot that
// compiled this manager's builtin execution plan. Custom dispatch will
// acquire a per-child generation lease in the next slice.
GenerationID uint64
SummaryModel ai.LanguageModel
Compaction *harness.CompactionSettings
// FullCompaction selects full checkpoints with child-owned history. When
// non-nil it takes precedence over legacy Compaction and SummaryModel.
// Summary requests use Model and RequestPolicy without the builtin child's
// final-output schema. Custom dispatcher runners own their own integration.
FullCompaction *compaction.Policy
RequestPolicy func(*ai.Request)
// StructuredResults restores the typed JSON result contract for builtin
// agents. The default is a free-text summary.
StructuredResults bool
Lifecycle Lifecycle
Options ExecutionOptions
AgentObservers []func(context.Context, agent.Event)
EventObservers []AgentEventObserver
// AdmissionObserver receives content-free shared-budget decisions. It is
// observational only and cannot veto or alter a reservation.
AdmissionObserver AdmissionObserver
// ActiveMessages opens the child messaging surface. A nil value keeps the
// gate closed: no messaging Tool is offered, and every delivery is refused
// rather than dropped. Its ports carry the Runtime-owned deliveries the
// coordinator cannot build itself.
ActiveMessages *MessagePorts
// required when Parent is a subagent Session.
Share *Manager
// DelegationDepth is the depth expected for children created by this
// manager. Root conversation Managers use zero.
DelegationDepth int
}
Config contains the application-owned dependencies for one parent Session.
type Delivery ¶
type Delivery string
Delivery selects whether the parent Tool waits for the child or returns immediately while the Runtime retains execution ownership.
type Detail ¶
type Detail struct {
Summary Summary
Plan ExecutionPlan
Transcript []ai.Message
Activity Activity
Result any
}
Detail extends Summary with durable replay data and optional live activity.
type DispatchInput ¶
type DispatchInput struct {
Plan ExecutionPlan
Request Request
Child *session.Handle
Observer Observer
OnEvent func(context.Context, agent.Event)
SystemSuffix string
Resume *ResumeSource
// Directory is the child's effective working directory when it differs
// from the parent workspace. An empty value means the child shares the
// parent workspace.
Directory string
// WorktreePath is the preserved Worktree the child runs in. It is set only
// alongside Directory and only when that directory is a Worktree.
WorktreePath string
}
DispatchInput is the bounded, application-owned input for a child runtime binding. The Session belongs solely to this child execution. SystemSuffix is the trusted lifecycle-hook context rendered into the child's system prompt. Resume is present only for a child that forked a completed sibling, and it carries that source's inherited working directory and preserved worktree.
type Dispatcher ¶
type Dispatcher interface {
// AgentIDs returns the bounded model-visible custom IDs captured for this
// Tool declaration. It is advisory schema metadata only; Compile remains
// the authorization boundary.
AgentIDs() []string
// Compile validates the request against the caller-visible immutable
// registry and returns a complete, non-legacy execution plan.
Compile(context.Context, Request) (ExecutionPlan, error)
// Open creates the child-owned runtime binding after the durable child
// Session exists. It must not retain a parent-bound controller, Tool, or
// interaction context.
Open(context.Context, DispatchInput) (Runner, error)
}
Dispatcher compiles and opens a non-builtin child execution. It is supplied by the Coding composition root for one parent interaction, never by a profile file or a generic caller. Compile must only narrow the ambient capability snapshot captured for that interaction.
Builtin compatibility agents intentionally bypass Dispatcher and retain their existing typed execution path.
type EffectiveCapability ¶
type EffectiveCapability struct {
WireName string `json:"wire_name"`
Source string `json:"source"`
Risk string `json:"risk"`
}
EffectiveCapability is one exact, runtime-owned Tool descriptor frozen into an execution plan. It is descriptive only; invoking the capability still requires a child-scoped factory and every normal execution-time policy gate.
type Event ¶
type Event struct {
Progress bool
State State
Identity AgentIdentity
Role Role
ChildSessionID string
ParentSessionID string
ParentInteractionID string
ParentRunID string
ParentToolCallID string
RootInteractionID string
Delivery Delivery
// Wake marks a continuation a message woke from a completed child. The
// sender already holds the acceptance reply, so a wake's terminal state is
// not surfaced as a second completion.
Wake bool
// Inherited reports that this child continues another child's conversation,
// so its own session already owns the turns that came before this run. It is
// lifecycle metadata, never content: the projection reads the history from the
// child's own session when it opens.
Inherited bool
ChildRunID string
Model string
TaskPreview string
Activity ActivitySummary
Code string
Stop agent.StopReason
Turns int
ToolCalls int
Usage ai.Usage
Duration time.Duration
Time time.Time
// Result is present only on an in-process terminal callback. It is never
// copied into the parent lifecycle event or telemetry projection.
Result *Result
}
Event is one content-bounded child lifecycle update.
type Evidence ¶
type Evidence struct {
Path string `json:"path"`
StartLine int `json:"start_line"`
EndLine int `json:"end_line"`
Claim string `json:"claim"`
}
Evidence ties one Explore claim to an observed workspace range.
type Execution ¶
type Execution struct {
// contains filtered or unexported fields
}
Execution is one cancelable, waitable child lifetime. It intentionally does not retain a context.Context.
type ExecutionOptions ¶
type ExecutionOptions struct {
Limits Limits
MaxDepth int
MaxConcurrent int
// MaxSpawnedPerRootInteraction bounds how many children one root
// interaction may spawn in total. Zero is unlimited, matching the
// reference, which bounds only concurrency.
MaxSpawnedPerRootInteraction int
// MaxAutoFollowUps bounds how many notification batches one root may
// receive. Zero is unlimited, matching the reference's count-free
// auto-wake switch.
MaxAutoFollowUps int
// LimitBehavior selects queue or fail at the concurrent cap. The empty
// value selects queue.
LimitBehavior LimitBehavior
// ForegroundBudget bounds a foreground queued wait before the caller is
// handed off to the background. Zero selects DefaultForegroundBudget.
ForegroundBudget time.Duration
}
ExecutionOptions provides embedder/test overrides without adding a user configuration protocol in P1. A zero Limits value selects DefaultLimits.
type ExecutionPlan ¶
type ExecutionPlan struct {
Schema string `json:"schema"`
Identity AgentIdentity `json:"identity"`
GenerationID uint64 `json:"generation_id,omitempty"`
Delivery Delivery `json:"delivery"`
Model string `json:"model"`
Instructions string `json:"instructions"`
InstructionsDigest string `json:"instructions_digest"`
// Persona is the resolved persona name applied to this child. It is empty
// when the agent type has no persona.
Persona string `json:"persona,omitempty"`
// PersonaReminder is the exact synthetic user-item body injected before the
// task prompt. It is persisted with the child transcript, and it is not
// re-inserted when the transcript already carries it.
PersonaReminder string `json:"persona_reminder,omitempty"`
// ReasoningEffort is the resolved portable reasoning level. It is empty
// when neither the role nor the persona declares one.
ReasoningEffort string `json:"reasoning_effort,omitempty"`
// Isolation is the resolved child execution environment. It is empty when
// the child shares the parent workspace and "worktree" when the child owns
// a preserved Git worktree.
Isolation string `json:"isolation,omitempty"`
// Cwd is the sanitized caller-supplied child working directory. It is
// empty when the child inherits the parent workspace, when isolation
// selects a worktree, and whenever the child resumes a sibling.
Cwd string `json:"cwd,omitempty"`
// ResumeFrom names the completed sibling child whose transcript, tool
// state, and usage this execution inherits.
ResumeFrom string `json:"resume_from,omitempty"`
Capabilities []EffectiveCapability `json:"capabilities"`
Skills []string `json:"skills"`
PreloadedSkills []string `json:"preloaded_skills"`
ToolSearch bool `json:"tool_search,omitempty"`
DelegationDepth int `json:"delegation_depth,omitempty"`
MaxDelegationDepth int `json:"max_delegation_depth,omitempty"`
Ancestry []string `json:"ancestry,omitempty"`
DelegationTargets []string `json:"delegation_targets,omitempty"`
PrivateMCP []PrivateBinding `json:"private_mcp,omitempty"`
PrivateHooks []PrivateBinding `json:"private_hooks,omitempty"`
Limits Limits `json:"limits"`
Output OutputContract `json:"output"`
// Legacy records did not carry an execution snapshot. It is set only while
// normalizing those durable records for read-only inspection; dispatch must
// never admit a legacy plan.
Legacy bool `json:"legacy,omitempty"`
}
ExecutionPlan is the immutable, auditable input accepted by subagent execution. It records the authority intersection computed by Coding, not merely the agent definition's requested capabilities.
func (ExecutionPlan) Clone ¶
func (p ExecutionPlan) Clone() ExecutionPlan
Clone returns a detached execution-plan snapshot.
func (ExecutionPlan) Digest ¶
func (p ExecutionPlan) Digest() (string, error)
Digest returns the SHA-256 digest of the canonical JSON plan payload.
type ExploreResult ¶
type ExploreResult struct {
Summary string `json:"summary"`
Evidence []Evidence `json:"evidence"`
Unknowns []string `json:"unknowns"`
}
ExploreResult is the structured output of the Explore specialist.
type Lifecycle ¶
type Lifecycle struct {
BeforeStart func(context.Context, LifecycleStart) string
BeforeStop func(context.Context, LifecycleStop) LifecycleStopDecision
}
Lifecycle provides Runtime-owned child lifecycle callbacks. Manager only transports bounded context and continuation requests; it neither discovers nor executes user hook configuration.
type LifecycleStart ¶
type LifecycleStart struct {
ChildSessionID string
Identity AgentIdentity
Role Role
Task string
Ownership Ownership
}
LifecycleStart describes a child after its durable session exists and before its harness begins its first run.
type LifecycleStop ¶
type LifecycleStop struct {
ChildSessionID string
Identity AgentIdentity
Role Role
Ownership Ownership
StopHookActive bool
LastAssistantMessage string
}
LifecycleStop describes one clean child-agent stop before Manager commits its terminal child record.
type LifecycleStopDecision ¶
LifecycleStopDecision asks Manager to issue one follow-up prompt to the already-open child harness. A false Continue leaves the child terminal.
type LimitBehavior ¶ added in v0.1.9
type LimitBehavior string
LimitBehavior selects what happens when the concurrent child cap is reached.
const ( // LimitBehaviorQueue parks a spawn in arrival order until a slot frees. LimitBehaviorQueue LimitBehavior = "queue" // LimitBehaviorFail rejects a spawn at the cap. LimitBehaviorFail LimitBehavior = "fail" )
func ParseLimitBehavior ¶ added in v0.1.9
func ParseLimitBehavior(value string) LimitBehavior
ParseLimitBehavior normalizes a configured behavior. An empty or unknown value selects queue, matching the source default.
type Limits ¶
type Limits struct {
MaxTurns int
FinalizationTurns int
// The repeat guard has two tiers, matching the reference. A run whose
// every call is read risk is nudged at RepeatedProblematicToolCallLimit
// and hard-stopped at RepeatedProblematicToolCallStopLimit; any other
// identical run uses the looser RepeatedToolCallLimit and
// RepeatedToolCallStopLimit.
RepeatedToolCallLimit int
RepeatedProblematicToolCallLimit int
RepeatedToolCallStopLimit int
RepeatedProblematicToolCallStopLimit int
MaxTokens int
MaxToolCalls int
MaxDuration time.Duration
MaxActivityTools int
MaxOutputTokens int
MaxTaskBytes int
MaxResultBytes int
MaxResultItems int
MaxFieldBytes int
}
Limits bounds one child execution and its persisted projections.
func DefaultLimits ¶
func DefaultLimits() Limits
DefaultLimits is the child execution policy: total turns, cumulative tokens, tool calls, and wall time are unlimited, while payloads and live projections remain bounded independently. The payload bounds are the hard ceilings validateBoundedLimits enforces, so a long child report is accepted; an embedder may still lower them. A caller may narrow any execution field explicitly too: the reference has no per-child execution budget either.
func NormalizeLimits ¶
NormalizeLimits applies the stable inherited defaults used by a compiled execution plan. It returns a value copy and grants no additional authority.
type Manager ¶
type Manager struct {
// contains filtered or unexported fields
}
Manager owns a bounded set of live child executions and all of their cleanup. Each admitted child runs until natural completion, cancellation, an explicit positive execution limit, or a structural safety policy stops it.
func New ¶
New constructs a current-parent child manager. Call Reconcile before New so interrupted child journals are repaired before the manager accepts work.
func (*Manager) Cancel ¶
Cancel cancels one running child. Repeating cancellation, including after the child is terminal, is safe.
func (*Manager) CancelRoot ¶
CancelRoot cancels every running background child created by one root interaction and returns the number of cancellation requests issued.
func (*Manager) Close ¶
Close stops admission, cancels every child, and waits for terminal persistence before returning.
func (*Manager) Inspect ¶
Inspect loads one current-parent child transcript and validated structured result. Arbitrary session IDs outside the current parent are rejected.
func (*Manager) List ¶
List returns newest-first durable descendants owned by this manager's execution tree.
func (*Manager) MaxAutoFollowUps ¶
MaxAutoFollowUps returns the validated Runtime coordination bound. Zero is unlimited, matching the reference's count-free auto-wake switch.
func (*Manager) MessageCoordinator ¶ added in v0.1.9
func (m *Manager) MessageCoordinator() *MessageCoordinator
MessageCoordinator returns this manager's child messaging coordinator, or nil while the messaging gate is closed.
func (*Manager) SpawnToolFor ¶
SpawnToolFor returns the concurrency-safe delegation Tool bound to one parent interaction. Completion is delivered by the Runtime rather than through model polling.
func (*Manager) SpawnToolForDispatcher ¶
func (m *Manager) SpawnToolForDispatcher( owner Ownership, observer Observer, dispatcher Dispatcher, ) agent.Tool
SpawnToolForDispatcher is the single delegation adapter for an interaction-scoped dispatcher.
func (*Manager) Start ¶
func (m *Manager) Start( ctx context.Context, request Request, observer Observer, ) (*Execution, error)
Start reserves one execution slot and starts one owned goroutine.
func (*Manager) StartWithDispatcher ¶
func (m *Manager) StartWithDispatcher( ctx context.Context, request Request, observer Observer, dispatcher Dispatcher, ) (*Execution, error)
StartWithDispatcher admits either a builtin compatibility request or a Runtime-compiled custom execution. Dispatcher is interaction-scoped: it owns registry visibility and the child-specific control binding, while this Manager retains quotas, durable lineage, lifecycle, and terminal cleanup.
type MessageBinding ¶ added in v0.1.9
type MessageBinding struct {
Identity MessageSenderIdentity
// contains filtered or unexported fields
}
MessageBinding is one Tool declaration's immutable sender state: the identity every call sends as, the attempt's outbound budget, and the wake port a wake needs. It is created once per Tool declaration, so the outbound cap covers exactly one sender attempt.
func NewMessageBinding ¶ added in v0.1.9
func NewMessageBinding(identity MessageSenderIdentity, wake WakePort) *MessageBinding
NewMessageBinding returns the sender state for one Tool declaration. A nil wake port makes every wake unsupported rather than silently dropped.
func (*MessageBinding) Sender ¶ added in v0.1.9
func (b *MessageBinding) Sender(call MessageCall) MessageSender
Sender returns the binding attributed to one Tool call. A nil binding yields no sender, so an unbound Tool can never deliver anything.
type MessageCall ¶ added in v0.1.9
type MessageCall struct {
// RunID is the parent Run the call belongs to.
RunID string
// ID is the Tool call's own identity.
ID string
}
MessageCall identifies one Tool call of one parent Run.
type MessageCoordinator ¶ added in v0.1.9
type MessageCoordinator struct {
// contains filtered or unexported fields
}
MessageCoordinator owns the process-local delivery state of one execution tree: who is sending, to which target incarnation, and how much is already in flight. It is never persisted, and it holds no child lifecycle record of its own.
func (*MessageCoordinator) Send ¶ added in v0.1.9
func (c *MessageCoordinator) Send( ctx context.Context, sender MessageSender, targetID string, text string, delivery MessageDelivery, ) (MessageOutcome, error)
Send resolves one target, applies the sender's outbound cap, and routes the delivery.
type MessageDelivery ¶ added in v0.1.9
type MessageDelivery string
MessageDelivery selects how a message reaches its target.
const ( // MessageDeliverySteer joins the target's run at its next turn boundary. // It is the default. MessageDeliverySteer MessageDelivery = "steer" // MessageDeliveryQueue waits for a later turn of the target. MessageDeliveryQueue MessageDelivery = "queue" // MessageDeliveryInterject is a steer that arrives ahead of any message // already queued to steer. MessageDeliveryInterject MessageDelivery = "interject" )
func ParseMessageDelivery ¶ added in v0.1.9
func ParseMessageDelivery(value string) (MessageDelivery, bool)
ParseMessageDelivery accepts the three delivery verbs.
type MessageDisposition ¶ added in v0.1.9
type MessageDisposition string
MessageDisposition classifies an outcome without collapsing uncertainty into failure.
const ( // MessageDispositionAccepted means admission was confirmed. MessageDispositionAccepted MessageDisposition = "accepted" // MessageDispositionRejected means admission was definitely refused. MessageDispositionRejected MessageDisposition = "rejected" // MessageDispositionUnconfirmed means admission could not be confirmed. MessageDispositionUnconfirmed MessageDisposition = "unconfirmed" )
type MessageOutcome ¶ added in v0.1.9
type MessageOutcome struct {
Kind MessageOutcomeKind
MessageID string
MaxInFlight int
Quota MessageQuotaKind
Limit int
MaxBytes int
ObservedBytes int
}
MessageOutcome is the bounded result of one delivery attempt. It is a protocol value rather than an error: Text renders its model-facing description, and an unset outcome reads as a rejection.
func (MessageOutcome) Accepted ¶ added in v0.1.9
func (o MessageOutcome) Accepted() bool
Accepted reports whether the target took ownership of the message.
func (MessageOutcome) Disposition ¶ added in v0.1.9
func (o MessageOutcome) Disposition() MessageDisposition
Disposition classifies the outcome without collapsing uncertainty.
func (MessageOutcome) Text ¶ added in v0.1.9
func (o MessageOutcome) Text() string
Text renders the bounded model-facing description of one outcome.
type MessageOutcomeKind ¶ added in v0.1.9
type MessageOutcomeKind string
MessageOutcomeKind is the closed result vocabulary of one delivery attempt.
const ( // MessageOutcomeAccepted means the target took ownership of the message. MessageOutcomeAccepted MessageOutcomeKind = "accepted" // MessageOutcomeNotFoundOrNotOwned means the target is unknown, outside // this tree, self-referential, or not a delegable child. MessageOutcomeNotFoundOrNotOwned MessageOutcomeKind = "not_found_or_not_owned" // MessageOutcomeNotActiveOrFinalizing means the target cannot take a // message in its current state. MessageOutcomeNotActiveOrFinalizing MessageOutcomeKind = "not_active_or_finalizing" // MessageOutcomeSaturated means a concurrent-admission bound refused it. MessageOutcomeSaturated MessageOutcomeKind = "saturated" // MessageOutcomeQuotaExceeded means a sender-scoped quota refused it. MessageOutcomeQuotaExceeded MessageOutcomeKind = "quota_exceeded" // MessageOutcomeAdmissionUncertain means the admission handshake did not // resolve, so the message may or may not have been accepted. MessageOutcomeAdmissionUncertain MessageOutcomeKind = "admission_uncertain" // MessageOutcomeNotAcceptedBeforeDeadline means a waiting delivery did not // resolve before its deadline. MessageOutcomeNotAcceptedBeforeDeadline MessageOutcomeKind = "not_accepted_before_deadline" // MessageOutcomeUnsupported means this context cannot deliver messages. MessageOutcomeUnsupported MessageOutcomeKind = "unsupported" // MessageOutcomeLimit means the text was empty or exceeded the byte bound. MessageOutcomeLimit MessageOutcomeKind = "limit" // MessageOutcomeChannelClosed means the target's channel closed first. MessageOutcomeChannelClosed MessageOutcomeKind = "channel_closed" )
type MessagePorts ¶ added in v0.1.9
type MessagePorts struct {
// DeliverParent routes one message to the root conversation that owns this
// execution tree.
DeliverParent func(ctx context.Context, delivery MessageDelivery, text string) error
}
MessagePorts carries the Runtime-scoped ports the coordinator cannot build itself. A nil port refuses its deliveries with unsupported rather than dropping them.
type MessageQuotaKind ¶ added in v0.1.9
type MessageQuotaKind string
MessageQuotaKind names the sender-scoped quota that refused a message.
const ( // MessageQuotaAttemptOutbound is one sender attempt's outbound cap. MessageQuotaAttemptOutbound MessageQuotaKind = "attempt_outbound" // MessageQuotaSenderTargetInFlight is one sender-to-target in-flight cap. MessageQuotaSenderTargetInFlight MessageQuotaKind = "sender_target_in_flight" )
type MessageSender ¶ added in v0.1.9
type MessageSender interface {
Sender() MessageSenderIdentity
// AdmitOutbound reserves one message against this attempt's outbound cap.
// It reports false once the cap is spent.
AdmitOutbound() bool
// wakeTarget starts the continuation of one completed child with task as
// its prompt. It returns ErrMessageWakeUnsupported when this binding cannot
// start a wake.
WakeTarget(ctx context.Context, target WakeTarget) error
}
MessageSender is the binding a messaging Tool sends through. Wake needs the sender's own dispatcher, which the coordinator cannot construct, so the binding starts the wake execution itself.
type MessageSenderIdentity ¶ added in v0.1.9
type MessageSenderIdentity struct {
// SessionID is the sender's own durable session.
SessionID string
// AttemptID identifies the sender's attempt. It namespaces every
// sender-scoped quota, so a new attempt starts with a clean budget.
AttemptID string
// Child reports a message-capable child of this tree. The zero value is the
// root conversation that owns the tree.
Child bool
// Ownership is the child's own durable ownership. It is empty for a root.
Ownership Ownership
// AgentID is the child's own agent identity. It is empty for a root.
AgentID string
}
MessageSenderIdentity is the immutable identity one messaging Tool sends as.
type MessageSink ¶ added in v0.1.9
type MessageSink interface {
AdmitMessage(
ctx context.Context,
delivery MessageDelivery,
messageID string,
text string,
onRelease func(),
) error
}
MessageSink accepts one admitted message for a live child. AdmitMessage returns once the child owns the message. onRelease runs exactly once, when the message leaves the child's pending set.
type Notification ¶
type Notification struct {
ID string `json:"id"`
AgentID string `json:"agent_id"`
Ownership Ownership `json:"ownership"`
Identity AgentIdentity `json:"identity,omitzero"`
Role Role `json:"role"`
Outcome Outcome `json:"outcome"`
Code string `json:"code"`
TaskPreview string `json:"task_preview,omitempty"`
Result ai.JSON `json:"result,omitempty"`
Usage ai.Usage `json:"usage"`
TerminalAt time.Time `json:"terminal_at"`
}
Notification is one bounded background-child completion waiting to be injected into its owning parent conversation.
type NotificationInbox ¶
type NotificationInbox struct {
// contains filtered or unexported fields
}
NotificationInbox is the one durable parent-owned pending queue. It persists delivery state in the parent Harness Session and is safe for concurrent terminal callbacks and Runtime coordination. Two record kinds ride it: a background child's completion, and a rendered parent message (a background watch's events or its completion). Both claim and acknowledge the same way, so a later child-to-idle-parent message adds a kind rather than a queue.
func NewNotificationInbox ¶
func NewNotificationInbox( parent *harness.Session, parentSessionID string, maxResultBytes int, ) (*NotificationInbox, error)
NewNotificationInbox constructs the parent-owned durable pending queue.
func (*NotificationInbox) Acknowledge ¶
func (i *NotificationInbox) Acknowledge(ids ...string) error
Acknowledge marks known pending records delivered, whichever kind they are. It is idempotent.
func (*NotificationInbox) Contains ¶
func (i *NotificationInbox) Contains(id string) (bool, error)
Contains reports whether a pending or delivered record already exists for the id, whichever kind carries it. The two id spaces are disjoint.
func (*NotificationInbox) Enqueue ¶
func (i *NotificationInbox) Enqueue(value Notification) error
Enqueue appends a pending record unless the exact completion is already known. A delivered notification remains delivered.
func (*NotificationInbox) EnqueueCompletion ¶
func (i *NotificationInbox) EnqueueCompletion(event Event) error
EnqueueCompletion durably records one background terminal result. Repeated callbacks for the same child are idempotent only when the payload matches.
func (*NotificationInbox) EnqueueMessage ¶ added in v0.1.9
func (i *NotificationInbox) EnqueueMessage(value ParentMessage) error
EnqueueMessage appends one rendered parent message to the shared queue. It is idempotent for the same payload: a record that was already queued is left alone, and one that was already delivered stays delivered.
func (*NotificationInbox) EnqueueRecovered ¶
func (i *NotificationInbox) EnqueueRecovered(summary Summary, result any) error
EnqueueRecovered repairs the crash window between a durable child terminal record and creation of its parent completion notification.
func (*NotificationInbox) Pending ¶
func (i *NotificationInbox) Pending() ([]Notification, error)
Pending returns terminal-time ordered undelivered notifications.
func (*NotificationInbox) PendingMessages ¶ added in v0.1.9
func (i *NotificationInbox) PendingMessages() ([]ParentMessage, error)
PendingMessages returns arrival-ordered undelivered parent messages.
type Observer ¶
Observer synchronously receives child lifecycle events. Implementations must return quickly, must not retain mutable input references, and return an error when the parent event stream can no longer accept the lifecycle.
type Outcome ¶
type Outcome string
Outcome is the durable terminal classification of an execution.
const ( // OutcomeSucceeded means a validated result was committed. OutcomeSucceeded Outcome = "succeeded" // OutcomeFailed means execution ended without a usable result. OutcomeFailed Outcome = "failed" // OutcomeCanceled means cancellation or a deadline stopped execution. OutcomeCanceled Outcome = "canceled" // OutcomeInterrupted means restart reconciliation found no terminal record. OutcomeInterrupted Outcome = "interrupted" )
type OutputContract ¶
type OutputContract struct {
Format OutputFormat `json:"format"`
Name string `json:"name"`
Schema json.RawMessage `json:"schema,omitempty"`
Digest string `json:"digest"`
}
OutputContract is a frozen output-validation contract. Schema is canonical JSON for JSON Schema and builtin adapters, and is copied on every boundary.
func NewOutputContract ¶
func NewOutputContract( format OutputFormat, name string, schema json.RawMessage, ) (OutputContract, error)
NewOutputContract freezes one custom output contract and computes its durable digest. Schema is copied so callers cannot mutate a compiled plan through a retained YAML/JSON slice.
func (OutputContract) Clone ¶
func (c OutputContract) Clone() OutputContract
Clone returns a detached output contract.
type OutputFormat ¶
type OutputFormat string
OutputFormat identifies the local final-result contract selected by a compiled plan.
const ( // OutputFormatBuiltin delegates validation to one of the existing typed // builtin result adapters. OutputFormatBuiltin OutputFormat = "builtin" // OutputFormatText accepts a bounded UTF-8 text final answer. OutputFormatText OutputFormat = "text" // OutputFormatJSONSchema requires a locally validated JSON Schema result. OutputFormatJSONSchema OutputFormat = "json_schema" )
type OutputValidator ¶
OutputValidator validates one final custom-Agent response against the immutable contract captured in its execution plan.
func NewOutputValidator ¶
func NewOutputValidator(contract OutputContract, limits Limits) (_ OutputValidator, returnErr error)
NewOutputValidator compiles a local output validator. JSON Schema resolution receives no external loader, so a profile can never make result validation fetch an external reference.
type Ownership ¶
type Ownership struct {
ParentSessionID string
ParentInteractionID string
ParentRunID string
ParentToolCallID string
RootInteractionID string
}
Ownership is the immutable parent location of one child execution.
type ParentMessage ¶ added in v0.1.9
type ParentMessage struct {
ID string `json:"id"`
Ownership Ownership `json:"ownership"`
Kind ParentMessageKind `json:"kind"`
TaskID string `json:"task_id,omitempty"`
Body string `json:"body"`
At time.Time `json:"at"`
}
ParentMessage is one rendered, parent-owned message waiting to be delivered to its conversation. It is the generic record of the shared durable pending queue, alongside the agent-completion record.
type ParentMessageKind ¶ added in v0.1.9
type ParentMessageKind string
ParentMessageKind classifies one rendered parent-owned message. A later child-to-idle-parent message adds a kind here instead of a second queue.
const ( // MessageKindBackgroundEvents carries one rendered batch of background events. MessageKindBackgroundEvents ParentMessageKind = "background_events" // MessageKindBackgroundCompletion carries one rendered completion. MessageKindBackgroundCompletion ParentMessageKind = "background_completion" )
Supported parent message kinds.
type PlanResult ¶
type PlanResult struct {
Summary string `json:"summary"`
Assumptions []string `json:"assumptions"`
Steps []PlanStep `json:"steps"`
Risks []string `json:"risks"`
Verification []string `json:"verification"`
}
PlanResult is the structured output of the Plan specialist.
type PlanStep ¶
type PlanStep struct {
Title string `json:"title"`
Files []string `json:"files"`
Rationale string `json:"rationale"`
}
PlanStep is one implementation step in a Plan result.
type PrivateBinding ¶
PrivateBinding freezes one Agent-private executable resource selected from the immutable Coding integration generation.
type Request ¶
type Request struct {
AgentID string
Role Role
Task string
// Model is the model the caller explicitly requested for the child. It is
// the first tier of the child model precedence chain; empty means unset.
Model string
// Isolation is the caller-selected execution environment: empty, "none",
// or "worktree". A role or persona default fills it in when it does not
// already request a worktree.
Isolation string
// Cwd is the sanitized caller-supplied child working directory. It is
// dropped when the child resumes a sibling.
Cwd string
// ResumeFrom names the completed sibling child whose transcript, tool
// state, and usage this execution inherits. It overrides AgentID and Model
// with the source's frozen values.
ResumeFrom string
// WakeOf names the completed child a message woke. A wake continues the
// source in the background with the message as its prompt; it is a distinct
// request from ResumeFrom, which a caller declares for a new named child.
WakeOf string
Ownership Ownership
Delivery Delivery
}
Request is the compatibility admission shape for one builtin specialist delegation. AgentID is the primary selector; Role remains a temporary wire alias for explore, plan, and review. Custom definitions are admitted only through a Runtime-compiled ExecutionPlan.
type Result ¶
type Result struct {
Identity AgentIdentity
Role Role
ChildSessionID string
ChildRunID string
// Persona is the resolved persona name applied to the child, or empty when
// the agent type has none.
Persona string
// WorktreePath is the preserved worktree the child ran in, or empty when
// the child ran in the parent workspace.
WorktreePath string
Outcome Outcome
Code string
Stop agent.StopReason
Turns int
ToolCalls int
Usage ai.Usage
Duration time.Duration
// Structured reports that Value is a typed structured result rather than
// the default free-text summary. It selects the clone decoder so a text
// result is never re-decoded into a role's typed shape.
Structured bool
Value any
}
Result is the terminal execution result returned to the parent Tool.
func ResultFromDetail ¶ added in v0.1.9
ResultFromDetail projects one inspected child into the result the spawn Tool and the task-output Tool both render. The persisted plan decides whether the value is structured, so a legacy builtin plan keeps its own shape.
type ResumeSource ¶ added in v0.1.9
type ResumeSource struct {
// ChildSessionID is the source child's durable Session. The resumed child
// forks this Session's transcript.
ChildSessionID string
// AgentID is the source's resolved agent type. It replaces the caller's
// requested type, because the inherited transcript only makes sense under
// the definition that produced it.
AgentID string
// Model is the source's frozen model. A caller model override is ignored
// while resuming.
Model string
// Cwd is the source's effective working directory, empty when it ran in
// the shared workspace or in a worktree.
Cwd string
// WorktreePath is the source's preserved worktree, empty when it had none.
WorktreePath string
// Usage is the source's terminal token usage. It is added to the reported
// usage of the resumed child so its budget and report stay cumulative.
Usage ai.Usage
}
ResumeSource is the validated, frozen description of the completed sibling child a resumed execution inherits from. It is resolved from the durable child Session, never from a caller-supplied summary.
func (ResumeSource) Zero ¶ added in v0.1.9
func (s ResumeSource) Zero() bool
Zero reports whether no source was resolved.
type ReviewFinding ¶
type ReviewFinding struct {
Severity string `json:"severity"`
Title string `json:"title"`
Path string `json:"path"`
Line int `json:"line"`
Evidence string `json:"evidence"`
Recommendation string `json:"recommendation"`
}
ReviewFinding is one evidence-backed Review issue.
type ReviewResult ¶
type ReviewResult struct {
Summary string `json:"summary"`
Findings []ReviewFinding `json:"findings"`
ResidualRisks []string `json:"residual_risks"`
}
ReviewResult is the structured output of the Review specialist.
type Role ¶
type Role string
Role selects one isolated read-only specialist behavior and output schema.
type Runner ¶
type Runner interface {
Run(context.Context, string) (RunnerResult, error)
// Close releases the child control scope after Manager durably persists its
// terminal record. It must be idempotent and safe after a failed Run.
Close(context.Context) error
}
Runner owns the child-specific execution/control scope for one compiled custom plan. Run returns only after terminal output validation; a paused approval or question remains internal to the runner until its child-owned resolver is resumed by Coding.
type RunnerResult ¶
type RunnerResult struct {
Run *agent.RunResult
Value any
Text string
ToolCalls int
Cwd string
WorktreePath string
StopCause string
}
RunnerResult is the validated terminal output returned by a child-owned Runner. Run is retained for standard stop/usage accounting; Value and Text have already passed the exact frozen output contract. Cwd and WorktreePath are the effective child directory the binding resolved, and WorktreePath is empty when the child ran in the parent workspace. StopCause is empty for every ordinary terminal run.
type State ¶
type State string
State is the durable lifecycle state of an execution.
const ( // StateCreated means durable child ownership has been established. StateCreated State = "created" // StateRunning means the child Agent run has started. StateRunning State = "running" // StateSucceeded means the child returned a validated result. StateSucceeded State = "succeeded" // StateFailed means the child ended without a usable result. StateFailed State = "failed" // StateCanceled means cancellation or a deadline stopped the child. StateCanceled State = "canceled" // StateInterrupted means reconciliation closed an orphan execution. StateInterrupted State = "interrupted" )
type Summary ¶
type Summary struct {
ChildSessionID string
Ownership Ownership
Delivery Delivery
// Wake reports that this child continues a completed sibling a message
// woke, so its terminal result is not surfaced as a completion.
Wake bool
Identity AgentIdentity
Role Role
State State
TaskPreview string
Model string
// Cwd is the child's effective working directory, empty when it shares the
// parent workspace.
Cwd string
// WorktreePath is the child's preserved worktree, empty when it has none.
WorktreePath string
CreatedAt time.Time
Duration time.Duration
Turns int
ToolCalls int
Usage ai.Usage
Code string
}
Summary is the durable current-parent list projection.
type ToolActivity ¶
type ToolActivity struct {
RunID string
Turn int
Call ai.ToolCallPart
Status ToolStatus
Update []ai.Part
Result ai.ToolResultPart
}
ToolActivity is one ordered, bounded child Tool observation.
type ToolStatus ¶
type ToolStatus string
ToolStatus is the observable lifecycle of one child Tool call.
const ( // ToolStatusUnknown means Tool lifecycle data is unavailable. ToolStatusUnknown ToolStatus = "" // ToolStatusRunning means the Tool has started but has not completed. ToolStatusRunning ToolStatus = "running" // ToolStatusCompleted means the Tool has produced its terminal result. ToolStatusCompleted ToolStatus = "completed" )
type WakePort ¶ added in v0.1.9
type WakePort func(ctx context.Context, target WakeTarget) error
WakePort starts the continuation of one completed child. The sender's binding supplies it because only that binding owns the dispatcher a wake needs to compile and open the continuing child.
type WakeTarget ¶ added in v0.1.9
type WakeTarget struct {
// ChildSessionID is the completed child the wake continues.
ChildSessionID string
// AgentID is that child's agent type, which the wake reuses.
AgentID string
// Model is that child's frozen model, which the wake reuses.
Model string
// Ownership is that child's durable ownership, which the wake inherits.
Ownership Ownership
// Task is the message text the wake runs as the child's prompt.
Task string
// Call identifies the Tool call that asked for the wake. The woken child's
// lifecycle is attributed to it, so the Run that asked for the wake is the
// Run that sees the child.
Call MessageCall
}
WakeTarget describes one completed child that a message must wake.