session

package
v0.4.0 Latest Latest
Warning

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

Go to latest
Published: Oct 24, 2026 License: MIT Imports: 69 Imported by: 0

Documentation

Overview

Package session orchestrates Compozy session lifecycle around ACP-backed agents.

Index

Constants

View Source
const (
	AttachmentKindImage = attachmentspkg.KindImage
	AttachmentKindFile  = attachmentspkg.KindFile
)
View Source
const (
	// DefaultListLimit is the server-owned page size for public session catalogs.
	DefaultListLimit = 50
	// MaxListLimit is the largest public session catalog page.
	MaxListLimit = 100

	ListSortRecent       = "recent"
	ListSortCreated      = "created"
	ListSortName         = "name"
	ListSortNavigator    = "navigator"
	ListSortLastActivity = "last_activity"
	ListSortAttention    = "attention"
	ListSortManual       = "manual"

	ArchiveExclude = store.SessionArchiveExclude
	ArchiveOnly    = store.SessionArchiveOnly
	ArchiveInclude = store.SessionArchiveInclude
)
View Source
const (
	GoalCommandVerbSet     = "set"
	GoalCommandVerbReplace = "replace"
	GoalCommandVerbStatus  = "status"
	GoalCommandVerbPause   = "pause"
	GoalCommandVerbResume  = "resume"
	GoalCommandVerbClear   = "clear"
	GoalCommandVerbDraft   = "draft"
)
View Source
const (
	PullRequestOpen        PullRequestState = "open"
	PullRequestClosed      PullRequestState = "closed"
	PullRequestMerged      PullRequestState = "merged"
	ChecksPassing          ChecksState      = "passing"
	ChecksFailing          ChecksState      = "failing"
	ChecksPending          ChecksState      = "pending"
	ChecksNone             ChecksState      = "none"
	ChecksUnknown          ChecksState      = "unknown"
	ReviewApproved         ReviewDecision   = "approved"
	ReviewChangesRequested ReviewDecision   = "changes_requested"
	ReviewRequired         ReviewDecision   = "review_required"
	ReviewNone             ReviewDecision   = "none"
	ReviewUnknown          ReviewDecision   = "unknown"
	MergeableYes           Mergeable        = "mergeable"
	MergeableConflicting   Mergeable        = "conflicting"
	MergeableUnknown       Mergeable        = "unknown"
	LookupOK               LookupState      = "ok"
	LookupPending          LookupState      = "pending"
	LookupError            LookupState      = "error"
	LookupIncomplete       LookupState      = "incomplete"
)
View Source
const (
	BoardNeedsYou BoardColumn = "needs_you"
	BoardWorking  BoardColumn = "working"
	BoardInReview BoardColumn = "in_review"
	BoardDone     BoardColumn = "done"
	BadgeWaiting  Badge       = "waiting"
)
View Source
const (
	RepairSeverityInfo    = "info"
	RepairSeverityWarning = "warning"
	RepairSeverityError   = "error"

	RepairIssueSequenceGap                = "event_sequence_gap"
	RepairIssueSequenceDuplicate          = "event_sequence_duplicate"
	RepairIssueSequenceRegression         = "event_sequence_regression"
	RepairIssueInvalidEventJSON           = "invalid_event_json"
	RepairIssueEventTypeMismatch          = "event_type_mismatch"
	RepairIssueNoRepairableTurn           = "no_repairable_turn"
	RepairIssueSessionNotStopped          = "session_not_stopped"
	RepairIssueStopReasonRequiresForce    = "stop_reason_requires_force"
	RepairIssueDanglingToolCallMissingID  = "dangling_tool_call_missing_id"
	RepairIssueTerminalEventAlreadyExists = "terminal_event_already_exists"

	RepairActionAppendInterruptedToolResult = "append_interrupted_tool_result"
	RepairActionAppendTerminalError         = "append_terminal_error"
)
View Source
const (
	RuntimeStatusUnbound       = store.SessionRuntimeUnbound
	RuntimeStatusBinding       = store.SessionRuntimeBinding
	RuntimeStatusReady         = store.SessionRuntimeReady
	RuntimeStatusReconfiguring = store.SessionRuntimeReconfiguring
	RuntimeStatusRecovering    = store.SessionRuntimeRecovering
	RuntimeStatusFailed        = store.SessionRuntimeFailed
)
View Source
const (
	RuntimeTransitionNone               = store.SessionRuntimeTransitionNone
	RuntimeTransitionInitialBind        = store.SessionRuntimeTransitionInitialBind
	RuntimeTransitionLiveConfiguration  = store.SessionRuntimeTransitionLiveConfiguration
	RuntimeTransitionProcessReplacement = store.SessionRuntimeTransitionProcessReplacement
	RuntimeTransitionAutomaticRecovery  = store.SessionRuntimeTransitionAutomaticRecovery
)
View Source
const (
	SessionCreationCodeInvalid          = "session_creation_invalid"
	SessionCreationCodeIdentityMismatch = "session_creation_identity_mismatch"
	SessionCreationCodeEffectUnknown    = "session_creation_effect_unknown"
	SessionCreationCodeStoreUnavailable = "session_creation_store_unavailable"
)
View Source
const (
	NotificationTitleMaxChars = 80
	NotificationBodyMaxChars  = 240
	NotificationRateWindow    = time.Second
)
View Source
const (
	WaitTimeoutDefault = 5 * time.Minute
	WaitTimeoutMax     = 30 * time.Minute
	WaitResumeGrace    = 10 * time.Second
	WaitEdgeBufferSize = 64
	WaitMaxPerSession  = 32
)
View Source
const (
	// DefaultSpawnMaxChildren is the MVP per-parent active child cap.
	DefaultSpawnMaxChildren = 5
	// DefaultSpawnMaxDepth is the MVP maximum child depth under a root session.
	DefaultSpawnMaxDepth = 1
	// DefaultSpawnRole is used when an agent omits the advisory child role.
	DefaultSpawnRole = "worker"
	// SpawnRoleAutoTitle marks daemon-owned title generator children.
	SpawnRoleAutoTitle = "auto-title"
)
View Source
const (
	// SpawnPermissionRuleSubset refuses an atom the parent ceiling does not grant.
	SpawnPermissionRuleSubset = "subset_of_parent"
	// SpawnPermissionRuleBlankAtom refuses an empty permission atom.
	SpawnPermissionRuleBlankAtom = "blank_atom"
	// SpawnPermissionRuleUnknownToolset refuses a toolset name the catalog cannot expand.
	SpawnPermissionRuleUnknownToolset = "known_toolset"
)

Spawn permission rules name why one requested atom was refused.

View Source
const (
	SpawnLimitMaxChildren           = "max_children"
	SpawnLimitMaxActivePerWorkspace = "max_active_per_workspace"
)

Spawn limits name the live-child cap a SpawnLimitError refers to.

View Source
const (
	SubagentIsolationWorktree = "worktree"

	SubagentModeAsync = "async"
	SubagentModeWait  = "wait"
)

Subagent modes.

View Source
const (
	// DefaultLivenessStallAfter defines how long a session may go without ACP
	// activity before recovery marks it stalled.
	DefaultLivenessStallAfter = 2 * time.Minute
)
View Source
const EventTypeClarify = acp.EventTypeClarify
View Source
const EventTypeGoalSnapshotChanged = "goal_snapshot_changed"

EventTypeGoalSnapshotChanged is the persisted session projection signal for Goal changes.

View Source
const (
	// EventTypeSessionStopped is emitted when a session transitions to the stopped state.
	EventTypeSessionStopped = "session_stopped"
)
View Source
const RuntimeModeVerdictOnly = "verdict-only"

RuntimeModeVerdictOnly disables provider-native tools for isolated verdict sessions.

View Source
const SessionNameMaxRunes = 64
View Source
const SessionPresenceLeaseTTL = 15 * time.Second
View Source
const StopVerificationFailedCode = "stop_verification_failed"

StopVerificationFailedCode is the stable diagnostic for an unverified process exit.

Variables

View Source
var (
	// ErrSessionArchived reports that a runtime action requires restoring the session first.
	ErrSessionArchived = errors.New("session: session is archived")
	// ErrSessionArchiveRequiresStopped reports an archive request for a live session.
	ErrSessionArchiveRequiresStopped = errors.New("session: session must be stopped before archiving")
	// ErrSessionArchiveUnavailable reports that archive persistence is not configured.
	ErrSessionArchiveUnavailable = errors.New("session: archive store is unavailable")
	// ErrSessionArchiveStopFailed reports that archive-with-stop could not stop
	// the session, which therefore stays unarchived.
	ErrSessionArchiveStopFailed = errors.New("session: stop before archiving failed")
)
View Source
var (
	// ErrListQueryInvalid reports unsupported filters, sorts, or limits.
	ErrListQueryInvalid = errors.New("session: list query is invalid")
	// ErrListCursorInvalid reports malformed cursors or cursors reused with another query.
	ErrListCursorInvalid = errors.New("session: list cursor is invalid")
)
View Source
var (
	ErrWorkspaceSelectionInvalid  = errors.New("workspace_breadth_invalid")
	ErrWorkspaceSelectionReserved = errors.New("workspace_reserved")
)
View Source
var (
	// ErrSessionNotDerivable rejects a continue or fork of a non-user session.
	ErrSessionNotDerivable = errors.New("only user sessions can be continued or forked")
	// ErrDeriveSourceArchived rejects a continue or fork of an archived source; it
	// matches ErrSessionArchived.
	ErrDeriveSourceArchived = fmt.Errorf("%w; unarchive it first", ErrSessionArchived)
	// ErrDeriveTurnInProgress reports a cut turn without a terminal event.
	ErrDeriveTurnInProgress = errors.New("the cut turn has not settled")
	// ErrDeriveFenceConflict reports client fences that differ from the snapshot.
	ErrDeriveFenceConflict = errors.New("transcript changed since the fences were read")
	// ErrDeriveIdempotencyConflict reports a derive key reused with a different request.
	ErrDeriveIdempotencyConflict = errors.New("idempotency key was used with a different request")
	// ErrDeriveRouteNotFound reports a declared route that does not exist (or changed).
	ErrDeriveRouteNotFound = errors.New("route_not_found")
	// ErrDeriveMessageNotFound reports a fork anchor that is not in the source session.
	ErrDeriveMessageNotFound = errors.New("message not found in session")
	// ErrDeriveAgentNotFound reports an unknown target agent.
	ErrDeriveAgentNotFound = errors.New("agent not found")
)
View Source
var (
	// ErrSessionNotFound reports that the requested active session does not exist.
	ErrSessionNotFound = errors.New("session: session not found")
	// ErrSessionNotActive reports that a known session cannot accept live approvals or prompts.
	ErrSessionNotActive = errors.New("session: session is not active")
	// ErrPendingPermissionNotFound reports that no waiting permission matched the approval request.
	ErrPendingPermissionNotFound = errors.New("session: pending permission not found")
	// ErrPendingPermissionConflict reports that the approval request matched multiple pending permissions.
	ErrPendingPermissionConflict = errors.New("session: pending permission lookup is ambiguous")
	// ErrInvalidPermissionDecision reports an approval decision unsupported by the pending provider request.
	ErrInvalidPermissionDecision = errors.New("session: invalid permission decision")
	// ErrInvalidRuntimeOverride reports that a session runtime override is invalid.
	ErrInvalidRuntimeOverride = errors.New("session: invalid runtime override")
	// ErrValidation reports structurally invalid session creation input.
	ErrValidation = errors.New("session: validation failed")
	// ErrHostedMCPUnavailable reports that a session requiring Compozy tools cannot host them.
	ErrHostedMCPUnavailable = errors.New("session: required hosted MCP is unavailable")
	// ErrConversationRewindBusy reports that live session work prevents a safe rewind.
	ErrConversationRewindBusy = errors.New("session: conversation rewind requires an idle session")
	// ErrConversationRewindManaged reports that daemon-managed sessions cannot be rewound.
	ErrConversationRewindManaged = errors.New("session: managed sessions cannot be rewound")
	// ErrConversationRewindFenceConflict reports that the visible transcript changed before rewind.
	ErrConversationRewindFenceConflict = errors.New("session: conversation rewind transcript changed")
)
View Source
var (
	// ErrPromptImagesUnsupported reports an image prompt rejected by negotiated ACP capabilities.
	ErrPromptImagesUnsupported = errors.New("session: prompt images unsupported")
	// ErrPromptFilesUnsupported reports an embedded file prompt rejected by negotiated ACP capabilities.
	ErrPromptFilesUnsupported = errors.New("session: prompt files unsupported")
	// ErrPromptAttachmentDigestMismatch reports attachment bytes that differ from admitted metadata.
	ErrPromptAttachmentDigestMismatch = errors.New("session: prompt attachment digest mismatch")
)
View Source
var (
	// ErrInvalidStateTransition reports that a session state transition is not allowed.
	ErrInvalidStateTransition = errors.New("session: invalid state transition")
	// ErrPromptInProgress reports that the session already has prompt setup or execution in flight.
	ErrPromptInProgress = errors.New("session: prompt already in progress")
	// ErrPromptNotInProgress reports that an operation requires an active prompt turn.
	ErrPromptNotInProgress = errors.New("session: prompt is not in progress")
	// ErrActiveTurnMismatch reports that a busy-input command targeted a different active turn.
	ErrActiveTurnMismatch = errors.New("session: active turn mismatch")
)
View Source
var (
	// ErrSessionMessageSelfTarget rejects a session message addressed to the calling session.
	//nolint:revive,staticcheck // This sentinel is the exact public message of the session message contract.
	ErrSessionMessageSelfTarget = errors.New("session_prompt cannot target the calling session.")
	// ErrSessionMessageRateLimited reports an exhausted per sender→target message budget.
	ErrSessionMessageRateLimited = errors.New("session message rate limit reached")
)
View Source
var (
	ErrSessionPresenceLeaseNotFound = errors.New("session: presence lease not found")
	ErrSessionPresenceLeaseMismatch = errors.New("session: presence lease belongs to another session")
)
View Source
var (
	// ErrSessionReparentRefused is the sentinel every lineage-rule refusal wraps.
	ErrSessionReparentRefused = errors.New("session: reparent refused")
	// ErrSessionReparentUnavailable reports that lineage persistence is not configured.
	ErrSessionReparentUnavailable = errors.New("session: session lineage store is unavailable")
)
View Source
var (
	ErrWaitValidation   = errors.New("session: invalid wait request")
	ErrWaitStateInvalid = errors.New("session: invalid wait state")
	ErrWaitLimit        = errors.New("session: concurrent wait limit reached")
	ErrWaitExpired      = errors.New("session: wait registration expired")
	ErrWaitInUse        = errors.New("session: wait registration is already attached")
)
View Source
var (
	// ErrSoulRefreshConflict reports that a Soul refresh cannot run because
	// another session-scoped operation or an active task run is in progress.
	ErrSoulRefreshConflict = errors.New("session: soul refresh conflict")
	// ErrSoulRefreshDigestConflict reports a stale body-level expected digest.
	ErrSoulRefreshDigestConflict = errors.New("session: soul refresh expected digest conflict")
)
View Source
var (
	// ErrSpawnValidation reports a structurally invalid spawn request.
	ErrSpawnValidation = errors.New("session: spawn validation failed")
	// ErrSpawnPermissionDenied reports a failed permission narrowing check.
	ErrSpawnPermissionDenied = errors.New("session: spawn permission denied")
	// ErrSpawnLimitExceeded reports a depth, child, or workspace cap violation.
	ErrSpawnLimitExceeded = errors.New("session: spawn limit exceeded")
)
View Source
var (
	// ErrSpawnWakeValidation reports structurally invalid child wake input.
	ErrSpawnWakeValidation = errors.New("session: spawn wake validation failed")
	// ErrSpawnWakeSessionNotLive reports that the creator cannot accept a wake prompt.
	ErrSpawnWakeSessionNotLive = errors.New("session: spawn wake creator is not live")
)
View Source
var (
	ErrSubagentParentNotActive   = errors.New("session: subagent parent turn is not active")
	ErrSubagentInvalidRequest    = errors.New("session: invalid subagent request")
	ErrSubagentTargetUnavailable = errors.New("session: subagent target unavailable")
	ErrSubagentCapabilityDenied  = errors.New("session: subagent capability denied")
	ErrSubagentNotFound          = errors.New("session: subagent not found")
	ErrSubagentNotCancelable     = errors.New("session: subagent not cancelable")
	ErrSubagentArchiveFollows    = errors.New("session: subagent archive follows parent")
)

Subagent error sentinels. API/tool layers map them to deterministic codes.

View Source
var (
	// ErrBadgeFilterInvalid reports an unsupported public badge filter.
	ErrBadgeFilterInvalid = errors.New("session: badge filter is invalid")
)
View Source
var ErrBoardFilterInvalid = fmt.Errorf("%w: %w", ErrListQueryInvalid, errors.New("invalid board selector"))
View Source
var ErrCatalogScopeInvalid = errors.New("session: catalog scope is invalid")
View Source
var ErrCompactionUnsupported = errors.New("session: agent does not advertise a compaction command")

ErrCompactionUnsupported reports an agent without a native compaction command.

View Source
var ErrCreateScopeConflict = errors.New("session_create_scope_conflict")

ErrCreateScopeConflict rejects project selectors supplied with explicit User scope.

View Source
var ErrInvalidNotification = errors.New("session: invalid operator notification")
View Source
var ErrPromptNotActive = errors.New("session: prompt is not active")

ErrPromptNotActive reports that no authoritative prompt run is published for the session.

View Source
var ErrRecoveryPersistence = errors.New("session: recovery persistence failed")

ErrRecoveryPersistence prevents admission against an incompletely recovered session inventory.

View Source
var ErrRestartContinuationSkipped = errors.New("session: restart continuation requires operator input")
View Source
var (
	// ErrRuntimeSelectionConflict reports a stale compare-and-set revision.
	ErrRuntimeSelectionConflict = errors.New("session: runtime selection revision conflict")
)
View Source
var ErrScopedInterruptNotFound = toolruntime.ErrProcessNotFound

ErrScopedInterruptNotFound reports that no registered tool process matched a scoped interrupt.

View Source
var ErrSessionLayoutUnavailable = errors.New("session: session layout store is unavailable")

ErrSessionLayoutUnavailable reports that layout persistence is not configured.

View Source
var ErrSessionMessageHopLimit = errors.New("Message chain limit reached (8 hops). Ask the operator to continue.")
View Source
var ErrStopVerificationFailed = errors.New("session: stop_verification_failed")

ErrStopVerificationFailed means the session cannot yet claim terminal state.

Functions

func ACPOptionSelectionsFromConfig

func ACPOptionSelectionsFromConfig(
	selections []compozyconfig.ACPOptionSelection,
) []acp.SessionConfigOptionSelection

ACPOptionSelectionsFromConfig converts configuration-owned ACP selections to runtime values.

func ACPOptionSelectionsFromStore

func ACPOptionSelectionsFromStore(
	selections []store.SessionACPOptionSelection,
) []acp.SessionConfigOptionSelection

ACPOptionSelectionsFromStore converts persisted ACP selections to their runtime representation.

func AnnotateUnpersistedRecovery

func AnnotateUnpersistedRecovery(meta *store.SessionMeta, err error) store.SessionMeta

AnnotateUnpersistedRecovery appends persistence failure detail to the recovered stopped-state metadata returned to callers when the synthetic crash classification could not be durably written.

func AttachableForInfo

func AttachableForInfo(info *Info, now time.Time) bool

AttachableForInfo computes whether a session snapshot is eligible for an explicit attach without consulting UI state or spawning a new runtime.

func BuildCreationProfile

func BuildCreationProfile(input CreationProfileInput) store.SessionCreationProfile

BuildCreationProfile constructs the current canonical profile used by daemon and Manager.

func ClassifyInactiveMetaForRecovery

func ClassifyInactiveMetaForRecovery(now time.Time, meta *store.SessionMeta) (store.SessionMeta, bool)

ClassifyInactiveMetaForRecovery preserves stopping until recorded process death is proven.

func ConfigACPOptionSelectionsFromACP

func ConfigACPOptionSelectionsFromACP(
	selections []acp.SessionConfigOptionSelection,
) []compozyconfig.ACPOptionSelection

ConfigACPOptionSelectionsFromACP converts runtime ACP selections to the shared authored representation.

func DispositionValues

func DispositionValues() []string

func IsInternalSpawnRole

func IsInternalSpawnRole(role string) bool

IsInternalSpawnRole reports whether a child is daemon-owned and must stay out of operator catalogs and metrics.

func MergeRuntimeACPOptions

MergeRuntimeACPOptions merges base ACP options with explicit runtime overrides in option ID order.

func NormalizeWorkspaceIDs

func NormalizeWorkspaceIDs(values []string, all bool) ([]string, error)

func ParseBoardColumns

func ParseBoardColumns(values []string) ([]string, error)

func ParseChildrenFilter

func ParseChildrenFilter(value string) (bool, error)

func RecoveryMetadataSkipReason

func RecoveryMetadataSkipReason(meta *store.SessionMeta) string

