subagent

type AgentName string

type AgentType string

type AssignedExecutionResolver interface {
	ResolveAssignedExecution(ctx context.Context, workspaceID string) (AssignedExecutionResources, error)
}

type AssignedExecutionResolverFunc func(context.Context, string) (AssignedExecutionResources, error)

type AssignedExecutionResources struct {
	Runner  AssignedRunner
	Catalog Catalog
}

type AssignedRunner interface {
	ExecuteAssignedSubagent(ctx context.Context, taskID string, envelope ExecutionEnvelope, req Request) (Result, error)
}

type BackgroundRunner interface {
	Runner
	StartBackground(ctx context.Context, req Request) (threadID string, err error)
}

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

type CASRegistryConfig struct {
	Blobs      casblob.Store
	Prefix     string
	MaxRetries int
	// DeferRecovery makes RecoverInterrupted record the requested recovery and
	// apply it on the first later read/write. Aether workers use this because KV
	// becomes available only after Start; successful connection of their stable
	// agent identity proves the prior duplicate is no longer active.
	DeferRecovery bool
}

type Catalog interface {
	List(ctx context.Context) ([]Definition, error)
	Get(ctx context.Context, typ AgentType) (Definition, error)
}

type Definition struct {
	Name           AgentName      `json:"name"`
	Type           AgentType      `json:"type"`
	Description    string         `json:"description"`
	Prompt         string         `json:"prompt,omitempty"`
	PromptPath     string         `json:"prompt_path,omitempty"`
	Model          string         `json:"model,omitempty"`
	MaxTurns       int            `json:"max_turns,omitempty"`
	AllowedTools   []string       `json:"tool_allow,omitempty"`
	DeniedTools    []string       `json:"tool_deny,omitempty"`
	Skills         []string       `json:"skills,omitempty"`
	MCPServers     []string       `json:"mcp_servers,omitempty"`
	PermissionMode PermissionMode `json:"permission_mode,omitempty"`
	ExecPolicyHint string         `json:"exec_policy_hint,omitempty"`
	Background     bool           `json:"background,omitempty"`
}

type ExecutionArtifactRef struct {
	Backend     string `json:"backend"`
	Kind        string `json:"kind"`
	WorkspaceID string `json:"workspace_id,omitempty"`
	SessionID   string `json:"session_id,omitempty"`
	RecordID    string `json:"record_id"`
	Digest      string `json:"digest,omitempty"`
}

type ExecutionEnvelope struct {
	SchemaRevision     uint32                       `json:"schema_revision"`
	Schema             string                       `json:"schema"`
	ExecutionID        string                       `json:"execution_id"`
	WorkspaceID        string                       `json:"workspace_id"`
	CatalogRevision    string                       `json:"catalog_revision,omitempty"`
	OutputSchema       json.RawMessage              `json:"output_schema,omitempty"`
	OutputSchemaDigest string                       `json:"output_schema_digest,omitempty"`
	ParentSessionID    string                       `json:"parent_session_id"`
	ChildSessionID     string                       `json:"child_session_id"`
	ParentTaskID       string                       `json:"parent_task_id,omitempty"`
	ParentMessageID    string                       `json:"parent_message_id,omitempty"`
	InvocationID       string                       `json:"invocation_id,omitempty"`
	Depth              int                          `json:"depth"`
	Background         bool                         `json:"background,omitempty"`
	ExecutionScope     *workspacepkg.ExecutionScope `json:"execution_scope,omitempty"`
	Input              ExecutionArtifactRef         `json:"input"`
	Result             ExecutionArtifactRef         `json:"result"`
	Checkpoint         ExecutionArtifactRef         `json:"checkpoint"`
	Policy             ExecutionPolicy              `json:"policy"`
	Ownership          ExecutionOwnership           `json:"ownership"`
}

type ExecutionOwnership struct {
	Authority       string `json:"authority"`
	ClaimRequired   bool   `json:"claim_required"`
	MaxAttempts     uint32 `json:"max_attempts"`
	UncertainPolicy string `json:"uncertain_policy"`
}

type ExecutionPolicy struct {
	AgentName      string   `json:"agent_name,omitempty"`
	AgentType      string   `json:"agent_type,omitempty"`
	Model          string   `json:"model,omitempty"`
	MaxTurns       int      `json:"max_turns,omitempty"`
	AllowedTools   []string `json:"allowed_tools,omitempty"`
	DeniedTools    []string `json:"denied_tools,omitempty"`
	Skills         []string `json:"skills,omitempty"`
	MCPServers     []string `json:"mcp_servers,omitempty"`
	PermissionMode string   `json:"permission_mode,omitempty"`
	ExecPolicyHint string   `json:"exec_policy_hint,omitempty"`
	SnapshotDigest string   `json:"snapshot_digest"`
}

type ExecutionScopeAuthorizationRequest struct {
	Parent    *workspacepkg.ExecutionScope
	Requested *workspacepkg.ExecutionScope
	Request   Request
	Reason    string
}

type ExecutionScopeAuthorizer interface {
	AuthorizeSubagentExecutionScope(context.Context, ExecutionScopeAuthorizationRequest) error
}

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

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

type LifecycleEvent struct {
	WorkspaceID string
	Record      spec.SessionSubagentRecord
}

