sessionruntime

func (*AcquireCanceledError) Error ¶

func (e *AcquireCanceledError) Error() string

func (*AcquireCanceledError) Unwrap ¶

func (e *AcquireCanceledError) Unwrap() error

func (*CheckpointError) Error ¶

func (e *CheckpointError) Error() string

func (*CheckpointError) Unwrap ¶

func (e *CheckpointError) Unwrap() error

func (*CompactionInputTooLargeError) Error ¶

func (*CompactionInputTooLargeError) Error() string

func (*DelegateError) Error ¶

func (e *DelegateError) Error() string

func (*DelegateError) ModelFacingError ¶

func (e *DelegateError) ModelFacingError() string

ModelFacingError exposes only the fixed, bounded category needed by the model-facing agent result. It deliberately omits all request fields; ordinary delegation errors continue to use the generic tool-result error.

func (*HustleConstructionError) Error ¶

func (e *HustleConstructionError) Error() string

func (*HustleConstructionError) Unwrap ¶

func (e *HustleConstructionError) Unwrap() error

func (*HustleModelResolveError) Error ¶

func (e *HustleModelResolveError) Error() string

func (*HustleModelResolveError) Unwrap ¶

func (e *HustleModelResolveError) Unwrap() error

func (*HustleShutdownReentryError) Error ¶

func (*HustleShutdownReentryError) Error() string

func (*InvalidWorkspaceOperationError) Error ¶

func (e *InvalidWorkspaceOperationError) Error() string

func (*Lifecycle) NewSession ¶

func (r *Lifecycle) NewSession(ctx context.Context, seed workspacestore.Ref, newOpts ...NewSessionOption) (*Session, error)

func (*Lifecycle) RestoreSession ¶

func (r *Lifecycle) RestoreSession(ctx context.Context, id uuid.UUID) (*Session, error)

RestoreSession rebuilds a live session from its durable journal under the id it was created with, delegating to runtime restoration with the Lifecycle's captured cfg, store, and base options. runtime restoration holds the store, so it builds its OWN lease/journal/appenders (and installs the lease-release hook) internally — the Lifecycle supplies only the captured caller options, NOT the per-session appenders NewSession builds. It refuses a config-fingerprint mismatch (typed *ConfigMismatchError) unless WithLifecycleAllowConfigMismatch was compiled in, and surfaces runtime restoration's typed errors unchanged (a *RestoreDiscoveryError for a session with no history, a *RestoreError for a lease/journal/replay failure), never a panic.

func (*MissingFingerprintProviderError) Error ¶

func (*MissingFingerprintProviderError) Error() string

func (*MissingStoreError) Error ¶

func (*MissingStoreError) Error() string

func (*MissingTopologyError) Error ¶

func (*MissingTopologyError) Error() string

func (*NewSessionError) Error ¶

func (e *NewSessionError) Error() string

func (*NewSessionError) Unwrap ¶

func (e *NewSessionError) Unwrap() error

func (OffloadGCPolicy) Configured ¶

func (p OffloadGCPolicy) Configured() bool

Configured reports whether the policy is armed (both fields positive). An unarmed policy wires no gate and no runner, leaving the journal undecorated (unchanged behavior).

func (*PlacementResolutionError) Error ¶

func (e *PlacementResolutionError) Error() string

func (*ProcessLifecycleOwnerMismatchError) Error ¶

func (e *ProcessLifecycleOwnerMismatchError) Error() string

func (*ProcessNotificationDeliveryStoppedError) Error ¶

func (e *ProcessNotificationDeliveryStoppedError) Error() string

func (*ProcessNotificationOwnerMismatchError) Error ¶

func (e *ProcessNotificationOwnerMismatchError) Error() string

func (*ProcessNotificationUnsupportedError) Error ¶

func (e *ProcessNotificationUnsupportedError) Error() string

func (*ProcessServicesUnsupportedError) Error ¶

func (e *ProcessServicesUnsupportedError) Error() string

func (*ResidencyReleaseRefusedError) Error ¶ added in v0.31.0

func (e *ResidencyReleaseRefusedError) Error() string

func (*ResidencyReleaseRefusedError) Unwrap ¶ added in v0.31.0

func (e *ResidencyReleaseRefusedError) Unwrap() error

func (*RestoredContextModelMismatchError) Error ¶

func (e *RestoredContextModelMismatchError) Error() string

func (*Session) ActivateGate ¶

func (s *Session) ActivateGate(ctx context.Context, id gate.ID, route gate.Route) error

ActivateGate is called by the owner after its local blocker/continuation exists. It requires a preparing gate, appends the public GateOpened event via the strict gateAppender, stores the private route, and flips the entry to open so ListGates returns it. A failed append leaves the gate preparing. An unknown or non-preparing gate returns a typed *GateError.

func (*Session) ActiveLoop ¶