RecoveryMetadataSkipReason refuses unsupported lifecycle metadata before recovery can normalize or persist it.

func ResolveCompactionCommand

func ResolveCompactionCommand(commands []store.SessionAdvertisedCommand) (string, bool)

ResolveCompactionCommand selects the native compaction command, preferring compact.

func ResolveSessionCWD

func ResolveSessionCWD(root string, requested string) (string, error)

ResolveSessionCWD normalizes a creation CWD and rejects execution-root escape.

func RuntimeStrategyForProvider

func RuntimeStrategyForProvider(providerID string) acp.RuntimeApplicationStrategy

RuntimeStrategyForProvider returns the public runtime application strategy owned by the provider adapter registry.

func SanitizeSpawnWakeText

func SanitizeSpawnWakeText(value string) string

SanitizeSpawnWakeText removes secrets and bounds wake-facing text to 240 runes.

func SpawnPromptMessageID

func SpawnPromptMessageID(childSessionID string) string

SpawnPromptMessageID is the stable message and idempotency identity of a child's first prompt, so a retried spawn call cannot admit the prompt twice.

func StartAccepted

func StartAccepted(err error) bool

StartAccepted reports whether a start/bind attempt reached ACP acceptance: a nil error, or an error carrying acp.AcceptedStartError anywhere in its chain. It is the only acceptance derivation chain owners use; a nil or non-nil process never decides it.

func TerminationBudget

func TerminationBudget(config compozyconfig.SessionStopConfig) time.Duration

TerminationBudget reserves all process termination phases independently of session count.

func ValidatePermissionSubset

func ValidatePermissionSubset(parent store.SessionPermissionPolicy, child store.SessionPermissionPolicy) error

ValidatePermissionSubset fails closed unless every child permission atom is present in the corresponding known parent category.

func ValidateReasoningEffort

func ValidateReasoningEffort(value string) error

ValidateReasoningEffort validates one reasoning effort override.

func WithActingSession

func WithActingSession(ctx context.Context, sessionID string) context.Context

WithActingSession records the trusted session that initiated a cross-session action.

func WithCompactionRequestedBy

func WithCompactionRequestedBy(ctx context.Context, source string) context.Context

WithCompactionRequestedBy records the transport initiating a compaction request.

func WorkSignalKindValues

func WorkSignalKindValues() []string

WorkSignalKindValues defines the closed vocabulary shared with public schemas.

Types

type ACPDriverAdapter

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

ACPDriverAdapter adapts the concrete ACP driver to the session-local interface.

func NewACPDriverAdapter

func NewACPDriverAdapter(driver *acp.Driver) *ACPDriverAdapter

NewACPDriverAdapter wraps the provided ACP driver for use by the session manager.

func (*ACPDriverAdapter) Cancel

func (a *ACPDriverAdapter) Cancel(ctx context.Context, proc *AgentProcess) error

Cancel lets higher layers stop prompt work without bypassing ACP-owned lifecycle handling.

func (*ACPDriverAdapter) CancelCooperatively

func (a *ACPDriverAdapter) CancelCooperatively(ctx context.Context, proc *AgentProcess) error

CancelCooperatively requests agent cancellation without detaching the prompt stream.

func (*ACPDriverAdapter) ConfigureRuntime

func (a *ACPDriverAdapter) ConfigureRuntime(
	ctx context.Context,
	proc *AgentProcess,
	config acp.RuntimeConfig,
) error

ConfigureRuntime applies mutable ACP settings to the active process.

func (*ACPDriverAdapter) ForkSession

func (a *ACPDriverAdapter) ForkSession(
	ctx context.Context,
	proc *AgentProcess,
	cwd string,
) (acp.ForkSessionResult, error)

ForkSession calls ACP session/fork on the process's bound session for cwd.

func (*ACPDriverAdapter) Interrupt

func (a *ACPDriverAdapter) Interrupt(
	ctx context.Context,
	sessionID string,
	turnID string,
) (toolruntime.InterruptReport, error)

Interrupt signals only registered tool processes scoped to the session turn.

func (*ACPDriverAdapter) Kill

func (a *ACPDriverAdapter) Kill(ctx context.Context, proc *AgentProcess) error

Kill requests the final forced termination phase from the process owner.

func (*ACPDriverAdapter) NotifyExtension

func (a *ACPDriverAdapter) NotifyExtension(
	ctx context.Context,
	proc *AgentProcess,
	method string,
	params any,
) error

NotifyExtension delivers one fire-and-forget extension notification over the live agent connection.

func (*ACPDriverAdapter) Prompt

func (a *ACPDriverAdapter) Prompt(
	ctx context.Context,
	proc *AgentProcess,
	req acp.PromptRequest,
) (<-chan acp.AgentEvent, error)

Prompt streams prompt events from the wrapped ACP runtime.

func (*ACPDriverAdapter) Start

Start launches a new ACP-backed runtime process.

func (*ACPDriverAdapter) Steer

func (a *ACPDriverAdapter) Steer(
	ctx context.Context,
	proc *AgentProcess,
	turnID, text string,
	attachments []acp.PromptAttachment,
) (acp.SteerResult, error)

func (*ACPDriverAdapter) Stop

func (a *ACPDriverAdapter) Stop(ctx context.Context, proc *AgentProcess) error

Stop stops the wrapped ACP runtime process.

func (*ACPDriverAdapter) StopBudget

func (a *ACPDriverAdapter) StopBudget() time.Duration

StopBudget reports how long a Stop of the wrapped ACP runtime may run.

func (*ACPDriverAdapter) VerifyExit

func (a *ACPDriverAdapter) VerifyExit(proc *AgentProcess) (bool, error)

VerifyExit asks the ACP process owner for termination evidence.

type ActiveTurnMismatchError

type ActiveTurnMismatchError struct {
	ExpectedTurnID string
	CurrentTurnID  string
}

ActiveTurnMismatchError carries the live fence observed before accepting a command.

func (*ActiveTurnMismatchError) Error

func (e *ActiveTurnMismatchError) Error() string

func (*ActiveTurnMismatchError) Unwrap

func (*ActiveTurnMismatchError) Unwrap() error

type AgentArtifactResolver

type AgentArtifactResolver interface {
	ResolveAgentArtifacts(name string, resolved *workspacepkg.ResolvedWorkspace) (AgentArtifacts, error)
}

AgentArtifactResolver resolves agent provenance when available.

type AgentArtifacts

type AgentArtifacts struct {
	Agent               compozyconfig.AgentDef
	ResourceID          string
	OwnerKind           string
	OwnerID             string
	Scope               resources.ResourceScope
	PackageOwned        bool
	SoulSourcePath      string
	SoulBody            string
	HeartbeatSourcePath string
	HeartbeatBody       string
}

AgentArtifacts returns an agent definition and resource ownership.

type AgentCatalogResolver

type AgentCatalogResolver interface {
	AgentResolver
	ListAgentDefinitions(resolved *workspacepkg.ResolvedWorkspace) []compozyconfig.AgentDef
}

AgentCatalogResolver enumerates the same scoped definitions used for target resolution.

type AgentCooperativeCanceler

type AgentCooperativeCanceler interface {
	CancelCooperatively(context.Context, *AgentProcess) error
}

AgentCooperativeCanceler requests cancellation while preserving peer completion evidence.

type AgentDriver

type AgentDriver interface {
	Start(ctx context.Context, opts acp.StartOpts) (*AgentProcess, error)
	Prompt(ctx context.Context, proc *AgentProcess, req acp.PromptRequest) (<-chan acp.AgentEvent, error)
	Cancel(ctx context.Context, proc *AgentProcess) error
	Stop(ctx context.Context, proc *AgentProcess) error
}

AgentDriver defines the ACP functionality consumed by the session manager.

type AgentEventNotifier

type AgentEventNotifier interface {
	OnAgentEventForSession(ctx context.Context, session *Session, event any)
}

AgentEventNotifier is an optional notifier extension that receives the active session alongside streamed agent events.

type AgentExitVerifier

type AgentExitVerifier interface {
	VerifyExit(proc *AgentProcess) (bool, error)
}

AgentExitVerifier lets the process owner verify local or remote exit identity.

type AgentExtensionNotifier

type AgentExtensionNotifier interface {
	NotifyExtension(ctx context.Context, proc *AgentProcess, method string, params any) error
}

AgentExtensionNotifier is the optional driver surface for fire-and-forget agent extension delivery over a live process connection.

type AgentHooks

AgentHooks groups agent start and stop lifecycle hook dispatch.

type AgentKiller

type AgentKiller interface {
	Kill(context.Context, *AgentProcess) error
}

AgentKiller is the process owner's final force-termination operation.

type AgentProcess

type AgentProcess struct {
	PID       int
	AgentName string
	Command   string
	Args      []string
	Cwd       string
	SessionID string
	StartedAt time.Time
	// contains filtered or unexported fields
}

AgentProcess is the session-owned handle for a running agent process.

func NewAgentProcess

func NewAgentProcess(opts AgentProcessOptions) *AgentProcess

NewAgentProcess constructs an AgentProcess for custom AgentDriver implementations.

func (*AgentProcess) ApprovePermission

func (p *AgentProcess) ApprovePermission(ctx context.Context, req acp.ApproveRequest) error

ApprovePermission resolves one pending interactive permission request.

func (*AgentProcess) CapsSnapshot

func (p *AgentProcess) CapsSnapshot() acp.Caps

CapsSnapshot returns the latest ACP capability/config snapshot for this process.

func (*AgentProcess) Done

func (p *AgentProcess) Done() <-chan struct{}

Done reports when the underlying runtime process exits.

func (*AgentProcess) ExitStatus

func (p *AgentProcess) ExitStatus() (subprocess.ExitStatus, bool)

ExitStatus returns the stable OS exit diagnostics exposed by the runtime process.

func (*AgentProcess) HasPendingPermission

func (p *AgentProcess) HasPendingPermission() bool

HasPendingPermission reports whether the runtime is waiting for an interactive permission decision.

func (*AgentProcess) HealthState

func (p *AgentProcess) HealthState() (subprocess.HealthState, bool)

HealthState returns the latest runtime health snapshot when the driver exposes subprocess health monitoring.

func (*AgentProcess) RequestPermission

RequestPermission asks the active runtime permission path for a tool approval decision.

func (*AgentProcess) Stderr

func (p *AgentProcess) Stderr() string

Stderr returns any captured stderr output for the runtime process.

func (*AgentProcess) ToolHost

func (p *AgentProcess) ToolHost() acp.ToolHost

ToolHost returns the local tool host when the process exposes one.

func (*AgentProcess) Wait

func (p *AgentProcess) Wait() error

Wait blocks until the runtime process exits and returns its terminal error state.

type AgentProcessOptions

type AgentProcessOptions struct {
	PID               int
	AgentName         string
	Command           string
	Args              []string
	Cwd               string
	SessionID         string
	Caps              acp.Caps
	StartedAt         time.Time
	Done              <-chan struct{}
	Wait              func() error
	Stderr            func() string
	ExitStatus        func() (subprocess.ExitStatus, bool)
	HealthState       func() subprocess.HealthState
	PendingPermission func() bool
	ApprovePermission func(context.Context, acp.ApproveRequest) error
	RequestPermission func(context.Context, acp.RequestPermissionRequest) (acp.RequestPermissionResponse, error)
	CapsSnapshot      func() acp.Caps
	ToolHost          acp.ToolHost
}

AgentProcessOptions defines the exported fields and lifecycle hooks needed to construct an AgentProcess.

type AgentResolver

type AgentResolver interface {
	ResolveAgent(name string, resolved *workspacepkg.ResolvedWorkspace) (compozyconfig.AgentDef, error)
}

AgentResolver resolves agent definitions from the daemon-authoritative catalog.

type AgentSessionMetrics

type AgentSessionMetrics struct {
	Total          int
	Active         int
	Failed         int
	RuntimeSeconds int64
	LastActivityAt time.Time
}

AgentSessionMetrics is the exact visible-session aggregate for one agent.

type AgentSteerer

type AgentSteerer interface {
	Steer(
		ctx context.Context,
		proc *AgentProcess,
		turnID, text string,
		attachments []acp.PromptAttachment,
	) (acp.SteerResult, error)
}

type AgentStopBudgeter

type AgentStopBudgeter interface {
	StopBudget() time.Duration
}

AgentStopBudgeter is the optional driver surface reporting how long one Stop may run.

type AllowedToolsPolicyError

type AllowedToolsPolicyError struct {
	Tool          toolspkg.ToolID
	DeniedByAgent bool
}

AllowedToolsPolicyError identifies an override rejected by the resolved Agent policy.

func (*AllowedToolsPolicyError) Error

func (e *AllowedToolsPolicyError) Error() string

func (*AllowedToolsPolicyError) Unwrap

func (e *AllowedToolsPolicyError) Unwrap() error

type ApprovalResult

type ApprovalResult struct {
	Outcome          string
	InteractionID    string
	RequestID        string
	Decision         string
	ResolvedDecision string
}

ApprovalResult reports the canonical outcome of one permission decision.

type AttachmentMeta

type AttachmentMeta struct {
	ID       string
	Name     string
	MIMEType string
	Bytes    int64
	SHA256   string
	Kind     string
	Width    int
	Height   int
}

AttachmentMeta is the session-owned attachment snapshot on a prompt.

func AttachmentMetaFromRef

func AttachmentMetaFromRef(ref attachmentspkg.AttachmentRef) AttachmentMeta

AttachmentMetaFromRef converts retained metadata into the session-owned prompt snapshot.

type AttachmentOpener

type AttachmentOpener interface {
	Open(
		ctx context.Context,
		workspaceID string,
		sessionID string,
		id string,
	) (io.ReadCloser, attachmentspkg.AttachmentRef, error)
}

AttachmentOpener is the attachment storage surface consumed during prompt dispatch.

type AttentionClass

type AttentionClass string

AttentionClass groups badges by the operator action they require.

const (
	AttentionNeedsYou AttentionClass = "needs-you"
	AttentionFinished AttentionClass = "finished"
	AttentionNone     AttentionClass = "none"
)

func ClassForBadge

func ClassForBadge(badge Badge) AttentionClass

ClassForBadge returns the stable attention class shared by every surface.

type AttentionEvent

type AttentionEvent struct {
	SessionID   string
	ProfileID   string
	WorkspaceID string
	From        Badge
	To          Badge
	Class       AttentionClass
	At          time.Time
}

AttentionEvent is the post-commit edge emitted by the canonical attention store.

type AttentionHooks

type AttentionHooks interface {
	DispatchSessionAttentionChanged(
		context.Context,
		hookspkg.SessionAttentionChangedPayload,
	) (hookspkg.SessionAttentionChangedPayload, error)
}

AttentionHooks groups committed attention observation dispatch.

type AttentionWorkspaceMuteReader

type AttentionWorkspaceMuteReader interface {
	IsAttentionWorkspaceMuted(ctx context.Context, profileID string, workspaceID string) (bool, error)
}

AttentionWorkspaceMuteReader reads the typed profile/workspace mute relation.

type AuthoredContextHooks

type AuthoredContextHooks interface {
	DispatchSessionHealthUpdateAfter(
		context.Context,
		hookspkg.SessionHealthUpdateAfterPayload,
	) (hookspkg.SessionHealthUpdateAfterPayload, error)
}

AuthoredContextHooks groups Soul, Heartbeat, and session-health observation hook dispatch.

type Badge

type Badge string

Badge is the canonical user-facing session status token.

const (
	BadgeRunning         Badge = "running"
	BadgeIdle            Badge = "idle"
	BadgeUnhealthy       Badge = "unhealthy"
	BadgeHung            Badge = "hung"
	BadgeWaitingForAuth  Badge = "waiting-for-auth"
	BadgeWaitingForInput Badge = "waiting-for-input"
	BadgeDone            Badge = "done"
	BadgeStopped         Badge = "stopped"
	BadgeFailed          Badge = "failed"
	BadgeUnknown         Badge = "unknown"
	BadgeNeedsAttention  Badge = "needs-attention"
)

func BadgeForHealth

func BadgeForHealth(info *Info, health heartbeat.SessionHealth) Badge

BadgeForHealth computes a badge from an explicit health row, preserving session/failure precedence from the base session info when supplied.

func BadgeForInfo

func BadgeForInfo(info *Info) Badge

BadgeForInfo computes a badge from the session manager/catalog snapshot.

func CanonicalBadge

func CanonicalBadge(input BadgeInputs) Badge

CanonicalBadge collapses runtime state, health, and failure classification into the stable badge vocabulary used by API, CLI, and web clients.

func NormalizeWaitBadges

func NormalizeWaitBadges(input []Badge) ([]Badge, error)

NormalizeWaitBadges validates, deduplicates, and applies the settled-set default used by every wait surface.

func ParseBadgeFilters

func ParseBadgeFilters(values []string) ([]Badge, error)

ParseBadgeFilters validates, deduplicates, and canonically orders public badge filters.

type BadgeInputs

type BadgeInputs struct {
	State                  State
	StopVerificationFailed bool
	SupervisionAttention   bool
	HealthState            heartbeat.SessionHealthState
	Health                 heartbeat.SessionHealthStatus
	Failure                *store.SessionFailure
	PendingAuth            bool
	PendingClarify         bool
	ActivePrompt           bool
	Stalled                bool
	Waiting                bool
	Unseen                 bool
	IneligibilityReason    string
}

BadgeInputs are the runtime-truth fields used to compute a session badge.

type BoardColumn

type BoardColumn string

func BoardColumnFor

func BoardColumnFor(badge Badge, prState PullRequestState) BoardColumn

type BranchKey

type BranchKey struct{ WorkspaceID, Branch string }

type BranchReader

type BranchReader interface {
	CurrentBranch(context.Context, string) (string, error)
}

type BranchSnapshotReader

type BranchSnapshotReader interface {
	SessionBranches(context.Context, []string) (map[string]string, error)
}

type BusyInputMode

type BusyInputMode string

BusyInputMode selects how a user-facing prompt behaves while a session is busy.

const (
	BusyInputModeQueue     BusyInputMode = "queue"
	BusyInputModeInterrupt BusyInputMode = "interrupt"
	BusyInputModeSteer     BusyInputMode = "steer"
)

type BusyInputState

type BusyInputState struct {
	DefaultMode     string                  `json:"default_mode"`
	SteerCapability config.SteerCapability  `json:"steer_capability"`
	SteerDelivery   store.SteerDeliveryMode `json:"steer_delivery,omitempty"`
}

BusyInputState describes the live session's follow-up behavior.

type CatalogEvent

type CatalogEvent struct {
	Sequence             int64
	Name                 CatalogEventName
	Kind                 CatalogEventKind
	ProfileID            string
	ProfileName          string
	WorkspaceID          string
	SessionID            string
	Attention            *AttentionEvent
	OperatorNotification *OperatorNotification
}

CatalogEvent identifies the workspace-scoped catalog snapshot to reconcile.

type CatalogEventKind

type CatalogEventKind string

CatalogEventKind identifies a durable session-catalog mutation.

const (
	// CatalogEventUpserted reports a created or changed catalog row.
	CatalogEventUpserted CatalogEventKind = "upserted"
	// CatalogEventDeleted reports a removed catalog row.
	CatalogEventDeleted CatalogEventKind = "deleted"
	// CatalogEventLayout reports a workspace folder or manual-order change.
	// It carries no session id: clients reread folders and the catalog.
	CatalogEventLayout CatalogEventKind = "layout"
)

type CatalogEventName

type CatalogEventName string

CatalogEventName identifies one named SSE delivery on the catalog stream.

const (
	CatalogEventNameChanged              CatalogEventName = "session_catalog_changed"
	CatalogEventNameAttention            CatalogEventName = "session_attention_changed"
	CatalogEventNameOperatorNotification CatalogEventName = "operator_notification"
)

type CatalogScope

type CatalogScope struct {
	ReadScope     store.ReadScope
	WorkspaceID   string
	AllWorkspaces bool
	Replay        bool
	ReplayAfter   int64
}

CatalogScope selects one explicit workspace or the labeled aggregate stream.

func (CatalogScope) Validate

func (s CatalogScope) Validate() error

type ChainOwner

type ChainOwner uint8

ChainOwner declares who runs the fallback chain for one launch, so no launch ever has two chain owners (ADR-004).

const (
	// ChainOwnerSession is the default: the session layer owns the agent's fallback_chain
	// for ordinary work sessions (HTTP/CLI/tool Create, first binds, agent-requested Spawn).
	ChainOwnerSession ChainOwner = iota
	// ChainOwnerCaller means a caller (a background role) owns its chain; the session layer
	// performs exactly the requested route and reports the structured acceptance outcome.
	ChainOwnerCaller
)

type ChecksState

type ChecksState string

type ClearPendingInputsResult

type ClearPendingInputsResult struct {
	Inputs          []PendingInput
	ClearedCount    int
	QueueGeneration int64
}

type CommandService