type LifecycleObserver interface {
	ObserveSubagent(ctx context.Context, event LifecycleEvent) error
}

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

type PermissionMode string

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

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

type Registry interface {
	LifecycleObserver
	ListSubagents(ctx context.Context, workspaceID, parentSessionID string) ([]spec.SessionSubagentRecord, error)
	RecoverInterrupted(ctx context.Context, at time.Time) error
}

type Request struct {
	Task   string
	Depth  int
	Parent protocol.MessageAddress
	// InvocationID identifies this spawn invocation independently from the child
	// thread. The reference tool supplies its stable tool-call ID so a durable
	// task backend can deduplicate an admission retry without collapsing later
	// follow-ups that resume the same child thread.
	InvocationID string
	GrantID      string
	SubjectType  string
	SubjectID    string
	// ExecutionScope pins the child to the parent's exact workspace view and
	// write ceiling. The spawn tool supplies it from trusted turn context; it is
	// never accepted as a model-authored absolute path or bearer grant.
	ExecutionScope *workspacepkg.ExecutionScope
	// CatalogRevision pins the immutable workspace catalog admitted by the
	// parent session so durable/external execution cannot silently use a newer
	// skill, MCP, or agent surface.
	CatalogRevision string
	// OutputSchema is an optional, admission-validated JSON Schema contract for
	// the child's final answer. The child receives it once in its bootstrap.
	OutputSchema json.RawMessage
	// Model optionally pins the sub-agent to a specific model (validated against
	// the registry by the runner; empty → the runner's normal per-turn selection).
	Model string
	// ResumeThreadID, when set, CONTINUES an existing child sub-agent thread
	// (used verbatim as the child thread id) instead of minting a new
	// "<parentThread>::sub::<seq>" thread. It is the handle returned as
	// Result.ThreadID from a prior spawn; empty → create a new child thread.
	ResumeThreadID string
	// ParentMessageID is the id of the spawning parent message, recorded on the
	// child thread's task message as MessageRef.ParentMessageID (the cross-thread
	// back-ref). Empty is acceptable (the back-ref still carries the parent
	// thread id).
	ParentMessageID string
	// Agent fields are populated when a file-backed catalog definition is used.
	// The OSS in-process runner applies Instructions, MaxTurns, AllowedTools,
	// DeniedTools, and Model. Skills, MCPServers, PermissionMode,
	// ExecPolicyHint, and Background are retained for catalog-compatible
	// backends until OSS has concrete runtime seams for them.
	AgentName      AgentName
	AgentType      AgentType
	Instructions   string
	MaxTurns       int
	AllowedTools   []string
	DeniedTools    []string
	Skills         []string
	MCPServers     []string
	PermissionMode PermissionMode
	ExecPolicyHint string
	Background     bool
}

type Result struct {
	Text string
	// StructuredPayload is set when OutputSchema was supplied and the final JSON
	// passed host-side validation. StructuredDigest identifies those exact bytes.
	StructuredPayload json.RawMessage
	StructuredDigest  string
	// ThreadID is the child sub-agent thread's id — the re-addressable handle.
	// Pass it back as Request.ResumeThreadID to continue the same sub-agent.
	ThreadID string
	// Summary is a compact one-line digest of the answer (first line / first
	// ~200 chars), suitable for the parent to keep as a reference.
	Summary string
}

type Runner interface {
	RunSubagent(ctx context.Context, req Request) (Result, error)
}

type TaskAdmission struct {
	WorkspaceID     string
	ParentSessionID string
	ChildSessionID  string
	ParentTaskID    string
	ParentMessageID string
	InvocationID    string
	Name            string
	Kind            string
	Model           string
	Depth           int
	Background      bool
	GrantID         string
	SubjectType     string
	SubjectID       string
	// Execution is the immutable, non-secret payload descriptor for an eventual
	// assignee. It references durable input/result/checkpoint state and records
	// claim/replay ownership without embedding prompt text or credentials.
	Execution ExecutionEnvelope
}

type TaskAwaiter interface {
	TaskBackend
	ExecutesExternally() bool
	Await(ctx context.Context, taskID string, observe func(TaskRecovery)) (TaskRecovery, error)
}

type TaskBackend interface {
	Admit(ctx context.Context, admission TaskAdmission) (taskID string, err error)
	Start(ctx context.Context, taskID string) error
	Finish(ctx context.Context, taskID string, outcome TaskOutcome, reason string) error
	Recover(ctx context.Context, taskID string) (TaskRecovery, error)
}

type TaskOutcome string

type TaskRecovery string

type TaskRecoveryRegistry interface {
	Registry
	RecoverInterruptedWithTasks(ctx context.Context, at time.Time, tasks TaskBackend) error
}

type ValidationError struct {
	Path    string `json:"path"`
	Message string `json:"message"`
}

type WorkspaceCatalog interface {
	Catalog
	ListWorkspace(ctx context.Context, workspaceID string) ([]Definition, error)
	GetWorkspace(ctx context.Context, workspaceID string, typ AgentType) (Definition, error)
}

type WorkspaceDefinitionProvider interface {
	LoadWorkspace(ctx context.Context, workspaceID string) ([]Definition, error)
}