session

package
v0.3.0-beta.17 Latest Latest
Warning

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

Go to latest
Published: Aug 14, 2026 License: MIT Imports: 59 Imported by: 0

Documentation

Overview

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

Index

Constants

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"
	ListSortLastActivity = "last_activity"

	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 (
	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
	RuntimeStatusFailed        = store.SessionRuntimeFailed
)
View Source
const (
	RuntimeTransitionNone               = store.SessionRuntimeTransitionNone
	RuntimeTransitionInitialBind        = store.SessionRuntimeTransitionInitialBind
	RuntimeTransitionLiveConfiguration  = store.SessionRuntimeTransitionLiveConfiguration
	RuntimeTransitionProcessReplacement = store.SessionRuntimeTransitionProcessReplacement
)
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 (
	// 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"
	// SpawnRoleMemoryExtractor marks daemon-owned extractor children.
	SpawnRoleMemoryExtractor = "memory-extractor"
	// SpawnRoleAutoTitle marks daemon-owned title generator children.
	SpawnRoleAutoTitle = "auto-title"
)
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

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")
)
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 (
	// 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 (
	// 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 (
	// 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 (
	// 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.

Functions

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 canonical v1 profile used by daemon and Manager.

func ClassifyInactiveMetaForRecovery

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

ClassifyInactiveMetaForRecovery rewrites non-terminal persisted session metadata into a stopped view that captures the best available supervision evidence after daemon interruption.

func IsInternalSpawnRole

func IsInternalSpawnRole(role string) bool

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

func ResolveSessionCWD

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

ResolveSessionCWD normalizes a creation CWD and rejects workspace escape.

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.

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) 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) 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) 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) Stop

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

Stop stops the wrapped ACP runtime process.

type AgentArtifactResolver

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

AgentArtifactResolver resolves agent provenance and sidecars 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 optional resource-backed authored-context sidecars.

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 AgentHooks

AgentHooks groups agent start and stop lifecycle hook dispatch.

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() sandbox.ToolHost

ToolHost returns the sandbox-owned 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
	ConfigureRuntime  func(func() TurnSource)
	ToolHost          sandbox.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 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"
	BadgeStopped        Badge = "stopped"
	BadgeFailed         Badge = "failed"
	BadgeUnknown        Badge = "unknown"
)

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 eight-token badge vocabulary used by API, CLI, and web clients.

type BadgeInputs

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

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

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 CatalogEvent

type CatalogEvent struct {
	Kind        CatalogEventKind
	WorkspaceID string
	SessionID   string
}

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"
)

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 CompactionHandler

type CompactionHandler interface {
	CompactSessionContext(ctx context.Context, request CompactionRequest) (CompactionResult, error)
}

CompactionHandler updates durable memory coverage for one replay span.

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 CompactionRequest

type CompactionRequest struct {
	WorkspaceID  string
	SessionID    string
	AgentName    string
	FromSequence int64
	ToSequence   int64
	Events       []store.SessionEvent
}

CompactionRequest carries one exact persisted replay span to the memory boundary.

type CompactionResult

type CompactionResult struct {
	Summary string
}