type CommandService interface {
	Catalog(
		ctx context.Context,
		info *Info,
		agent compozyconfig.AgentDef,
	) (commandpkg.Catalog, error)
	Expand(
		ctx context.Context,
		info *Info,
		agent compozyconfig.AgentDef,
		invocations []commandpkg.Invocation,
		message string,
	) (string, error)
}

CommandService projects and expands slash commands for one concrete session.

type CompactionEnvelope

type CompactionEnvelope struct {
	ContextAfter *contextusage.ContextAfter
	Sequence     int64
	At           time.Time
	TurnID       string
	Payload      CompactionFiredPayload
	Status       string
}

type CompactionFiredPayload

type CompactionFiredPayload struct {
	CompactionID string `json:"compaction_id"`
	Trigger      string `json:"trigger"`
	ContextUsed  *int64 `json:"context_used"`
	ContextSize  *int64 `json:"context_size"`
}

type CompactionHooks

type CompactionHooks interface {
	DispatchContextPreCompact(
		context.Context,
		hookspkg.ContextPreCompactPayload,
	) (hookspkg.ContextPreCompactPayload, error)
	DispatchContextPostCompact(
		context.Context,
		hookspkg.ContextPostCompactPayload,
	) (hookspkg.ContextPostCompactPayload, error)
}

CompactionHooks groups context compaction hook dispatch.

type CompactionRequestResult

type CompactionRequestResult struct {
	SessionID string
	PromptID  string
	Command   string
}

CompactionRequestResult identifies the accepted maintenance turn.

type ContextEvents

type ContextEvents struct {
	WorkTime    contextusage.WorkTime
	Usage       []UsageEventEnvelope
	Deliveries  []DeliveryEventEnvelope
	Compactions []CompactionEnvelope
	Settled     SettledTurn
	ClearedBy   *contextusage.ClearedBy
}

type ContinueSessionOpts

type ContinueSessionOpts struct {
	SourceSessionID string
	WorkspaceID     string
	ProfileID       string
	AgentName       string
	// Runtime is exclusive with Route.
	Runtime *DeriveRuntime
	// Route is the 1-based declared route of AgentName's fallback_chain; 0 = none.
	Route          int
	Name           string
	Message        string
	IdempotencyKey string
	Fences         DeriveFences
}

ContinueSessionOpts continues a user session with another agent, runtime, or route.

type ConversationHooks

ConversationHooks groups turn/message hook dispatch used during prompt streaming.

type ConversationRewindOptions

type ConversationRewindOptions struct {
	MessageID           string
	IdempotencyKey      string
	ExpectedEpoch       int64
	ExpectedGeneration  int64
	ExpectedMaxSequence int64
}

ConversationRewindOptions identifies one durable user message and the transcript version the caller observed before requesting a rewind.

type ConversationRewindResult

type ConversationRewindResult struct {
	Session         *Session
	TranscriptEpoch int64
	TargetMessageID string
	ArchivedFrom    int64
	ArchivedThrough int64
	ArchivedEvents  int64
	Generation      int64
	MaxSequence     int64
	DraftText       string
	Replayed        bool
}

ConversationRewindResult describes the committed transcript cut and the fresh runtime session that now owns the retained conversation prefix.

type CreateAcceptedOpts

type CreateAcceptedOpts struct {
	Session CreateOpts
}

CreateAcceptedOpts carries one logical user-session creation request.

type CreateOpts

type CreateOpts struct {
	Origin           workspaceaccess.Origin
	Scope            workspacepkg.ScopeKind
	DesiredSessionID string
	ProfileID        string
	AgentName        string
	Provider         string
	Model            string
	ReasoningEffort  string
	Speed            speedpkg.Speed
	ACPOptions       []acp.SessionConfigOptionSelection
	CWD              string
	Permissions      compozyconfig.PermissionMode
	Name             string
	Workspace        string
	WorkspacePath    string
	// Worktree names an existing ready worktree within the resolved parent workspace.
	Worktree        string
	PromptOverlay   string
	ContractOverlay string
	RuntimeMode     string
	Type            Type
	Lineage         *store.SessionLineage
	// ProvenanceParentSessionID links an internal system session to its informational origin.
	// It does not grant spawn governance and is unavailable on public create surfaces.
	ProvenanceParentSessionID string
	ParentSoulDigest          string
	// AllowedToolsOverride is a concrete subset narrowing of the resolved agent tool policy.
	AllowedToolsOverride []string
	// DeniedToolsOverride adds internal deny patterns without widening the resolved agent policy.
	DeniedToolsOverride []string
	CreationProfile     *store.SessionCreationProfile
	CreationIdentity    *store.SessionCreationIdentity
	// Command is an explicit launch command for this attempt (a fallback route's
	// account). Empty keeps the provider-aware resolution and spawn inheritance.
	Command    string
	SessionEnv compozyconfig.SessionEnv
	// Derivation and ImportedContext are set only by the continue/fork derive path.
	Derivation      *store.SessionDerivation
	ImportedContext *store.SessionImportedContext

	// ChainOwner declares who owns the fallback chain for this launch; role-owned
	// launches pass ChainOwnerCaller so the session layer performs exactly one route.
	ChainOwner ChainOwner
	// DiscardStartFailure prevents internal retry attempts from leaving durable
	// session artifacts when provider startup fails before Create returns.
	DiscardStartFailure bool
	// contains filtered or unexported fields
}

CreateOpts defines the inputs required to create a new session.

type CreationError

type CreationError struct {
	Effect EffectCertainty
	Code   string
	Err    error
}

CreationError carries typed session-creation effect certainty through errors.As.

func (*CreationError) Error

func (e *CreationError) Error() string

func (*CreationError) Unwrap

func (e *CreationError) Unwrap() error

type CreationProfileInput

type CreationProfileInput struct {
	Scope           workspacepkg.ScopeKind
	AgentName       string
	Provider        string
	Model           string
	ReasoningEffort string
	Speed           speedpkg.Speed
	ACPOptions      []acp.SessionConfigOptionSelection
	ProfileID       string
	WorkspaceID     string
	CWD             string
	WorktreeRef     string
	Permissions     string
	AllowedTools    []string
	AgentTools      []string
	AgentToolsets   []string
	DeniedTools     []string
	RuntimeMode     string
	PromptOverlay   string
	ContractOverlay string
}

CreationProfileInput is the resolved, secret-free creation policy material.

type DeliveryEventEnvelope

type DeliveryEventEnvelope struct {
	Sequence int64
	At       time.Time
	Manifest acp.DeliveryManifest
}

type DeriveCut

type DeriveCut struct {
	MessageID       string
	TurnID          string
	ThroughSequence int64
	TurnSettled     bool
}

DeriveCut is the turn-resolved cut of a fork anchor.

type DeriveFences

type DeriveFences struct {
	ExpectedEpoch       *int64
	ExpectedGeneration  *int64
	ExpectedMaxSequence *int64
}

DeriveFences are the optional transcript fences a client observed; all three or none.

type DerivePreview

type DerivePreview struct {
	MessageCount int
	// SourceMessageCount is the whole source transcript's message count (inherited
	// context plus every settled turn), before any fork cut or budget bounding.
	SourceMessageCount   int
	ReplayBytes          int
	OmittedCount         int
	Truncated            bool
	SourceTurnInProgress bool
	Cut                  *DeriveCut
	Epoch                int64
	Generation           int64
	MaxSequence          int64
	NativeForkPossible   bool
}

DerivePreview reports what a continue or fork of the source would carry right now.

type DeriveResult

type DeriveResult struct {
	// Child is the derived session's current read model; nil when the child was deleted.
	Child                *Info
	Kind                 store.LineageKind
	SourceSessionID      string
	OriginAgentName      string
	OriginMessageID      string
	Seed                 DeriveSeed
	NativeState          string
	ACPSessionID         string
	NativeForkError      string
	ReplayMessageCount   int
	ReplayBytes          int
	Truncated            bool
	OmittedCount         int
	SourceTurnInProgress bool
	ThroughTurnID        string
	FirstPrompt          string
	Replayed             bool
	ChildDeleted         bool
	ChildSessionID       string
}

DeriveResult is the outcome of one continue or fork, fresh or replayed from its receipt.

type DeriveRuntime

type DeriveRuntime struct {
	Provider        string
	Model           string
	ReasoningEffort string
	Speed           speedpkg.Speed
	ACPOptions      []acp.SessionConfigOptionSelection
}

DeriveRuntime is an explicit runtime for the derived session's first bind.

type DeriveSeed

type DeriveSeed string

DeriveSeed names how a derived session is seeded.

const (
	// DeriveSeedReplay seeds the child with the bounded carried context.
	DeriveSeedReplay DeriveSeed = store.SessionDerivationSeedReplay
	// DeriveSeedNativeFork seeds the child with the agent's own session clone.
	DeriveSeedNativeFork DeriveSeed = store.SessionDerivationSeedNativeFork
)

type Disposition

type Disposition string
const (
	DispositionDirect       Disposition = "direct"
	DispositionSteering     Disposition = "steering"
	DispositionQueued       Disposition = "queued"
	DispositionInterrupting Disposition = "interrupting"
)

type EffectCertainty

type EffectCertainty string

EffectCertainty classifies whether an external effect is proven absent.

const (
	// EffectKnownFalse proves no target effect crossed its durable linearization.
	EffectKnownFalse EffectCertainty = "known-false"
	// EffectUnknown means the caller must not retry with a different identity.
	EffectUnknown EffectCertainty = "unknown"
)

type EnsureCreatedOutcome

type EnsureCreatedOutcome string

EnsureCreatedOutcome is the exhaustive idempotent creation result.

const (
	EnsureCreatedOutcomeCreated       EnsureCreatedOutcome = "created"
	EnsureCreatedOutcomeExistingMatch EnsureCreatedOutcome = "existing-match"
)

type EnsureCreatedResult

type EnsureCreatedResult struct {
	SessionID string
	Outcome   EnsureCreatedOutcome
}

EnsureCreatedResult identifies the created or identity-matched session.

type ErrSubagentIsolationFailed

type ErrSubagentIsolationFailed struct {
	Cause  string
	Detail string
	Err    error
}

func (*ErrSubagentIsolationFailed) Error

func (*ErrSubagentIsolationFailed) Unwrap

func (e *ErrSubagentIsolationFailed) Unwrap() error

type EventHooks

EventHooks groups event-record persistence hook dispatch.

type EventReadCloser

type EventReadCloser = store.EventReadCloser

EventReadCloser is the read-only per-session storage surface consumed by query paths.

type EventRecorder

type EventRecorder = store.EventRecorder

EventRecorder is the per-session storage surface consumed by session/.

type FallbackRoute

type FallbackRoute struct {
	Provider        string
	Model           string
	ReasoningEffort string
	Speed           speedpkg.Speed
	ACPOptions      []acp.SessionConfigOptionSelection
	// Command is the route's explicit launch command (its account); empty inherits the
	// provider-aware resolution. It never leaves the resolver boundary as text.
	Command    string
	SessionEnv compozyconfig.SessionEnv
}

FallbackRoute is one ordered pre-acceptance route for a work session.

type FinalizationNotifier

type FinalizationNotifier interface {
	OnSessionFinalizing(ctx context.Context, session *Session)
}

FinalizationNotifier is an optional lifecycle seam invoked after the process stop, but before the recorder closes and the durable ledger is materialized.

type ForkDriver

type ForkDriver interface {
	ForkSession(ctx context.Context, proc *AgentProcess, cwd string) (acp.ForkSessionResult, error)
}

ForkDriver is the optional driver surface for ACP session/fork on a bound process. The clone's traffic never reaches the process's bound session (ADR-003).

type ForkSessionOpts

type ForkSessionOpts struct {
	SourceSessionID string
	WorkspaceID     string
	ProfileID       string
	// MessageID is the durable user message to cut through; "" forks the whole session.
	MessageID      string
	Name           string
	IdempotencyKey string
	Fences         DeriveFences
}

ForkSessionOpts forks a user session with the same agent, runtime, and account; the whole conversation, or through one durable user message and its turn.

type GoalBlockingIssue

type GoalBlockingIssue struct {
	ID   string
	Note string
}

GoalBlockingIssue is one public verdict blocker without Loop/gate package coupling.

type GoalCommand

type GoalCommand struct {
	Verb          string
	Objective     string
	ExpectedRunID string
	Runtime       *RuntimeSelection
}

GoalCommand is one closed `/goal` command parsed at authenticated operator ingress.

func ParseGoalCommand

func ParseGoalCommand(message string) (GoalCommand, bool, error)

ParseGoalCommand recognizes the exact leading `/goal` namespace and closed reserved verbs.

type GoalCommandError

type GoalCommandError struct {
	Code GoalReasonCode
	Err  error
}

GoalCommandError carries one deterministic parser reason.

func (*GoalCommandError) Error

func (e *GoalCommandError) Error() string

func (*GoalCommandError) Unwrap

func (e *GoalCommandError) Unwrap() error

type GoalCommandHandler

type GoalCommandHandler interface {
	Handle(
		context.Context,
		string,
		string,
		PromptCaller,
		GoalCommand,
	) (GoalDispatchDecision, error)
}

GoalCommandHandler is the daemon-owned command execution boundary.

type GoalCommandHandlerFunc

type GoalCommandHandlerFunc func(
	context.Context,
	string,
	string,
	PromptCaller,
	GoalCommand,
) (GoalDispatchDecision, error)

GoalCommandHandlerFunc adapts a function to GoalCommandHandler.

func (GoalCommandHandlerFunc) Handle

func (f GoalCommandHandlerFunc) Handle(
	ctx context.Context,
	workspaceID string,
	sessionID string,
	caller PromptCaller,
	command GoalCommand,
) (GoalDispatchDecision, error)

Handle implements GoalCommandHandler.

type GoalCommandOutcome

type GoalCommandOutcome string

GoalCommandOutcome is the session-domain structured Goal result vocabulary.

const (
	GoalOutcomeStarted  GoalCommandOutcome = "started"
	GoalOutcomeReplaced GoalCommandOutcome = "replaced"
	GoalOutcomeStatus   GoalCommandOutcome = "status"
	GoalOutcomePaused   GoalCommandOutcome = "paused"
	GoalOutcomeResumed  GoalCommandOutcome = "resumed"
	GoalOutcomeCleared  GoalCommandOutcome = "cleared"
	GoalOutcomeError    GoalCommandOutcome = "error"
)

type GoalCommandResult

type GoalCommandResult struct {
	Outcome       GoalCommandOutcome
	ReasonCode    *GoalReasonCode
	Snapshot      *GoalSnapshot
	ReplacedRunID *string
}

GoalCommandResult is the session-domain structured command envelope.

type GoalContextSnapshot

type GoalContextSnapshot struct {
	State      string
	Used       *int64
	Size       *int64
	Ratio      *float64
	NudgeRatio float64
	ReportedAt *time.Time
}

GoalContextSnapshot is the checkpoint-pinned context telemetry projection.

type GoalCriterionResult

type GoalCriterionResult struct {
	ID             string
	Type           string
	Outcome        string
	Passed         bool
	Broken         bool
	ExitCode       *int
	Stdout         string
	Stderr         string
	Score          *float64
	Evidence       json.RawMessage
	BlockingIssues []GoalBlockingIssue
	Warnings       []GoalDiagnosticWarning
	Payload        json.RawMessage
}

GoalCriterionResult is one sanitized Goal judge criterion result.

type GoalDiagnosticWarning

type GoalDiagnosticWarning struct {
	Code    string
	Message string
}

GoalDiagnosticWarning is one non-terminal Goal judge diagnostic.

type GoalDispatchDecision

type GoalDispatchDecision struct {
	Kind             GoalDispatchKind
	Result           *GoalCommandResult
	RewrittenMessage string
	BypassGoalParse  bool
	BusyPolicy       string
	BusyReason       GoalReasonCode
}

GoalDispatchDecision returns either structured JSON or an ordinary streamed prompt rewrite.

type GoalDispatchKind

type GoalDispatchKind string

GoalDispatchKind selects a structured response or ordinary prompt continuation.

const (
	GoalDispatchRespond GoalDispatchKind = "respond"
	GoalDispatchPrompt  GoalDispatchKind = "prompt"
)

type GoalEvent

type GoalEvent struct {
	EventID         string
	SessionID       string
	SyntheticTurnID string
	AgentName       string
	Type            string
	Content         []byte
	CreatedAt       time.Time
}

GoalEvent is one deterministic Goal projection event for a session database.

func (GoalEvent) Validate

func (e GoalEvent) Validate() error

Validate enforces the closed Goal projection event shape.

type GoalObjectiveContract

type GoalObjectiveContract struct {
	Objective   string
	Verify      []string
	Constraints []string
}

GoalObjectiveContract is the line-oriented free-form objective subset.

func ParseGoalObjective

func ParseGoalObjective(raw string) (GoalObjectiveContract, error)

ParseGoalObjective extracts exact lowercase verify/constraints clauses without creating commands.

type GoalPromptMeta

type GoalPromptMeta struct {
	Kind          string
	RunID         string
	NodeID        string
	Generation    int64
	ItemIndex     int
	Turn          *int
	PromptAttempt int
	PromptID      string
}

GoalPromptMeta classifies one engine-owned Goal prompt in persisted transcript events.

type GoalReasonCode

type GoalReasonCode string

GoalReasonCode is a stable machine-readable Goal outcome or transition cause.

const (
	GoalReasonNotActive           GoalReasonCode = "goal_not_active"
	GoalReasonReplaceRequired     GoalReasonCode = "goal_replace_required"
	GoalReasonReplaceStale        GoalReasonCode = "goal_replace_stale"
	GoalReasonObjectiveRequired   GoalReasonCode = "goal_objective_required"
	GoalReasonObjectiveTooLarge   GoalReasonCode = "goal_objective_too_large"
	GoalReasonContractClauseEmpty GoalReasonCode = "goal_contract_clause_empty"
	GoalReasonCommandInvalid      GoalReasonCode = "goal_command_invalid"
	GoalReasonDraftRequiresIdle   GoalReasonCode = "goal_draft_requires_idle"
	GoalReasonRuntimeInvalid      GoalReasonCode = "goal_runtime_invalid"
	GoalReasonCallerUnauthorized  GoalReasonCode = "goal_caller_unauthorized"
)

type GoalSessionStopHandler

type GoalSessionStopHandler interface {
	StopSessionGoals(context.Context, *Info) error
}

GoalSessionStopHandler cancels session-origin Goals when the operator stops their session.

type GoalSnapshot

type GoalSnapshot struct {
	RunID           string
	NodeID          string
	Objective       string
	OriginSessionID string
	BoundSessionID  string
	Status          string
	RunStatus       string
	Cause           *GoalReasonCode
	TurnsUsed       int
	TurnLimit       int
	Live            bool
	ContractSummary string
	LastVerdict     *GoalVerdictSummary
	Context         GoalContextSnapshot
}

GoalSnapshot is the canonical newest session-origin Goal projection.

type GoalTurn

type GoalTurn struct {
	Seq            int64
	Generation     int64
	NodeID         string
	ItemIndex      int
	Turn           int
	PromptAttempt  int
	SessionID      string
	BindingHandle  string
	BindingEpoch   int64
	PromptID       string
	ResultStatus   *string
	ReasonCode     *GoalReasonCode
	StopReason     *string
	VerdictOutcome *string
	BlockingIssues []GoalBlockingIssue
	Criteria       []GoalCriterionResult
	Warnings       []GoalDiagnosticWarning
	EvidenceRef    *string
	PromptRef      *string
	TokensUsed     *int64
	ActorKind      string
	ActorID        string
	StartedAt      time.Time
	EndedAt        *time.Time
}

GoalTurn is one immutable-start, optionally terminal Goal audit row.

type GoalTurnPage

type GoalTurnPage struct {
	Turns        []GoalTurn
	NextAfterSeq *int64
}

GoalTurnPage is one run-wide monotonic cursor page.

type GoalVerdictSummary

type GoalVerdictSummary struct {
	Outcome        string
	BlockingIssues []GoalBlockingIssue
	EvidenceRef    *string
	EvaluatedAt    time.Time
}

GoalVerdictSummary is the latest evaluated Goal verdict.

type HealthRecoveryResult

type HealthRecoveryResult struct {
	RefreshedActive int
	Recomputed      int
	MarkedStale     int64
}

HealthRecoveryResult summarizes one metadata-only restart recovery pass.

type HealthStore

type HealthStore interface {
	UpsertSessionHealth(ctx context.Context, health heartbeat.SessionHealth) (heartbeat.SessionHealth, error)
	GetSessionHealth(ctx context.Context, sessionID string) (heartbeat.SessionHealth, error)
	ListSessionHealth(ctx context.Context, query heartbeat.SessionHealthListQuery) ([]heartbeat.SessionHealth, error)
	ListSessionHealthByIDs(ctx context.Context, sessionIDs []string) ([]heartbeat.SessionHealth, error)
	ListSessionHealthRecoveryInputs(ctx context.Context, limit int) ([]heartbeat.SessionHealth, error)
	MarkSessionHealthStale(ctx context.Context, cutoff time.Time, updatedAt time.Time) (int64, error)
}

HealthStore is the durable store used by metadata-only session health.

