# Session Runtime

SessionRuntime is the canonical owner of mutable task-session state for execution-oriented work. It sits between `TaskExecutor` and the lower-level turn executor, so the executor keeps task lifecycle responsibilities while the runtime owns the session mirror, permission state, persistence, and recovery behavior.

## What It Owns

SessionRuntime groups all mutable session state into explicit buckets:

- `transcript`: conversation history, latest user and assistant outputs, chat summary blocks, and step outcome summaries
- `tooling`: tool failure tracking, tool usage counters, tool-result memory, web evidence memory, and visible-tool render caching
- `files`: file-read tracking and file-operation tracking
- `loop`: turn counts, continuation counters, compaction counters, loop fingerprints, and soft-deadline flags
- `recovery`: retry and failure-signature state, recovery classification, and tool-disable scopes
- `queues`: pending follow-ups and step-feedback signals
- `worker`: mentioned-agent dispatch state and verification-agent state
- `verification`: verification evidence and failed-step tracking
- `checklist`: session-local execution checklist items, nudge state, and checklist timestamps
- `promptCache`: stable system blocks, stable-prefix hash, tool-schema hash, provider-family mode, and invalidation reason
- `usage`: cumulative token and cost tracking plus usage offsets
- `permissions`: default mode, session-local rules, temporary grants, denial counters, and latest prompt context

This is the state that used to be mirrored across the executor and related helpers. It now lives in one place so task resume, retry, and completion logic read the same source of truth.

## Managed Session Relationship

Managed Agents adds a durable API-facing run object, `ManagedSession`, above the existing runtime.

The ownership split is:

- `ManagedSession` is the stable control-plane resource for reusable runs, event history, and resume/cancel semantics
- `Task` remains the execution worker that owns `SessionRuntime`
- `SessionRuntime` still owns mutable task-session state and `session_runtime_v2` snapshots

In practice, a managed session points at one backing task and optionally one backing team run. Managed-session events mirror sanitized task and daemon events so UI/backend consumers can observe one durable session stream without bypassing the task runtime.

## Tool Availability and Rendering

SessionRuntime also owns the runtime-facing available-tools path used by execution and follow-up turns.

The sequence is:

1. start from the tool catalog
2. apply restriction, allowlist, policy, mode, and intent filters
3. render prompt-aware descriptions only for the remaining visible tools
4. cache the rendered result for repeated turns under the same visible-tool and render-context state

This means tool-local guidance is attached only to tools the current task can actually see.

The render-context inputs include:

- execution mode
- task domain
- web-search mode
- shell availability
- agent type
- worker role
- user-input allowance

The provider-facing tool shape remains unchanged after rendering; providers still receive only `name`, rendered `description`, and `input_schema`.

## Prompt Cache State

SessionRuntime persists the stable prompt-cache context needed to reuse provider-side prompt prefixes across turns and restarts.

It tracks:

- stable session-scoped `systemBlocks`
- `stablePrefixHash`
- `toolSchemaHash`
- prompt-cache mode and provider family
- the latest invalidation reason when the stable prefix changes

This lets CoWork reuse the same cacheable prefix after follow-ups, resume from `session_runtime_v2` snapshots without rebuilding it blindly, and explain why a cache epoch changed when model, provider family, tool schema, or stable prompt contracts changed.

## Public Surface

The runtime exposes a narrow API for the executor and task orchestration layers:

- `runStepLoop(...)`
- `runFollowUpLoop(...)`
- `runTextLoop(...)`
- `queueFollowUp(...)`
- `setStepFeedback(...)`
- `drainAllPendingFollowUps(...)`
- `maybeAutoContinueAfterTurnLimit(...)`
- `continueAfterBudgetExhausted(...)`
- `resetForRetry(...)`
- `saveSnapshot(...)`
- `restoreFromEvents(...)`
- `projectTaskState(...)`
- `createTaskList(...)`
- `updateTaskList(...)`
- `listTaskList(...)`
- `getTaskListState(...)`
- `clearTaskListVerificationNudge()`
- `getOutputState(...)`
- `getVerificationState(...)`
- `getRecoveryState(...)`
- `getPermissionState(...)`
- `applyWorkspaceUpdate(...)`

The executor still owns task bootstrap, plan construction, completion policy, UI/daemon updates, and final result projection. It now delegates session state changes instead of duplicating them.

## Session Checklist Primitive

SessionRuntime now owns a lightweight session checklist that is separate from:

- plan steps
- shared team checklists
- any database-backed durable checklist model

The checklist is session-scoped, agent-managed, and persisted only inside `session_runtime_v2` snapshots and checklist events. It exists to keep execution disciplined during multi-step work without creating a second planning system.

### Tool surface