func (s *Session) ActiveLoop() loop.Handle

func (*Session) ActiveLoopID ¶

func (s *Session) ActiveLoopID() uuid.UUID

ActiveLoopID returns the session's mutable active loop id, the default target for Submit. It is safe to call concurrently.

func (*Session) AdmissionFaultErr ¶

func (s *Session) AdmissionFaultErr() error

AdmissionFaultErr is the loop actor's last-moment admission probe, closing the Session submit check→send race without changing the narrower change-event FaultErr seam.

func (*Session) ApplyRuntimeCommand ¶ added in v0.31.0

func (s *Session) ApplyRuntimeCommand(ctx context.Context, admitted runtimecommand.Admitted) (runtimecommand.Disposition, error)

ApplyRuntimeCommand applies one previously admitted command.

The ordering is the contract. The private application prefix — public CommandID, the one RuntimeCommandID it maps to, and the lease epoch — is made durable BEFORE any runtime-visible effect. A delivery that finds the prefix already durable applied nothing and returns the ORIGINAL disposition; a delivery whose public id is durably bound to a DIFFERENT runtime id fails closed.

Harness allocates no identity here. The dispatched command carries the admitted RuntimeCommandID verbatim, and the opaque public id is never parsed as a UUID.

A NON-NIL ERROR DOES NOT MEAN THE COMMAND MAY BE RE-OFFERED, and the RETURNED DISPOSITION is how a caller tells the two apart:

• zero Disposition + error: nothing durable was written (validation, a lost or stale lease, a mapping conflict, an unreadable prefix, a failed prefix append). The command is untouched and may be re-offered.
• non-zero PrefixSequence + error: the prefix COMMITTED and the effect then failed — an exited loop, a cancelled context. Every later delivery is a duplicate that applies nothing.

The second case is inherent to writing the correlation before the effect, and it is the safe direction: the alternative is applying the command twice. Returning the earned disposition alongside the error is what keeps it observable without forcing a redelivery to find out. See TestEffectFailureAfterTheDurablePrefixStrandsTheCommand.

KNOWN GAP — A HOST ADAPTER MUST NOT BLOCK ON ANY APPLICATION SETTLING, of any kind. The released settlement correlation resolves a prefix by ADJACENCY: the record at prefix+1 must be the public event the command caused, and its resolve() switches on that record's envelope kind without ever inspecting the command's kind. This applier writes the prefix LAST before the effect, so adjacency holds when nothing else is writing — but nothing GUARANTEES it. A concurrent legacy Submit's audit intent record, another loop's event in a multi-loop session, or a checkpoint landing in that slot resolves an INPUT unresolved exactly as readily as an interrupt. The interrupt is merely the kind that is always in that position: it has no guaranteed public event at all, and an idle interrupt is fail-quiet.

Unresolved never licenses a rejection, so this is liveness and not correctness — which is precisely why it is written down: nothing fails, the command simply never settles, and a caller that waits for it waits forever. Closing it needs either a guaranteed durable effect record per kind or the prefix-and-effect pair serialized against every other append; both are decisions about the public event vocabulary and the writer's admission rather than about this seam, so neither is made here. pkg/sessionstore's TestAdjacencyIsNotGuaranteedForAnyCommandKind measures the consequence for both kinds and holds the semantics still while it waits.

func (*Session) AwaitGateAnswer ¶

func (s *Session) AwaitGateAnswer(ctx context.Context, id gate.ID) (gate.Answer, error)

AwaitGateAnswer blocks until a HOST-OWNED gate is answered and returns the validated answer, including the form values that are deliberately absent from every durable record.

It is the host's half of the loop's command dispatch: the opener of a form or open-url gate calls PrepareGateOpen, ActivateGate, then this. It returns a typed *GateError{GateNotFound} for a gate that is not host-owned, was never prepared, or whose answer was already taken — an answer is delivered exactly once.

The opener MUST either await or CloseGate, which is the same obligation ActivateGate already places on it. Both paths free the slot.

A ctx cancellation abandons the wait and frees the slot; it does NOT close the gate, because the gate is durable state and ctx is the caller's. An opener that gives up should CloseGate.

func (*Session) CheckpointWorkspace ¶

func (s *Session) CheckpointWorkspace(ctx context.Context) (workspacestore.Ref, error)

CheckpointWorkspace durably snapshots the session's configured workspace root and records a WorkspaceCheckpointed enduring event pointing at the snapshot — the resume token the restore path materializes from. It returns the snapshot Ref (also carried on the event) so the caller can correlate the checkpoint.

Snapshot-before-append: the archive bytes are durable (Snapshot's Blobs.Put has returned) BEFORE the event is appended, so a crash between the two leaks an unreferenced blob (GC's job) — never a dangling ref. That ordering is guaranteed by call order here (Snapshot returns before PublishEvent runs), not by any stronger signal.