CompactionResult carries the durable summary produced before event archiving.

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 {
	DesiredSessionID     string
	AgentName            string
	Provider             string
	Model                string
	ReasoningEffort      string
	Speed                speedpkg.Speed
	CWD                  string
	SandboxRef           string
	DisableSandbox       bool
	Permissions          compozyconfig.PermissionMode
	Name                 string
	Workspace            string
	WorkspacePath        string
	NetworkParticipation *participation.Request
	// ResolvedNetworkParticipation binds an internal worker session to the immutable owner snapshot.
	// Callers must not set it together with NetworkParticipation.
	ResolvedNetworkParticipation *participation.Spec
	// NetworkOwnerKey binds an internal worker session to its task or loop budget owner.
	// Empty values default to the session's own identity.
	NetworkOwnerKey string
	// NetworkAuthority carries the concrete delegated channel scope for child-owned resolution.
	NetworkAuthority *participation.AuthorityScope
	PromptOverlay    string
	ContractOverlay  string
	RuntimeMode      string
	Type             Type
	Lineage          *store.SessionLineage
	ParentSoulDigest string
	// AllowedToolsOverride is a concrete subset narrowing of the resolved agent tool policy.
	AllowedToolsOverride []string
	CreationProfile      *store.SessionCreationProfile
	CreationIdentity     *store.SessionCreationIdentity
	// DiscardStartFailure prevents internal retry attempts from leaving durable
	// session artifacts when provider startup fails before Create returns.
	DiscardStartFailure bool
}

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 {
	AgentName       string
	Provider        string
	Model           string
	ReasoningEffort string
	WorkspaceID     string
	CWD             string
	SandboxMode     string
	SandboxRef      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 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 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 FinalizationNotifier

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

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

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
}

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"
)

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
	Sandbox         SandboxHooks
	Prompt          PromptHooks
	Events          EventHooks
	Agent           AgentHooks
	Conversation    ConversationHooks
	Tools           ToolHooks
	Compaction      CompactionHooks
	Spawn           SpawnHooks
	AuthoredContext AuthoredContextHooks
}

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
	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
	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 {
	ID                       string
	Name                     string
	AgentName                string
	Provider                 string
	Model                    string
	ReasoningEffort          string
	Speed                    speedpkg.Speed
	SpeedResolution          *speedpkg.Resolution
	RuntimeStatus            RuntimeStatus
	RuntimeTransition        RuntimeTransitionStrategy
	RuntimeFailure           string
	SelectedRuntime          *RuntimeSelection
	RuntimeSelectionRevision int64
	EffectivePermissions     string
	WorkspaceID              string
	Workspace                string
	NetworkParticipation     participation.Spec
	NetworkOwnerKey          string
	Type                     Type
	Lineage                  *store.SessionLineage
	State                    State
	PendingPermission        bool
	StopReason               store.StopReason
	StopDetail               string
	Failure                  *store.SessionFailure
	ACPSessionID             string
	ACPCaps                  acp.Caps
	AdvertisedCommands       []store.SessionAdvertisedCommand
	Liveness                 *store.SessionLivenessMeta
	Sandbox                  *store.SessionSandboxMeta
	SoulSnapshotID           string
	SoulDigest               string
	ParentSoulDigest         string
	AttachedTo               string
	AttachExpiresAt          *time.Time
	TranscriptEpoch          int64
	ArchivedAt               *time.Time
	CreatedAt                time.Time
	UpdatedAt                time.Time
}

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

type InputQueueSummary

type InputQueueSummary struct {
	QueueGeneration int64
	PendingInputs   int
}

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

type LedgerMaterializer

type LedgerMaterializer interface {
	MaterializeSessionLedger(ctx context.Context, record store.SessionLedgerRecord) error
	DiscardSessionLedger(ctx context.Context, record store.SessionLedgerRecord) error
}

LedgerMaterializer is the thin session-end seam for forensic ledger projection.

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
}

ListPage contains one bounded public session catalog result.

type ListQuery

type ListQuery struct {
	WorkspaceID     string
	State           string
	SessionType     Type
	AgentName       string
	ParentSessionID string
	RootSessionID   string
	Search          string
	Resumable       bool
	Archive         store.SessionArchiveFilter
	Sort            string
	Cursor          string
	Limit           int
}

ListQuery describes one public session catalog page.

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 {
	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) AggregateSessionsByAgent

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

AggregateSessionsByAgent returns workspace-scoped durable metrics overlaid with the manager's current live-session snapshots.

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) error

ApprovePermission resolves one pending interactive permission request for an active session.

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.

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) BindNetworkPeer

func (m *Manager) BindNetworkPeer(
	ctx context.Context,
	sessionID string,
	spec participation.Spec,
	ownerKey string,
) error

BindNetworkPeer temporarily registers an active session in a task-run-owned Live channel without changing the session's durable creation participation.

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) error

