@arnilo/prism 0.7.0 → 0.8.0

package/CHANGELOG.md

@@ -1,3 +1,38 @@
+## [Unreleased]
+
+## [0.8.0] - 2026-09-18 (messaging channels, connected apps, work family, durable runs, honesty gates)
+
+> **Eleven publishable packages.** `@arnilo/prism-channels` is new; `@arnilo/prism-work` replaces `@arnilo/prism-office`. Predecessor published line is **0.7.0**. Registry/tag writes stay operator-authorized.
+
+### Added
+- **Messaging channels.** `@arnilo/prism-channels` ships the transport-neutral runtime (deny-by-default sender authorization, owned session binding, serialized turns, current-run replies, one-use durable approvals, bounded attachment refs), official Telegram (private DMs, opt-in granted groups/topics, private-chat drafts, bounded media, optional voice transcription/synthesis, opt-in notices to one already-bound pair), and experimental pinned signal-cli Signal. See [docs/messaging-channels.md](docs/messaging-channels.md), [docs/telegram-channel.md](docs/telegram-channel.md), [docs/signal-channel.md](docs/signal-channel.md), [docs/messaging-channel-operations.md](docs/messaging-channel-operations.md).
+- **Connected apps and work HTTP.** Identity-bound MCP connected-app sessions admit host-selected transports and register prefixed tools. Google Workspace and Microsoft 365 HTTP adapters live under `@arnilo/prism-work/connectors`. Slack MCP wrap and Open Connector sidecar stay examples. See [docs/connected-apps.md](docs/connected-apps.md), [docs/work-connectors.md](docs/work-connectors.md).
+- **Durable runs, turn-boundary stops, and run-bundle snapshots.** `AgentRunStateOptions.checkpointPolicy: "every-turn"` checkpoints a run at the provider-turn boundary so a crashed worker resumes with the host-only `decision: "continue"` action (never reachable from AG-UI or the server boundary, and rejected while any approval or ready tool call is pending). `RunOptions.turnPolicy` (`TurnPolicyOptions`) stops a run synchronously at a turn boundary and reports `stopReason: "host_policy"` with a redacted, bounded `stopDetail` on the result, the ledger row, the `agent_finished` event, and the execution timeline; a host-policy stop stays resumable. `snapshotRunBundle` returns a `RunBundleSnapshot` — a frozen, redacted digest projection of the effective run bundle with zero store or network reads. `createClaimGroundingGuardrail` (stage `"output"`) blocks or flags numeric claims that no tool result or host evidence supports. `ErrorInfo.failureClass` (`ProviderFailureClass`) types provider failures as `quota` / `rate_limited` / `auth` / `transient` / `permanent` / `unknown`; `ModelCapabilities.toolCallStrictness` adds advisory tool-call reliability. See [docs/durable-runs.md](docs/durable-runs.md), [docs/run-bundle.md](docs/run-bundle.md), [docs/guardrails.md](docs/guardrails.md).
+- **Work sandbox and vendored skills.** `@arnilo/prism-work/sandbox` plus `createWorkComposition` run office/exec in an injected Docker sandbox; connectors stay on the host. The package ships `docx`, `xlsx`, `powerpoint`, `pdf` skills.
+
+### Changed
+- **Lockstep `0.7.0` → `0.8.0`.** All eleven publishable manifests move together with `^0.8.0` internal ranges; the lockfile, the `src/index.ts` version constant, the docs index banner, the release-workflow tag lists, and the generated package-truth artifact agree (enforced by `scripts/version-literal-gate.test.mjs`).
+- **Work family rename.** `@arnilo/prism-office` is replaced by `@arnilo/prism-work` (connectors, documents, sheets, diagrams, document-reader, sandbox, skills, tools). No pre-1.0 shim. See [docs/migrate-to-0.8.md](docs/migrate-to-0.8.md).
+- **AG-UI input authority is opt-in server-side.** `CreateAgUiHandlerOptions.inputPolicy.clientState: "ignore"` validates then discards client-supplied AG-UI state and tools before projection, and stops advertising client-provided tools; the default `"honor"` path is byte-identical to 0.7.0.
+- **Observational-memory workers are tool-only.** Text/thinking/done-only turns are successful no-ops. Limit and unknown-tool failures throw `MemoryError` / `MemoryLimitError` rather than matching an English message prefix.
+- **Channel lease release is fail-closed.** In-memory `route.lease` clears only after the store acknowledges; a failed release retries on idle/`stop`. TTL remains the cross-process backstop.
+- **This-tree Postgres evidence.** `release:gate` reports `test:postgres` as pass only when `scripts/postgres-evidence.json` matches current `git rev-parse HEAD`. A stale phase baseline is blocked.
+- **Compat baselines regenerated** at 0.8.0. Inherited 083 `@arnilo/prism-office` → `@arnilo/prism-work` removals (and `prism-core` / `prism-coding-tools` moves) are listed separately from 085 additions. This cut's own Tasks 1–6 add no public removals.
+- **Migration guide for 0.7.0 hosts**: [docs/migrate-to-0.8.md](docs/migrate-to-0.8.md), indexed from [docs/migration.md](docs/migration.md) and [docs/index.md](docs/index.md).
+
+### Fixed
+- **Portable work-idempotency error codes survived the work-family move.** The enterprise PostgreSQL `IdempotencyStore` adapter keeps `ERR_PRISM_WORK_IDEMPOTENCY` / `ERR_PRISM_WORK_IDEMPOTENCY_CONFLICT`; only the error class changed (`EnterprisePostgresError`).
+- **Stale ownership assertions in the protected PostgreSQL leg:** a foreign checkpoint scope is a miss plus a generic CAS conflict, and a foreign agent-run status read is indistinguishable from a missing run (`ERR_PRISM_AGENT_RUN_STATE`).
+- **Wiki isolation nested-runner flake.** The wiki scratch gate spawns `node --test --test-isolation=none` (still strips `NODE_TEST_CONTEXT` / `NODE_TEST_WORKER_ID`) so worker IPC deserialization cannot fail the gate under `npm test` load.
+- **Coverage artifact names.** Package keys in `scripts/coverage-summary.json` must equal live workspace manifests (`@arnilo/prism-work`, not `@arnilo/prism-office`).
+- **Alibaba video `fetchUrl`.** Declared `fetchUrl` now downloads generated video bytes; unused OpenAI speech `_bearerHeaders` deleted.
+
+### Security
+- **Numeric claims must be grounded or they fail closed.** The claim-grounding guardrail blocks by default, bounds every reported span, caps evidence collection (4,096 figures, 16 levels, 128 KiB), and treats a missing evidence set as ungrounded rather than passing silently.
+- **Crash recovery cannot bypass approval gates.** `"continue"` resumes only a running checkpoint with no pending decision or ready call, and keeps the recorded fingerprint, revision, ownership/fencing, and CAS-version gates.
+- **Failed channel lease release is not success.** This process does not treat the binding as free until the store acknowledges; TTL is the other-process backstop.
+- **Postgres release pass cannot be inherited.** Missing or stale this-tree evidence is blocked, never a pass from a previous commit's counts.
+
 ## [0.7.0] - 2026-09-15 (extended line: plans 072, 073, 074, 075, 077, 078)
 
 > **Channels are not in this cut.** Plan 079 (Telegram/Signal adapters) was reassigned to **0.8.0** so the 0.7.0 cut stops waiting on it; nothing in this release mentions or ships a channel adapter.