The WorkspaceCheckpointed is Enduring, so it flows through the hub's REQUIRED durable tap: the event is appended synchronously BEFORE fan-out, and a durable-append failure surfaces as a SESSION FAULT (the hub latches it via ReportFault) exactly like every other enduring event — PublishEvent itself returns nil on that path. This method adds no stronger durability signal; on the happy path the event IS durably appended by the time it returns.

WHEN to call this — a quiescence point (a turn done, a user question, about to suspend) — is the composition root's decision, consistent with looprig-as-SDK and the foreign-loop quiescence model; the session only exposes the capability. Without WithWorkspaceCheckpointing the capability is unconfigured and this fails closed with a typed *WorkspaceNotConfiguredError, having touched nothing. ctx bounds the snapshot I/O and the durable append.

func (*Session) CloseGate ¶

func (s *Session) CloseGate(ctx context.Context, id gate.ID, reason gate.CloseReason) error

CloseGate closes or abandons a session-owned gate without dispatching an answer to the resolver. Preparing gates were never public, so they are removed without a public GateResolved. Open gates are durably resolved before removal.

func (*Session) CommitBoundary ¶

func (s *Session) CommitBoundary(ctx context.Context, ev event.Event) error

CommitBoundary is the native loop-actor boundary seam. Without a configured workspace policy it preserves ordinary publication; with one it delegates the already-stamped StepDone/turn terminal to the session checkpoint controller.

func (*Session) CommitContextBoundary ¶

func (s *Session) CommitContextBoundary(ctx context.Context, ev event.Event) (bool, error)

CommitContextBoundary is the context-mutating boundary seam. The committed result distinguishes an event append failure from a later checkpoint failure, so the loop actor can keep live history aligned with durable restore state.

func (*Session) CommitSessionIdle ¶

func (s *Session) CommitSessionIdle(ctx context.Context, idle event.SessionIdle, commit func() error) error

CommitSessionIdle is the hub's narrow derived-idle collaborator. The hub retains append/fanout ownership in commit; the controller brackets it with the workspace permit and accepted checkpoint walk when idle is the configured trigger.

func (*Session) CommittedPublicEvents ¶ added in v0.31.0

func (s *Session) CommittedPublicEvents() (sessionapi.CommittedPublicEventSource, bool)

CommittedPublicEvents reports the segregated committed-public-event capability (sessionapi.CommittedPublicEventProvider). It is true only when this session's injected event appender can report the EXACT canonical public bytes a durable append stored; a headless/no-persistence session and one over a journal without that seam both answer (nil, false).

The capability is discovered rather than assumed because it is a property of the injected persistence, not of *Session: the same type serves both. Returning the session itself as the source once the hub confirms support keeps the refusal at discovery time, before a consumer has subscribed and started advancing a cursor.

func (*Session) Compact ¶

func (s *Session) Compact(ctx context.Context) (uuid.UUID, error)

Compact requests manual compaction of the currently active loop. The active id is sampled once, then routed through the exact-target implementation.

func (*Session) CompactToLoop ¶

func (s *Session) CompactToLoop(ctx context.Context, loopID uuid.UUID) (uuid.UUID, error)

CompactToLoop requests manual compaction of one exact live native loop. The trusted session boundary owns user agency and command coordinates; callers receive only the correlation id used by durable waiter outcomes.

func (*Session) Done ¶ added in v0.30.0

func (s *Session) Done() <-chan struct{}

Done reports session liveness: the returned channel is closed once Shutdown has BEGUN (teardown admits no new work) and never reopens. It is the signal an out-of-process observer needs, because a shut-down session is otherwise indistinguishable from a live one from outside: Hub.SubscribeEvents still succeeds after the hub is stopped, so an event stream over a dead session would heartbeat forever, pinning its handler goroutine, its subscription and this whole Session.

A receive on it must never be read as "cleanup finished" — it fires at the start of teardown, deliberately.

The channel is minted here on first use under the same shutdownMu that Shutdown closes it under, so every Session reports liveness however it was built. Done takes only shutdownMu and calls nothing, and Shutdown never calls Done, so the two cannot deadlock.

func (*Session) EnterExecution ¶

func (s *Session) EnterExecution(ctx context.Context, loopID uuid.UUID) (func(), error)

EnterExecution is the inference-step session-wide checkpoint and loop-scoped interrupt admission seam.

func (*Session) EnterTurnStart ¶

func (s *Session) EnterTurnStart(ctx context.Context, loopID uuid.UUID) (loopruntime.TurnStartCapability, error)

EnterTurnStart reserves the Hub activity transition before acquiring the first checkpoint reader. Its returned capability publishes the exact opening event and releases the checkpoint reader when the first inference step ends.

func (*Session) FaultErr ¶

func (s *Session) FaultErr() error