type HookSet

type HookSet struct {
	Session         LifecycleHooks
	RuntimeRecovery RuntimeRecoveryHooks
	Prompt          PromptHooks
	Events          EventHooks
	Agent           AgentHooks
	Conversation    ConversationHooks
	Tools           ToolHooks
	Compaction      CompactionHooks
	Spawn           SpawnHooks
	AuthoredContext AuthoredContextHooks
	Attention       AttentionHooks
}

HookSet collects the grouped session hook domains. Nil groups are treated as no-op implementations so callers only provide the domains they exercise.

type HostedMCPLaunchRequest

type HostedMCPLaunchRequest struct {
	SessionID   string
	ProfileID   string
	WorkspaceID string
	AgentName   string
}

HostedMCPLaunchRequest describes the session identity for a hosted MCP entry.

type HostedMCPLauncher

type HostedMCPLauncher interface {
	Launch(ctx context.Context, req HostedMCPLaunchRequest) (compozyconfig.MCPServer, error)
	ArmLaunch(ctx context.Context, sessionID string) error
	BindRun(ctx context.Context, sessionID, runID string, generation int64) error
	ReleaseRun(sessionID, runID string, generation int64)
	CancelLaunch(sessionID string)
	ReleaseSession(sessionID string)
}

HostedMCPLauncher mints and releases session-bound hosted MCP launch records.

type IDGenerator

type IDGenerator func() (string, error)

IDGenerator returns a unique identifier or the entropy failure that prevented allocation.

type IdempotentSessionCreator

type IdempotentSessionCreator interface {
	EnsureCreated(context.Context, CreateOpts) (EnsureCreatedResult, error)
}

IdempotentSessionCreator creates one preallocated session or reuses its exact identity.

type Info

type Info struct {
	BoardColumn BoardColumn
	ParentTitle string
	Children    *store.SessionBoardCounts

	VerdictOnly              bool `json:"-"`
	Supervision              *SupervisionState
	BusyInput                *BusyInputState
	ID                       string
	ProfileID                string
	Name                     string
	AgentName                string
	Provider                 string
	ProviderHomePolicy       compozyconfig.ProviderHomePolicy
	Model                    string
	ReasoningEffort          string
	Speed                    speedpkg.Speed
	ACPOptions               []acp.SessionConfigOptionSelection
	SpeedResolution          *speedpkg.Resolution
	RuntimeStatus            RuntimeStatus
	RuntimeTransition        RuntimeTransitionStrategy
	RuntimeFailure           string
	RuntimeGeneration        int64
	RuntimeRecovery          *store.SessionRuntimeRecovery
	SelectedRuntime          *RuntimeSelection
	RuntimeSelectionRevision int64
	EffectiveWorkspaceAccess string
	EffectivePermissions     string
	WorkspaceID              string
	Workspace                string
	WorktreeID               string
	Type                     Type
	Lineage                  *store.SessionLineage
	// Derivation is present only on continued or forked children.
	Derivation             *store.SessionDerivation
	State                  State
	PendingPermission      bool
	StopReason             store.StopReason
	StopCause              StopCause
	StopEscalated          bool
	StopVerificationFailed bool
	StopDetail             string
	Failure                *store.SessionFailure
	ACPSessionID           string
	ACPCaps                acp.Caps
	ACPCapsKnown           bool
	AdvertisedCommands     []store.SessionAdvertisedCommand
	Liveness               *store.SessionLivenessMeta
	SoulSnapshotID         string
	SoulDigest             string
	ParentSoulDigest       string
	AttachedTo             string
	AttachExpiresAt        *time.Time
	TranscriptEpoch        int64
	PendingPermissionCount int
	PendingClarifyCount    int
	AttentionRevision      int64
	LastSettledRevision    int64
	LastSeenRevision       int64
	LastSeenAt             *time.Time
	AttentionChangedAt     *time.Time
	PendingInteractions    []store.PendingInteraction
	ArchivedAt             *time.Time
	CreatedAt              time.Time
	UpdatedAt              time.Time
	// contains filtered or unexported fields
}

Info is the external read model returned by session list/get operations.

func (*Info) EffectiveRuntime

func (info *Info) EffectiveRuntime() RuntimeSelection

EffectiveRuntime projects the latest provider observations while Info retains persisted intent.

func (*Info) RequestedRuntime

func (info *Info) RequestedRuntime() RuntimeSelection

RequestedRuntime returns the persisted intent of the current or last binding.

type InputQueueSummary

type InputQueueSummary struct {
	QueueGeneration int64
	PendingInputs   int
	Cap             int
}

InputQueueSummary is the session package projection of durable busy-input queue state.

type LifecycleHooks

LifecycleHooks groups create/resume/stop session lifecycle hook dispatch.

type ListPage

type ListPage struct {
	Sessions   []*Info
	NextCursor string
	HasMore    bool
	Total      int
	Limit      int
	// Placements carries folder membership for page sessions that have one.
	Placements map[string]store.SessionPlacement
}

ListPage contains one bounded public session catalog result.

type ListQuery

type ListQuery struct {
	Columns         []string
	HideChildren    bool
	Subagents       string
	ReadScope       store.ReadScope
	WorkspaceID     string
	WorkspaceIDs    []string
	AllWorkspaces   bool
	WorktreeID      string
	State           string
	SessionType     Type
	AgentName       string
	ParentSessionID string
	RootSessionID   string
	SearchFields    string
	Search          string
	Resumable       bool
	AttentionOnly   bool
	Badges          []Badge
	Archive         store.SessionArchiveFilter
	Sort            string
	Cursor          string
	Limit           int
	SkipTotal       bool
}

ListQuery describes one public session catalog page.

type LookupState

type LookupState string

type MCPResolver

type MCPResolver interface {
	Resolve(skills []*skillspkg.Skill) []compozyconfig.MCPServer
}

MCPResolver resolves skill-declared MCP servers into runtime config entries.

type ManagedInputClaim

type ManagedInputClaim struct {
	Owner       ManagedInputOwner
	RequestedAt time.Time
}

ManagedInputClaim asks the daemon lifecycle to perform the durable start linearization.

type ManagedInputEffectError

type ManagedInputEffectError struct {
	Owner      ManagedInputOwner
	Certainty  EffectCertainty
	ReasonCode string
	Finalized  bool
	Err        error
}

ManagedInputEffectError carries typed certainty through errors.As.

func (*ManagedInputEffectError) Error

func (e *ManagedInputEffectError) Error() string

func (*ManagedInputEffectError) Unwrap

func (e *ManagedInputEffectError) Unwrap() error

type ManagedInputLifecycle

type ManagedInputLifecycle interface {
	BeginSubmission(context.Context, ManagedInputClaim) (ManagedInputSubmission, error)
	RecordDriverAttached(context.Context, ManagedInputReceipt) error
	RecordRejected(context.Context, ManagedInputRejection) error
	RecordAmbiguous(context.Context, ManagedInputReceipt) error
	RecordTerminal(context.Context, ManagedInputTerminal) error
	Revoke(context.Context, ManagedInputOwner, string) error
}

ManagedInputLifecycle is the neutral daemon callback used inside the real prompt slot.

type ManagedInputOwner

type ManagedInputOwner struct {
	QueueEntryID  string
	SessionID     string
	OwnerKind     string
	LoopRunID     string
	TaskRunID     string
	RunGeneration int64
	PromptAttempt int
	ControlEpoch  int64
	BindingEpoch  int64
	PromptID      string
	PromptKind    string
}

ManagedInputOwner is the complete identity persisted on a managed queue row.

type ManagedInputPromptMeta

type ManagedInputPromptMeta struct {
	LoopRunID     string
	NodeID        string
	PromptID      string
	Kind          string
	Generation    int64
	ItemIndex     int
	PromptAttempt int
	Turn          *int
}

ManagedInputPromptMeta is persisted with transcript events without importing Loop.

type ManagedInputReceipt

type ManagedInputReceipt struct {
	Owner         ManagedInputOwner
	DispatchToken string
	DriverTurnID  string
	ReasonCode    string
}

ManagedInputReceipt correlates post-claim driver evidence.

type ManagedInputRejection

type ManagedInputRejection struct {
	Owner            ManagedInputOwner
	ReasonCode       string
	EffectKnownFalse bool
}

ManagedInputRejection records a pre-claim effect-known-false rejection.

type ManagedInputSubmission

type ManagedInputSubmission struct {
	Delivery      PromptDelivery
	Owner         ManagedInputOwner
	PromptMeta    ManagedInputPromptMeta
	DispatchToken string
	BudgetVersion int64
	StartedAt     time.Time
	UsageReporter ManagedInputUsageReporter
}

ManagedInputSubmission proves a claim/start commit and returns its one-time token.

type ManagedInputTerminal

type ManagedInputTerminal struct {
	Owner          ManagedInputOwner
	DispatchToken  string
	DriverTurnID   string
	Outcome        string
	Text           string
	Structured     []byte
	EventStartSeq  int64
	EventEndSeq    int64
	TokensUsed     int64
	TokensReported bool
	StopReason     acp.PromptStopReason
	ReasonCode     string
	TerminalAt     time.Time
}

ManagedInputTerminal is the exact persisted terminal evidence from the prompt pump.

type ManagedInputUsageReporter

type ManagedInputUsageReporter interface {
	ReportActionTokensUsed(int64)
}

ManagedInputUsageReporter receives cumulative usage for one managed operation.

type Manager

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

Manager owns active session lifecycle and runtime orchestration.

func NewManager

func NewManager(opts ...Option) (*Manager, error)

NewManager constructs a session manager with sensible defaults.

func (*Manager) AcquireWorktreeDeliveryFence

func (m *Manager) AcquireWorktreeDeliveryFence(
	ctx context.Context,
	workspaceID, worktreeID, callerID string,
) (func(), error)

AcquireWorktreeDeliveryFence excludes new and resumed runtimes while the exact bound session hands its checkout to daemon-owned delivery. Other sessions are never stopped by this operation.

func (*Manager) ActivePromptRun

func (m *Manager) ActivePromptRun(ctx context.Context, sessionID string) (PromptRunIdentity, error)

ActivePromptRun returns the complete identity of the session's active prompt.

func (*Manager) AddTurnEndNotifier

func (m *Manager) AddTurnEndNotifier(fn TurnEndNotifier)

AddTurnEndNotifier appends a post-construction callback without replacing callbacks already installed by other daemon subsystems.

func (*Manager) AdoptSession

func (m *Manager) AdoptSession(
	ctx context.Context,
	workspaceID string,
	sessionID string,
	parentSessionID string,
) (*Info, error)

AdoptSession makes a parentless user session a provenance child of another user session in the same workspace and profile. The session's subtree is re-rooted under the new parent's root; governance fields are unchanged.

func (*Manager) AggregateSessionsByAgent

func (m *Manager) AggregateSessionsByAgent(
	ctx context.Context,
	readScope store.ReadScope,
	workspaceID string,
) (map[string]AgentSessionMetrics, error)

AggregateSessionsByAgent overlays live sessions on durable metrics; an empty workspace selects Global.

func (*Manager) AppendSessionEventIfAbsent

func (m *Manager) AppendSessionEventIfAbsent(ctx context.Context, event GoalEvent) error

AppendSessionEventIfAbsent persists and publishes one deterministic Goal projection event.

func (*Manager) ApplyAutomaticSessionTitle

func (m *Manager) ApplyAutomaticSessionTitle(
	ctx context.Context,
	sessionID string,
	title string,
) (bool, error)

ApplyAutomaticSessionTitle persists one generated title when the user session is still unnamed. Explicit names and an earlier successful generation win.

func (*Manager) ApprovePermission

func (m *Manager) ApprovePermission(
	ctx context.Context,
	id string,
	req acp.ApproveRequest,
) (ApprovalResult, error)

ApprovePermission resolves either a live provider request or its restart-orphaned record.

func (*Manager) Archive

func (m *Manager) Archive(ctx context.Context, workspaceID string, sessionID string) (*Info, error)

Archive removes a stopped session from the default catalog without deleting its history or attachments, which remain readable after unarchive.

func (*Manager) ArchiveWithStop

func (m *Manager) ArchiveWithStop(ctx context.Context, workspaceID string, sessionID string) (*Info, error)

ArchiveWithStop archives a session in one daemon-owned operation: every live member of its archive family is stopped through the normal user stop path, which cancels active turns and cascades to subagents, and the family is then archived. Completed subagents whose sessions the reaper has not stopped yet are stopped here too. A stopped family archives exactly as Archive does. A failed stop leaves the session unarchived and reports ErrSessionArchiveStopFailed.

func (*Manager) AttachSession

func (m *Manager) AttachSession(
	ctx context.Context,
	req store.SessionAttachRequest,
) (store.SessionAttach, error)

AttachSession acquires the durable attach lock before updating the live session snapshot.

func (*Manager) AttentionSummary

func (m *Manager) AttentionSummary(
	ctx context.Context,
	readScope store.ReadScope,
) (store.SessionAttentionSummary, error)

AttentionSummary derives exact counts with the same badge authority used by row payloads.

func (*Manager) AwaitStopped

func (m *Manager) AwaitStopped(ctx context.Context, id string) (StopOutcome, error)

AwaitStopped waits for the shared operation, including an unverified outcome.

func (*Manager) AwaitTurnQuiesced

func (m *Manager) AwaitTurnQuiesced(ctx context.Context, id, turnID string) (TurnCancelOutcome, error)

AwaitTurnQuiesced joins the shared cancellation independently of its request context.

func (*Manager) CancelManagedInputLease

func (m *Manager) CancelManagedInputLease(owner ManagedInputOwner) bool

CancelManagedInputLease cancels only the exact owner lease, never a newer prompt.

func (*Manager) CancelPrompt

func (m *Manager) CancelPrompt(ctx context.Context, id string) (PromptCancelResult, error)

CancelPrompt cancels prompt setup/execution for a known session.

func (*Manager) CancelPromptWithCause

func (m *Manager) CancelPromptWithCause(
	ctx context.Context,
	id string,
	cause PromptCancelCause,
) (PromptCancelResult, error)

func (*Manager) CancelQueuedPrompt

func (m *Manager) CancelQueuedPrompt(ctx context.Context, id string, queueEntryID string) (SendPromptResult, error)

CancelQueuedPrompt cancels one pending busy-input queue entry.

func (*Manager) CancelTurn

func (m *Manager) CancelTurn(ctx context.Context, id, expectedTurn string, cause StopCause) error

CancelTurn requests cancellation of the current turn and preserves the session.

func (*Manager) CaptureRestartInterruptions

func (m *Manager) CaptureRestartInterruptions(ctx context.Context, infos []*Info) error

CaptureRestartInterruptions runs before pending-interaction expiration and history repair.

func (*Manager) CatalogFacets

func (m *Manager) CatalogFacets(ctx context.Context, query ListQuery) (store.SessionCatalogFacetResult, error)

CatalogFacets combines exact durable metadata with authoritative active badges. Search and selected badge do not change population chips; row queries own them.

func (*Manager) ClearConversation

func (m *Manager) ClearConversation(ctx context.Context, id string) (_ *Session, err error)

ClearConversation resets the persisted transcript and ACP conversation context for an existing session while preserving the same session id. The session is restarted on a fresh event store so subsequent prompts start from a clean conversation. Attachments are retained because they remain scoped to the unchanged session identity and may still be referenced outside the cleared epoch.

func (*Manager) ClearPendingInputs

func (m *Manager) ClearPendingInputs(
	ctx context.Context,
	id string,
	caller PromptCaller,
) (ClearPendingInputsResult, error)

func (*Manager) ClearRuntimeSelection

func (m *Manager) ClearRuntimeSelection(ctx context.Context, id string, expectedRevision int64) (*Info, error)

ClearRuntimeSelection removes the durable runtime preference for future prompts.

func (*Manager) CommandCatalog

func (m *Manager) CommandCatalog(ctx context.Context, id string) (commandpkg.Catalog, error)

CommandCatalog returns the authoritative slash command projection for a session.

func (*Manager) CompactionBoundary

func (m *Manager) CompactionBoundary(ctx context.Context, id string) (*int64, error)

func (*Manager) CompactionClearBoundary

func (m *Manager) CompactionClearBoundary(ctx context.Context, id string) (*contextusage.ClearedBy, error)

func (*Manager) Compactions

func (m *Manager) Compactions(ctx context.Context, id string) ([]CompactionEnvelope, error)

func (*Manager) ConfigurePullRequests

func (m *Manager) ConfigurePullRequests(reader PullRequestReader, branches BranchSnapshotReader)

ConfigurePullRequests connects the optional read model at daemon composition.

func (*Manager) ContextEvents

func (m *Manager) ContextEvents(ctx context.Context, id string) (ContextEvents, error)

ContextEvents derives context history and its boundaries from one ledger snapshot.

func (*Manager) ContinueSession

func (m *Manager) ContinueSession(ctx context.Context, opts ContinueSessionOpts) (DeriveResult, error)

ContinueSession continues a user session with another agent, runtime, or declared route. The source is only read; the child is committed with its derive receipt in one transaction; a retry with the same key returns the recorded outcome.

func (*Manager) Create

func (m *Manager) Create(ctx context.Context, opts CreateOpts) (_ *Session, err error)

Create resolves an agent definition, opens the session store, and starts a new runtime session.

func (*Manager) CreateAccepted

func (m *Manager) CreateAccepted(ctx context.Context, opts CreateAcceptedOpts) (*Info, error)

CreateAccepted durably creates an active logical user session. The ACP process is intentionally left unbound until the first prompt supplies its runtime snapshot.

func (*Manager) CreateSessionFolder

func (m *Manager) CreateSessionFolder(
	ctx context.Context,
	scope store.SessionLayoutScope,
	name string,
) (store.SessionFolder, error)

CreateSessionFolder adds a named folder at the top of the folder order.

func (*Manager) CreateWorktreeForkAccepted

func (m *Manager) CreateWorktreeForkAccepted(
	ctx context.Context,
	originSessionID string,
	opts CreateAcceptedOpts,
) (*Info, error)

CreateWorktreeForkAccepted atomically keeps the origin idle while accepting one clean child session.

func (*Manager) CurrentTurnEffectiveHop

func (m *Manager) CurrentTurnEffectiveHop(ctx context.Context, sessionID string) (int, error)

CurrentTurnEffectiveHop includes the pre-provider fence and every durable input in the active turn.

func (*Manager) Delete

func (m *Manager) Delete(ctx context.Context, id string) (err error)

Delete removes one session from active runtime state and persisted history.

func (*Manager) DeleteSessionFolder

func (m *Manager) DeleteSessionFolder(ctx context.Context, scope store.SessionLayoutScope, folderID string) error

DeleteSessionFolder removes a folder and returns its sessions to the root.

func (*Manager) Deliveries

func (m *Manager) Deliveries(ctx context.Context, id string) ([]DeliveryEventEnvelope, error)

func (*Manager) DerivePreview

func (m *Manager) DerivePreview(
	ctx context.Context,
	workspaceID string,
	sourceSessionID string,
	messageID string,
) (DerivePreview, error)

DerivePreview reports what a continue or fork of the source would carry right now, from the same snapshot and bounding the derive uses. It never writes and never repairs the source.

func (*Manager) DetachSession

func (m *Manager) DetachSession(ctx context.Context, workspaceID string, sessionID string) (*Info, error)

DetachSession makes an adopted (provenance) child a top-level session again, re-rooting its subtree at the session itself.

func (*Manager) EnqueueSyntheticWake

func (m *Manager) EnqueueSyntheticWake(
	ctx context.Context,
	id string,
	opts SyntheticPromptOpts,
) (store.SessionInputQueueEntry, error)

EnqueueSyntheticWake admits daemon-owned work to the durable queue and returns only its receipt. Unlike PromptSynthetic it opens no delivery stream or persistence observer: the shared queue pump owns execution, so wake producers that never read the turn (monitors) cost one queue row and one pump nudge. A stable opts.MessageID makes a retried admission return the existing row.

func (*Manager) EnsureCreated

func (m *Manager) EnsureCreated(ctx context.Context, opts CreateOpts) (EnsureCreatedResult, error)

EnsureCreated creates one preallocated session exactly once by immutable creation identity.

func (*Manager) EventMetadata

func (m *Manager) EventMetadata(
	ctx context.Context,
	id string,
	query store.EventQuery,
) (events []store.EventMetadata, err error)

func (*Manager) Events

func (m *Manager) Events(
	ctx context.Context,
	id string,
	query store.EventQuery,
) (events []store.SessionEvent, err error)

Events returns persisted session events for active or stopped sessions.

func (*Manager) ExpireRestartInteractions

func (m *Manager) ExpireRestartInteractions(ctx context.Context, sessionID string) (int, error)

ExpireRestartInteractions terminalizes decisions whose provider turn was lost during restart.

func (*Manager) ForkSession

func (m *Manager) ForkSession(ctx context.Context, opts ForkSessionOpts) (DeriveResult, error)

ForkSession forks a user session with the same agent: the whole conversation through its last settled turn, or through one durable user message and its turn. When the agent can clone its own session (ADR-003) the child loads that clone at its first bind; otherwise, and as the clone's fallback, it carries the bounded context.