Execution-capable paths expose three runtime tools:

- `task_list_create`
- `task_list_update`
- `task_list_list`

They are intentionally unavailable in chat, plan, analyze, and other non-executing paths.

### Runtime semantics

- `task_list_create` creates the first ordered checklist and fails if one already exists
- `task_list_update` replaces the full ordered state
- existing items keep their ids when the caller supplies them
- new items may omit `id` and the runtime generates one
- `kind` defaults to `implementation`
- create and update reject empty lists, duplicate ids, and more than one `in_progress` item

### Verification nudge algorithm

The checklist can raise a non-blocking verification reminder when all of the following are true:

- a session checklist exists
- at least one checklist item has `kind: "implementation"`
- every implementation item is `completed`
- no checklist item has `kind: "verification"`
- the current plan does not already contain a verification step
- the task is not already on a verified path with explicit verification coverage

When that happens:

- `task_list_update` returns `verificationNudgeNeeded: true`
- `task_list_create` and `task_list_update` can append an immediate human-readable reminder in the tool result payload seen by the model
- SessionRuntime persists that flag in checklist state
- the runtime emits `task_list_verification_nudged`
- next-turn preparation injects a short reminder to add or run a verification item before final completion

The reminder is advisory. It does not fail completion by itself, and the post-hoc verification runtime remains the final enforcement layer.

### UI/event model

Checklist state is replayable from events alone. The runtime emits:

- `task_list_created`
- `task_list_updated`
- `task_list_verification_nudged`

Each payload carries the full current checklist snapshot so the renderer can reconstruct the latest read-only checklist state without a separate query path.

## Turn Execution Flow

```
TaskExecutor
  -> SessionRuntime
      -> TurnKernel for the active step / follow-up / text turn
      -> provider-aware output-budget policy
      -> adaptive truncation retry helpers
      -> session state updates
      -> task projection updates
      -> snapshot save / restore
```

The turn kernel is still responsible for a single turn of execution. SessionRuntime is responsible for choosing when to run it, which state to feed into it, and how to persist the results.

## Adaptive Output Budgeting

When `COWORK_LLM_OUTPUT_POLICY=adaptive` is enabled, execution and follow-up turns resolve output limits through one shared provider-aware policy path instead of relying on provider defaults or a single tool-call floor.

### Request kinds

The runtime resolves a budget for three request kinds:

- `agentic_main`: the first execution turn for a step or follow-up
- `tool_followup`: the next turn after tool results are present in the transcript
- `continuation`: explicit continuation-only retries after a visible truncation

### Policy shape

For the current internal rollout, the runtime uses provider-family defaults for the mainstream routes first:

- Anthropic-family routes
- Bedrock Claude routes
- OpenAI routes
- Azure OpenAI routes
- Gemini routes
- OpenRouter routes
- generic fallback for everything else

Default behavior:

- main execution turns start with `8000`
- tool-follow-up turns start with `16000`
- if a main/tool turn is truncated, the runtime retries the same request once with a higher budget before injecting any continuation prompt
- the escalated target is typically `48000`
- Anthropic-family routes can escalate to `64000`
- generic fallback escalation is capped at `16000`

The runtime always sends an explicit output limit for agentic turns in adaptive mode. It does not depend on provider-side defaults because gateways and compatible endpoints vary too much.

### Budget selection

The runtime resolves the outbound limit in this order:

1. task-level `agentConfig.maxTokens`, when present
2. `COWORK_LLM_MAX_OUTPUT_TOKENS`
3. provider-family defaults for the current request kind
4. final clamping by known hard caps and context headroom

Known provider caps remain a safety rail even when task-level or env-level overrides request more.

### Truncation handling

If a turn stops because it hit the output limit, the runtime classifies the result as one of:

- `visible_partial_output`: the model produced usable answer text but was cut off
- `reasoning_exhausted`: the model spent the budget on internal reasoning or otherwise produced no usable answer text

Recovery order:

1. same-request escalation once
2. if still truncated and visible partial output exists, fall back to the normal continuation prompt path
3. if still truncated and the result is reasoning-only, stop burning continuation retries and surface a targeted guidance message instead

This keeps continuation retries focused on recoverable truncation and avoids loops where the model repeatedly spends the entire budget without producing visible output.

### Logging and rollout controls

The runtime logs output-budget decisions on each agentic call, including:

- provider family
- request kind
- chosen budget
- transport token field
- cap source
- escalation attempted
- truncation classification
- whether continuation fallback was allowed or skipped

Internal rollout is controlled by environment flags:

- `COWORK_LLM_OUTPUT_POLICY=legacy|adaptive`
- `COWORK_LLM_MAX_OUTPUT_TOKENS`
- `COWORK_LLM_AGENTIC_INITIAL_MAX_TOKENS`
- `COWORK_LLM_AGENTIC_ESCALATED_MAX_TOKENS`