FaultErr is the loop actor's post-emit durable-fault probe (loopruntime type-asserts the session for it). It returns the latched persistence fault (a required Enduring append failed) or nil. After emitting a mode/inference change event, the actor calls it: because the hub raises the fault INLINE (synchronously on the same actor goroutine, via ReportFault) when the append fails, a non-nil result here means the change event did not persist, so the actor declines to apply the change (fail-secure, no partial apply).

func (*Session) Interrupt ¶

func (s *Session) Interrupt(ctx context.Context) (bool, error)

Interrupt is the human "stop everything": it cancels the running turn of EVERY live loop in the session — every registered loop — marking each interrupt-pending before fanning the command.Interrupt out to all of them CONCURRENTLY (design: "Session.Interrupt marks every live loop interrupt-pending before concurrently sending commands"). Idle loops ack false and are harmless; Interrupt returns true iff ANY loop reported it cancelled a running turn. A fully-idle interrupt is fail-quiet: it returns false and appends no events. ctx bounds the fan-out so a slow actor cannot wedge it.

Unlike Shutdown, Interrupt does NOT latch closing and does NOT tear loops down. It stamps Agency=AgencyUser (a human pressed interrupt). Selection + marking + concurrent delivery + the admission barrier live in interrupt.go (runInterrupt); this is the session-wide scope.

func (*Session) LeaseEpoch ¶ added in v0.33.0

func (s *Session) LeaseEpoch() (uint64, bool)

LeaseEpoch is the exported session.LeaseEpochReporter capability: it reports the single-writer journal lease epoch this resident process currently holds, and whether it holds one at all. The contract, and the argument for the two-result shape, live on session.LeaseEpochReporter; this is where the answer is produced.

It is gated on Valid(), which is the ONE way it differs from the unexported leaseEpoch() the residency record uses. That difference is deliberate and the two must not be merged. leaseEpoch() runs inside teardown, while the lease is still held, and records the epoch that produced the work being released — history, which stays true afterwards. This one answers a live consumer asking what it may stamp NOW, and a lease that has been released or lost may not be stamped against at all, so it reports absence rather than the number it used to hold. journal.Lease keeps reporting its Epoch after Release (no pinned provider zeroes it), so consulting Valid is the only thing that distinguishes the two states.

It reads two fields set once at construction and does no I/O, so it neither blocks nor takes the session lock.

func (*Session) ListGates ¶

func (s *Session) ListGates(context.Context) []gate.Gate

ListGates returns the public envelopes of all open gates — preparing, claiming, and closed entries are excluded. The returned slice is a snapshot; mutating it does not affect the directory.

func (*Session) Loop ¶

func (s *Session) Loop(id uuid.UUID) (loop.Handle, bool)

func (*Session) LoopController ¶

func (s *Session) LoopController(id uuid.UUID) (loop.Controller, bool)

func (*Session) NewLoop ¶

func (s *Session) NewLoop(parent loop.Provenance, cfg loop.Definition) (uuid.UUID, error)

NewLoop creates another loop inside this session. The new loop shares SessionID but receives its own loop id and loop goroutine. parent is the provenance of the spawning turn/step (zero for a root loop); the session records it in the registry and passes it to loopruntime.New. The session stores the loop handle and returns only the loop id, because callers route through session methods rather than writing to a loop command channel directly.

func (*Session) NotifyProcessCompletion ¶

func (s *Session) NotifyProcessCompletion(ctx context.Context, n tool.ProcessCompletionNotification) error