CancelPrompt cancels prompt setup/execution for a known session.

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) 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.

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) 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) CreateLifecycleContinuation

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

CreateLifecycleContinuation starts a Dream session for daemon-owned work that was accepted before public work admission began draining.

func (*Manager) Delete

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

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

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) 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) ExecSandbox

func (m *Manager) ExecSandbox(ctx context.Context, req SandboxExecRequest) (SandboxExecResult, error)

ExecSandbox runs a command through the active session's sandbox tool host.

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) 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) InvokeTransientModel

func (m *Manager) InvokeTransientModel(
	ctx context.Context,
	call TransientModelCall,
) (result TransientModelResult, operationErr error)

InvokeTransientModel performs one ACP turn without publishing a session row.

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) 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) 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) 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) NotifyManagedInputReady

func (m *Manager) NotifyManagedInputReady(sessionID string)

NotifyManagedInputReady runs the unified selector for an idle session.

func (*Manager) PrepareWorkspaceRemoval

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

PrepareWorkspaceRemoval atomically stages every stopped session directory so the workspace store can delete its database-owned rows without orphaning transcript state. Commit or Rollback releases the serialized deletion lease.

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) PromptLifecycleContinuation

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

PromptLifecycleContinuation submits the turn for a daemon-owned Dream session whose lifecycle work was accepted before public admission drained.

func (*Manager) PromptNetwork

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

PromptNetwork sends one network-originated prompt turn to an active session.

func (*Manager) PromptSynthetic

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

PromptSynthetic submits one daemon-owned synthetic prompt turn.

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) RecoverSessionHealth

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

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

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) 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) 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) RequestStopWithCause

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

RequestStopWithCause marks a session as stopping and sends the cooperative ACP cancel signal without forcing process termination.

func (*Manager) RestoreNetworkPeer

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

RestoreNetworkPeer returns an active session to its durable creation participation after task-run ownership ends.

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) 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) (SendPromptResult, error)

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

func (*Manager) SessionAgentDefinition

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

SessionAgentDefinition returns the concrete definition for one live session.

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) SetCompactionHandler

func (m *Manager) SetCompactionHandler(handler CompactionHandler)

SetCompactionHandler late-binds the daemon memory runtime after manager construction.

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) SetNetworkPeerLifecycle

func (m *Manager) SetNetworkPeerLifecycle(lifecycle NetworkPeerLifecycle)

SetNetworkPeerLifecycle installs the late-bound network join/leave callbacks used after session activation and before final stop cleanup.

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) SetTurnEndNotifier

func (m *Manager) SetTurnEndNotifier(fn TurnEndNotifier)

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

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 stops a session while preserving the explicit stop initiator.

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,
) (<-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) 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) 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) 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) Unarchive

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

Unarchive restores a session to the default catalog.

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.

type NetworkPeerCapability

type NetworkPeerCapability struct {
	ID                string
	Summary           string
	Outcome           string
	Version           string
	Digest            string
	ContextNeeded     []string
	ArtifactsExpected []string
	ExecutionOutline  []string
	Constraints       []string
	Examples          []string
	Requirements      []string
}

NetworkPeerCapability is the runtime-owned capability projection shared with the network join lifecycle for brief and rich discovery.

type NetworkPeerJoin

type NetworkPeerJoin struct {
	SessionID            string
	PeerID               string
	WorkspaceID          string
	DisplayName          string
	Channel              string
	OwnerKey             string
	NetworkParticipation participation.Spec
	Capabilities         []NetworkPeerCapability
}

NetworkPeerJoin describes one daemon-local peer registration request for the late-bound network lifecycle.

type NetworkPeerLifecycle

type NetworkPeerLifecycle interface {
	JoinChannel(ctx context.Context, join NetworkPeerJoin) error
	LeaveChannel(ctx context.Context, sessionID string) error
}

NetworkPeerLifecycle is the late-bound network join/leave surface consumed by the session manager without importing the network package.

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 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 WithCommandService

func WithCommandService(service CommandService) Option

WithCommandService injects the daemon-owned slash command authority.