package/README.md

@@ -158,20 +158,21 @@ printf '{"id":"1","command":"prompt","params":{"input":"Hi"}}\n' \
 ## Packages
 
 <!-- generated:package-truth:inventory begin -->
-**10 publishable manifests** — root `@arnilo/prism` plus 9 workspace packages (3 `prism-*` family packages, 6 capability packages). Generated by `node scripts/package-truth.mjs --emit-docs` — do not hand-edit.
+**11 publishable manifests** — root `@arnilo/prism` plus 10 workspace packages (4 `prism-*` family packages, 6 capability packages). Generated by `node scripts/package-truth.mjs --emit-docs` — do not hand-edit.
 
 | package | version | notes |
 | --- | --- | --- |
-| `@arnilo/prism` | 0.7.0 | core — runtime, CLI/RPC, templates, docs |
-| `@arnilo/prism-coding-tools` | 0.7.0 | family — /agent, /security, /document-reader, /openapi, /computer-use-linux, /dev, /caveman, /ponytail, /impeccable subpaths |
-| `@arnilo/prism-core` | 0.7.0 | family — /runtime, /sessions, /governance, /credentials, /enterprise, /work, /validation subpaths |
-| `@arnilo/prism-providers` | 0.7.0 | family — all provider adapters as `/<adapter>` subpaths |
-| `@arnilo/prism-acp-agent` | 0.7.0 | capability — ACP adapter |
-| `@arnilo/prism-ag-ui` | 0.7.0 | capability — AG-UI/A2A/A2UI adapter |
-| `@arnilo/prism-mcp` | 0.7.0 | capability — MCP client/server/OAuth interop |
-| `@arnilo/prism-memory` | 0.7.0 | capability — memory plus /rag, /compaction/*, /fabric, /graft, /wiki subpaths |
-| `@arnilo/prism-office` | 0.7.0 | capability — /documents, /sheets, /diagrams subpaths |
-| `@arnilo/prism-web-tools` | 0.7.0 | capability — Brave/Exa/Firecrawl plus peer-gated /browser and /obscura subpaths |
+| `@arnilo/prism` | 0.8.0 | core — runtime, CLI/RPC, templates, docs |
+| `@arnilo/prism-channels` | 0.8.0 | family — transport-neutral messaging runtime, durable journal, pairing and one-use approvals; official /telegram (private DMs, opt-in granted groups/topics) and experimental pinned signal-cli /signal |
+| `@arnilo/prism-coding-tools` | 0.8.0 | family — /agent, /security, /openapi, /computer-use-linux, /dev, /caveman, /ponytail, /impeccable subpaths |
+| `@arnilo/prism-core` | 0.8.0 | family — /runtime, /sessions, /governance, /credentials, /enterprise, /validation subpaths |
+| `@arnilo/prism-providers` | 0.8.0 | family — all provider adapters as `/<adapter>` subpaths |
+| `@arnilo/prism-acp-agent` | 0.8.0 | capability — ACP adapter |
+| `@arnilo/prism-ag-ui` | 0.8.0 | capability — AG-UI/A2A/A2UI adapter |
+| `@arnilo/prism-mcp` | 0.8.0 | capability — MCP client/server/OAuth interop |
+| `@arnilo/prism-memory` | 0.8.0 | capability — memory plus /rag, /compaction/*, /fabric, /graft, /wiki subpaths |
+| `@arnilo/prism-web-tools` | 0.8.0 | capability — Brave/Exa/Firecrawl plus peer-gated /browser and /obscura subpaths |
+| `@arnilo/prism-work` | 0.8.0 | capability — /connectors, /documents, /sheets, /diagrams, /document-reader, /sandbox, /skills, /tools subpaths |
 <!-- generated:package-truth:inventory end -->
 
 ## Scripts

package/dist/agent-approval.d.ts

@@ -10,6 +10,10 @@ export declare function pendingDecisionsOf(state: StoredAgentRunState): readonly
  * crash with raw TypeErrors. State-dependent checks (foreign/stale/duplicate ids, scope,
  * schema, policy) stay in {@link resolveRunDecisions}. Errors never include tool arguments,
  * elicitation payloads, credentials, or foreign approval details.
+ *
+ * The legacy `decision` accepts `continue` (plan 084 Task 1) in addition to `approve`/`deny`;
+ * it is a crash-recovery action for running-state checkpoints and is resolved in
+ * `prepareAgentRunResume`, never as an approval outcome.
  */
 export declare function assertValidAgentRunResume(resume: AgentRunResume): void;
 interface ResolvedRunDecisions {

package/dist/agent-approval.js

@@ -28,6 +28,10 @@ export function pendingDecisionsOf(state) {
  * crash with raw TypeErrors. State-dependent checks (foreign/stale/duplicate ids, scope,
  * schema, policy) stay in {@link resolveRunDecisions}. Errors never include tool arguments,
  * elicitation payloads, credentials, or foreign approval details.
+ *
+ * The legacy `decision` accepts `continue` (plan 084 Task 1) in addition to `approve`/`deny`;
+ * it is a crash-recovery action for running-state checkpoints and is resolved in
+ * `prepareAgentRunResume`, never as an approval outcome.
  */
 export function assertValidAgentRunResume(resume) {
     const invalid = (message) => new AgentDecisionError("ERR_PRISM_DECISION_INVALID", message);
@@ -45,7 +49,7 @@ export function assertValidAgentRunResume(resume) {
     if (!hasDecision && !hasDecisions)
         throw invalid("Resume requires a decision or decisions");
     if (hasDecision) {
-        if (resume.decision !== "approve" && resume.decision !== "deny") {
+        if (resume.decision !== "approve" && resume.decision !== "deny" && resume.decision !== "continue") {
             throw invalid("Unknown legacy decision");
         }
         return;

package/dist/agent-run-lifecycle.js

@@ -1,7 +1,7 @@
 import { assertValidAgentRunResume, pendingDecisionsOf, resolveRunDecisions } from "./agent-approval.js";
-import { parseAttentionStickyFrontier } from "./attention-compiler.js";
 import { agentFingerprint, loadAgentRunState, publicState, saveAgentRunState } from "./agent-run-state.js";
 import { RuntimeAgentSession, throwIfAbortedSignal } from "./agent-session.js";
+import { parseAttentionStickyFrontier } from "./attention-compiler.js";
 import { AgentRunStateError } from "./contracts.js";
 function assertAgentId(actual, expected) {
     if (expected !== undefined && actual !== expected)
@@ -28,6 +28,7 @@ export function createAgentRunLifecycle(options) {
                 ownership: request.ownership,
                 fencingToken: options.fencingToken,
                 definitionRevision: resolved.definitionRevision,
+                signal: request.signal,
                 persistSessionState: request.persistSessionState,
                 includeSkillBodies: request.includeSkillBodies,
             });
@@ -55,7 +56,8 @@ export function createAgentRunLifecycle(options) {
 // Resume free functions moved from agents.ts at 0.1.4 (verbatim; the barrel re-exports the two public ones).
 /** Resume a persisted built-in run. A claimed/dispatched tool is never replayed automatically. */
 export async function resumeAgentRun(agent, ref, resume, options) {
-    return executePreparedAgentRunResume(await prepareAgentRunResume(agent, ref, resume, options));
+    throwIfAbortedSignal(options.signal);
+    return executePreparedAgentRunResume(await prepareAgentRunResume(agent, ref, resume, options, options.signal), options.signal);
 }
 /** Subscribe before resuming one durable run. Early consumer return aborts that resumed execution. */
 export async function* resumeAgentRunStream(agent, ref, resume, options) {
@@ -81,20 +83,39 @@ export async function* resumeAgentRunStream(agent, ref, resume, options) {
         }
     }
 }
+/**
+ * A `continue` resume needs a run whose frontier is intact: a crash-recovery checkpoint
+ * (`status: "running"`) or a turn-policy stop, which writes a terminal state that still carries
+ * the frontier (plan 084 Task 2). Every other terminal state is final — a naturally finished run
+ * must never be resurrected.
+ */
+function isContinuableState(state) {
+    return state.status === "running" || (state.status === "succeeded" && state.stopReason === "host_policy");
+}
 async function prepareAgentRunResume(agent, ref, resume, options, signal) {
     throwIfAbortedSignal(signal);
     // Plan 020 Task 2: one shared shape assertion before any checkpoint read/write, agent
     // resolution, subscription, or tool execution. Unknown legacy decisions (e.g. "sideways")
     // and malformed untyped batches fail closed here instead of falling through to approval.
     assertValidAgentRunResume(resume);
+    const continuing = resume.decision === "continue";
     const { record, state } = await loadAgentRunState(options.checkpoints, ref, options.ownership);
     if (state.definitionRevision !== options.definitionRevision ||
         state.agentId !== (agent.config.id ?? agent.config.name) ||
         state.fingerprint !== agentFingerprint(agent, options.definitionRevision)) {
         throw new AgentRunStateError("Agent definition revision or fingerprint mismatch on resume");
     }
-    if (record.version !== resume.expectedVersion || state.status !== "suspended") {
-        throw new AgentRunStateError("Stale or non-suspended agent run resume");
+    if (record.version !== resume.expectedVersion || !(continuing ? isContinuableState(state) : state.status === "suspended")) {
+        throw new AgentRunStateError(continuing ? "Stale or non-running agent run resume" : "Stale or non-suspended agent run resume");
+    }
+    // Crash recovery never bypasses a gate: only a running checkpoint with no unresolved work may
+    // continue. A suspended state (tool approval, elicitation, input guardrail) requires a decision.
+    if (continuing) {
+        const pending = pendingDecisionsOf(state);
+        const awaitingDispatch = state.pending?.status === "ready" || state.pendingCalls?.some((entry) => entry.status === "ready") === true;
+        if (state.interruption !== undefined || (pending?.length ?? 0) > 0 || awaitingDispatch) {
+            throw new AgentRunStateError("Continue resume requires a running checkpoint with no pending decisions");
+        }
     }
     const session = new RuntimeAgentSession({ agent, id: state.sessionId, leafId: state.leafId });
     // Plan 078 Task 7: hand the reconstructed session to an observer (supervisor child-event pump)
@@ -250,7 +271,7 @@ async function prepareAgentRunResume(agent, ref, resume, options, signal) {
         fencingToken: options.fencingToken,
     });
     return {
-        kind: "approve",
+        kind: "claim",
         session,
         state: claimed.state,
         decisions: resolved?.decisionsById,
@@ -261,6 +282,9 @@ async function prepareAgentRunResume(agent, ref, resume, options, signal) {
             interruptBeforeTool: state.interruptBeforeTool,
             fencingToken: options.fencingToken,
             resumeNestedRun: options.resumeNestedRun,
+            // The checkpoint records its own cadence (plan 084 Task 1), so a continued run keeps writing
+            // turn checkpoints without the host repeating the option on resume.
+            ...(state.checkpointPolicy ? { checkpointPolicy: state.checkpointPolicy } : {}),
         },
     };
 }

package/dist/agent-run-state.d.ts

@@ -1,5 +1,5 @@
-import type { Agent, AgentRunInterruption, AgentRunRef, AgentRunState, AgentRunStateOptions, CheckpointRecord, CheckpointStore, JsonValue, Message, ModelConfig, NestedRunRef, OwnershipScope, RunDecision, RunLimitCounters, StickyDecision, ToolCallContent } from "./contracts.js";
 import { type PersistedAttentionStickyFrontier } from "./attention-compiler.js";
+import type { Agent, AgentRunInterruption, AgentRunRef, AgentRunState, AgentRunStateOptions, CheckpointRecord, CheckpointStore, JsonValue, Message, ModelConfig, NestedRunRef, OwnershipScope, RunDecision, RunLimitCounters, StickyDecision, ToolCallContent } from "./contracts.js";
 import type { SecretRedactor } from "./redaction.js";
 import { type LoadedSkillBodiesEntry } from "./skill-load.js";
 export declare const AGENT_RUN_STATE_NAMESPACE = "prism.agent-run";
@@ -53,6 +53,18 @@ export interface StoredAgentRunState extends AgentRunState {
     };
     /** Per-run allow-list (Task 21). Absent = full registered set (legacy checkpoints). */
     readonly toolNames?: readonly string[];
+    /**
+     * Recorded checkpoint cadence (plan 084 Task 1). Present only for `"every-turn"` runs, so
+     * default checkpoints stay byte-identical. A resume of such a state keeps checkpointing each
+     * turn without the host repeating the option.
+     */
+    readonly checkpointPolicy?: "every-turn";
+    /**
+     * Set when a terminal state was written by a `RunOptions.turnPolicy` stop (plan 084 Task 2):
+     * the run succeeded cleanly but its frontier is intact, so `decision: "continue"` may resume
+     * it. Absent on every other state — a naturally finished run is never continuable.
+     */
+    readonly stopReason?: "host_policy";
 }
 /** Session-state caps (plan 015 Task 4): bounded names charged against the run-state byte budget. */
 export declare const MAX_PERSISTED_SKILL_NAMES = 64;

package/dist/agent-run-state.js

@@ -1,6 +1,6 @@
 import { createHash } from "node:crypto";
-import { AgentLoopStateError, AgentRunStateError } from "./contracts.js";
 import { parseAttentionStickyFrontier } from "./attention-compiler.js";
+import { AgentLoopStateError, AgentRunStateError } from "./contracts.js";
 import { validateLoadedSkillBodies } from "./skill-load.js";
 import { HARD_RUN_TOOL_NAMES } from "./tools.js";
 export const AGENT_RUN_STATE_NAMESPACE = "prism.agent-run";
@@ -102,6 +102,9 @@ export function validateRunStateOptions(options) {
     if (!Number.isSafeInteger(bytes) || bytes < 1 || bytes > HARD_MAX_AGENT_RUN_STATE_BYTES) {
         throw new AgentRunStateError(`maxStateBytes must be a positive safe integer at most ${HARD_MAX_AGENT_RUN_STATE_BYTES}`);
     }
+    if (options.checkpointPolicy !== undefined && options.checkpointPolicy !== "decision" && options.checkpointPolicy !== "every-turn") {
+        throw new AgentRunStateError('checkpointPolicy must be "decision" or "every-turn"');
+    }
 }
 export async function loadAgentRunState(checkpoints, ref, ownership) {
     const record = await checkpoints.loadCheckpoint({ namespace: AGENT_RUN_STATE_NAMESPACE, key: ref.runId, ...ownership });
@@ -130,7 +133,7 @@ export async function saveAgentRunState(input) {
     return { record, state: { ...bounded, version: record.version } };
 }
 export function publicState(state) {
-    const { input: _input, pending: _pending, pendingCalls: _pendingCalls, nestedRuns: _nestedRuns, interruptBeforeTool: _interruptBeforeTool, counters: _counters, deadlineAt: _deadlineAt, toolNames: _toolNames, ...publicValue } = state;
+    const { input: _input, pending: _pending, pendingCalls: _pendingCalls, nestedRuns: _nestedRuns, interruptBeforeTool: _interruptBeforeTool, counters: _counters, deadlineAt: _deadlineAt, toolNames: _toolNames, checkpointPolicy: _checkpointPolicy, stopReason: _stopReason, ...publicValue } = state;
     return publicValue;
 }
 export function initialAgentRunState(input) {
@@ -152,6 +155,7 @@ export function initialAgentRunState(input) {
         interruptBeforeTool: input.interruptBeforeTool,
         counters: input.counters,
         deadlineAt: input.deadlineAt,
+        ...(input.options.checkpointPolicy === "every-turn" ? { checkpointPolicy: "every-turn" } : {}),
     };
 }
 export function parseAgentRunState(value, version) {
@@ -215,6 +219,12 @@ export function parseAgentRunState(value, version) {
             }
         }
     }
+    if (state.checkpointPolicy !== undefined && state.checkpointPolicy !== "every-turn") {
+        throw new AgentRunStateError("Malformed agent run checkpoint policy");
+    }
+    if (state.stopReason !== undefined && state.stopReason !== "host_policy") {
+        throw new AgentRunStateError("Malformed agent run stop reason");
+    }
     // Load bounds against the hard cap, not the default: the configured maxStateBytes is a
     // save-side policy knob, while the load-side bound is only a DoS ceiling. States saved
     // with a raised maxStateBytes must remain resumable.

package/dist/agent-session/helpers.js

@@ -53,7 +53,12 @@ export function finalAssistantMessage(history) {
     return { content: [], text: "" };
 }
 export function errorFromInfo(error) {
-    return Object.assign(new Error(error.message), { name: error.name ?? "Error", cause: error.cause, code: error.code });
+    return Object.assign(new Error(error.message), {
+        name: error.name ?? "Error",
+        cause: error.cause,
+        code: error.code,
+        failureClass: error.failureClass,
+    });
 }
 export class ProviderTurnFailure extends Error {
     info;

package/dist/agent-session/session/assemble.js

@@ -19,11 +19,104 @@ import { resolveToolResultFold } from "../../tool-result-fold.js";
 import { createSearchToolsTool, createToolSearchState, resolveToolsDisclosure } from "../../tool-search.js";
 import { createToolRegistry, selectRunTools } from "../../tools.js";
 import { bridgeAbort, createUsageAccumulator, inputToMessages, isDurableLoop, isSteerSoftInterrupt, mergeGuardrails, throwIfAborted, } from "../helpers.js";
-import { cleanupRun, persistDurable, persistSucceeded, suspendDurable } from "./persist.js";
+import { checkpointDurableTurn, cleanupRun, persistDurable, persistSucceeded, suspendDurable } from "./persist.js";
 import { generateWithRetry, recordProviderUsage } from "./provider-round.js";
 import { bindChargeToolRound, bindDispatchToolCall, replayDurableNestedAndPending, runLoopUntilSettled, suspendGatedRound, } from "./tool-round.js";
 const PROMPT_VERSION_MAX_NAME_BYTES = 256;
 const PROMPT_VERSION_HASH_PATTERN = /^sha256:[0-9a-f]{64}$/;
+/** Cap on the host stop detail that reaches the result, ledger, and timeline (plan 084 Task 2). */
+const TURN_STOP_DETAIL_MAX_BYTES = 256;
+/**
+ * `RunOptions.turnPolicy` stopped the run at a turn boundary (plan 084 Task 2). Internal control
+ * signal: it unwinds any loop shape and `executeRun` turns it into a clean terminal success with
+ * `stopReason: "host_policy"` — never a run error.
+ */
+class AgentRunStopped extends Error {
+    constructor() {
+        super("Agent run stopped by host turn policy");
+        this.name = "AgentRunStopped";
+    }
+}
+/** Host turn-policy misuse: a throwing or malformed callback fails the run closed. */
+class TurnPolicyError extends Error {
+    code = "ERR_PRISM_TURN_POLICY";
+    constructor(message, options) {
+        super(message, options);
+        this.name = "TurnPolicyError";
+    }
+}
+/** Validate `RunOptions.turnPolicy` once, before any provider turn (plan 084 Task 2). */
+function assertTurnPolicy(policy, resolvedLimits) {
+    if (policy === undefined)
+        return;
+    if (typeof policy !== "object" || policy === null)
+        throw new TypeError("RunOptions.turnPolicy must be an object");
+    if (policy.stop !== undefined && typeof policy.stop !== "function") {
+        throw new TypeError("RunOptions.turnPolicy.stop must be a function");
+    }
+    const maxTurns = policy.maxTurns;
+    if (maxTurns === undefined)
+        return;
+    if (!Number.isSafeInteger(maxTurns) || maxTurns < 1) {
+        throw new TypeError("RunOptions.turnPolicy.maxTurns must be a positive safe integer");
+    }
+    // Same narrowing law as `limits`: a run overlay may tighten the agent's cap, never widen it.
+    const configured = resolvedLimits.maxTurns;
+    if (configured !== null && maxTurns > configured) {
+        throw new TypeError(`RunOptions.turnPolicy.maxTurns (${maxTurns}) cannot widen limits.maxTurns (${configured})`);
+    }
+}
+/** Redact and bound a host stop reason; anything unusable fails the run closed. */
+function boundedStopDetail(session, reason) {
+    if (typeof reason !== "string" || reason.length === 0) {
+        throw new TurnPolicyError("RunOptions.turnPolicy.stop must return a non-empty reason string");
+    }
+    const redacted = session.redact(reason);
+    if (Buffer.byteLength(redacted, "utf8") > TURN_STOP_DETAIL_MAX_BYTES) {
+        throw new TurnPolicyError(`RunOptions.turnPolicy.stop reason must be at most ${TURN_STOP_DETAIL_MAX_BYTES} UTF-8 bytes`);
+    }
+    return redacted;
+}
+/**
+ * Evaluate the host turn policy at the current provider-turn boundary (plan 084 Task 2). Returns
+ * the stop to record, or `undefined` to run the turn. Omitted policy → nothing is read or called.
+ */
+function evaluateTurnStop(ctx) {
+    const policy = ctx.options.turnPolicy;
+    if (!policy)
+        return undefined;
+    const turn = Math.max(1, ctx.session.activeLoopTurn);
+    const turns = turn - 1;
+    if (policy.maxTurns !== undefined && turns >= policy.maxTurns)
+        return { reason: "turn_limit", detail: "maxTurns" };
+    if (!policy.stop)
+        return undefined;
+    const context = {
+        sessionId: ctx.session.id,
+        runId: ctx.runId,
+        turn,
+        turns,
+        toolCalls: ctx.toolCalls,
+        ...(ctx.runUsage.value() ? { usage: ctx.runUsage.value() } : {}),
+        metadata: ctx.metadata,
+    };
+    let decision;
+    try {
+        decision = policy.stop(context);
+    }
+    catch (error) {
+        throw new TurnPolicyError("RunOptions.turnPolicy.stop threw", { cause: error });
+    }
+    if (decision === null || typeof decision !== "object" || typeof decision.then === "function") {
+        throw new TurnPolicyError("RunOptions.turnPolicy.stop must synchronously return a TurnStopDecision");
+    }
+    const action = decision.action;
+    if (action === "continue")
+        return undefined;
+    if (action !== "stop")
+        throw new TurnPolicyError('RunOptions.turnPolicy.stop decision action must be "continue" or "stop"');
+    return { reason: "host_policy", detail: boundedStopDetail(ctx.session, decision.reason) };
+}
 function assertPromptVersionRef(ref) {
     if (ref === undefined)
         return undefined;
@@ -174,6 +267,8 @@ async function assembleRoundContext(params) {
         assembledTurn: false,
         artifactFinished: false,
         artifactFailedInfo: undefined,
+        toolCalls: 0,
+        toolResults: [],
         runUsage,
         loopCtx: undefined,
     };
@@ -236,10 +331,24 @@ async function assembleRoundContext(params) {
             if (!ctx.assembledTurn)
                 limits.charge("maxTurns");
             ctx.assembledTurn = false;
+            // Host turn policy (plan 084 Task 2): evaluated at the same turn boundary as the
+            // crash-recovery checkpoint below, before any provider work. Throwing unwinds any loop
+            // shape; `executeRun` converts it into a clean terminal success with `stopReason`.
+            const stop = evaluateTurnStop(ctx);
+            if (stop) {
+                ctx.runStop = stop;
+                ctx.loopCtx.finishReason = stop.reason;
+                throw new AgentRunStopped();
+            }
+            // Crash-recovery boundary (plan 084 Task 1): after the previous turn's tool results are in
+            // the store and before this provider request. No-op unless `checkpointPolicy: "every-turn"`.
+            if (session.activeDurable?.options.checkpointPolicy === "every-turn") {
+                await checkpointDurableTurn(session, { runId, model, limits });
+            }
             const policyResult = await session.applyProviderRequestPolicies(request, runId, options, metadata, controller.signal);
             const middlewareRequest = (await session.agent.config.middleware?.run("provider_request", policyResult.request)) ?? policyResult.request;
             try {
-                return await generateWithRetry(session, session.redactProviderRequest(middlewareRequest), runId, options, controller.signal, policyResult.secrets, session.activeLoopTurn, (turnUsage, turn, attempt) => recordProviderUsage(ctx, turnUsage, turn, attempt));
+                return await generateWithRetry(session, session.redactProviderRequest(middlewareRequest), runId, options, controller.signal, policyResult.secrets, session.activeLoopTurn, (turnUsage, turn, attempt) => recordProviderUsage(ctx, turnUsage, turn, attempt), ctx.toolResults);
             }
             catch (error) {
                 if (isSteerSoftInterrupt(error)) {
@@ -288,6 +397,7 @@ export async function executeRun(session, input, options, runId, resumed) {
     }
     const requestedLimits = options.limits;
     const resolvedLimits = resolveRunLimits(session.agent.config.limits, requestedLimits);
+    assertTurnPolicy(options.turnPolicy, resolvedLimits);
     const durableOptions = options.runState ?? session.agent.config.runState;
     if (session.agent.config.runState && options.runState && session.agent.config.runState !== options.runState) {
         throw new AgentRunStateError("RunOptions cannot replace agent durable run-state configuration");
@@ -330,6 +440,9 @@ export async function executeRun(session, input, options, runId, resumed) {
     const startedAt = new Date().toISOString();
     let runError;
     let runStatus = "succeeded";
+    // Set only on the clean-success path; the finish ledger record carries them (plan 084 Task 2).
+    let stopReason;
+    let stopDetail;
     const runUsage = createUsageAccumulator();
     let usage;
     const metadata = {
@@ -374,8 +487,16 @@ export async function executeRun(session, input, options, runId, resumed) {
             }
             ctx.loop.restore?.(resumedLoopState.snapshot);
         }
-        const loopUsage = await runLoopUntilSettled(ctx);
-        if (ctx.loop.name === "generate-validate-revise" && !ctx.artifactFinished) {
+        const loopUsage = await runLoopUntilSettled(ctx).catch((error) => {
+            // Host turn-policy stop (plan 084 Task 2): the loop was unwound on purpose at a turn
+            // boundary. Not an error — the run settles cleanly and stays resumable.
+            if (error instanceof AgentRunStopped)
+                return undefined;
+            throw error;
+        });
+        stopReason = ctx.runStop?.reason ?? ctx.loopCtx.finishReason;
+        stopDetail = ctx.runStop?.detail;
+        if (!ctx.runStop && ctx.loop.name === "generate-validate-revise" && !ctx.artifactFinished) {
             throw Object.assign(new Error(ctx.artifactFailedInfo?.message ?? "artifact loop ended without a validated artifact"), {
                 name: "ArtifactFailed",
                 code: ctx.artifactFailedInfo?.code ?? "artifact_failed",
@@ -418,7 +539,7 @@ export async function executeRun(session, input, options, runId, resumed) {
         throw new AgentRunError(result, { cause: error });
     }
     finally {
-        await cleanupRun({ session, controller, cleanupSignal, runId, model, startedAt, runStatus, runError });
+        await cleanupRun({ session, controller, cleanupSignal, runId, model, startedAt, runStatus, runError, stopReason, stopDetail });
     }
 }
 //# sourceMappingURL=assemble.js.map

package/dist/agent-session/session/persist.d.ts

@@ -15,6 +15,19 @@ export declare function suspendDurable(session: SessionHost, input: {
     /** Full replacement when provided; otherwise the recorded nested runs are preserved. */
     readonly nestedRuns?: readonly NestedRunRef[];
 }): Promise<AgentRunState>;
+/**
+ * Turn-boundary crash-recovery checkpoint (plan 084 Task 1). Called before each provider
+ * request when `checkpointPolicy: "every-turn"`; a no-op otherwise, so default-policy runs keep
+ * the 0.8.x checkpoint shape and write count unchanged. Pending-decision markers are dropped:
+ * at a turn boundary every gated call has been resolved or the run already suspended, and a
+ * stale marker must never replay. The recorded `checkpointPolicy` makes the cadence survive
+ * into a resumed run, and loop-local state rides along exactly as it does at suspension.
+ */
+export declare function checkpointDurableTurn(session: SessionHost, input: {
+    readonly runId: string;
+    readonly model: ModelConfig;
+    readonly limits: RunLimitTracker;
+}): Promise<void>;
 export declare function persistSucceeded(ctx: RoundContext, loopUsage: Usage | undefined): Promise<AgentRunResult>;
 export declare function cleanupRun(input: {
     session: SessionHost;
@@ -25,4 +38,7 @@ export declare function cleanupRun(input: {
     startedAt: string;
     runStatus: AgentRunResult["status"];
     runError: ErrorInfo | undefined;
+    /** Clean stop taxonomy for the finish record; only written for a succeeded run (plan 084 Task 2). */
+    stopReason?: import("../../contracts.js").AgentFinishReason;
+    stopDetail?: string;
 }): Promise<void>;

package/dist/agent-session/session/persist.js

@@ -77,8 +77,50 @@ export async function suspendDurable(session, input) {
         counters: input.limits.snapshot(),
     });
 }
+/**
+ * Turn-boundary crash-recovery checkpoint (plan 084 Task 1). Called before each provider
+ * request when `checkpointPolicy: "every-turn"`; a no-op otherwise, so default-policy runs keep
+ * the 0.8.x checkpoint shape and write count unchanged. Pending-decision markers are dropped:
+ * at a turn boundary every gated call has been resolved or the run already suspended, and a
+ * stale marker must never replay. The recorded `checkpointPolicy` makes the cadence survive
+ * into a resumed run, and loop-local state rides along exactly as it does at suspension.
+ */
+export async function checkpointDurableTurn(session, input) {
+    const durable = session.activeDurable;
+    if (durable?.options.checkpointPolicy !== "every-turn")
+        return;
+    const loop = session.activeLoop;
+    const loopState = loop?.snapshot ? boundedLoopSnapshot(loop.name, loop.revision ?? "1", loop.snapshot()) : undefined;
+    const state = durable.state ??
+        initialAgentRunState({
+            agent: session.agent,
+            options: durable.options,
+            runId: input.runId,
+            sessionId: session.id,
+            leafId: session.currentLeafId,
+            model: input.model,
+            counters: input.limits.snapshot(),
+            deadlineAt: input.limits.deadlineAt,
+            status: "running",
+            interruptBeforeTool: durable.options.interruptBeforeTool,
+        });
+    await persistDurable(session, {
+        ...state,
+        leafId: session.currentLeafId,
+        status: "running",
+        interruption: undefined,
+        // The input messages are already in the session store by the time a turn boundary is
+        // reached; keeping them would re-append them on a later resume.
+        input: undefined,
+        pending: undefined,
+        pendingCalls: undefined,
+        ...(loopState ? { loopState } : {}),
+        counters: input.limits.snapshot(),
+    });
+}
 export async function persistSucceeded(ctx, loopUsage) {
     const { session, runId, runUsage } = ctx;
+    const stop = ctx.runStop;
     const usage = runUsage.value() ?? loopUsage;
     if (usage && session.activeLedger) {
         const usageRecord = {
@@ -97,12 +139,15 @@ export async function persistSucceeded(ctx, loopUsage) {
         ? await persistDurable(session, {
             ...session.activeDurable.state,
             status: "succeeded",
+            // Plan 084 Task 2: a host-policy stop is terminal for the run but leaves the frontier
+            // intact — the loop state is kept and the state is marked continuable.
+            ...(stop ? { stopReason: "host_policy", leafId: session.currentLeafId } : {}),
             pending: undefined,
             pendingCalls: undefined,
             nestedRuns: undefined,
             stickyDecisions: undefined,
             interruption: undefined,
-            loopState: undefined,
+            ...(stop ? {} : { loopState: undefined }),
         })
         : undefined;
     session.emit({
@@ -111,8 +156,17 @@ export async function persistSucceeded(ctx, loopUsage) {
         runId,
         usage,
         ...(ctx.loopCtx.finishReason ? { finishReason: ctx.loopCtx.finishReason } : {}),
+        ...(stop?.detail ? { stopDetail: stop.detail } : {}),
+    });
+    const stopReason = ctx.runStop?.reason ?? ctx.loopCtx.finishReason;
+    return session.buildRunResult({
+        runId,
+        status: "succeeded",
+        usage,
+        runState,
+        ...(stopReason ? { stopReason } : {}),
+        ...(stop?.detail ? { stopDetail: stop.detail } : {}),
     });
-    return session.buildRunResult({ runId, status: "succeeded", usage, runState });
 }
 export async function cleanupRun(input) {
     const { session, controller, cleanupSignal, runId, model, startedAt, runStatus, runError } = input;
@@ -138,6 +192,8 @@ export async function cleanupRun(input) {
                 status: runStatus,
                 startedAt,
                 finishedAt: new Date().toISOString(),
+                ...(input.runStatus === "succeeded" && input.stopReason ? { stopReason: input.stopReason } : {}),
+                ...(input.runStatus === "succeeded" && input.stopDetail ? { stopDetail: input.stopDetail } : {}),
                 abortReason: controller.signal.aborted ? String(controller.signal.reason) : undefined,
                 error: runError,
                 ...(session.activePromptVersion ? { promptVersion: session.activePromptVersion } : {}),

package/dist/agent-session/session/provider-round.d.ts

@@ -1,6 +1,6 @@
 /** Provider-round phase of runInternal (plan 059). */
-import type { ProviderRequest, ProviderTurnResult, RunOptions, Usage } from "../../contracts.js";
+import type { ProviderRequest, ProviderTurnResult, RunOptions, ToolResult, Usage } from "../../contracts.js";
 import type { RoundContext, SessionHost } from "./types.js";
 export declare function recordProviderUsage(ctx: RoundContext, turnUsage: Usage | undefined, turn: number, attempt: number): Promise<void>;
-export declare function generateWithRetry(session: SessionHost, request: ProviderRequest, runId: string, options: RunOptions, signal: AbortSignal, requestSecrets?: readonly (string | undefined)[], turn?: number, recordUsage?: (usage: Usage | undefined, turn: number, attempt: number) => Promise<void>): Promise<ProviderTurnResult>;
-export declare function generateProviderTurn(session: SessionHost, request: ProviderRequest, runId: string, signal: AbortSignal, secrets?: readonly (string | undefined)[], turn?: number, attempt?: number, recordUsage?: (usage: Usage | undefined, turn: number, attempt: number) => Promise<void>): Promise<ProviderTurnResult>;
+export declare function generateWithRetry(session: SessionHost, request: ProviderRequest, runId: string, options: RunOptions, signal: AbortSignal, requestSecrets?: readonly (string | undefined)[], turn?: number, recordUsage?: (usage: Usage | undefined, turn: number, attempt: number) => Promise<void>, toolResults?: readonly ToolResult[]): Promise<ProviderTurnResult>;
+export declare function generateProviderTurn(session: SessionHost, request: ProviderRequest, runId: string, signal: AbortSignal, secrets?: readonly (string | undefined)[], turn?: number, attempt?: number, recordUsage?: (usage: Usage | undefined, turn: number, attempt: number) => Promise<void>, toolResults?: readonly ToolResult[]): Promise<ProviderTurnResult>;