func (*Manager) Get

func (m *Manager) Get(id string) (*Session, bool)

Get returns the active in-memory session by id.

func (*Manager) GetSessionHealth

func (m *Manager) GetSessionHealth(ctx context.Context, id string) (heartbeat.SessionHealth, error)

GetSessionHealth returns a route-ready metadata-only health read model.

func (*Manager) HasPendingRestart

func (m *Manager) HasPendingRestart(ctx context.Context, id string) (bool, error)

HasPendingRestart reports unsettled restart work without scanning the complete transcript.

func (*Manager) History

func (m *Manager) History(
	ctx context.Context,
	id string,
	query store.EventQuery,
) (history []store.TurnHistory, err error)

History returns turn-grouped persisted session events for active or stopped sessions.

func (*Manager) InputQueueSummary

func (m *Manager) InputQueueSummary(ctx context.Context, id string) (InputQueueSummary, error)

InputQueueSummary returns the durable busy-input state for one session.

func (*Manager) IsPrompting

func (m *Manager) IsPrompting(id string) bool

IsPrompting reports whether the target session currently has an in-flight prompt setup or active turn.

func (*Manager) LatestSessionEventByType

func (m *Manager) LatestSessionEventByType(
	ctx context.Context,
	sessionID string,
	eventType string,
) (*store.SessionEvent, error)

LatestSessionEventByType returns the newest persisted event for one session event type.

func (*Manager) LatestSettledTurn

func (m *Manager) LatestSettledTurn(ctx context.Context, id string) (SettledTurn, error)

func (*Manager) List

func (m *Manager) List() []*Info

List returns active in-memory sessions in stable order.

func (*Manager) ListAll

func (m *Manager) ListAll(ctx context.Context) ([]*Info, error)

ListAll returns active and stopped sessions discovered from on-disk metadata.

func (*Manager) ListForWorkspace

func (m *Manager) ListForWorkspace(ctx context.Context, workspaceID string) ([]*Info, error)

ListForWorkspace hydrates only sessions belonging to one registered workspace.

func (*Manager) ListLive

func (m *Manager) ListLive(ctx context.Context) ([]*Info, error)

ListLive includes retained live sessions whose runtimes have not been rebound after restart.

func (*Manager) ListPage

func (m *Manager) ListPage(ctx context.Context, query ListQuery) (ListPage, error)

ListPage returns a stable, bounded union of durable and active sessions. Active snapshots replace their durable rows before filtering, counting, and cutting.

func (*Manager) ListPendingInputs

func (m *Manager) ListPendingInputs(ctx context.Context, id string) ([]PendingInput, error)

ListPendingInputs returns the daemon-owned current-generation input queue.

func (*Manager) ListSessionFolders

func (m *Manager) ListSessionFolders(
	ctx context.Context,
	scope store.SessionLayoutScope,
) ([]store.SessionFolder, error)

ListSessionFolders returns one profile's folders inside a workspace.

func (*Manager) ListSessionHealth

func (m *Manager) ListSessionHealth(
	ctx context.Context,
	query heartbeat.SessionHealthListQuery,
) ([]heartbeat.SessionHealth, error)

ListSessionHealth refreshes active rows, marks stale rows, and returns persisted health.

func (*Manager) MoveSession

func (m *Manager) MoveSession(
	ctx context.Context,
	scope store.SessionLayoutScope,
	sessionID string,
	folderID string,
) error

MoveSession moves a session to the end of a folder, or to the root when folderID is empty.

func (*Manager) NotifyAgentExtension

func (m *Manager) NotifyAgentExtension(
	ctx context.Context,
	sessionID, method string,
	params any,
) error

NotifyAgentExtension delivers one fire-and-forget extension notification to the live agent process.

func (*Manager) NotifyManagedInputReady

func (m *Manager) NotifyManagedInputReady(sessionID string)

NotifyManagedInputReady runs the unified selector for an idle session.

func (*Manager) PendingInteractions

func (m *Manager) PendingInteractions(
	ctx context.Context,
	sessionID string,
	statuses []string,
) ([]store.PendingInteraction, error)

PendingInteractions lists the sanitized canonical records for one session.

func (*Manager) PopulateSessionRelations

func (m *Manager) PopulateSessionRelations(ctx context.Context, info *Info) error

PopulateSessionRelations enriches one already-authorized detail with scoped family metadata.

func (*Manager) PrepareDaemonShutdown

func (m *Manager) PrepareDaemonShutdown(ctx context.Context, restart bool) error

PrepareDaemonShutdown records intent before brokers or subprocesses can settle an interrupted turn.

func (*Manager) PrepareWorkspaceRemoval

func (m *Manager) PrepareWorkspaceRemoval(
	ctx context.Context,
	workspaceID string,
) (workspacepkg.UnregisterPreparation, error)

func (*Manager) PromotePendingInputToSteer

func (m *Manager) PromotePendingInputToSteer(
	ctx context.Context,
	id string,
	entryID string,
	opts PromotePendingInputOpts,
) (SendPromptResult, error)

PromotePendingInputToSteer atomically prioritizes queued input and interrupts its target turn.

func (*Manager) Prompt

func (m *Manager) Prompt(ctx context.Context, id string, msg string) (<-chan acp.AgentEvent, error)

Prompt sends one prompt turn to an active session and mirrors the runtime stream into storage and observers.

func (*Manager) PromptAdmissionReplayOrigin

func (m *Manager) PromptAdmissionReplayOrigin(
	ctx context.Context,
	workspaceID, sessionID, messageID, idempotencyKey string,
) (bool, *acp.PromptOriginMeta, error)

PromptAdmissionReplayOrigin reports whether this message identity was already admitted for the target and returns the origin frozen with it (nil for operator or pre-origin admissions). A retry of an admitted send replays that receipt even when a new send from the caller would now be refused.

func (*Manager) PromptSynthetic

func (m *Manager) PromptSynthetic(
	ctx context.Context,
	id string,
	opts SyntheticPromptOpts,
) (<-chan acp.AgentEvent, error)

PromptSynthetic admits daemon-owned work to the shared durable queue.

func (*Manager) PromptWithOpts

func (m *Manager) PromptWithOpts(ctx context.Context, id string, opts PromptOpts) (<-chan acp.AgentEvent, error)

PromptWithOpts sends one prompt turn with daemon-local provenance metadata.

func (*Manager) PublishClarifyEvent

func (m *Manager) PublishClarifyEvent(ctx context.Context, event toolspkg.ClarifyEvent) error

PublishClarifyEvent durably records one typed clarification transition before SSE publication.

func (*Manager) PublishOperatorNotification

func (m *Manager) PublishOperatorNotification(
	ctx context.Context,
	req NotifyRequest,
) (NotifyResult, error)

PublishOperatorNotification validates, rate-limits, and publishes one sanitized event.

func (*Manager) PublishSessionCatalogChanged

func (m *Manager) PublishSessionCatalogChanged(ctx context.Context, sessionID string)

PublishSessionCatalogChanged wakes catalog subscribers for one session whose daemon-owned projection (such as its active monitors) changed outside the session record. An unknown or deleted session publishes nothing.

func (*Manager) PublishWorkspaceCatalogChanged

func (m *Manager) PublishWorkspaceCatalogChanged(workspaceID string, profiles []string)

PublishWorkspaceCatalogChanged wakes catalog and session reads in every affected profile.

func (*Manager) QualifyRestartContinuation

func (m *Manager) QualifyRestartContinuation(ctx context.Context, id string) (bool, error)

QualifyRestartContinuation shares restart safety checks with Loop recovery, whose durable node transition owns retry.

func (*Manager) QuiesceReplyWatches

func (m *Manager) QuiesceReplyWatches(ctx context.Context) error

QuiesceReplyWatches closes the reply-watch service before the daemon stops sessions, so a target settling during shutdown cannot resume a sender that is being stopped. Shutdown closes it again.

func (*Manager) ReconcileDerivedSessionEvents

func (m *Manager) ReconcileDerivedSessionEvents(ctx context.Context, infos []*Info) (int, error)