func WithCompactionHandler

func WithCompactionHandler(handler CompactionHandler) Option

WithCompactionHandler injects the durable summary boundary used before archiving.

func WithDriver

func WithDriver(driver AgentDriver) Option

WithDriver injects the runtime driver used for session lifecycle operations.

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 WithLedgerMaterializer

func WithLedgerMaterializer(materializer LedgerMaterializer) Option

WithLedgerMaterializer injects the forensic session-ledger materializer.

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 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 WithParticipationResolver

func WithParticipationResolver(resolver participation.Resolver) Option

WithParticipationResolver injects the shared resolver used before session creation writes.

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 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 WithSandboxIDGenerator

func WithSandboxIDGenerator(generator IDGenerator) Option

WithSandboxIDGenerator overrides sandbox id allocation.

func WithSandboxRegistry

func WithSandboxRegistry(registry *sandbox.Registry) Option

WithSandboxRegistry injects the runtime sandbox provider registry.

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 WithSessionCompactionConfig

func WithSessionCompactionConfig(config compozyconfig.SessionCompactionConfig) Option

WithSessionCompactionConfig overrides pressure-triggered context compaction guards.

func WithSessionCreationStore

func WithSessionCreationStore(creationStore store.SessionCreationStore) Option

WithSessionCreationStore injects the immutable session creation catalog.

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 WithSessionPromptAdmissionStore

func WithSessionPromptAdmissionStore(admissionStore store.SessionPromptAdmissionStore) Option

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

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 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 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 WithWorkAdmissionChecker

func WithWorkAdmissionChecker(checker admission.Checker) Option

WithWorkAdmissionChecker injects the daemon-owned new-work gate.

func WithWorkspaceResolver

func WithWorkspaceResolver(resolver workspacepkg.RuntimeResolver) Option

WithWorkspaceResolver injects workspace resolution for create/resume flows.

type PendingInput

type PendingInput struct {
	ID               string
	SessionID        string
	MessageID        string
	IdempotencyKey   string
	TargetTurnID     string
	Status           string
	Mode             BusyInputMode
	Delivery         string
	Text             string
	QueueGeneration  int64
	EnqueuedAt       time.Time
	Runtime          *RuntimeSelection
	SkillInvocations []commandpkg.Invocation
}

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

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 PromptDelivery

type PromptDelivery struct {
	SessionID string
	TurnID    string
}

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

type PromptDeliveryPreparer