NotifyProcessCompletion is Task 24C's real implementation of tool.ProcessCompletionNotifier, attached behind the session-owned sessionProcessServiceBridge exactly like 24B's checked lifecycle publisher (see process_services.go's attachProcessCompletionNotifier). It reports only the boundary contract's plain error (nil on ACCEPTED or DUPLICATE, the durable append's typed collision on COLLISION, and a typed reason on STOPPED); notifyProcessCompletion below carries the richer command.ProcessNotificationResult a caller inspecting the disposition (tests, and a future retry policy) needs.

func (*Session) OpenHostGate ¶

func (s *Session) OpenHostGate(ctx context.Context, loopID uuid.UUID, g gate.Gate, payload gate.Payload) (gate.ID, error)

OpenHostGate opens a HOST-OWNED gate and returns its id, ready to be awaited.

It is the ONLY gate-opening entry point on the published session.GateHost contract, and it is deliberately not PrepareGateOpen. PrepareGateOpen takes an arbitrary kind, resolver, payload, and — through the ActivateGate route that must follow it — an arbitrary target loop, which together are exactly the loop-owned command path (dispatchGateCommand). A host must not be able to reach that: minting an "approve this tool call" gate against someone else's loop is not a capability an integration should acquire by being able to ask a human a question. This entry point takes the same arguments minus the route and refuses everything that is not host-owned, so the loop path is unreachable through it by construction rather than by convention.

It collapses prepare and activate into one call, which is safe precisely because the gate is host-owned. The two phases exist so a LOOP can install its blocker while the gate is still private; a host's blocker is the answer slot, and PrepareGateOpen installs that itself. There is no window here for the opener to miss.

Every rejection is a *GateError{GateKindMismatch}, checked BEFORE anything is journaled:

• hostOwnedGate — the same predicate that governs answer time, so open time and answer time cannot drift apart. A form gate declaring ResolverLoop is refused here rather than accepted and then refused after a human has already answered it.
• the payload must match the kind, so a form gate cannot be opened with an open-url payload (which would strand its answer at ParseFormAnswers).
• the payload's own invariants (ValidateFormSchema / ValidateOpenURLPayload) must hold, because an unanswerable or targetless prompt should never reach a human.

It then DERIVES the trusted half of the public projection from the validated payload (projectHostGatePrompt), so the envelope a renderer sees cannot disagree with the payload a response is validated against.

The caller MUST either AwaitGateAnswer or CloseGate; both free the slot.

func (*Session) PrepareGateOpen ¶

func (s *Session) PrepareGateOpen(ctx context.Context, loopID uuid.UUID, g gate.Gate, payload gate.Payload) (gate.ID, error)

PrepareGateOpen durably commits the public envelope plus private payload as a private GatePreparedRecord. It mints the GateID, stamps the GatePrepared event with the session's coordinates and the caller's loopID, appends the record via the strict gateAppender, and — only on success — inserts a non-listable preparing entry. A failed append returns a typed *GateError{GateAppendFailed} and does not mutate the directory. loopID is the producing loop's id (the GatePrepared event is loopScoped); TurnID/StepID are read from the gate's Subject.

func (*Session) PublishEvent ¶

func (s *Session) PublishEvent(ctx context.Context, ev event.Event) error

PublishEvent is the session's eventPublisher implementation passed to loopruntime.New. It delegates to the hub, which fans the event out to matching subscribers and applies any quiescence transition the event implies. The loop depends only on the narrow eventPublisher interface; it never sees the hub, its subscriber set, or its shutdown state (Interface Segregation / least privilege).

func (*Session) PublishEventChecked ¶

func (s *Session) PublishEventChecked(ctx context.Context, ev event.Event) error

PublishEventChecked is the transactional publication path for state transitions whose caller must not mutate live state unless the required append commits. Delegate acceptance, public gate open/resolve transitions, and native checkpoint boundaries use it to receive append failures directly while retaining durable-first fan-out.

func (*Session) ReleaseResidency ¶ added in v0.31.0

func (s *Session) ReleaseResidency(ctx context.Context) error

ReleaseResidency gives up THIS process's resident runtime for the session — subscriptions, actors, supervised processes, leases, local contexts — while leaving the logical session restorable elsewhere. It is the nonterminal counterpart of Shutdown and satisfies session.Releaser.

It deliberately does NOT call Shutdown. Shutdown's hub stop durably appends SessionStopped, which makes the logical session terminal; a registry loser that used it to hand a session over would have ended someone's session instead of releasing it. Everything else about the teardown IS Shutdown's: both drive the one sequence in Session.teardown, differing only at the plan seams below.

The order is:

1. Admission. The session must not be faulted and must be whole-session idle. This runs before the teardown owner is elected, so a refusal leaves the session exactly as it was and returns *ResidencyReleaseRefusedError.
2. The shared teardown: latch closing, revoke collaboration origins, close hustle admission, shut down and drain every loop, stop the checkpoint controller and the offload GC, terminate the session resource registry.
3. Take and durably commit the anchoring workspace checkpoint, then append SessionResidencyReleased carrying that checkpoint's sequence and the lease epoch. A checkpoint that does not commit writes NO residency record — a record naming an anchor that does not exist is worse than no record.
4. Close the hub LOCALLY, appending no SessionStopped.
5. Release the workspace root lease then the session lease, cancel the session context, and abandon foreign delivery hooks.

Done closes at the START of step 2, not at the end, so a supervisor learns the session is going away while teardown is still running.

Concurrent and repeated calls — and a race with Shutdown — join ONE teardown owner and receive its result. Whoever is elected runs its own mode to completion; the stream therefore carries either a SessionResidencyReleased or a SessionStopped, never both.

WHICH one it carries is not in this call's return value — a joined caller gets the owner's result, and nil means "teardown succeeded" under either mode. A caller that needs to know reads the session catalog, which projects the two apart on purpose (sessionstore.applyEvent): a release leaves Status/State untouched and sets Residency=cold, so the session reads cold AND restorable, while a stop sets Residency=cold together with Status=stopped/State=stopped. Residency alone never distinguishes them — no process is resident after either — so a caller deciding whether a session can still be restored must read the terminality axis, not residency.

The idle admission is not a lock: a Submit to an already-registered loop may still be accepted between the admission check and the closing latch. It is not lost and it does not corrupt the anchor — step 2 sends every loop a Shutdown command and waits for the drain, so the checkpoint in step 3 is taken with no loop running.

func (*Session) ReportFault ¶

func (s *Session) ReportFault(_ context.Context, fault *hub.SessionPersistenceFault)

ReportFault is the session's fail-secure response to a hub persistence fault (a required durable append failed): it latches the faulted state (so every new Submit/NewLoop is refused) and wakes every blocked WaitIdle waiter with the fault. It is the hub's FaultReporter — the hub calls it inline (outside the hub lock) when AppendEvent fails the durable tap. It is idempotent: the FIRST fault latches and records the cause; a later fault still wakes any new waiters but keeps the first recorded cause (the root failure). The session is NOT torn down here — restore / operator action owns recovery; this only stops admitting new work and unblocks callers stuck waiting on a session that can no longer reach idle durably.

func (*Session) RespondGate ¶

func (s *Session) RespondGate(ctx context.Context, response gate.GateResponse) error

RespondGate claims an open gate, durably appends GateResolved, and dispatches the translated command to the owning loop. It is durable-first: the GateResolved append happens BEFORE the command dispatch, so a crash after the append leaves the gate closed (not re-answerable) even if the command was not yet consumed. A failed append reverts the in-memory claim and leaves the gate answerable. Command dispatch uses s.sessionCtx (not the caller's ctx) so a client disconnect after the durable commit does not cancel delivery.

A caller-supplied response whose Source.Kind is gate.ResponseFromClassifier is rejected outright, before any locking or validation: only the private respondFromClassifier method (called exclusively from the permission-review adapter once gate.CombinePermissionAssessments reports eligibility) may produce that provenance. gate.ResponseSource's fields are exported — a public caller CAN construct one with Kind set to ResponseFromClassifier — so this is a runtime, defense-in-depth check rather than a type-system guarantee; respondFromClassifier reaches the shared core below directly and is not subject to it.

func (*Session) RestoreWorkspace ¶

func (s *Session) RestoreWorkspace(ctx context.Context, ref workspacestore.Ref) error

RestoreWorkspace rewinds the managed workspace to ref. It fails closed with *WorkspaceNotConfiguredError when no placement is configured, and with a typed *WorkspaceRestoreError on any admission, staging, or commit failure.

func (*Session) RunAgent ¶

func (s *Session) RunAgent(ctx context.Context, parent loop.Provenance, cfg loop.Definition, blocks []content.Block, parentToolUseID string) (string, error)

RunAgent creates an in-session sub-loop, runs one turn on it for the given blocks (machine-originated), and returns the sub-loop's final assistant text. It is the SOLE exported entry point of the agent composition: it wires together the unexported building blocks (NewLoop + SubscribeEvents + submitToLoop + drainToFinalText + interruptLoopID) so the agent collaboration tools' injected capability (a later task) has one method to call and the blocks stay package-private.

cfg is the sub-loop's loop.Definition — the CALLER builds a FRESH cfg per call (its own ToolSet and access gate) so each sub-loop has independent approval state; RunAgent never reuses a shared ToolSet. parent is the spawning loop/turn/step provenance (recorded on the sub-loop's registry entry and stamped on its LoopStarted). The submit is stamped Agency=AgencyMachine — an agent turn is a machine action, never falsely attributed to a human.

The sub-loop PERSISTS idle after the turn (loops are never deleted, design §8): RunAgent closes only the SUBSCRIPTION, never the loop. The ordering is load-bearing: it subscribes (scoped to the new sub-loop) BEFORE submitting, so the opening TurnStarted the drain correlates on cannot be missed — the hub has no replay (design §4).

Errors propagate from the first block that fails: NewLoop (e.g. SessionClosing while shutting down, or id-gen failure), SubscribeEvents, the submit, or the drain's typed §5 failures (*drainFailedError / *TurnRejectedError / *drainInterruptedError / *drainLostError). ctx is the calling turn's context; because submits carry no ctx, a ctx cancel cannot reach the sub-loop's turn — the drain translates it into a single loop-targeted Interrupt (the closure below) and drains to the resulting TurnInterrupted terminal.

func (*Session) RuntimeCommands ¶ added in v0.31.0

func (s *Session) RuntimeCommands() (runtimecommand.Applier, bool)

RuntimeCommands reports whether this session can apply Host-admitted runtime commands, and hands back the applier when it can.

This is a SEGREGATED capability, not a method on session.Session, for the same reason CommittedPublicEventSource is: almost every Session implementation — every test double, the TUI's view, an adapter that only reads — will never apply an admitted command, and widening the base contract would force all of them to grow a method they cannot honor. The two-result form is what lets a Host adapter learn the answer BEFORE it has acknowledged a command as accepted.

func (*Session) SessionActivated ¶

func (s *Session) SessionActivated()

SessionActivated lets the hub cancel an active best-effort quiescent walk before newly active work proceeds. Required and shared-fuzzy policies ignore activation.

func (*Session) SessionID ¶

func (s *Session) SessionID() uuid.UUID

func (*Session) SetActiveLoop ¶

func (s *Session) SetActiveLoop(ctx context.Context, id uuid.UUID) error

func (*Session) Shutdown ¶

func (s *Session) Shutdown(ctx context.Context) error

Shutdown drives the WHOLE session to its stopped phase and blocks until every loop's actor exits. Sub-loops are retained (each runs its own goroutine and loopCtx), so Shutdown must reach every loop. The order is deliberate:

1. Latch closing AND snapshot the loops in ONE loopsMu critical section. This is the atomicity NewLoop's registration check pairs with (it re-tests closing under the same lock): a loop is either already in this snapshot or refused by NewLoop — never registered after the snapshot is taken.
2. Close hustle admission and cancel queued/executing inference. Keep the checkpoint controller, hub, and session context open for owned cleanup.
3. Send command.Shutdown to EVERY loop in the snapshot, recording each reached loop's (loop, ack) pair. Per loop: mint a CommandID; on id-gen failure SKIP that loop's graceful shutdown (the final sessionCancel hard-cancels it) rather than aborting the whole Shutdown. A loop already exited is skipped.
4. Wait for every recorded ack, then join hustle terminal audit, finalizers, and blocking activity release through Controller.Drained.
5. Stop/join checkpoints and offload GC, terminate session resources, append SessionStopped/stop the hub, release root/session leases, and cancel sessionCtx last.
6. Loop/checkpoint/hub phases have private deadlines derived from validated component bounds. Hustle audit, finalization, and worker drain use their own trusted inner bounds and are always joined; an outer deadline never detaches owned cleanup. Caller cancellation is diagnostic only.

Concurrent and repeated calls join one teardown owner and receive the same cleanup result, augmented with each caller's own context error after cleanup completes. That owner is shared with ReleaseResidency, so a session is either stopped or released, never both.

Steps 1-5 are Session.teardown, the sequence both teardown modes run; Shutdown supplies only the terminal plan (terminalTeardown).

func (*Session) StartPermissionReview ¶

func (s *Session) StartPermissionReview(ctx context.Context, req loopruntime.PermissionReviewRequest)

StartPermissionReview implements the loop actor's private permissionReviewStarter seam (internal/loopruntime/gate.go): the ONLY thing the actor calls, inline and fire-and-forget, after a gatePermission registration activates and the runner has been acked (design §14.2/§14.3). It MUST return promptly — the actor never wraps this call in a goroutine of its own, so classifier inference is moved onto a fresh goroutine here (`go adapter.review(...)`) before this method returns.

StartPermissionReview no-ops (starts no review) whenever:

• no permission classifiers are configured for this session (s.permissionClassifiers is the zero PermissionClassifierSet); or
• the session's shared Hustle runtime is not yet bound (s.hustleController == nil — cannot happen once a session has finished construction, but is checked rather than assumed); or
• the classifier/policy configuration itself is invalid (newPermissionReviewAdapter's own validation).

Every one of those is a "nothing to review" outcome, never a denial or an approval: this method has no path to RespondGate at all (see permissionReviewAdapter's type doc), so the human gate this handoff accompanies is always preserved regardless of what happens here.

func (*Session) Submit ¶

func (s *Session) Submit(ctx context.Context, input []content.Block) (uuid.UUID, error)

Submit is the HUMAN-ONLY submit entry point: it stamps Agency=AgencyUser (a person authored this input). Programmatic/machine callers go through submitToLoop with Agency=AgencyMachine (the agent path).

Submit sends input as a queueable UserInput to the active loop, FIRE-AND-FORGET: it returns the InputID (the submit command's id, == the Cause.CommandID on the resulting Reply events) and a transport error only if the command could not be handed to the loop. The outcome — InputQueued / TurnStarted / TurnFoldedInto / TurnRejected / InputCancelled — is observed on the event fan-in (each Reply carries Cause.CommandID == this returned id), NOT returned here.

A submit while a turn is running QUEUES rather than rejecting; a submit while idle starts a turn. Submit never reads a reply, so it returns the instant the command is accepted by the loop.

The send carries the standard escapes: ctx.Done() → SessionContextDone, the loop's Done → SessionLoopExited, and a missing active loop → SessionLoopNotFound. On any of those the returned id is the zero UUID, because nothing was sent and there is no correlation to hand back.

func (*Session) SubmitToLoop ¶

func (s *Session) SubmitToLoop(ctx context.Context, loopID uuid.UUID, blocks []content.Block) (uuid.UUID, error)

SubmitToLoop is the loop-targeted counterpart of Submit: it sends human-authored (AgencyUser) input to a SPECIFIC loop's CommandSink rather than the active selection. It is the modern viewport's "submit to the FOCUSED loop" primitive — a submit while focused on a agent runs a NEW turn on THAT loop (accepted: a submit to an idle-but-tracked agent starts a fresh turn on it), while a submit to the active loop id behaves exactly like Submit.

Like Submit it stamps command.UserInput with Agency=AgencyUser and is FIRE-AND-FORGET: it returns the minted InputID (the Cause.CommandID the resulting Reply events carry on the session fan-in) and a transport error only; the turn outcome — InputQueued / TurnStarted / TurnFoldedInto / TurnRejected / InputCancelled — is observed on the event fan-in, never returned here. The send carries the same escapes as Submit: ctx.Done() → SessionContextDone, the loop's Done → SessionLoopExited, and an unknown loop id → SessionLoopNotFound. On any of those the returned id is the zero UUID, because nothing was sent and there is no correlation to hand back. It delegates to the shared loop-targeted core submitToLoop with AgencyUser, exactly as Submit does for the active loop.

func (*Session) SubscribeCommittedPublicEvents ¶ added in v0.31.0

func (s *Session) SubscribeCommittedPublicEvents(filter event.EventFilter) (event.Subscription, error)

SubscribeCommittedPublicEvents attaches a consumer to the committed public event stream, on which every delivery carries the canonical body the durable append stored. It delegates to the hub, which refuses with *hub.CommittedPublicEventsUnavailableError if the capability is not supported — so a caller that reached this method without going through CommittedPublicEvents still cannot obtain a stream the persistence cannot back.

func (*Session) SubscribeEvents ¶

func (s *Session) SubscribeEvents(filter event.EventFilter) (event.Subscription, error)

SubscribeEvents attaches a consumer to the session fan-in with the given filter. The returned subscription's Events() channel yields the filtered stream; the caller must Close it when done. It delegates to the hub.

func (*Session) WaitIdle ¶

func (s *Session) WaitIdle(ctx context.Context) error

WaitIdle blocks until the session is quiescent, ctx is done, or the session has stopped (hub.ErrSessionStopped). It is the headless caller's "is the whole interaction at rest?" primitive; it delegates to the hub's quiescence model.

func (*Session) WorkspaceStatus ¶ added in v0.31.0

func (s *Session) WorkspaceStatus() sessionapi.WorkspaceStatus

WorkspaceStatus reports what this session knows about the workspace it came up on. It satisfies sessionapi.WorkspaceReporter, the segregated capability a Host discovers by assertion; the contract's doc comment is authoritative for what each field means.

A session with no managed workspace reports the zero value. On a fresh session the boundary fields are zero because there is no prior stream to fold; Restore is the only caller that has one.

FRESHNESS: Root and LogicalRoot are read live, the boundary fields are AS OF RESTORE and never refresh. A session that checkpoints again after coming up still reports the boundary it came up on, so a caller polling this for a live checkpoint position gets a mix of live and frozen fields. Refreshing it would mean folding the stream again on every call; the report exists for the restore decision, not as a checkpoint cursor.

It is a REPORT. Nothing in it recovers a lost mutation or bounds how much was lost.

func (*SessionResourceStorageError) Error ¶

func (e *SessionResourceStorageError) Error() string

func (*SessionResourceStorageError) Unwrap ¶

func (e *SessionResourceStorageError) Unwrap() error

func (*ShutdownCleanupTimeoutError) Error ¶

func (e *ShutdownCleanupTimeoutError) Error() string

func (*ShutdownCleanupTimeoutError) Unwrap ¶

func (e *ShutdownCleanupTimeoutError) Unwrap() error

func (*WorkflowActivityOwnerMismatchError) Error ¶

func (e *WorkflowActivityOwnerMismatchError) Error() string

func (*WorkspaceLifetimeAccessError) Error ¶

func (e *WorkspaceLifetimeAccessError) Error() string

func (*WorkspacePathError) Error ¶

func (e *WorkspacePathError) Error() string

func (WorkspacePlacement) Configured ¶

func (p WorkspacePlacement) Configured() bool

Configured reports whether the placement provisions a managed workspace.

func (*WorkspaceRestoreError) Error ¶

func (e *WorkspaceRestoreError) Error() string

func (*WorkspaceRestoreError) Unwrap ¶

func (e *WorkspaceRestoreError) Unwrap() error

func (*WorkspaceSeedError) Error ¶

func (e *WorkspaceSeedError) Error() string

func (*WorkspaceSeedError) Unwrap ¶

func (e *WorkspaceSeedError) Unwrap() error

func (*ZeroSuppliedCommandIDError) Error ¶ added in v0.31.0

func (*ZeroSuppliedCommandIDError) Error() string