`COWORK_LLM_OUTPUT_POLICY` defaults to `legacy` unless explicitly enabled. `COWORK_LLM_TOOL_RESPONSE_MAX_TOKENS` remains a legacy compatibility input and is no longer the primary path in adaptive mode.

## Snapshot And Restore Algorithm

Persisted task state uses the legacy `conversation_snapshot` event name for compatibility, but the payload is now versioned as `session_runtime_v2`.

### Write path

1. SessionRuntime captures the full runtime snapshot.
2. It writes a `conversation_snapshot` event with:
   - `schema: "session_runtime_v2"`
   - `version: 2`
   - transcript, tooling, files, loop, recovery, queues, worker, verification, checklist, prompt-cache, usage, and permissions state
3. `TaskExecutor` no longer writes the payload directly.

### Restore path

`restoreFromEvents()` follows a strict precedence order:

1. Load a V2 checkpoint payload, if present.
2. Otherwise load the latest V2 `conversation_snapshot` event payload.
3. Otherwise restore from a legacy checkpoint payload that still contains `conversationHistory`.
4. Otherwise restore from a legacy `conversation_snapshot` event payload with `conversationHistory`.
5. Otherwise rebuild a readable fallback conversation from task events.

If a legacy payload is restored, the runtime writes back a V2 snapshot on the next checkpoint so future resumes use the canonical schema.

### Why the order matters

- Checkpoints are the most recent durable session state.
- Event payloads provide a replayable source of truth when a checkpoint is absent or stale.
- Legacy payloads remain readable so older tasks can still resume.
- Event-derived fallback keeps very old or partially migrated tasks usable even when no snapshot payload is available.

## Task Projection

`projectTaskState()` exposes the runtime-owned task fields that still need to be reflected on the task row:

- budget usage
- continuation count and window
- lifetime turns used
- compaction count and last compaction markers
- no-progress streak
- last loop fingerprint

This keeps the task row synchronized with the runtime without copying the rest of the session state into the database row itself.

## Turn-Budget Ownership

SessionRuntime and the executor now treat window turn caps as optional runtime state.

- normal interactive tasks have no implicit strategy-derived window cap
- explicit `agentConfig.maxTurns` or `agentConfig.windowTurnCap` opt a task into a bounded window
- `turnBudgetPolicy` is only meaningful when one of those explicit caps exists

Runtime telemetry reflects that distinction:

- `turn_policy_selected` records whether a task is effectively uncapped or using an explicit window cap
- `turn_window_soft_exhausted` only appears when an explicit adaptive window is actually configured
- `Global turn limit exceeded: X/X` is now reserved for tasks that intentionally opted into capped behavior

Uncapped tasks still project and enforce:

- budget usage
- continuation count and window
- lifetime turns used
- emergency fuse thresholds
- loop and no-progress safety state

## Terminal Status Synchronization

The runtime boundary is also responsible for keeping the task row and the event stream in the same terminal state.

### Completion algorithm

1. The executor computes the final outcome and terminal metadata.
2. The daemon persists the task row first, including `status`, `completedAt`, `terminalStatus`, `failureClass`, and completion summaries.
3. Only after the row update succeeds does the daemon emit `task_completed` or the final `task_status` event.

This ordering ensures the event stream never advertises completion ahead of the durable task row update.

### Resume safety algorithm

Late resume calls can happen after approvals, structured-input responses, or renderer-side event handling. To prevent a finished task from being reopened accidentally:

1. resume callers ask the daemon to resume instead of writing `executing` themselves
2. the daemon re-reads the persisted task row and derives the canonical lifecycle state
3. if the task is already terminal, resume is rejected and no state is rewritten
4. if the task is already `executing`, the daemon skips duplicate `executing` writes
5. only a genuinely resumable non-terminal task is moved back to `executing`

This protects terminal fields from stale post-resume writes and keeps task rows aligned with `task_completed` events even when approval or follow-up flows resolve very quickly.

## Workspace Refresh

When the active workspace changes, SessionRuntime swaps to the new tool registry, invalidates tool availability caches, and preserves the live transcript and loop state. This lets the task continue without resetting the session mirror.

It also clears workspace-derived permission cache entries so the next evaluation uses the refreshed
workspace rule set.

## Related Docs

- [Architecture](architecture.md)
- [Execution Runtime Model](execution-runtime-model.md)
- [Features](features.md)
- [Context Compaction](context-compaction.md)
- [Project Status](project-status.md)
- [Session Note: 2026-04-02](session-notes/2026-04-02-session-runtime-owner.md)