type PromptDeliveryPreparer func(context.Context, PromptDelivery) 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 {
	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 ProviderSecretResolver

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

ProviderSecretResolver resolves provider-bound secret refs at launch time.

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 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 ReplacePendingInputOpts

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

ReplacePendingInputOpts carries an atomic queued-input replacement.

type ResumeContextProvider

type ResumeContextProvider interface {
	ResumeContextSection(ctx context.Context, startup StartupPromptContext) (string, error)
}

ResumeContextProvider supplies workspace continuity that must accompany a degraded resume replay without coupling session lifecycle code to memory.

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 RuntimeSelection

type RuntimeSelection struct {
	Provider        string
	Model           string
	ReasoningEffort string
	Speed           speedpkg.Speed
}

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 SandboxExecRequest

type SandboxExecRequest struct {
	SessionID string
	Command   string
	Timeout   time.Duration
}

SandboxExecRequest describes one command execution inside a session sandbox.

type SandboxExecResult

type SandboxExecResult struct {
	ExitCode int
	Stdout   string
	Stderr   string
}

SandboxExecResult reports the terminal execution result.

type SandboxHooks

SandboxHooks groups execution-sandbox lifecycle hook dispatch.

type SandboxLifecycleEvent

type SandboxLifecycleEvent struct {
	Name        string
	Span        string
	SessionID   string
	WorkspaceID string
	SandboxID   string
	Backend     string
	Profile     string
	InstanceID  string
	Reason      string
	Duration    time.Duration
	ErrorKind   string
	Error       string
	Timestamp   time.Time
}

SandboxLifecycleEvent reports provider lifecycle timing to optional observers.

type SandboxLifecycleNotifier

type SandboxLifecycleNotifier interface {
	OnSandboxLifecycleEvent(context.Context, SandboxLifecycleEvent)
}

SandboxLifecycleNotifier is an optional notifier extension for sandbox lifecycle spans.

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 SendPromptOpts

type SendPromptOpts struct {
	Message         string
	MessageID       string
	IdempotencyKey  string
	Mode            BusyInputMode
	Runtime         *RuntimeSelection
	ExpectedTurnID  string
	DeliveryContext context.Context
	Caller          PromptCaller
	AllowCommands   bool
}

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

type SendPromptResult

type SendPromptResult struct {
	Status                string
	Mode                  BusyInputMode
	Delivery              string
	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.

type Session

type Session struct {
	ID                       string
	Name                     string
	AgentName                string
	Provider                 string
	Model                    string
	ReasoningEffort          string
	Speed                    speedpkg.Speed
	SpeedResolution          *speedpkg.Resolution
	RuntimeStatus            RuntimeStatus
	RuntimeTransition        RuntimeTransitionStrategy
	RuntimeFailure           string
	SelectedRuntime          *RuntimeSelection
	RuntimeSelectionRevision int64
	EffectivePermissions     string
	WorkspaceID              string
	Workspace                string
	CWD                      string
	NetworkParticipation     participation.Spec
	NetworkOwnerKey          string
	Type                     Type
	Lineage                  *store.SessionLineage
	State                    State

	ACPSessionID       string
	ACPCaps            acp.Caps
	AdvertisedCommands []store.SessionAdvertisedCommand
	Liveness           *store.SessionLivenessMeta
	Sandbox            *store.SessionSandboxMeta
	SoulSnapshotID     string
	SoulDigest         string
	ParentSoulDigest   string
	AttachedTo         string
	AttachExpiresAt    *time.Time
	TranscriptEpoch    int64
	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 (*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) 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

CurrentSkillInvocations returns the explicit skills admitted for the active turn.

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.

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 SpawnOpts

type SpawnOpts struct {
	ParentSessionID      string
	AgentName            string
	Provider             string
	Model                string
	ReasoningEffort      string
	Speed                speedpkg.Speed
	Name                 string
	Workspace            string
	WorkspacePath        string
	NetworkParticipation *participation.Request
	PromptOverlay        string
	SpawnRole            string
	TTL                  time.Duration
	AutoStopOnParent     bool
	PermissionPolicy     store.SessionPermissionPolicy
	IdempotencyKey       string
	AllowStoppedParent   bool
	// DiscardStartFailure is reserved for ephemeral internal role attempts.
	DiscardStartFailure bool
}

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

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
	SessionName          string
	AgentName            string
	Provider             string
	WorkspaceID          string
	Workspace            string
	NetworkParticipation participation.Spec
	SessionType          Type
	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 {
	Message        string
	MessageID      string
	IdempotencyKey string
	ExpectedTurnID string
	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
)

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 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 SyntheticPromptOpts

type SyntheticPromptOpts struct {
	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 TransientModelCall

type TransientModelCall struct {
	Config          *compozyconfig.Config
	Provider        string
	Model           string
	ReasoningEffort string
	CWD             string
	SystemPrompt    string
	Prompt          string
	MaxOutputBytes  int
}

TransientModelCall describes one provider-backed model turn that must not create a durable Compozy session.

type TransientModelResult

type TransientModelResult struct {
	Output   string
	Accepted bool
}

TransientModelResult reports whether the provider accepted the prompt. Once accepted, higher layers must not attempt a route fallback.

type TurnEndNotifier

type TurnEndNotifier func(sessionID string)

TurnEndNotifier is invoked once after a prompt turn finishes dispatching.

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"
	SessionTypeDream       Type = "dream"
	SessionTypeSystem      Type = "system"
	SessionTypeCoordinator Type = "coordinator"
	SessionTypeSpawned     Type = "spawned"
)

Source Files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

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