ReconcileDerivedSessionEvents re-emits session.derived for committed derived children whose ledger row is missing (ADR-007: a crash between the child's commit and the event write). The receipt's immutable outcome is the payload source; a child that already has the event, lost its derivation (cleared conversation), or has no matching receipt is skipped. It runs at boot before new work is admitted and returns the re-emitted count.

func (*Manager) ReconcileInactiveSessions

func (m *Manager) ReconcileInactiveSessions(ctx context.Context) error

ReconcileInactiveSessions recovers retained metadata before runtime admission.

func (*Manager) RecoverPendingInteractions

func (m *Manager) RecoverPendingInteractions(ctx context.Context, sessionID string) (int, error)

RecoverPendingInteractions marks requests from a dead turn as restart-orphaned.

func (*Manager) RecoverPendingStops

func (m *Manager) RecoverPendingStops(ctx context.Context) error

RecoverPendingStops settles verified exits and terminates recovered orphans before boot admits work.

func (*Manager) RecoverSessionHealth

func (m *Manager) RecoverSessionHealth(ctx context.Context) (HealthRecoveryResult, error)

RecoverSessionHealth recomputes persisted rows after daemon restart before wake decisions run.

func (*Manager) RecoverStaleInputDispatches

func (m *Manager) RecoverStaleInputDispatches(ctx context.Context) (int, error)

RecoverStaleInputDispatches settles busy-input leases a previous daemon process left in dispatching so they stop holding queue capacity. Boot calls it before any session can claim new input.

func (*Manager) RefreshSessionPullRequest

func (m *Manager) RefreshSessionPullRequest(ctx context.Context, info *Info) (PullRequestProjection, error)

func (*Manager) RefreshSoul

func (m *Manager) RefreshSoul(ctx context.Context, id string) (SoulRefreshResult, error)

RefreshSoul explicitly refreshes the session's resolved Soul snapshot.

func (*Manager) RefreshSoulWithExpectedDigest

func (m *Manager) RefreshSoulWithExpectedDigest(
	ctx context.Context,
	id string,
	expectedDigest string,
) (SoulRefreshResult, error)

RefreshSoulWithExpectedDigest explicitly refreshes a session Soul snapshot after service-owned CAS.

func (*Manager) Rename

func (m *Manager) Rename(
	ctx context.Context,
	workspaceID string,
	sessionID string,
	name string,
) (*Info, error)

Rename changes the durable display name of one user session without altering its runtime lifecycle or transcript identity.

func (*Manager) RenameSessionFolder

func (m *Manager) RenameSessionFolder(
	ctx context.Context,
	scope store.SessionLayoutScope,
	folderID string,
	name string,
) (store.SessionFolder, error)

RenameSessionFolder changes one folder's display name.

func (*Manager) ReorderSessionFolders

func (m *Manager) ReorderSessionFolders(
	ctx context.Context,
	scope store.SessionLayoutScope,
	folderIDs []string,
) ([]store.SessionFolder, error)

ReorderSessionFolders applies a complete folder order.

func (*Manager) ReorderSessions

func (m *Manager) ReorderSessions(
	ctx context.Context,
	scope store.SessionLayoutScope,
	folderID string,
	sessionIDs []string,
) error

ReorderSessions pins a manual session order inside one container.

func (*Manager) RepairSession

func (m *Manager) RepairSession(
	ctx context.Context,
	opts RepairOpts,
) (result *RepairResult, err error)

RepairSession inspects one persisted session transcript and, when safe, appends terminal repair events for an interrupted final prompt turn.

func (*Manager) ReplacePendingInput

func (m *Manager) ReplacePendingInput(
	ctx context.Context,
	id string,
	entryID string,
	opts ReplacePendingInputOpts,
) (PendingInput, error)

ReplacePendingInput atomically swaps one queued item for a new durable identity.

func (*Manager) ReplyWatches

func (m *Manager) ReplyWatches() ReplyWatchService

func (*Manager) RequestCompaction

func (m *Manager) RequestCompaction(
	ctx context.Context,
	sessionID string,
) (CompactionRequestResult, <-chan acp.AgentEvent, error)

RequestCompaction submits the advertised native command through exclusive prompt admission.

func (*Manager) RequestPermission

func (m *Manager) RequestPermission(
	ctx context.Context,
	id string,
	req acp.RequestPermissionRequest,
) (acp.RequestPermissionResponse, error)

RequestPermission asks an active session's permission path for a tool-call decision.

func (*Manager) RequestStop

func (m *Manager) RequestStop(ctx context.Context, id string, cause StopCause) error

RequestStop starts or joins a session stop without waiting for termination.

func (*Manager) RequestStopWithCause

func (m *Manager) RequestStopWithCause(ctx context.Context, id string, cause StopCause, detail string) error

RequestStopWithCause persists stopping and starts the shared escalation operation.

func (*Manager) ResolveOrphanedClarification

func (m *Manager) ResolveOrphanedClarification(
	ctx context.Context,
	scope toolspkg.Scope,
	requestID string,
	request toolspkg.ClarifyAnswerRequest,
) (toolspkg.ClarifyAnswerResult, error)

ResolveOrphanedClarification atomically records and queues an answer after daemon restart.

func (*Manager) ResolveSpawnWorkspace

func (m *Manager) ResolveSpawnWorkspace(ctx context.Context, parentSessionID, workspaceRef string) (string, error)

ResolveSpawnWorkspace authorizes a spawn's target workspace for the parent through the same workspace-access seam as Spawn, before any transport side effect such as creating a worktree there. An empty ref resolves to the parent's workspace.

func (*Manager) Resume

func (m *Manager) Resume(ctx context.Context, id string) (resumed *Session, err error)

Resume restarts a stopped session from its persisted metadata and event history.

func (*Manager) ResumeInterruptedSession

func (m *Manager) ResumeInterruptedSession(ctx context.Context, id string) (bool, error)

ResumeInterruptedSession consumes a durable interruption through the existing prompt admission owner.

func (*Manager) ResumeInterruptedSessions

func (m *Manager) ResumeInterruptedSessions(ctx context.Context) error

ResumeInterruptedSessions admits ordinary sessions; delegated and task sessions keep their owning recovery path.

func (*Manager) RevokeManagedInput

func (m *Manager) RevokeManagedInput(owner ManagedInputOwner, reason string)

RevokeManagedInput reconciles durable revocation and cancels only the exact in-memory lease.

func (*Manager) RewindConversation

func (m *Manager) RewindConversation(
	ctx context.Context,
	id string,
	opts ConversationRewindOptions,
) (ConversationRewindResult, error)

RewindConversation archives the selected user message and the active suffix, then restarts the same logical session with a fresh ACP conversation context.

func (*Manager) SendPrompt

func (m *Manager) SendPrompt(ctx context.Context, id string, opts SendPromptOpts) (result SendPromptResult, err error)

SendPrompt submits a user-facing prompt and applies busy-input policy when a turn is active.

func (*Manager) SendSpawnPrompt

func (m *Manager) SendSpawnPrompt(ctx context.Context, req SpawnPromptRequest) (SendPromptResult, error)

SendSpawnPrompt admits the first prompt into a freshly spawned child as a session message from its parent with notify_on_complete, so the parent's reply wake carries the child's final answer.

func (*Manager) SessionAgentDefinition

func (m *Manager) SessionAgentDefinition(id string) (compozyconfig.AgentDef, bool)

SessionAgentDefinition returns the concrete definition for one live session.

func (*Manager) SessionEnvironment

func (m *Manager) SessionEnvironment(ctx context.Context, identity PromptRunIdentity) (config.SessionEnv, error)

SessionEnvironment returns only references from the bound runtime, never secret values.

func (*Manager) SessionHealthForPage

func (m *Manager) SessionHealthForPage(
	ctx context.Context,
	infos []*Info,
) (map[string]heartbeat.SessionHealth, error)

SessionHealthForPage derives current health for one bounded catalog page. Durable health is loaded in one query; no session metadata files are opened.

func (*Manager) SessionMessageOrigin

func (m *Manager) SessionMessageOrigin(
	ctx context.Context,
	req MessageOriginRequest,
) (*acp.PromptOriginMeta, error)

SessionMessageOrigin stamps the immutable sender origin for one agent-to-agent message.

A message answering a session that drives the sender's active turn, or one whose in_reply_to names a message that target sent to the sender, keeps the turn's hop instead of adding one: hop measures forwarding depth, not conversation length. The per sender→target rate budget is the flood guard.

func (*Manager) SessionMetadataHealth

func (m *Manager) SessionMetadataHealth(ctx context.Context) (int, loggerpkg.FailureSummary, error)

SessionMetadataHealth reads persisted witnesses without repairing metadata or changing warning cadence.

func (*Manager) SessionOwner

func (m *Manager) SessionOwner(ctx context.Context, sessionID string) (store.SessionOwner, error)

SessionOwner returns the scope that owns a session, proven against the catalog, without repairing its metadata: resolving where a session lives never writes it (a continue/fork source stays byte-for-byte unchanged, ADR-007).

func (*Manager) SessionPresence

func (m *Manager) SessionPresence(
	ctx context.Context,
	sessionID string,
	leaseID string,
	visible bool,
) (string, error)

SessionPresence acquires, renews, or releases one opaque per-client lease.

func (*Manager) SessionPullRequests

func (m *Manager) SessionPullRequests(ctx context.Context, infos []*Info) (map[string]PullRequestProjection, error)

func (*Manager) SetAttentionConfig

func (m *Manager) SetAttentionConfig(cfg compozyconfig.AttentionConfig) error

SetAttentionConfig applies the live notification policy.

func (*Manager) SetBusyInputDefaultMode

func (m *Manager) SetBusyInputDefaultMode(mode string) error

SetBusyInputDefaultMode applies the follow-up preference to subsequent admissions.

func (*Manager) SetGoalCommandHandler

func (m *Manager) SetGoalCommandHandler(handler GoalCommandHandler)

SetGoalCommandHandler installs the late-bound daemon dispatcher before API servers start.

func (*Manager) SetManagedInputLifecycle

func (m *Manager) SetManagedInputLifecycle(lifecycle ManagedInputLifecycle)

SetManagedInputLifecycle installs the late-bound daemon lifecycle adapter.

func (*Manager) SetReplyWatchService

func (m *Manager) SetReplyWatchService(s ReplyWatchService)

func (*Manager) SetRuntimeSelection

func (m *Manager) SetRuntimeSelection(
	ctx context.Context,
	id string,
	selection RuntimeSelection,
	expectedRevision int64,
) (*Info, error)

SetRuntimeSelection durably selects the default runtime for future prompts.

func (*Manager) SetSubagentService

func (m *Manager) SetSubagentService(s SubagentService)

func (*Manager) SetSupervisedWorkRecovery

func (m *Manager) SetSupervisedWorkRecovery(recoverWork SupervisedWorkRecovery)

SetSupervisedWorkRecovery installs the task settlement hook before stop replay or live supervision begins.

func (*Manager) SetTurnEndNotifier

func (m *Manager) SetTurnEndNotifier(fn TurnEndNotifier)

SetTurnEndNotifier installs a post-construction callback invoked after each prompt turn finishes.

func (*Manager) SetWorkSignalSources

func (m *Manager) SetWorkSignalSources(sources ...WorkSignalSource)

SetWorkSignalSources installs the daemon's authoritative inspection adapters.

func (*Manager) SetWorkspaceAccessPolicy

func (m *Manager) SetWorkspaceAccessPolicy(policy workspaceaccess.Policy)

SetWorkspaceAccessPolicy installs the late-bound cross-workspace policy.

func (*Manager) Shutdown

func (m *Manager) Shutdown(ctx context.Context) error

Shutdown releases session-manager background resources after active sessions stop.

func (*Manager) Spawn

func (m *Manager) Spawn(ctx context.Context, opts SpawnOpts) (*Session, error)

Spawn creates a bounded child session after enforcing lineage, TTL, caps, workspace bounds, and permission narrowing.

func (*Manager) Status

func (m *Manager) Status(ctx context.Context, id string) (*Info, error)

Status returns the current session status from memory or on-disk metadata.

func (*Manager) SteerPrompt

func (m *Manager) SteerPrompt(ctx context.Context, id string, opts SteerPromptOpts) (SendPromptResult, error)

SteerPrompt durably accepts guidance that replaces the fenced active turn.

func (*Manager) Stop

func (m *Manager) Stop(ctx context.Context, id string) error

Stop stops an active session and persists the stopped state to disk.

func (*Manager) StopWithCause

func (m *Manager) StopWithCause(ctx context.Context, id string, cause StopCause, detail string) error

StopWithCause waits for the same operation used by asynchronous stop requests.

func (*Manager) StopWithSpawnTTL

func (m *Manager) StopWithSpawnTTL(ctx context.Context, id string, detail string) error

StopWithSpawnTTL stops a spawned session and classifies its prompt state atomically with the lifecycle transition.

func (*Manager) SubprocessHealthSnapshots

func (m *Manager) SubprocessHealthSnapshots() []SubprocessHealthSnapshot

SubprocessHealthSnapshots returns immutable snapshots for active processes that expose health state.

func (*Manager) SubscribeSessionCatalogEvents

func (m *Manager) SubscribeSessionCatalogEvents(
	ctx context.Context,
	scope CatalogScope,
) (<-chan CatalogEvent, func(), error)

SubscribeSessionCatalogEvents registers a request-owned catalog wake stream. The caller must invoke the returned cancel function on every exit.

func (*Manager) SubscribeSessionEventWakes

func (m *Manager) SubscribeSessionEventWakes(
	ctx context.Context,
	sessionID string,
) (<-chan store.SessionEvent, func(), error)

SubscribeSessionEventWakes registers an unfiltered projection wake subscriber.

func (*Manager) SubscribeSessionEvents

func (m *Manager) SubscribeSessionEvents(
	ctx context.Context,
	sessionID string,
	afterSequence int64,
) (<-chan store.SessionEvent, func(), error)

SubscribeSessionEvents registers an in-process stream subscriber for already-persisted session events. Callers must read catch-up events after registration and deduplicate by sequence.

func (*Manager) Supervise

func (m *Manager) Supervise(ctx context.Context, now time.Time) error

Supervise inspects live sessions; the daemon owns its joined periodic cadence.

func (*Manager) TokenUsage

func (m *Manager) TokenUsage(ctx context.Context, id string) (usage []store.TokenUsage, err error)

TokenUsage returns the per-turn usage projection for active or stopped sessions.

func (*Manager) ToolHookContext

func (m *Manager) ToolHookContext(ctx context.Context, sessionID string) context.Context

ToolHookContext attaches the active session's canonical hook audit writers to registry calls.

func (*Manager) TouchSessionPresence

func (m *Manager) TouchSessionPresence(ctx context.Context, id string) (heartbeat.SessionHealth, error)

TouchSessionPresence records an idle metadata-only presence touch for an attachable session.

func (*Manager) TranscriptChanges

func (m *Manager) TranscriptChanges(
	ctx context.Context,
	id string,
	query transcript.ChangeQuery,
) (transcript.ChangePage, error)

TranscriptChanges returns materialized entries shaped after an event cursor.

func (*Manager) TranscriptOutline

func (m *Manager) TranscriptOutline(ctx context.Context, id string) (transcript.OutlineResult, error)

TranscriptOutline returns every retained operator message and its reply preview.

func (*Manager) TranscriptPage

func (m *Manager) TranscriptPage(
	ctx context.Context,
	id string,
	query transcript.PageQuery,
) (transcript.Page, error)

TranscriptPage returns one bounded materialized transcript window.

func (*Manager) TranscriptSearch

func (m *Manager) TranscriptSearch(
	ctx context.Context,
	id string,
	query transcript.SearchQuery,
) (transcript.SearchResult, error)

TranscriptSearch returns bounded literal matches from the session's projection.

func (*Manager) TransportStats

func (m *Manager) TransportStats(sessionID string) (TransportDeliveryStats, error)

TransportStats reports the ephemeral queues used by the active session.

func (*Manager) TurnResult

func (m *Manager) TurnResult(ctx context.Context, sessionID, turnID string) (TurnResult, error)

func (*Manager) Unarchive

func (m *Manager) Unarchive(ctx context.Context, workspaceID string, sessionID string) (*Info, error)

Unarchive restores a session to the default catalog.

func (*Manager) UpgradeSessionDatabase

func (m *Manager) UpgradeSessionDatabase(ctx context.Context, id string) error

UpgradeSessionDatabase lets the daemon migrate retained histories before publishing read-only surfaces. Older schemas and stale rewind baselines open a writer; unknown, ahead, corrupt, or foreign databases retain their refusal unchanged.

func (*Manager) UsageEvents

func (m *Manager) UsageEvents(ctx context.Context, id string) ([]UsageEventEnvelope, error)

func (*Manager) WaitForBadge

func (m *Manager) WaitForBadge(ctx context.Context, req WaitRequest) (outcome WaitOutcome, retErr error)

WaitForBadge blocks until a matching transition, bounded timeout, cancellation, overflow, or target identity loss. Registration precedes the initial snapshot.

func (*Manager) WaitForFinalizations

func (m *Manager) WaitForFinalizations(ctx context.Context) error

WaitForFinalizations blocks until all in-flight finalization routines finish.

func (*Manager) WaitForPromptDrains

func (m *Manager) WaitForPromptDrains(ctx context.Context) error

WaitForPromptDrains blocks until active prompt tasks finish.

func (*Manager) WaitManagedInputLease

func (m *Manager) WaitManagedInputLease(ctx context.Context, owner ManagedInputOwner) error

WaitManagedInputLease waits until the exact prompt pump has persisted its terminal and released.

func (*Manager) WithSoulClaimLock

func (m *Manager) WithSoulClaimLock(ctx context.Context, sessionID string, fn func() error) error

WithSoulClaimLock runs fn while holding the session Soul lock used by refresh.

func (*Manager) WorkingDir

func (m *Manager) WorkingDir(ctx context.Context, sessionID string) (string, error)

WorkingDir returns the directory the session's agent runs in, using the launch precedence (CreationProfile.CWD, else persisted cwd, else execution root) normalized by ResolveSessionCWD.

type MentionReferenceForm

type MentionReferenceForm string

MentionReferenceForm names the session-references block form chosen for a dispatch.

const (
	// MentionReferenceFormReference tells the agent to read each session with compozy__session_history.
	MentionReferenceFormReference MentionReferenceForm = "reference"
	// MentionReferenceFormInline carries a budgeted history tail per referenced session.
	MentionReferenceFormInline MentionReferenceForm = "inline"
	// MentionReferenceFormUnavailable lists the references without any history access.
	MentionReferenceFormUnavailable MentionReferenceForm = "unavailable"
)

type MentionReferenceRenderer

type MentionReferenceRenderer func(
	ctx context.Context,
	target *Session,
	refs []mention.Mention,
	humanIngress bool,
) (MentionReferences, error)

MentionReferenceRenderer renders the session-references text block for one dispatch. humanIngress reports whether the prompt came from human operator ingress.

type MentionReferences

type MentionReferences struct {
	Text     string
	Form     MentionReferenceForm
	Sessions int // referenced sessions still available and rendered
	// SessionIDs lists the rendered sessions in block order; it feeds the delivery manifest.
	SessionIDs []string
}

MentionReferences is the rendered session-references block for one dispatch. Text is empty when no referenced session is still available.

type Mergeable

type Mergeable string

type MessageOriginRequest

type MessageOriginRequest struct {
	SenderSessionID  string
	AgentName        string
	TargetSessionID  string
	InReplyTo        string
	NotifyOnComplete bool
}

MessageOriginRequest describes one agent session sending a message to another session.

type MessageRateLimitError

type MessageRateLimitError struct {
	TargetSessionID string
	Limit           int
	Window          time.Duration
	RetryAfter      time.Duration
}

MessageRateLimitError carries the budget that refused a session message.

func (*MessageRateLimitError) Error

func (e *MessageRateLimitError) Error() string

func (*MessageRateLimitError) Unwrap

func (e *MessageRateLimitError) Unwrap() error

type NativeSubagentEvent

type NativeSubagentEvent struct {
	WorkspaceID        string
	ParentTurnID       string
	ProviderToolCallID string
	ToolName           string // Agent | Task
	Title              string
	Model              string
	Status             string // ACP tool-call status: pending|in_progress|completed|failed
	// Background reports a call the provider runs in the background: its
	// completed tool result is a launch receipt, not the subagent's outcome.
	Background bool
	Result     string
	Error      string
	At         time.Time
}

NativeSubagentEvent is a provider-native (Claude Agent/Task) tool event observed on a parent session.

func NativeSubagentEventFromStored

func NativeSubagentEventFromStored(workspaceID string, stored store.SessionEvent) (NativeSubagentEvent, bool, error)

NativeSubagentEventFromStored converts a committed tool event for native ingest.

type Notifier

type Notifier interface {
	OnSessionCreated(ctx context.Context, session *Session)
	OnSessionStopped(ctx context.Context, session *Session)
	OnAgentEvent(ctx context.Context, sessionID string, event any)
}

Notifier fans out session lifecycle and prompt events to downstream observers.

type NotifyOutcome

type NotifyOutcome string
const (
	NotifyOutcomeDelivered      NotifyOutcome = "delivered"
	NotifyOutcomeNoClient       NotifyOutcome = "no-client"
	NotifyOutcomeMutedWorkspace NotifyOutcome = "muted-workspace"
	NotifyOutcomeRateLimited    NotifyOutcome = "rate-limited"
)

type NotifyRequest

type NotifyRequest struct {
	SessionID   string
	ProfileID   string
	WorkspaceID string
	Title       string
	Body        string
}

type NotifyResult

type NotifyResult struct {
	Outcome      NotifyOutcome
	RetryAfterMS int64
}

type OperatorNotification

type OperatorNotification struct {
	NotificationID string
	SessionID      string
	ProfileID      string
	WorkspaceID    string
	Title          string
	Body           string
	At             time.Time
}

type Option

type Option func(*Manager)

Option customizes the session manager.

func WithAgentResolver

func WithAgentResolver(resolver AgentResolver) Option

WithAgentResolver injects the daemon-authoritative agent definition resolver.

func WithAttachmentOpener

func WithAttachmentOpener(opener AttachmentOpener) Option

WithAttachmentOpener injects session-scoped attachment reads at prompt dispatch.

func WithAttentionConfig

func WithAttentionConfig(config compozyconfig.AttentionConfig) Option

WithAttentionConfig injects the live operator notification policy.

func WithAttentionWorkspaceMuteReader

func WithAttentionWorkspaceMuteReader(reader AttentionWorkspaceMuteReader) Option

WithAttentionWorkspaceMuteReader injects the per-profile workspace mute catalog.

func WithCommandService

func WithCommandService(service CommandService) Option

WithCommandService injects the daemon-owned slash command authority.

func WithDriver

func WithDriver(driver AgentDriver) Option

WithDriver injects the runtime driver used for session lifecycle operations.

func WithEventLedger

func WithEventLedger(ledger store.EventSummaryStore) Option

WithEventLedger injects the daemon ledger that records session.fallback.used before each fallback attempt (readable through GET /api/logs).

func WithGoalCommandHandler

func WithGoalCommandHandler(handler GoalCommandHandler) Option

WithGoalCommandHandler injects the daemon-owned authenticated `/goal` dispatcher.

func WithHomePaths

func WithHomePaths(homePaths compozyconfig.HomePaths) Option

WithHomePaths overrides the resolved Compozy home directory layout.

func WithHookSet

func WithHookSet(hooks HookSet) Option

WithHookSet injects the grouped hook dispatch surface used by the session manager for lifecycle and runtime hook points.

func WithHostedMCPLauncher

func WithHostedMCPLauncher(launcher HostedMCPLauncher) Option

WithHostedMCPLauncher injects the session-bound Compozy-hosted MCP launcher.

func WithInteractionIDGenerator

func WithInteractionIDGenerator(generator IDGenerator) Option

WithInteractionIDGenerator overrides pending-interaction id allocation.

func WithLifecycleContext

func WithLifecycleContext(ctx context.Context) Option

WithLifecycleContext injects the daemon-owned lifecycle context used by background goroutines.

func WithLogger

func WithLogger(logger *slog.Logger) Option

WithLogger injects the logger used by the session manager.

func WithMCPResolver

func WithMCPResolver(resolver MCPResolver) Option

WithMCPResolver injects the skill MCP resolver used during session start.

func WithManagedInputLifecycle

func WithManagedInputLifecycle(lifecycle ManagedInputLifecycle) Option

WithManagedInputLifecycle injects the daemon-owned managed prompt callbacks.

func WithMentionReferenceRenderer

func WithMentionReferenceRenderer(renderer MentionReferenceRenderer) Option

WithMentionReferenceRenderer installs the daemon renderer for session mentions.

func WithModelCatalog

func WithModelCatalog(catalog modelcatalog.Service) Option

WithModelCatalog injects the live model catalog used to validate explicit runtime models.

func WithNotifier

func WithNotifier(notifier Notifier) Option

WithNotifier injects the async notification fan-out implementation.

func WithNow

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

WithNow overrides the manager clock, mainly for tests.

func WithPresenceLeaseIDGenerator

func WithPresenceLeaseIDGenerator(generator IDGenerator) Option

WithPresenceLeaseIDGenerator overrides operator-presence lease id allocation.

func WithProfileNameResolver

func WithProfileNameResolver(resolver ProfileNameResolver) Option

WithProfileNameResolver injects stable-id to current-name resolution for profile-owned resources.

func WithPromptAssembler

func WithPromptAssembler(assembler PromptAssembler) Option

WithPromptAssembler injects prompt assembly for session startup.

func WithPromptBufferSize

func WithPromptBufferSize(size int) Option

WithPromptBufferSize overrides the size of the returned prompt event buffer.

func WithPromptInputAugmenter

func WithPromptInputAugmenter(augmenter PromptInputAugmenter) Option

WithPromptInputAugmenter injects a bounded pre-dispatch message augmenter.

func WithPromptRecoveryDelays

func WithPromptRecoveryDelays(delays ...time.Duration) Option

WithPromptRecoveryDelays overrides the bounded automatic recovery schedule.

func WithProviderSecretResolver

func WithProviderSecretResolver(resolver ProviderSecretResolver) Option

WithProviderSecretResolver injects the launch-time provider secret resolver.

func WithQueryStore

func WithQueryStore(opener QueryStoreOpener) Option

WithQueryStore injects the opener used for stopped-session transcript/event reads. Production uses a read-only no-create opener so stale viewers cannot recreate events.db during clear/delete races.

func WithSessionBusyInputConfig

func WithSessionBusyInputConfig(config compozyconfig.SessionBusyInputConfig) Option

WithSessionBusyInputConfig overrides busy-input queue behavior.

func WithSessionCatalog

func WithSessionCatalog(catalog store.SessionCatalog) Option

WithSessionCatalog injects the global session catalog updated by lifecycle transitions.

func WithSessionCreationStore

func WithSessionCreationStore(creationStore store.SessionCreationStore) Option

WithSessionCreationStore injects the immutable session creation catalog.

func WithSessionDeriveConfig

func WithSessionDeriveConfig(cfg compozyconfig.SessionDeriveConfig) Option

WithSessionDeriveConfig sets the carried-context bounds for continue and fork.

func WithSessionHealthConfig

func WithSessionHealthConfig(config compozyconfig.HeartbeatConfig) Option

WithSessionHealthConfig injects Agent Heartbeat bounds used by session health.

func WithSessionHealthStore

func WithSessionHealthStore(store HealthStore) Option

WithSessionHealthStore injects durable metadata-only session health storage.

func WithSessionIDGenerator

func WithSessionIDGenerator(generator IDGenerator) Option

WithSessionIDGenerator overrides session id allocation.

func WithSessionInputQueueStore

func WithSessionInputQueueStore(queueStore store.SessionInputQueueStore) Option

WithSessionInputQueueStore injects durable busy-input queue storage.

func WithSessionMessagingConfig

func WithSessionMessagingConfig(config compozyconfig.SessionMessagingConfig) Option

WithSessionMessagingConfig sets the agent messaging rate budget and reply-watch TTL.

func WithSessionPromptAdmissionStore

func WithSessionPromptAdmissionStore(admissionStore store.SessionPromptAdmissionStore) Option

WithSessionPromptAdmissionStore injects durable at-most-once prompt command storage.

func WithSessionStopConfig

func WithSessionStopConfig(config compozyconfig.SessionStopConfig) Option

WithSessionStopConfig sets the cooperative grace used before escalation.

func WithSessionSupervision

func WithSessionSupervision(config compozyconfig.SessionSupervisionConfig) Option

WithSessionSupervision overrides runtime activity supervision settings.

func WithSkillRegistry

func WithSkillRegistry(registry SkillRegistry) Option

WithSkillRegistry injects the active-skill registry used during session start.

func WithSoulRunActivityChecker

func WithSoulRunActivityChecker(checker SoulRunActivityChecker) Option

WithSoulRunActivityChecker injects the active-run predicate used by Soul refresh.

func WithSoulSnapshotStore

func WithSoulSnapshotStore(store SoulSnapshotStore) Option

WithSoulSnapshotStore injects durable Soul snapshot/session provenance storage.

func WithSpawnWakeNotifier

func WithSpawnWakeNotifier(notifier SpawnWakeNotifier) Option

WithSpawnWakeNotifier injects creator wake delivery for spawned sessions.

func WithStartupPromptOverlay

func WithStartupPromptOverlay(overlay StartupPromptOverlay) Option

WithStartupPromptOverlay injects a daemon-owned startup prompt overlay.

func WithStore

func WithStore(opener StoreOpener) Option

WithStore injects the opener used to create per-session event recorders.

func WithToolUniverse

func WithToolUniverse(ids []toolspkg.ToolID) Option

WithToolUniverse injects the concrete native tool IDs used to materialize root-session delegation budgets from agent tool patterns and toolsets.

func WithToolsetCatalog

func WithToolsetCatalog(catalog toolspkg.ToolsetCatalog) Option

WithToolsetCatalog injects the catalog used to validate toolset-backed overrides.

func WithTranscriptEpochStore

func WithTranscriptEpochStore(epochStore store.SessionTranscriptEpochStore) Option

WithTranscriptEpochStore injects durable transcript reset epoch storage.

func WithTurnIDGenerator

func WithTurnIDGenerator(generator IDGenerator) Option

WithTurnIDGenerator overrides prompt turn id allocation.

func WithWindowReconciler

func WithWindowReconciler(reconciler WindowReconciler) Option

WithWindowReconciler injects the daemon-owned window cleanup invoked after a session catalog deletion succeeds.

func WithWorkAdmissionChecker

func WithWorkAdmissionChecker(checker admission.Checker) Option

WithWorkAdmissionChecker injects the daemon-owned new-work gate.

func WithWorkspaceResolver

func WithWorkspaceResolver(resolver WorkspaceResolver) Option

WithWorkspaceResolver injects workspace resolution for create/resume flows.

func WithWorktreeResolver

func WithWorktreeResolver(resolver WorktreeResolver) Option

WithWorktreeResolver injects ready-worktree resolution for bound sessions.

type PendingInput

type PendingInput struct {
	Origin           json.RawMessage
	ID               string
	SessionID        string
	OwnerKind        string
	OwnerID          string
	MessageID        string
	IdempotencyKey   string
	TargetTurnID     string
	Status           string
	Mode             BusyInputMode
	Delivery         string
	SteerDelivery    store.SteerDeliveryMode
	Text             string
	QueueGeneration  int64
	EnqueuedAt       time.Time
	Runtime          *RuntimeSelection
	SkillInvocations []commandpkg.Invocation
	Mentions         []mention.Mention
	Attachments      []AttachmentMeta
}

PendingInput is one daemon-owned operator input waiting for dispatch.

type PendingInteractionResolution

type PendingInteractionResolution struct {
	Outcome       string
	InteractionID string
	RequestID     string
	Resolution    string
}

PendingInteractionResolution reports one canonical orphan-resolution attempt.

type ProfileNameResolver

type ProfileNameResolver interface {
	ProfileName(ctx context.Context, profileID string) (string, error)
}

ProfileNameResolver maps stable profile ids to the current vault/resource name.

type PromotePendingInputOpts

type PromotePendingInputOpts struct {
	Text           string
	MessageID      string
	IdempotencyKey string
	ExpectedTurnID string
	AllowCommands  bool
	Caller         PromptCaller
}

PromotePendingInputOpts carries an atomic queue-to-steer replacement.

type PromptAssembler

type PromptAssembler interface {
	Assemble(
		ctx context.Context,
		agent compozyconfig.AgentDef,
		workspace *workspacepkg.ResolvedWorkspace,
	) (string, error)
}

PromptAssembler assembles the prompt context for a new session start.

type PromptCaller

type PromptCaller struct {
	Kind   string
	ID     string
	Source string
}

PromptCaller is the authenticated operator identity admitted by an external prompt ingress.

func (PromptCaller) Validate

func (c PromptCaller) Validate() error

Validate rejects incomplete caller provenance.

type PromptCancelCause

type PromptCancelCause string
const (
	PromptCancelUser               PromptCancelCause = "user"
	PromptCancelAgent              PromptCancelCause = "agent"
	PromptCancelSyntheticAdmission PromptCancelCause = "synthetic_admission"
	PromptCancelSteerFallback      PromptCancelCause = "steer_fallback"
)

type PromptCancelOutcome

type PromptCancelOutcome string

PromptCancelOutcome is the stable result of one idempotent cancellation request.

const (
	PromptCancelOutcomeCanceled        PromptCancelOutcome = "canceled"
	PromptCancelOutcomeNothingInFlight PromptCancelOutcome = "nothing-in-flight"
)

type PromptCancelResult

type PromptCancelResult struct {
	Outcome PromptCancelOutcome
	TurnID  string
}

PromptCancelResult identifies the canceled turn when one was active.

type PromptDelivery

type PromptDelivery string

PromptDelivery controls context delivery for a prompt turn.

const (
	PromptDeliveryNormal       PromptDelivery = ""
	PromptDeliveryMaintenance  PromptDelivery = "maintenance"
	PromptDeliveryAgentCommand PromptDelivery = "agent_command"
)

type PromptDeliveryInfo

type PromptDeliveryInfo struct {
	SessionID string
	TurnID    string
}

PromptDeliveryInfo identifies a prompt whose agent-event stream is ready to start.

type PromptDeliveryPreparer

type PromptDeliveryPreparer func(context.Context, PromptDeliveryInfo) error

PromptDeliveryPreparer runs after the provider accepts a prompt and before its first event is pumped.

type PromptHooks

type PromptHooks interface {
	DispatchInputPreSubmit(context.Context, hookspkg.InputPreSubmitPayload) (hookspkg.InputPreSubmitPayload, error)
	DispatchPromptPostAssemble(context.Context, hookspkg.PromptPayload) (hookspkg.PromptPayload, error)
}

PromptHooks groups prompt assembly and user-input hook dispatch.

type PromptInputAugmenter

type PromptInputAugmenter func(ctx context.Context, session *Session, message string) (string, error)

PromptInputAugmenter can add bounded daemon-local context before prompt dispatch.

type PromptOpts

type PromptOpts struct {
	Delivery        PromptDelivery
	Message         string
	TurnSource      TurnSource
	PromptMeta      acp.PromptMeta
	DeliveryContext context.Context
	PrepareDelivery PromptDeliveryPreparer
}

PromptOpts carries per-turn metadata through the session prompt pipeline.

type PromptProvider

type PromptProvider interface {
	PromptSection(ctx context.Context, workspace *workspacepkg.ResolvedWorkspace) (string, error)
}

PromptProvider returns one workspace-scoped prompt section for composed system-prompt assembly.

type PromptRunIdentity

type PromptRunIdentity struct {
	TurnID      string
	WorkspaceID string
	ProfileID   string
	SessionID   string
	RunID       string
	Generation  int64
}

PromptRunIdentity is the complete authority tuple for one active prompt run.

type ProviderSecretResolver

type ProviderSecretResolver interface {
	ResolveRef(ctx context.Context, ref string) (string, error)
}

ProviderSecretResolver resolves provider-bound secret refs at launch time.

type PullRequest

type PullRequest struct {
	Provider       string
	Number         int
	URL            string
	State          PullRequestState
	Draft          *bool
	HeadSHA        string
	Checks         PullRequestChecks
	ReviewDecision ReviewDecision
	Mergeable      Mergeable
	ReadyToMerge   bool
}

type PullRequestChecks

type PullRequestChecks struct {
	State       ChecksState
	Passed      int
	Failed      int
	Pending     int
	FailedNames []string
}

type PullRequestDefaultBranchReader

type PullRequestDefaultBranchReader interface {
	DefaultBranchNames(context.Context, store.ReadScope, []string) map[string][]string
}

PullRequestDefaultBranchReader shares default-branch suppression with durable board reads.

type PullRequestLookup

type PullRequestLookup struct {
	State      LookupState
	Cause      string
	ObservedAt time.Time
	Stale      bool
}

type PullRequestProjection

type PullRequestProjection struct {
	Branch string
	PullRequestView
}

type PullRequestReader

type PullRequestReader interface {
	PullRequests(context.Context, []BranchKey) map[BranchKey]PullRequestView
}

type PullRequestRepositoryReader

type PullRequestRepositoryReader interface {
	RepositoryKeys(context.Context, store.ReadScope, []string) map[string]string
}

PullRequestRepositoryReader resolves current identities for scoped catalog SQL. A nil workspace list selects all readable workspaces. Missing keys never match.

type PullRequestState

type PullRequestState string

type PullRequestView

type PullRequestView struct {
	Lookup      PullRequestLookup
	PullRequest *PullRequest
}

type QueryStoreOpener

type QueryStoreOpener func(ctx context.Context, owner store.SessionDBOwner, path string) (EventReadCloser, error)

QueryStoreOpener opens the read-only per-session events store for the exact immutable owner. Implementations must forward both owner fields unchanged.

type QuietWarning

type QuietWarning struct {
	QuietSince time.Time  `json:"quiet_since"`
	WarnedAt   time.Time  `json:"warned_at"`
	StopAt     *time.Time `json:"stop_at"`
}

QuietWarning records one quiet episode and its optional inactivity-stop deadline.

type RepairAction

type RepairAction struct {
	Code       string
	TurnID     string
	EventID    string
	ToolCallID string
	ToolName   string
	Persisted  bool
}

RepairAction is one append-only mutation planned or persisted by repair.

type RepairIssue

type RepairIssue struct {
	Code     string
	Severity string
	TurnID   string
	EventID  string
	Detail   string
}

RepairIssue is one non-mutating diagnostic discovered during repair.

type RepairOpts

type RepairOpts struct {
	SessionID string
	DryRun    bool
	Force     bool
}

RepairOpts controls one persisted session repair pass.

type RepairResult

type RepairResult struct {
	SessionID string
	Issues    []RepairIssue
	Actions   []RepairAction
	Persisted bool
}

RepairResult describes the detected inconsistencies and append-only repair events planned or persisted for a session.

type ReparentError

type ReparentError struct {
	Reason    ReparentRefusal
	SessionID string
	Detail    string
}

ReparentError reports which lineage rule refused a reparent request.

func (*ReparentError) Error

func (e *ReparentError) Error() string

func (*ReparentError) Unwrap

func (e *ReparentError) Unwrap() error

Unwrap exposes ErrSessionReparentRefused to errors.Is.

type ReparentRefusal

type ReparentRefusal string

ReparentRefusal names the lineage rule that rejected a reparent request.

const (
	// ReparentRefusalCrossWorkspace rejects subtrees spanning workspace boundaries.
	ReparentRefusalCrossWorkspace ReparentRefusal = "cross_workspace_subtree"
	// ReparentRefusalSourceHasParent rejects adopting a session that already has a parent.
	ReparentRefusalSourceHasParent ReparentRefusal = "source_has_parent"
	// ReparentRefusalSourceNotUser rejects reparenting managed, spawned, or subagent sessions.
	ReparentRefusalSourceNotUser ReparentRefusal = "source_not_user"
	// ReparentRefusalParentIneligible rejects a parent that is not a user session.
	ReparentRefusalParentIneligible ReparentRefusal = "parent_ineligible"
	// ReparentRefusalCycle rejects a parent that is the session itself or one of its descendants.
	ReparentRefusalCycle ReparentRefusal = "cycle"
	// ReparentRefusalArchived rejects reparenting when either session is archived.
	ReparentRefusalArchived ReparentRefusal = "archived"
	// ReparentRefusalNotDetachable rejects detaching a session that was not adopted.
	ReparentRefusalNotDetachable ReparentRefusal = "not_detachable"
)

type ReplacePendingInputOpts

type ReplacePendingInputOpts struct {
	Text           string
	MessageID      string
	IdempotencyKey string
	AllowCommands  bool
	Caller         PromptCaller
}

ReplacePendingInputOpts carries an atomic queued-input replacement.

type ReplyWatchRef

type ReplyWatchRef struct{ ID, State string }

ReplyWatchRef identifies the optional reply watch registered by the admission owner.

type ReplyWatchService

type ReplyWatchService interface {
	Close(context.Context) error
	Reconcile(context.Context, string) error
	OnTurnSettled(context.Context, string, string)
	OnQueueEntryTerminal(context.Context, *store.SessionInputQueueEntry)
	OnSteerResolved(context.Context, string, string)
	OnSendResult(context.Context, string, error)
	Deliver(context.Context, string) error
	OnSenderTurnSettled(context.Context, string)
	OnSessionResumed(context.Context, string)
	OnSenderGone(context.Context, string) error
	OnTargetGone(context.Context, string)
	Recover(context.Context) error
	ListForSender(context.Context, string, string) ([]store.ReplyWatch, error)
	// AwaitingReplySignals reports the sender's open watches that still count as work until the given time.
	AwaitingReplySignals(context.Context, string, time.Time) ([]WorkSignal, error)
}

func NewReplyWatchService

func NewReplyWatchService(db store.ReplyWatchStore, manager *Manager) (ReplyWatchService, error)

type ReviewDecision

type ReviewDecision string

type RuntimeConfigurator

type RuntimeConfigurator interface {
	ConfigureRuntime(ctx context.Context, proc *AgentProcess, config acp.RuntimeConfig) error
}

RuntimeConfigurator is the optional driver surface for applying mutable ACP settings at a prompt boundary without replacing the process.

type RuntimeRecoveryHooks

RuntimeRecoveryHooks groups automatic runtime recovery observation dispatch.

type RuntimeSelection

type RuntimeSelection struct {
	Provider        string
	Model           string
	ReasoningEffort string
	Speed           speedpkg.Speed
	ACPOptions      []acp.SessionConfigOptionSelection
}

RuntimeSelection is the immutable runtime snapshot accepted with one prompt.

func NormalizeRuntimeSelection

func NormalizeRuntimeSelection(selection RuntimeSelection) (RuntimeSelection, error)

NormalizeRuntimeSelection returns the canonical prompt-bound runtime input.

type RuntimeStatus

type RuntimeStatus = store.SessionRuntimeStatus

RuntimeStatus reports the binding lifecycle between a logical session and its current ACP process.

type RuntimeTransitionStrategy

type RuntimeTransitionStrategy = store.SessionRuntimeTransition

RuntimeTransitionStrategy identifies how the effective runtime changed at a prompt boundary.

type ScopedInterrupter

type ScopedInterrupter interface {
	Interrupt(ctx context.Context, sessionID string, turnID string) (toolruntime.InterruptReport, error)
}

ScopedInterrupter is the optional process-scoped interrupt surface for drivers.

type SendOutcome

type SendOutcome struct {
	Disposition    Disposition
	Delivery       store.SteerDeliveryMode
	TurnID         string
	EntryID        string
	MessageID      string
	IdempotencyKey string
	QueuePosition  int
	Replayed       bool
}

SendOutcome is the immutable acceptance shared by all prompt transports.

type SendPromptOpts

type SendPromptOpts struct {
	Origin           *acp.PromptOriginMeta
	NotifyOnComplete bool
	// Supersede replaces the same sender's older queued entry to the same target.
	Supersede       bool
	Message         string
	MessageID       string
	IdempotencyKey  string
	Mode            BusyInputMode
	Runtime         *RuntimeSelection
	ExpectedTurnID  string
	DeliveryContext context.Context
	Caller          PromptCaller
	AllowCommands   bool
	Attachments     []AttachmentMeta
}

SendPromptOpts carries one user-facing prompt plus optional busy-input mode.

type SendPromptResult

type SendPromptResult struct {
	TargetWorkspaceID     string
	ReplyWatch            *ReplyWatchRef
	Status                string
	Mode                  BusyInputMode
	Delivery              string
	SteerDelivery         store.SteerDeliveryMode
	MessageID             string
	IdempotencyKey        string
	Replayed              bool
	Events                <-chan acp.AgentEvent
	QueueEntryID          string
	QueuePosition         int
	QueueGeneration       int64
	EstimatedSendAt       *time.Time
	PreviousTurnID        string
	NewTurnID             string
	CanceledQueuedEntries int
	Goal                  *GoalCommandResult
}

SendPromptResult reports how and when the daemon accepted input for delivery.

func (SendPromptResult) Outcome

func (r SendPromptResult) Outcome() SendOutcome

type Session

type Session struct {
	ID                       string
	ProfileID                string
	Name                     string
	AgentName                string
	Provider                 string
	Model                    string
	ReasoningEffort          string
	Speed                    speedpkg.Speed
	ACPOptions               []acp.SessionConfigOptionSelection
	SpeedResolution          *speedpkg.Resolution
	RuntimeStatus            RuntimeStatus
	RuntimeTransition        RuntimeTransitionStrategy
	RuntimeFailure           string
	RuntimeGeneration        int64
	RuntimeRecovery          *store.SessionRuntimeRecovery
	SelectedRuntime          *RuntimeSelection
	RuntimeSelectionRevision int64
	EffectiveWorkspaceAccess string
	EffectivePermissions     string

	WorkspaceID string
	Workspace   string
	WorktreeID  string
	CWD         string
	Type        Type
	Lineage     *store.SessionLineage
	State       State

	ACPSessionID           string
	ACPCaps                acp.Caps
	ACPCapsKnown           bool
	AdvertisedCommands     []store.SessionAdvertisedCommand
	Liveness               *store.SessionLivenessMeta
	SoulSnapshotID         string
	SoulDigest             string
	ParentSoulDigest       string
	AttachedTo             string
	AttachExpiresAt        *time.Time
	TranscriptEpoch        int64
	PendingPermissionCount int
	PendingClarifyCount    int
	AttentionRevision      int64
	LastSettledRevision    int64
	LastSeenRevision       int64
	LastSeenAt             *time.Time
	AttentionChangedAt     *time.Time
	PendingInteractions    []store.PendingInteraction
	CreatedAt              time.Time
	UpdatedAt              time.Time
	// contains filtered or unexported fields
}

Session is the in-memory runtime representation of one active or stopping session.

func NotificationSessionFromInfo

func NotificationSessionFromInfo(info *Info) *Session

NotificationSessionFromInfo builds a detached lifecycle snapshot for notifier consumers that need the same immutable read model as a managed Session.

func (*Session) AgentDefinition

func (s *Session) AgentDefinition() compozyconfig.AgentDef

AgentDefinition returns the concrete definition snapshot that owns this session. The snapshot is immutable from callers' perspective.

func (*Session) ApprovePermission

func (s *Session) ApprovePermission(ctx context.Context, req acp.ApproveRequest) error

ApprovePermission resolves one pending permission request for an active session.

func (*Session) CurrentPromptDelivery

func (s *Session) CurrentPromptDelivery() PromptDelivery

CurrentPromptDelivery reports the active prompt's context-delivery policy.

func (*Session) CurrentPromptMessage

func (s *Session) CurrentPromptMessage() string

CurrentPromptMessage reports the authored text of the active prompt turn.

func (*Session) CurrentPromptMeta

func (s *Session) CurrentPromptMeta() acp.PromptMeta

CurrentPromptMeta reports the normalized metadata for the currently active prompt turn.

func (*Session) CurrentSkillInvocations

func (s *Session) CurrentSkillInvocations() []commandpkg.Invocation

func (*Session) CurrentTurnID

func (s *Session) CurrentTurnID() string

CurrentTurnID reports the active prompt turn identifier.

func (*Session) CurrentTurnSource

func (s *Session) CurrentTurnSource() TurnSource

CurrentTurnSource reports the provenance of the currently active prompt turn.

func (*Session) DBPath

func (s *Session) DBPath() string

DBPath reports the on-disk per-session event database path.

func (*Session) Info

func (s *Session) Info() *Info

Info returns a consistent snapshot of the current session state.

func (*Session) IsPrompting

func (s *Session) IsPrompting() bool

IsPrompting reports whether the session currently has prompt setup or turn execution in flight.

func (*Session) Meta

func (s *Session) Meta() store.SessionMeta

Meta returns the current metadata snapshot for persistence.

func (*Session) MetaPath

func (s *Session) MetaPath() string

MetaPath reports the on-disk metadata file path.

func (*Session) RequestPermission

RequestPermission asks the active session process for a permission decision.

func (*Session) SessionDir

func (s *Session) SessionDir() string

SessionDir reports the on-disk session directory path.

func (*Session) StoppingDeadline

func (s *Session) StoppingDeadline(cooperativeGrace time.Duration) time.Time

StoppingDeadline derives the fixed stop episode budget without renewing it on reads.

type SettledTurn

type SettledTurn struct {
	TurnID   string
	Sequence int64
}

type SignalSource

type SignalSource interface {
	Signals(context.Context, string) ([]WorkSignal, error)
}

SignalSource inspects one authoritative subsystem without renewing its evidence.

type SignalSourceFunc

type SignalSourceFunc func(context.Context, string) ([]WorkSignal, error)

SignalSourceFunc adapts a subsystem's existing read boundary.

func (SignalSourceFunc) Signals

func (f SignalSourceFunc) Signals(ctx context.Context, id string) ([]WorkSignal, error)

type SignalSourceState

type SignalSourceState struct {
	Kind  WorkSignalKind `json:"kind"`
	State string         `json:"state"`
	Ref   string         `json:"ref,omitempty"`
	Error string         `json:"error,omitempty"`
}

SignalSourceState makes absence, stale evidence and failed inspections explicit.

type SkillRegistry

type SkillRegistry interface {
	ForWorkspace(ctx context.Context, resolved *workspacepkg.ResolvedWorkspace) ([]*skillspkg.Skill, error)
	ForAgentDef(
		ctx context.Context,
		resolved *workspacepkg.ResolvedWorkspace,
		agent compozyconfig.AgentDef,
	) ([]*skillspkg.Skill, error)
}

SkillRegistry resolves the active skill set for a workspace during session start.

type SoulRefreshResult

type SoulRefreshResult struct {
	SessionID        string
	AgentName        string
	SoulSnapshotID   string
	SoulDigest       string
	ParentSoulDigest string
	Snapshot         *soul.Snapshot
	Soul             *soul.ResolvedSoul
	ConfigProvenance soul.ConfigProvenance
	RefreshedAt      time.Time
}

SoulRefreshResult is the internal result returned after a session Soul refresh.

type SoulRunActivityChecker

type SoulRunActivityChecker interface {
	HasActiveRunForSession(ctx context.Context, sessionID string, now time.Time) (bool, error)
}

SoulRunActivityChecker reports whether a session currently owns an active run.

type SoulSnapshotStore

type SoulSnapshotStore interface {
	UpsertSoulSnapshot(ctx context.Context, snapshot soul.Snapshot) (soul.Snapshot, error)
	GetSoulSnapshot(ctx context.Context, id string) (soul.Snapshot, error)
	UpdateSessionSoulSnapshot(ctx context.Context, update store.SessionSoulSnapshotUpdate) error
}

SoulSnapshotStore is the durable storage needed by session Soul integration.

type SpawnHooks

SpawnHooks groups safe child-session spawn hook dispatch.

type SpawnLimitError

type SpawnLimitError struct {
	// Limit is SpawnLimitMaxChildren or SpawnLimitMaxActivePerWorkspace.
	Limit string
	Max   int
	Live  int
	// Scope is the parent session ID or the target workspace ID the cap applies to.
	Scope string
}

SpawnLimitError reports a spawn refused by a live-child cap. It matches ErrSpawnLimitExceeded. Only live (starting, active, or stopping) governed children count; stopped children and subagents do not hold a slot.

func (*SpawnLimitError) Error

func (e *SpawnLimitError) Error() string

Error names the cap, its value, and the live count.

func (*SpawnLimitError) Is

func (e *SpawnLimitError) Is(target error) bool

Is lets callers branch on ErrSpawnLimitExceeded.

type SpawnOpts

type SpawnOpts struct {
	ParentTurnID    string
	Permissions     compozyconfig.PermissionMode
	Subagent        *hookspkg.SubagentSpawnPayload
	ParentSessionID string
	// InheritedWorktreeID is daemon-owned structural context copied from the parent.
	// Public callers cannot select or override it.
	InheritedWorktreeID string
	IsolatedWorktreeID  string
	AgentName           string
	Provider            string
	Model               string
	ReasoningEffort     string
	Speed               speedpkg.Speed
	ACPOptions          []acp.SessionConfigOptionSelection
	Name                string
	Workspace           string
	WorkspacePath       string
	PromptOverlay       string
	SpawnRole           string
	TTL                 time.Duration
	AutoStopOnParent    bool
	NotifyCreator       bool
	NotifyCreatorSet    bool
	PermissionPolicy    store.SessionPermissionPolicy
	// InheritPermissions starts from the parent's ceiling; PermissionNarrowing lists
	// replace only the categories they set. Without it, PermissionPolicy is literal.
	InheritPermissions  bool
	PermissionNarrowing *SubagentPermissionNarrowing
	// Toolsets selects parent-granted tools by toolset ID; it never widens the parent.
	Toolsets       []string
	IdempotencyKey string
	// DiscardStartFailure is reserved for ephemeral internal role attempts.
	DiscardStartFailure bool
	// Command is an explicit launch command for this attempt (a fallback route's account).
	Command    string
	SessionEnv compozyconfig.SessionEnv
	// ChainOwner declares who owns the fallback chain; see CreateOpts.ChainOwner.
	ChainOwner ChainOwner
}

SpawnOpts defines the safe child-session creation request accepted by the manager.

type SpawnPermissionError

type SpawnPermissionError struct {
	// Field is the request field, such as tools, toolsets, or workspace_paths.
	Field string
	// Value is the refused atom.
	Value string
	// Rule is one of the SpawnPermissionRule* constants.
	Rule string
	// Allowed is the parent's ceiling for Field; empty means the parent grants none.
	Allowed []string
}

SpawnPermissionError reports the one field, value, and rule that refused a spawn permission request. It matches ErrSpawnPermissionDenied.

func (*SpawnPermissionError) Error

func (e *SpawnPermissionError) Error() string

Error names the field, value, and rule without reformatting the request.

func (*SpawnPermissionError) Is

func (e *SpawnPermissionError) Is(target error) bool

Is lets callers branch on ErrSpawnPermissionDenied.

func (*SpawnPermissionError) Recovery

func (e *SpawnPermissionError) Recovery() string

Recovery is the caller-facing next step for this refusal.

type SpawnPromptRequest

type SpawnPromptRequest struct {
	ParentSessionID string
	ParentAgentName string
	ChildSessionID  string
	Message         string
	// Source names the ingress (tool ID or route) for prompt caller provenance.
	Source string
}

SpawnPromptRequest sends a spawned child its first prompt on behalf of its parent.

type SpawnWakeEvent

type SpawnWakeEvent struct {
	ChildSessionID string          `json:"child_session_id"`
	ChildAgentName string          `json:"child_agent_name,omitempty"`
	Reason         SpawnWakeReason `json:"reason"`
	Badge          Badge           `json:"badge"`
	Detail         string          `json:"detail,omitempty"`
	WakeEventID    string          `json:"wake_event_id"`
}

SpawnWakeEvent is the bounded child-session wake payload handed to the daemon bridge.

func (SpawnWakeEvent) Normalize

func (event SpawnWakeEvent) Normalize() SpawnWakeEvent

Normalize returns canonical, redacted, bounded wake data.

func (SpawnWakeEvent) Validate

func (event SpawnWakeEvent) Validate() error

Validate reports whether a normalized wake event has a complete delivery identity.

type SpawnWakeNotifier

type SpawnWakeNotifier interface {
	WakeSpawnCreator(ctx context.Context, creatorSessionID string, event SpawnWakeEvent) error
}

SpawnWakeNotifier delivers a child-session wake to its creator.

type SpawnWakeReason

type SpawnWakeReason string

SpawnWakeReason identifies why a child woke its creator.

const (
	// SpawnWakeReasonStopped wakes the creator when a child stops without failure.
	SpawnWakeReasonStopped SpawnWakeReason = "stopped"
	// SpawnWakeReasonFailed wakes the creator when a child reaches a failed badge.
	SpawnWakeReasonFailed SpawnWakeReason = "failed"
	// SpawnWakeReasonNeedsAttention wakes the creator when a child needs input or approval.
	SpawnWakeReasonNeedsAttention SpawnWakeReason = "needs_attention"
	// SpawnWakeReasonCompleted wakes the creator when a child finishes its turn normally.
	SpawnWakeReasonCompleted SpawnWakeReason = "completed"
)

type StartupManifestAssembler

type StartupManifestAssembler interface {
	AssembleStartupWithManifest(
		context.Context,
		StartupPromptContext,
		compozyconfig.AgentDef,
		*workspacepkg.ResolvedWorkspace,
	) (string, acp.StartupManifest, error)
}

StartupManifestAssembler retains the section boundaries of an assembled prompt.

type StartupPromptAssembler

type StartupPromptAssembler interface {
	AssembleStartup(
		ctx context.Context,
		startup StartupPromptContext,
		agent compozyconfig.AgentDef,
		workspace *workspacepkg.ResolvedWorkspace,
	) (string, error)
}

StartupPromptAssembler optionally extends PromptAssembler with durable startup context so daemon-owned assemblers can select sections before the final system prompt is concatenated.

type StartupPromptContext

type StartupPromptContext struct {
	SessionID          string
	ProfileID          string
	SessionName        string
	AgentName          string
	Provider           string
	ProviderHomePolicy compozyconfig.ProviderHomePolicy
	WorkspaceID        string
	Workspace          string
	WorktreeID         string
	SessionType        Type
	SpawnRole          string
	SoulSnapshot       *soul.Snapshot
	CreatedAt          time.Time
	UpdatedAt          time.Time
}

StartupPromptContext carries the durable session metadata available during startup prompt assembly and overlay selection.

type StartupPromptOverlay

type StartupPromptOverlay interface {
	Apply(ctx context.Context, startup StartupPromptContext, prompt string) (string, error)
}

StartupPromptOverlay applies daemon-owned startup prompt overlays after the base assembler has produced the startup prompt.

type State

type State string

State is the lifecycle state of a managed runtime session.

const (
	StateStarting State = "starting"
	StateActive   State = "active"
	StateStopping State = "stopping"
	StateStopped  State = "stopped"
)

type SteerPromptOpts

type SteerPromptOpts struct {
	Attachments    []AttachmentMeta
	Message        string
	MessageID      string
	IdempotencyKey string
	ExpectedTurnID string
	Runtime        *RuntimeSelection
	AllowCommands  bool
	Caller         PromptCaller
}

SteerPromptOpts carries one explicitly identified steering command.

type StopCause

type StopCause int

StopCause records why a session stop was initiated.

const (
	CauseNone StopCause = iota
	CauseCompleted
	CauseFailed
	CauseUserRequested
	CauseShutdown
	CauseHookDenied
	CauseProcessExited
	CauseTimeout
	CauseClearConversation
	CauseConversationRewind
	// CauseSpawnTTLExpired asks the session manager to classify the stop while
	// holding the session lifecycle lock, so prompt admission cannot race the
	// TTL decision.
	CauseSpawnTTLExpired
	CauseInactivity
	// CauseOwnerReleased ends a managed session's ownership without asserting
	// that its task succeeded or that an operator canceled it.
	CauseOwnerReleased
)

func (StopCause) String

func (cause StopCause) String() string

String returns the stable cause token used by public stop diagnostics.

type StopContract

type StopContract interface {
	CancelTurn(context.Context, string, string, StopCause) error
	AwaitTurnQuiesced(context.Context, string, string) (TurnCancelOutcome, error)
	RequestStop(context.Context, string, StopCause) error
	AwaitStopped(context.Context, string) (StopOutcome, error)
}

StopContract exposes the two scopes of managed termination.

type StopOutcome

type StopOutcome struct {
	FinalState State
	Verified   bool
	Cause      StopCause
	Escalated  bool
	Phase      StopPhase
	Elapsed    time.Duration
}

StopOutcome records confirmed termination or exhausted verification.

type StopPhase

type StopPhase string

StopPhase identifies the last attempted termination phase.

const (
	StopPhaseCooperative StopPhase = "cooperative"
	StopPhaseForced      StopPhase = "forced"
	StopPhaseKilled      StopPhase = "killed"
)

type StoreOpener

type StoreOpener func(ctx context.Context, owner store.SessionDBOwner, path string) (EventRecorder, error)

StoreOpener opens the per-session events store for the exact immutable owner. Implementations must forward both owner fields unchanged to the storage boundary.

type Subagent

type Subagent struct {
	store.SessionSubagent
	WaitTimedOut  bool   // mode=wait only
	Hint          string // set when ResultTruncated
	ResultPreview string // first line of Result, ≤ 280
}

Subagent is a store row plus call-scoped presentation fields.

type SubagentActor

type SubagentActor struct {
	Kind   string // "agent" | "operator"
	ID     string
	Caller *SubagentCaller // set when Kind == "agent"
}

SubagentActor is the caller of operator-reachable operations (CLI/HTTP/UDS or agent).

type SubagentAgentOption

type SubagentAgentOption struct {
	Name        string
	Provider    string
	CanDelegate bool
	Constraints []string
}

SubagentAgentOption is one delegable agent in the capabilities payload.

type SubagentCaller

type SubagentCaller struct {
	WorkspaceID string
	SessionID   string
	TurnID      string
	ToolCallID  string
	AgentName   string
}

SubagentCaller identifies the agent tool call that invokes a subagent operation.

type SubagentCancelOutcome

type SubagentCancelOutcome struct {
	ID     string
	Status string // cancel_requested | <terminal status>
}

SubagentCancelOutcome reports a cancel request.

type SubagentCapabilities

type SubagentCapabilities struct {
	ParentSessionID string
	Inherited       SubagentTarget
	PermissionMode  compozyconfig.PermissionMode
	Depth           int
	Live            int
	Agents          []SubagentAgentOption
	Providers       []SubagentProviderOption
}

SubagentCapabilities answers compozy__subagent_capabilities.

type SubagentError

type SubagentError struct {
	Code    string
	Message string
	Err     error
}

SubagentError preserves a public failure code and message across transport boundaries.

func (*SubagentError) Error

func (e *SubagentError) Error() string

func (*SubagentError) Unwrap

func (e *SubagentError) Unwrap() error

type SubagentModelOption

type SubagentModelOption struct {
	ID               string
	Label            string
	ReasoningEfforts []string
	Speeds           []string
}

SubagentModelOption advertises model-specific runtime choices.

type SubagentOption

type SubagentOption func(*subagentService)

func WithSubagentResultLimit

func WithSubagentResultLimit(get func(context.Context, string) (int, error)) SubagentOption

func WithSubagentSettledDispatcher

func WithSubagentSettledDispatcher(d SubagentSettledDispatcher) SubagentOption

func WithSubagentWorktrees

func WithSubagentWorktrees(w SubagentWorktrees) SubagentOption

type SubagentPermissionNarrowing

type SubagentPermissionNarrowing struct {
	Tools          []string
	Skills         []string
	MCPServers     []string
	WorkspacePaths []string
}

SubagentPermissionNarrowing narrows the caller's permission atoms. A nil list inherits the caller's list; a non-nil list must be a subset of it.

type SubagentProviderOption

type SubagentProviderOption struct {
	Provider        string
	DisplayName     string
	Models          []SubagentModelOption
	ModelsTotal     int
	ModelsTruncated bool
	CanDelegate     bool
	Constraints     []string
}

SubagentProviderOption is one delegable provider in the capabilities payload.

type SubagentRequest

type SubagentRequest struct {
	// Isolation and BaseRef are omitted from the idempotency fingerprint when zero, so a shared
	// delegation keeps the fingerprint it had before isolation existed (subagentFingerprint).
	Isolation      string `json:",omitzero"`
	BaseRef        string `json:",omitzero"`
	Caller         SubagentCaller
	Task           string
	Title          string
	Role           string
	Target         SubagentTarget
	Mode           string                       // async|wait
	Timeout        time.Duration                // wait only
	IdempotencyKey string                       // "" → Caller.ToolCallID
	PermissionMode compozyconfig.PermissionMode // "" = inherit
	Narrowing      *SubagentPermissionNarrowing // nil = inherit
}

SubagentRequest is one delegation request.

type SubagentService

type SubagentService interface {
	Capabilities(ctx context.Context, caller SubagentCaller) (SubagentCapabilities, error)
	Delegate(ctx context.Context, req SubagentRequest) (Subagent, error)
	Status(ctx context.Context, caller SubagentCaller, id string) (Subagent, error)
	Cancel(ctx context.Context, actor SubagentActor, id, reason string) (SubagentCancelOutcome, error)
	Get(ctx context.Context, workspaceID, id string) (Subagent, error)
	List(ctx context.Context, q store.SubagentListQuery) (store.SubagentPage, error)
	Summaries(ctx context.Context, parentIDs []string) (map[string]store.SubagentSummary, error)

	OnChildActivity(ctx context.Context, childSessionID string, progress string)
	OnChildSettled(ctx context.Context, childSessionID string) error
	OnWakeDispatched(ctx context.Context, parentID, wakeMessageID string) error
	OnWakeTurnSettled(ctx context.Context, parentID, wakeMessageID string, canceled bool) error
	OnWakeCanceled(ctx context.Context, parentID, wakeMessageID string) error
	OnWakeFailed(ctx context.Context, parentID, wakeMessageID string) error
	OnSteerOutcome(ctx context.Context, parentID, wakeMessageID string, injected bool) error
	OnParentTurnSettled(ctx context.Context, parentID, turnID string) error
	OnParentTurnInterrupted(ctx context.Context, parentID, turnID string) error
	OnParentStopped(ctx context.Context, parentID string) error
	UpgradeWakePolicy(ctx context.Context, id string) error
	OnNativeToolEvent(ctx context.Context, parentID string, ev NativeSubagentEvent) error
	OnNativeTurnDone(ctx context.Context, parentID, turnID string, at time.Time) error
	Recover(ctx context.Context) error
}

SubagentService owns subagent records, delivery, and lifecycle. Transition owners are called from the session manager call sites listed in the spec.

func NewSubagentService

func NewSubagentService(db store.SubagentStore, manager *Manager, opts ...SubagentOption) (SubagentService, error)

type SubagentSettledDispatcher

type SubagentSettledDispatcher interface {
	DispatchSubagentSettled(context.Context, store.SessionSubagent) error
}

SubagentSettledDispatcher observes the one successful terminal transition.

type SubagentTarget

type SubagentTarget struct {
	Agent           string
	Provider        string
	Model           string
	ReasoningEffort string
	Speed           string
	ACPOptions      []acp.SessionConfigOptionSelection
}

SubagentTarget is the requested (or resolved) runtime of a subagent.

type SubagentUpdate

type SubagentUpdate struct {
	ParentSessionID string
	Subagent        Subagent
}

SubagentUpdate is published after every committed change to a subagent row. The session stream forwards it as `subagent_updated` on the parent's stream.

type SubagentUpdateSubscriber

type SubagentUpdateSubscriber interface {
	SubscribeSubagentUpdates(ctx context.Context, parentSessionID string) (<-chan SubagentUpdate, func(), error)
}

SubagentUpdateSubscriber streams committed subagent row changes for one parent session. The returned cancel func releases the subscription; the channel closes after cancel.

type SubagentWorktree

type SubagentWorktree struct{ ID, Name, Branch, Path, BaseRef, BaseSHA string }

type SubagentWorktreeFacts

type SubagentWorktreeFacts = store.SubagentWorktreeFacts

type SubagentWorktreeRequest

type SubagentWorktreeRequest struct {
	WorkspaceID, ProfileID, SubagentID, Title string
	BaseRef                                   string
	// CallerPath is the already-authorized checkout, used only to resolve an omitted base.
	CallerPath       string
	CallerWorktreeID string
}

type SubagentWorktrees

type SubagentWorktrees interface {
	Provision(context.Context, SubagentWorktreeRequest) (SubagentWorktree, error)
	Rollback(ctx context.Context, workspaceID, worktreeID, subagentID string) error
	FindByRun(ctx context.Context, workspaceID, subagentID string) (*SubagentWorktree, error)
	SafeRollback(ctx context.Context, workspaceID, worktreeID, subagentID, baseSHA string) (bool, error)
	Observe(ctx context.Context, workspaceID, worktreeID, baseSHA string) SubagentWorktreeFacts
}

type SubprocessHealthNotifier

type SubprocessHealthNotifier interface {
	OnSubprocessHealth(context.Context, SubprocessHealthSnapshot)
}

SubprocessHealthNotifier is an optional notifier extension for observed failed health verdicts.

type SubprocessHealthSnapshot

type SubprocessHealthSnapshot struct {
	SessionID   string
	WorkspaceID string
	AgentName   string
	Health      subprocess.HealthState
}

SubprocessHealthSnapshot is one immutable health observation for an active session process.

type SupervisedWorkRecovery

type SupervisedWorkRecovery func(context.Context, *Info, string) error

SupervisedWorkRecovery settles task ownership while the verified inactivity stop receipt still fences session reuse.

type SupervisionState

type SupervisionState struct {
	WorkSignals  []WorkSignal        `json:"work_signals"`
	Sources      []SignalSourceState `json:"sources"`
	QuietWarning *QuietWarning       `json:"quiet_warning"`
}

SupervisionState is the session's last authoritative work inspection.

func CloneSupervisionState

func CloneSupervisionState(state *SupervisionState) *SupervisionState

CloneSupervisionState isolates runtime read models and preserves empty arrays.

type SyntheticPromptOpts

type SyntheticPromptOpts struct {
	MessageID               string
	Priority                int
	Delivery                PromptDelivery
	Message                 string
	Metadata                acp.PromptSyntheticMeta
	TurnID                  string
	SkipIfBusy              bool
	InterruptIfAgentWaiting bool
}

SyntheticPromptOpts carries daemon-owned synthetic prompt input plus wake-up metadata required for persistence and later reentry handling.

type ToolHooks

ToolHooks groups provider-native tool execution hook dispatch.

type TransportDeliveryStats

type TransportDeliveryStats struct {
	Ingest    acp.IngestStats
	Broadcast acp.BroadcastStats
}

TransportDeliveryStats separates durable ingestion from watcher delivery.

type TurnCancelOutcome

type TurnCancelOutcome struct {
	TurnID    string
	Quiesced  bool
	Escalated bool
	Phase     StopPhase
	Elapsed   time.Duration
}

TurnCancelOutcome describes verified turn quiescence and any escalation.

type TurnEndNotifier

type TurnEndNotifier func(context.Context, PromptRunIdentity)

TurnEndNotifier is invoked once after a prompt run finishes dispatching.

type TurnResult

type TurnResult struct {
	Outcome string
	Text    string
	Error   string
}

type TurnSource

type TurnSource string

TurnSource classifies the origin of a prompt turn inside the daemon runtime.

type Type

type Type string

Type identifies why a session was created.

const (
	SessionTypeUser        Type = "user"
	SessionTypeSystem      Type = "system"
	SessionTypeCoordinator Type = "coordinator"
	SessionTypeSpawned     Type = "spawned"
)

type UsageEventEnvelope

type UsageEventEnvelope struct {
	Sequence int64
	At       time.Time
	TurnID   string
	Usage    acp.TokenUsage
}

type WaitOutcome

type WaitOutcome struct {
	Outcome  WaitResult
	State    Badge
	Waited   time.Duration
	Revision int64
	ResumeID string
}

WaitOutcome reports the observed edge and its catalog-owned fence.

type WaitRequest

type WaitRequest struct {
	SessionID string
	Until     []Badge
	Timeout   time.Duration
	Epoch     int64
	ResumeID  string
}

WaitRequest describes one always-bounded badge wait or resume attempt.

type WaitResult

type WaitResult string

WaitResult is the terminal result of one bounded badge wait.

const (
	WaitResultStateReached WaitResult = "state-reached"
	WaitResultTimeout      WaitResult = "timeout"
	WaitResultSessionGone  WaitResult = "session-gone"
	WaitResultCanceled     WaitResult = "canceled"
	WaitResultOverflow     WaitResult = "overflow"
)

type WaitingOn

type WaitingOn string
const (
	WaitingOnSessions WaitingOn = "sessions"
	WaitingOnMonitor  WaitingOn = "monitor"
)

func WaitingOnFor

func WaitingOnFor(signals []WorkSignal) WaitingOn

type WindowReconciler

type WindowReconciler interface {
	ReconcileDeletedSession(ctx context.Context, profileID, workspaceID, sessionID string) error
}

WindowReconciler removes durable session windows after a session deletion has committed its catalog mutation.

type WorkSignal

type WorkSignal struct {
	Kind  WorkSignalKind `json:"kind"`
	Since time.Time      `json:"since"`
	Ref   string         `json:"ref,omitempty"`

	ValidUntil      time.Time `json:"-"`
	StaleAttention  bool      `json:"-"`
	AttentionReason string    `json:"-"`
}

WorkSignal is ephemeral evidence of work; it never enters session persistence.

type WorkSignalKind

type WorkSignalKind string

WorkSignalKind names the authoritative sources allowed to defer inactivity stops.

const (
	WorkSignalAgentProgress WorkSignalKind = "agent_progress"
	WorkSignalToolRunning   WorkSignalKind = "tool_running"
	WorkSignalActiveChild   WorkSignalKind = "active_child"
	WorkSignalLoopRun       WorkSignalKind = "loop_run"
	WorkSignalTaskLease     WorkSignalKind = "task_lease"
	WorkSignalScheduledWait WorkSignalKind = "scheduled_wait"
	WorkSignalActiveMonitor WorkSignalKind = "active_monitor"
	// WorkSignalAwaitingReply keeps a sender alive while a session it asked is still working on the answer.
	WorkSignalAwaitingReply WorkSignalKind = "awaiting_reply"
)

type WorkSignalRegistry

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

WorkSignalRegistry collects fresh evidence without owning the evidence's lifecycle.

func NewWorkSignalRegistry

func NewWorkSignalRegistry(sources ...WorkSignalSource) *WorkSignalRegistry

func (*WorkSignalRegistry) Inspect

Inspect reports unknown sources explicitly; no failed inspection renews a signal.

func (*WorkSignalRegistry) Register

func (r *WorkSignalRegistry) Register(sources ...WorkSignalSource)

type WorkSignalSource

type WorkSignalSource struct {
	Kind   WorkSignalKind
	Source SignalSource
}

WorkSignalSource binds a known kind to its authoritative inspection adapter.

type WorkspaceResolver

type WorkspaceResolver interface {
	workspacepkg.RuntimeResolver
	Get(context.Context, string) (workspacepkg.Workspace, error)
}

WorkspaceResolver supplies runtime snapshots and inexpensive persisted registrations.

type WorktreeResolver

type WorktreeResolver interface {
	ResolveSessionWorktree(ctx context.Context, workspaceRegistryID, ref string) (id, root string, err error)
}

WorktreeResolver resolves one ready worktree within its parent workspace.

Source Files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL