@arnilo/prism 0.0.5 → 0.0.7

package/dist/thinking.js

@@ -0,0 +1,92 @@
+import { mergeProviderRequestOptions } from "./provider-request-policy.js";
+/**
+ * Portable thinking / reasoning effort levels shared across first-party providers.
+ * Model-dependent legality (which values a given model accepts) stays provider-owned.
+ */
+export const THINKING_LEVELS = ["none", "minimal", "low", "medium", "high", "xhigh", "max"];
+export function isThinkingLevel(value) {
+    return typeof value === "string" && THINKING_LEVELS.includes(value);
+}
+/**
+ * Normalize a host thinkingLevel string. Known levels are lowercased; other non-empty
+ * strings pass through as opaque effort values for forward-compatible provider fields.
+ */
+export function normalizeThinkingLevel(level) {
+    const normalized = level.trim().toLowerCase();
+    if (!normalized)
+        return undefined;
+    return isThinkingLevel(normalized) ? normalized : normalized;
+}
+/**
+ * Build the `ProviderRequestOptions.compat` patch for a shared thinking level.
+ * Does not invent a second options tree — providers keep reading official fields from `compat`.
+ */
+export function thinkingCompatFor(family, level) {
+    const normalized = typeof level === "string" ? normalizeThinkingLevel(level) : level;
+    if (!normalized || family === "noop")
+        return {};
+    switch (family) {
+        case "openai_reasoning":
+            return { reasoning: { effort: normalized } };
+        case "reasoning_effort":
+            return { reasoning_effort: normalized };
+        case "thinking_type":
+            return { thinking: { type: normalized === "none" ? "disabled" : "enabled" } };
+        default: {
+            const _exhaustive = family;
+            return _exhaustive;
+        }
+    }
+}
+/**
+ * Merge a shared thinking level into `providerOptions.compat` for the given family.
+ * Per-turn patches win over prior compat via {@link mergeProviderRequestOptions}.
+ */
+export function applyThinkingLevel(options, level, family = "reasoning_effort") {
+    const normalized = normalizeThinkingLevel(String(level));
+    if (!normalized || family === "noop")
+        return options ?? {};
+    const patch = thinkingCompatFor(family, normalized);
+    if (family === "openai_reasoning" && options?.compat?.reasoning && typeof options.compat.reasoning === "object" && !Array.isArray(options.compat.reasoning)) {
+        return mergeProviderRequestOptions(options, {
+            compat: {
+                reasoning: {
+                    ...options.compat.reasoning,
+                    ...patch.reasoning,
+                },
+            },
+        });
+    }
+    return mergeProviderRequestOptions(options, { compat: patch });
+}
+/**
+ * Best-effort family inference from model metadata without a second options tree.
+ * Prefer an explicit family in hosts/use-case workers when the provider is known.
+ *
+ * Heuristics (ordered):
+ * 1. Existing `compat.thinking` object → `thinking_type`
+ * 2. Existing `compat.reasoning` → `openai_reasoning`
+ * 3. Existing `compat.reasoning_effort` → `reasoning_effort`
+ * 4. Provider id starting with `openai` → `openai_reasoning`
+ * 5. Provider id `neuralwatt` → `reasoning_effort`
+ * 6. `capabilities.reasoning` → `reasoning_effort` (portable string field)
+ * 7. Else `noop`
+ */
+export function thinkingFamilyForModel(model) {
+    const compat = model.compat ?? {};
+    if (compat.thinking != null && typeof compat.thinking === "object")
+        return "thinking_type";
+    if (compat.reasoning != null)
+        return "openai_reasoning";
+    if (compat.reasoning_effort != null)
+        return "reasoning_effort";
+    const provider = model.provider.trim().toLowerCase();
+    if (provider === "openai" || provider.startsWith("openai"))
+        return "openai_reasoning";
+    if (provider === "neuralwatt")
+        return "reasoning_effort";
+    if (model.capabilities?.reasoning)
+        return "reasoning_effort";
+    return "noop";
+}
+//# sourceMappingURL=thinking.js.map

package/dist/tools.d.ts

@@ -1,8 +1,9 @@
-import type { AgentEvent, ErrorInfo, JsonObject, OwnershipScope, RunLedger, ToolCallContent, ToolDefinition, ToolExecutionContext, ToolRegistry, ToolResult } from "./contracts.js";
+import type { AgentEvent, ErrorInfo, Guardrails, JsonObject, OwnershipScope, RunLedger, ToolCallContent, ToolDefinition, ToolExecutionContext, ToolRegistry, ToolResult } from "./contracts.js";
+import type { RunLimitTracker } from "./run-limits.js";
 import type { MiddlewareRegistry } from "./middleware.js";
 import { type SecretRedactor } from "./redaction.js";
 import { type DuplicateRegistrationOptions } from "./registry-options.js";
-import { type PermissionPolicy } from "./security.js";
+import { type PermissionPolicy, type TrustPolicy } from "./security.js";
 export interface ToolFilter {
     readonly allow?: readonly string[];
     readonly deny?: readonly string[];
@@ -33,12 +34,19 @@ export interface DispatchToolCallOptions {
     readonly filter?: ToolFilterInput;
     readonly middleware?: MiddlewareRegistry;
     readonly validate?: ToolValidator;
+    /** Adapter-specific policy check immediately before the tool side effect. */
+    readonly beforeExecute?: (call: ToolCallContent, tool: ToolDefinition, context: ToolExecutionContext) => void | Promise<void>;
     readonly emit?: (event: AgentEvent) => void | Promise<void>;
     readonly secrets?: readonly (string | undefined)[];
     readonly permission?: PermissionPolicy;
+    readonly trust?: TrustPolicy;
     readonly redactor?: SecretRedactor;
     readonly ledger?: RunLedger;
     readonly ownership?: OwnershipScope;
+    /** Tool stages run after middleware normalization and before side effects/exposure. */
+    readonly guardrails?: Guardrails;
+    /** Shared run tracker; direct hosts may supply one for their call scope. */
+    readonly limitTracker?: RunLimitTracker;
 }
 export interface ToolRegistryOptions extends DuplicateRegistrationOptions {
 }

package/dist/tools.js

@@ -1,7 +1,9 @@
 import { isJsonObject } from "./config.js";
+import { createId } from "./ids.js";
+import { GuardrailError, runGuardrails } from "./guardrails.js";
 import { errorToErrorInfo, redactRunLedgerRecord, redactSecrets } from "./redaction.js";
 import { assertCanRegister } from "./registry-options.js";
-import { assertPermission } from "./security.js";
+import { assertPermission, assertTrusted } from "./security.js";
 /** Wrap a schema adapter as the existing `ToolValidator` seam used by dispatch and the agent runtime. */
 export function createToolParameterValidator(validator, options = {}) {
     const missingSchema = options.missingSchema ?? "allow";
@@ -58,10 +60,28 @@ function toolExecutionMetadata(startedAt, status) {
 export async function dispatchToolCall(options) {
     const secrets = options.secrets ?? [];
     const startedAt = new Date().toISOString();
-    const precheck = await checkCall(options.call, options, startedAt);
-    if (precheck)
-        return precheck;
+    options.limitTracker?.charge("maxToolCalls");
     const mediatedCall = await (options.middleware?.run("tool_call", options.call) ?? options.call);
+    const inputGuards = await runGuardrails({
+        stage: "tool_input",
+        guardrails: options.guardrails,
+        value: mediatedCall,
+        context: {
+            sessionId: options.context.sessionId,
+            runId: options.context.runId,
+            toolCallId: mediatedCall.id,
+            toolName: mediatedCall.name,
+            metadata: options.context.metadata ?? {},
+            signal: options.context.signal,
+        },
+        redactor: options.redactor,
+        emit: options.emit,
+    });
+    if (inputGuards.terminal) {
+        if (inputGuards.terminal.action !== "block")
+            throw new GuardrailError(inputGuards.terminal);
+        return blocked(mediatedCall, options.context, "guardrail_blocked", { message: "Tool call blocked by guardrail" }, options, startedAt);
+    }
     const tool = options.registry.get(mediatedCall.name);
     const postcheck = await checkCall(mediatedCall, options, startedAt);
     if (postcheck)
@@ -88,6 +108,7 @@ export async function dispatchToolCall(options) {
         },
     };
     try {
+        await assertTrusted(options.trust, { kind: "tool", target: mediatedCall.name, capability: "execute", metadata: options.context.metadata });
         await assertPermission(options.permission, { kind: "tool", action: "execute", target: mediatedCall.name, metadata: options.context.metadata });
     }
     catch (error) {
@@ -96,11 +117,39 @@ export async function dispatchToolCall(options) {
     const validation = await options.validate?.(tool, mediatedCall.arguments, context);
     if (validation)
         return blocked(mediatedCall, context, "validation_failed", toErrorInfo(validation, secrets), options, startedAt);
+    try {
+        await options.beforeExecute?.(mediatedCall, tool, context);
+    }
+    catch (error) {
+        if (error?.code === "ERR_PRISM_AGENT_RUN_SUSPENDED")
+            throw error;
+        return blocked(mediatedCall, context, "execution_denied", errorToErrorInfo(error, secrets), options, startedAt);
+    }
     await options.emit?.({ type: "tool_execution_started", sessionId: context.sessionId, runId: context.runId, call: mediatedCall });
     await appendToolCallRecord(options, "started", mediatedCall, startedAt, {});
     try {
         const raw = await tool.execute(mediatedCall.arguments, context);
         const mediatedResult = await (options.middleware?.run("tool_result", raw) ?? raw);
+        const outputGuards = await runGuardrails({
+            stage: "tool_output",
+            guardrails: options.guardrails,
+            value: mediatedResult,
+            context: {
+                sessionId: context.sessionId,
+                runId: context.runId,
+                toolCallId: mediatedCall.id,
+                toolName: mediatedCall.name,
+                metadata: context.metadata ?? {},
+                signal: context.signal,
+            },
+            redactor: options.redactor,
+            emit: options.emit,
+        });
+        if (outputGuards.terminal) {
+            if (outputGuards.terminal.action !== "block")
+                throw new GuardrailError(outputGuards.terminal);
+            return blocked(mediatedCall, context, "guardrail_blocked", { message: "Tool result blocked by guardrail" }, options, startedAt);
+        }
         const result = options.redactor?.redact(mediatedResult) ?? mediatedResult;
         const finishedAt = new Date().toISOString();
         const metadata = toolExecutionMetadata(startedAt, "finished");
@@ -109,6 +158,8 @@ export async function dispatchToolCall(options) {
         return result;
     }
     catch (error) {
+        if (error instanceof GuardrailError)
+            throw error;
         const info = errorToErrorInfo(error, secrets);
         const result = { toolCallId: mediatedCall.id, name: mediatedCall.name, error: info };
         const finishedAt = new Date().toISOString();
@@ -149,9 +200,7 @@ async function blocked(call, context, reason, error, options, startedAt) {
 function toErrorInfo(value, secrets) {
     return typeof value === "string" ? errorToErrorInfo(value, secrets) : redactSecrets(value, secrets);
 }
-function randomId(prefix) {
-    return `${prefix}_${globalThis.crypto?.randomUUID?.() ?? Math.random().toString(36).slice(2)}`;
-}
+const randomId = createId;
 function appendToolCallRecord(options, status, call, startedAt, fields) {
     if (!options.ledger)
         return undefined;

package/dist/use-case-model.d.ts

@@ -0,0 +1,63 @@
+import type { ModelConfig, ProviderRequestOptions } from "./contracts.js";
+/**
+ * Host binding for a non-session LLM job (observational memory, LLM compaction,
+ * declarative agents, evals, etc.). Omitting `model` means "use the session model"
+ * when a session fallback is supplied to {@link resolveUseCaseModel}.
+ *
+ * Workers must not write `model_change` session entries; they resolve a model for
+ * their own provider calls only.
+ */
+export interface UseCaseModelBinding {
+    /** Explicit use-case model. When omitted, {@link resolveUseCaseModel} falls back to `sessionModel`. */
+    readonly model?: ModelConfig;
+    /**
+     * Optional provider id hint for docs / credential routing.
+     * When `model` is set, `model.provider` is authoritative.
+     */
+    readonly provider?: string;
+    readonly providerOptions?: ProviderRequestOptions;
+    /** Portable thinking level; packages map via `applyThinkingLevel` into `compat`. */
+    readonly thinkingLevel?: string;
+    /**
+     * When true, do not fall back to `sessionModel` — leave resolution empty if
+     * `model` is omitted (preserves historical explicit-worker `missing_model` behavior).
+     */
+    readonly requireExplicitModel?: boolean;
+}
+export interface ResolveUseCaseModelInput {
+    /** Explicit use-case model (or `binding.model`). */
+    readonly configured?: ModelConfig;
+    /** Active session / agent model used when `configured` is omitted. */
+    readonly sessionModel?: ModelConfig;
+    /** When true, skip session fallback (OM `missing_model` escape hatch). */
+    readonly requireExplicitModel?: boolean;
+    readonly providerOptions?: ProviderRequestOptions;
+    readonly thinkingLevel?: string;
+}
+export interface ResolvedUseCaseModel {
+    readonly model: ModelConfig;
+    /** Whether the model came from the use-case binding or session fallback. */
+    readonly source: "configured" | "session";
+    readonly providerOptions?: ProviderRequestOptions;
+    readonly thinkingLevel?: string;
+}
+/**
+ * Resolve the model for a non-session LLM job.
+ *
+ * Precedence:
+ * 1. `configured` → `source: "configured"`
+ * 2. Else `sessionModel` when `requireExplicitModel` is not set → `source: "session"`
+ * 3. Else `undefined` (caller skips / throws per package policy)
+ *
+ * O(1); no network. Does not mutate session history.
+ */
+export declare function resolveUseCaseModel(input: ResolveUseCaseModelInput): ResolvedUseCaseModel | undefined;
+/**
+ * Resolve from a {@link UseCaseModelBinding} plus optional session fallback.
+ */
+export declare function resolveUseCaseModelBinding(binding: UseCaseModelBinding | undefined, sessionModel?: ModelConfig): ResolvedUseCaseModel | undefined;
+/**
+ * Provider id for credential requests: always the **resolved** model's provider.
+ * Optional `binding.provider` is only a hint when no model resolved yet.
+ */
+export declare function useCaseCredentialProviderId(resolved: ResolvedUseCaseModel | undefined, binding?: Pick<UseCaseModelBinding, "provider">): string | undefined;

package/dist/use-case-model.js

@@ -0,0 +1,52 @@
+/**
+ * Resolve the model for a non-session LLM job.
+ *
+ * Precedence:
+ * 1. `configured` → `source: "configured"`
+ * 2. Else `sessionModel` when `requireExplicitModel` is not set → `source: "session"`
+ * 3. Else `undefined` (caller skips / throws per package policy)
+ *
+ * O(1); no network. Does not mutate session history.
+ */
+export function resolveUseCaseModel(input) {
+    const { providerOptions, thinkingLevel } = input;
+    if (input.configured) {
+        return {
+            model: input.configured,
+            source: "configured",
+            providerOptions,
+            thinkingLevel,
+        };
+    }
+    if (input.requireExplicitModel)
+        return undefined;
+    if (input.sessionModel) {
+        return {
+            model: input.sessionModel,
+            source: "session",
+            providerOptions,
+            thinkingLevel,
+        };
+    }
+    return undefined;
+}
+/**
+ * Resolve from a {@link UseCaseModelBinding} plus optional session fallback.
+ */
+export function resolveUseCaseModelBinding(binding, sessionModel) {
+    return resolveUseCaseModel({
+        configured: binding?.model,
+        sessionModel,
+        requireExplicitModel: binding?.requireExplicitModel,
+        providerOptions: binding?.providerOptions,
+        thinkingLevel: binding?.thinkingLevel,
+    });
+}
+/**
+ * Provider id for credential requests: always the **resolved** model's provider.
+ * Optional `binding.provider` is only a hint when no model resolved yet.
+ */
+export function useCaseCredentialProviderId(resolved, binding) {
+    return resolved?.model.provider ?? binding?.provider;
+}
+//# sourceMappingURL=use-case-model.js.map

package/docs/a2a.md

@@ -21,7 +21,7 @@ Use it to expose one explicitly selected Prism agent at an A2A endpoint or call
 
 ## Outputs / response / events
 
-The handler serves `GET /.well-known/agent-card.json` and its configured POST endpoint. JSON-RPC returns `{ result: { task } }` or a bounded error. Streaming returns backpressure-driven SSE task envelopes. Client `send()` maps a terminal remote task to `AgentRunResult`; `stream()` yields validated/redacted text artifacts.
+The handler serves `GET /.well-known/agent-card.json` and its configured POST endpoint. JSON-RPC returns `{ result: { task } }` or a bounded error. Streaming returns backpressure-driven SSE task envelopes. Client `send()` maps a terminal remote task to `AgentRunResult`; `stream()` incrementally yields validated/redacted text artifacts. Client SSE accepts LF, CRLF, mixed blank-line separators, comments/unknown fields, and multiline `data:` joined with LF.
 
 ## Request/response example
 
@@ -59,7 +59,9 @@ Only `text` parts are accepted. File/data parts, push notifications, task persis
 ## Security and performance notes
 
 - Endpoints and card URLs must be HTTPS and exactly origin-allow-listed before fetch; `redirect: "error"` prevents redirect SSRF.
-- Treat every remote card, error, task, status, artifact, and SSE frame as untrusted. Shape/count/byte/time limits apply before mapping.
+- Treat every remote card, error, task, status, artifact, and SSE frame as untrusted. Shape/count/byte/time limits apply before mapping. Streaming keeps raw stream bytes, current frame bytes, and event count as separate existing limits.
+- One fatal streaming UTF-8 decoder is reused across every body chunk and flushed once at EOF. Split multibyte code points are preserved; malformed/truncated UTF-8 fails rather than inserting `U+FFFD` into JSON. A small coalesced line buffer keeps one-byte chunk handling incremental.
+- SSE frames require a terminating blank line. A non-whitespace final partial frame, malformed JSON, missing terminal task, failed/canceled task, or any event after a completed task fails with bounded package-owned text. Existing request/response/event/stream/count/timeout hard caps are unchanged.
 - Card verification pins `alg=ES256`, optional key ID, issue/expiry, optional maximum age, and canonical unsigned-card payload. Hosts provision trusted public keys; remote `jku` is never fetched automatically.
 - Card discovery is public; extended-card and invoke methods call host authorization. Use TLS, rate limits, and replay controls at the host edge.
 - Credentials remain in the client auth callback or server authorizer and never enter cards, messages, events, or metrics.

package/docs/agent-events.md

@@ -38,11 +38,12 @@ The `AgentEvent` union (grouped by concern):
 
 | Group | Variants |
 | --- | --- |
-| Agent lifecycle | `agent_started`, `agent_finished` |
+| Agent lifecycle | `agent_started`, `agent_suspended`, `agent_resumed`, `agent_denied`, `agent_finished` |
 | Turns | `turn_started`, `turn_finished` |
 | Provider turns | `provider_turn_started`, `provider_turn_finished` |
 | Assistant messages | `message_started`, `message_delta`, `message_finished` |
 | Tool execution | `tool_execution_started`, `tool_execution_progress`, `tool_execution_finished`, `tool_execution_error`, `tool_execution_blocked` |
+| Guardrails | `guardrail_decision` |
 | Queue/subscribers | `queue_updated`, `event_subscriber_overflow` |
 | Compaction | `compaction_started`, `compaction_finished` |
 | Retry | `retry_scheduled` |
@@ -59,6 +60,9 @@ Agent / turn / message events:
 | --- | --- |
 | `agent_started` | `sessionId`, `runId` |
 | `agent_finished` | `sessionId`, `runId`, `usage?: Usage` (aggregate of all usage-bearing provider turns) |
+| `agent_suspended` | `sessionId`, `runId`, redacted `interruption`, checkpoint `version`; no tool side effect has started. |
+| `agent_resumed` | `sessionId`, `runId`, checkpoint `version`. |
+| `agent_denied` | `sessionId`, `runId`, redacted `interruption`, checkpoint `version`; no tool side effect runs. |
 | `turn_started` / `turn_finished` | `sessionId`, `runId`, `turn: number` |
 | `message_started` / `message_finished` | `sessionId`, `runId`, `message: Message` |
 | `message_delta` | `sessionId`, `runId`, `content: ContentBlock` (`tool_call_delta` fragments may appear here for live UI streaming; stored messages use final `tool_call` blocks) |
@@ -75,6 +79,14 @@ Tool execution events:
 | `tool_execution_error` | `sessionId`, `runId`, `call: ToolCallContent`, `error: ErrorInfo`, `metadata: ToolExecutionMetadata` |
 | `tool_execution_blocked` | `sessionId`, `runId`, `toolCallId`, `name`, `reason: string`, `error: ErrorInfo`, `metadata: ToolExecutionMetadata` |
 
+Guardrail events:
+
+| Variant | Fields |
+| --- | --- |
+| `guardrail_decision` | `sessionId`, `runId`, optional `toolCallId`/`toolName`, and redacted bounded `record: GuardrailRecord` (`guardrail`, stage, action, reason, metadata). |
+
+Guardrails emit their decision before a terminal run error or blocked tool result. Provider-output checks buffer assistant content, and tool-output checks discard blocked raw results before event/ledger/transcript exposure; see [Guardrails](guardrails.md).
+
 Queue / subscriber / compaction / retry / provider events:
 
 | Variant | Fields |
@@ -100,28 +112,23 @@ Artifact validation/refinement events (emitted only by `generateValidateReviseLo
 | `artifact_validation_finished` | `sessionId`, `runId`, `turn`, `attempt`, `result: ArtifactValidation` |
 | `artifact_revision_started` | `sessionId`, `runId`, `turn`, `attempt`, `failure: ArtifactValidation` |
 | `artifact_finished` | `sessionId`, `runId`, `turn`, `attempt`, `result: ArtifactValidation` (loop ended successfully) |
-| `artifact_failed` | `sessionId`, `runId`, `turn`, `attempt`, `result: ArtifactValidation` (budget exhausted) |
+| `artifact_failed` | `sessionId`, `runId`, `turn`, `attempt`, `result: ArtifactValidation` (candidate budget exhausted, or `result.metadata.reason === "tool_round_limit"`) |
 
 ### Artifact event ordering
 
-A `generateValidateReviseLoop` run emits normal turn/message events for every provider turn, then a strictly ordered artifact sequence, correlated by `runId` / `turn` / `attempt`:
+A call-free candidate in `generateValidateReviseLoop` emits normal turn/message events then a strictly ordered artifact sequence, correlated by `runId` / `turn` / `attempt`:
 
 ```
-turn_started
-  → message_started
-    → message_delta*
-      → message_finished
-        → turn_finished
-          → artifact_validation_started
-            → artifact_validation_finished
-              → artifact_revision_started   # when a revision will run next
-               | artifact_finished          # loop ended successfully
-               | artifact_failed            # budget exhausted (maxRevisions+1 attempts)
+turn_started → message_started → message_delta* → message_finished → turn_finished
+  → artifact_validation_started → artifact_validation_finished
+    → artifact_revision_started | artifact_finished | artifact_failed
 ```
 
-- `attempt` is 1-indexed per validation attempt and equals the provider `turn` within `generateValidateReviseLoop`; it mirrors `retry_scheduled.attempt` and the `tool_execution_*` block/finish pairing.
+With opt-in `toolCalls: "bounded"`, a provider turn containing calls emits its normal assistant envelope followed by existing `tool_execution_*` events and matching persisted tool results; it emits no validation event and the next provider turn consumes that transcript. A post-`maxToolRounds` call emits terminal `artifact_failed` directly after `turn_finished` and has no tool execution event.
+
+- `attempt` is 1-indexed per call-free validation candidate. It can differ from provider `turn` when bounded tool calls occur.
 - Single-shot runs emit zero artifact events.
-- **Validation failure triggering a revision is recoverable and never an `error`.** Only terminal budget exhaustion emits `artifact_failed`. The `error` channel is reserved for real failures (provider failures not caught by retry, aborts, etc.), matching the existing convention used by `tool_execution_blocked`.
+- **Validation failure triggering a revision is recoverable and never an `error`.** Terminal candidate-budget or `tool_round_limit` exhaustion emits `artifact_failed`; real failures remain on the `error` channel.
 
 ## Request/response example
 
@@ -193,7 +200,7 @@ for await (const event of session.stream("draft", { loop: { strategy: "generate-
 - Slow consumers are bounded by `SubscribeOptions`. Use `RunLedger` or host storage for durable replay; do not rely on a live subscriber as a queue.
 - Redaction is exact-string-match only and opt-in via `createSecretRedactor`; values not passed as known secrets are not redacted.
 - `ArtifactValidation.errors[].message` and `metadata` may echo model text; `redactAgentEvent` walks arbitrary nesting and replaces cyclic references with `"[Circular]"` (WeakSet cycle guard), so secret values in `result`/`failure` are redacted without crashing.
-- `artifact_*` events are bounded by `maxRevisions + 1` validation attempts; an always-failing validator cannot loop forever and emits exactly one terminal `artifact_failed`.
+- `artifact_*` validation events are bounded by `maxRevisions + 1` call-free candidates. With opt-in bounded artifact tools, provider turns are additionally bounded by run-global `maxToolRounds` (maximum `1 + maxRevisions + maxToolRounds`); a post-cap call emits exactly one terminal `artifact_failed` with `result.metadata.reason === "tool_round_limit"` and has no tool lifecycle event because it never dispatches.
 - Runtime events contain messages/content only; do not put secrets in prompts, metadata, provider events, session entries, tool results, or artifact validation payloads.
 
 ## Related APIs

package/docs/agent-loops.md

@@ -16,7 +16,7 @@ The `Artifact*` contracts (`ArtifactValidation`, `ArtifactContext`, `ArtifactPar
 
 Use the default `singleShotLoop` implicitly whenever you call `session.run()` — no configuration needed. Opt into `generateValidateReviseLoop` when a run should produce an artifact that must satisfy a host-supplied schema before it is considered complete (e.g. structured output, a validated JSON document, a generated file passing lint) and the host wants Prism to drive the revision turns.
 
-Do not use a loop to re-implement provider calls, retry, abort, store, or event emission — those stay runtime-owned and are exposed to the loop only through `LoopContext`. A loop that needs tools in revision turns is out of scope for `generateValidateReviseLoop`; use `singleShotLoop` or supply a custom `AgentLoopStrategy`.
+Do not use a loop to re-implement provider calls, retry, abort, store, or event emission — those stay runtime-owned and are exposed to the loop only through `LoopContext`. Artifact-loop tools stay disabled by default; opt into bounded calls only for host-registered, least-privilege lookup tools that must inform an artifact candidate.
 
 ## Inputs / request
 
@@ -57,6 +57,7 @@ await session.run(input, {
     parser: hostParser,       // optional; default treats assistant text as the value
     repairer: hostRepairer,  // optional; default stringifies validation.errors[].message
     maxRevisions: 3,         // optional; default 3
+    toolCalls: "bounded",    // optional; default "disabled"; uses limits.maxToolRounds
   },
 });
 
@@ -79,6 +80,8 @@ type AgentLoopOptions =
       readonly parser?: ArtifactParser<unknown>;
       readonly repairer?: ArtifactRepairer<unknown>;
       readonly maxRevisions?: number;
+      /** Default "disabled". "bounded" dispatches sequentially up to limits.maxToolRounds. */
+      readonly toolCalls?: "disabled" | "bounded";
     };
 ```
 
@@ -106,13 +109,17 @@ Host callback contracts (all generic over host `T`):
 | `appendMessage(message)` | Appends to the store under the run (redacted). |
 | `emit(event)` | Emits a redacted `AgentEvent`. |
 
+## Durable runs
+
+`RunOptions.runState` supports only built-in loop options (`single-shot` and `generate-validate-revise`). A custom `AgentLoopStrategy` has arbitrary in-memory cursor state, so durable configuration rejects it before provider work. Built-in suspension occurs only before an input provider call or immediately before a tool side effect; completed provider turns remain in `SessionStore` history and are not repeated after `resumeAgentRun()`.
+
 ## Outputs / response / events
 
 `AgentLoopStrategy.run(ctx)` returns `Promise<Usage | undefined>` as a fallback for custom loops. Core runtime independently accumulates every usage-bearing provider turn in O(turns), persists scoped turn/run rows, and emits `agent_finished` with the aggregate.
 
 Events during a loop run are the existing `AgentEvent`s (`turn_started`, `message_started`, `message_delta`, `message_finished`, `turn_finished`, tool-execution events when the loop dispatches tools, `error` on real failures). Both built-in loops emit `turn_started` before each provider turn, `message_finished` for every assistant draft, and `turn_finished` after the assistant draft is appended. First-turn input is appended to live history once, matching the already-persisted user message.
 
-Validation-failure-triggering-a-revision is **not** an `error` event — it is recoverable, like `tool_execution_blocked`. `generateValidateReviseLoop` emits normal turn/message events around each provider turn, then the artifact event sequence `artifact_validation_started` → `artifact_validation_finished` → (`artifact_revision_started`)* → `artifact_finished` (success) | `artifact_failed` (budget exhausted), correlated by `runId`/`turn`/`attempt`; see [Agent events § Artifact event ordering](agent-events.md#artifact-event-ordering). `singleShotLoop` emits zero artifact events. Real failures stay on the `error` channel.
+Validation-failure-triggering-a-revision is **not** an `error` event — it is recoverable, like `tool_execution_blocked`. In bounded artifact mode, a tool-calling provider response emits normal assistant/tool lifecycle events, skips artifact parsing/validation, then the next turn sees its persisted result. `generateValidateReviseLoop` emits artifact events only for call-free candidates: `artifact_validation_started` → `artifact_validation_finished` → (`artifact_revision_started`)* → `artifact_finished` | `artifact_failed`. A request beyond `maxToolRounds` executes nothing and emits terminal `artifact_failed` with `result.metadata.reason === "tool_round_limit"`; see [Agent events § Artifact event ordering](agent-events.md#artifact-event-ordering). `singleShotLoop` emits zero artifact events. Real failures stay on the `error` channel.
 
 A loop has no path to credentials, provider objects, or unredacted secrets. `LoopContext.generate` receives the already-policy-applied, middleware-run, redacted request; `LoopContext.emit` runs through `redactAgentEvent` with the active `SecretRedactor`.
 
@@ -198,20 +205,24 @@ await session.run(input, { loop: twoShotLoop });
 - `RunOptions.loop` wins over `AgentConfig.loop`; when neither is set the runtime uses `singleShotLoop`. This mirrors the other `RunOptions` overrides (`redactor`, `validate`, `activeSkills`).
 - `{ strategy: "single-shot" }` resolves to the exported `singleShotLoop`; `{ strategy: "generate-validate-revise", ... }` is mapped by `resolveLoop()` to `generateValidateReviseLoop(opts)`. An unknown `strategy` throws before the first turn. Passing an `AgentLoopStrategy` instance bypasses the options form entirely (custom-loop escape hatch).
 - The loop is resolved once per run inside `RuntimeAgentSession.run()`, after the usual setup (provider/skills/tools resolution, history rebuild, model-change entry, input append, auto-compaction). The runtime's outer try/catch/finally, run-exclusivity, abort bridging, and subscriber close remain in place around `loop.run(ctx)`.
-- `LoopContext.assemble(nextInput, toolResults?)` accepts an optional tool-result accumulator so `singleShotLoop` can pass its loop-local `toolResults`; `generateValidateReviseLoop` omits it (no tools in revision turns).
-- `maxToolRounds` bounds `singleShotLoop` tool rounds; `toolConcurrency` (default `1`) bounds how many independent tool calls from one provider turn may execute concurrently. Results and transcript rows are still appended in original call order. If any resolved `ToolDefinition` in a turn has `exclusive: true`, that turn uses concurrency `1`; later non-exclusive turns restore configured concurrency.
-- `maxRevisions` (default 3) bounds `generateValidateReviseLoop` revision turns. Budget exhaustion ends the loop and returns the last usage; it does not throw.
-- A revision cycle appends one assistant draft and one repair user message per revision to the session store, so store entries reflect every attempted draft. The original user input is stored once by the runtime and pushed into loop history once on the first turn.
+- `LoopContext.assemble(nextInput, toolResults?)` accepts an optional tool-result accumulator so `singleShotLoop` can pass its loop-local results. Bounded artifact tools append results directly to shared history, then assemble the next turn with empty new input; no second transcript path exists.
+- `limits.maxToolRounds` bounds both `singleShotLoop` and opt-in bounded artifact tool rounds across the whole run. Artifact mode always dispatches sequentially, regardless of `toolConcurrency`; all dispatches still use existing registry/filter/permission/validator/middleware/redactor/ledger guards. Deprecated `maxToolRounds` only narrows this limit.
+- `maxRevisions` (default 3) counts only failed call-free artifact candidates. Bounded artifact runs make at most `1 + maxRevisions + maxToolRounds` provider turns. A tool-round limit is terminal and returns last usage after `artifact_failed`; it does not throw.
+- A revision cycle appends one assistant draft and one repair user message per revision to the session store, so store entries reflect every attempted draft. The original user input is stored once by the runtime and pushed into loop history once on the first turn. Repair messages are assembled as the next provider `nextInput` and only pushed into live history after that revision request has been generated, so the model never receives a duplicated repair instruction.
 
 ## Security and performance notes
 
 - Loops have no path to credentials, provider objects, or unredacted secrets. `LoopContext.generate` consumes an already-redacted request; `LoopContext.emit` runs through `redactAgentEvent` with the active `SecretRedactor`; `LoopContext.appendMessage` appends a redacted entry.
 - `ArtifactValidation.errors[].message` may echo model text — `artifact_*` event payloads flow through the same `redactAgentEvent` path as other `AgentEvent`s (see [Agent events](agent-events.md)).
-- `generateValidateReviseLoop` makes at most `maxRevisions + 1` provider turns; it cannot loop forever on an always-failing validator. Each revision costs one provider turn plus one store append.
-- Parallel tool dispatch uses a bounded worker pool over the calls in one turn; queue depth is `calls.length`, not unbounded. Exclusive turns use the same sequential path. Each call still runs through `dispatchToolCall` (permission + validation + execute). Tool lifecycle events may complete out of order; history/store appends stay in call order.
+- `generateValidateReviseLoop` makes at most `1 + maxRevisions + maxToolRounds` provider turns when bounded tools are enabled (otherwise `maxRevisions + 1`); it cannot loop forever. Each revision costs one provider turn plus one store append.
+- Bounded artifact tool calls run sequentially through `dispatchToolCall` (permission + validation + execute); their assistant call and result are persisted before the next provider request. `singleShotLoop` retains its bounded parallel worker pool and original call-order transcript behavior.
 - The loop is a plain object/factory; no class hierarchy, no background work, no extra dependencies. `LoopContext` is a single object literal of bound arrows built once per run.
 - The Synapta-free boundary is guarded by tests: `src/` imports no `synapta*` package, and the `Artifact*`/`AgentLoop*`/`LoopContext` contracts contain no `workflow`/`node`/`step` field names. Hosts supply their own schema; no host domain type is imported by `src/`.
 
+## Guardrails
+
+Built-in loops and custom loops that use `LoopContext.generate()` / `LoopContext.dispatchToolCall()` inherit runtime guardrails. Provider output is checked before a loop appends assistant content; tool stages remain in shared dispatch. Do not call providers or `ToolDefinition.execute()` directly if guardrail enforcement is required; see [Guardrails](guardrails.md).
+
 ## Related APIs
 - [Agent/session runtime](agent-session-runtime.md): `RuntimeAgentSession.run()` builds the `LoopContext` and delegates to the resolved loop.
 - [Agent events](agent-events.md): the `artifact_*` event variants and ordering emitted by `generateValidateReviseLoop`.

package/docs/agent-session-runtime.md

@@ -5,6 +5,7 @@
 The agent/session runtime adds the minimal shared SDK surface for running provider turns, dispatching complete host-owned tool calls, and subscribing to session events:
 
 - `createAgent(config)`
+- `createSecureAgent(options)` for opt-in fail-closed composition
 - `createAgentSession(config)`
 - `agent.createSession(config)`
 - `session.run(input, options)` → `AgentRunResult`
@@ -17,6 +18,8 @@ The agent/session runtime adds the minimal shared SDK surface for running provid
 - `session.checkout(leafId?)`
 - `session.fork(options?)`
 - `session.clone(options?)`
+- `resumeAgentRun(agent, ref, decision, options)`
+- `createAgentRunLifecycle({ checkpoints, resolveAgent })` for host-selected remote status/resume adapters
 
 The runtime streams provider text/tool-call content into `AgentEvent` values. Complete `tool_call` events are dispatched through the active host `ToolRegistry`, then returned as tool-result messages on the next provider turn. When a store is supplied, user, assistant, tool-result, and model-change entries are appended under the current branch leaf. Abort propagation and run exclusivity use native `AbortController`.
 
@@ -43,7 +46,9 @@ string | Message | readonly Message[]
 
 `AgentSessionConfig.store` overrides `AgentConfig.store`; otherwise the session gets a private memory store. `AgentSessionConfig.leafId` selects the branch leaf to resume from.
 
-`RunOptions.model` can override the request model for a run. Model overrides append a `model_change` entry. `AgentConfig.inputLayout` selects the default input assembly layout (`"legacy"` by default, or opt-in `"cache_aware"`); `RunOptions.inputLayout` wins for one run. `AgentConfig.providerOptions`/`RunOptions.providerOptions` supply generic provider request options; `timeoutMs`, `maxRetries`, and `maxRetryDelayMs` are deprecated inert provider-level hints in first-party providers. Use `RunOptions.signal`/host abort controllers for timeouts and `AgentConfig.retry`/`RunOptions.retry` for retry. `AgentConfig.providerRequestPolicies`/`RunOptions.providerRequestPolicies` run before `AIProvider.generate()` and before `provider_request` middleware. `AgentConfig.systemPrompt` and `RunOptions.systemPrompt` add explicit layered system prompt contributions; `RunOptions.systemPrompt: false` disables configured prompt layers for that run while keeping `AgentConfig.instructions` as the base path. `RunOptions.compaction` can enable auto-compaction for that run or use `false` to disable configured auto-compaction. `RunOptions.retry` can enable provider-turn retry for that run or use `false` to disable configured retry. `RunOptions.metadata` is merged with agent/session metadata for assembly, provider requests, and tool contexts. `RunOptions.maxToolRounds` bounds repeated tool turns and defaults to `1`. `RunOptions.signal` is bridged into the per-run abort signal passed to assembly, providers, tools, auto-compaction, and retry backoff.
+`AgentConfig.limits` sets run ceilings; `RunOptions.limits` may only narrow configured agent values. Limits cover turns, provider attempts, tool rounds/calls, wall time, request/response bytes, tokens, and optional single-currency cost. A breach emits one `run_limit_exceeded` event and throws `AgentRunError` with `result.limit`; see [Runs and usage ledger](runs-and-usage.md#run-limits).
+
+`RunOptions.model` can override the request model for a run. Model overrides append a `model_change` entry. `AgentConfig.inputLayout` selects the default input assembly layout (`"legacy"` by default, or opt-in `"cache_aware"`); `RunOptions.inputLayout` wins for one run. `AgentConfig.providerOptions`/`RunOptions.providerOptions` supply generic provider request options; `timeoutMs`, `maxRetries`, and `maxRetryDelayMs` are deprecated inert provider-level hints in first-party providers. Use `RunOptions.signal`/host abort controllers for timeouts and `AgentConfig.retry`/`RunOptions.retry` for retry. `AgentConfig.providerRequestPolicies`/`RunOptions.providerRequestPolicies` run before `AIProvider.generate()` and before `provider_request` middleware. `AgentConfig.systemPrompt` and `RunOptions.systemPrompt` add explicit layered system prompt contributions; `RunOptions.systemPrompt: false` disables configured prompt layers for that run while keeping `AgentConfig.instructions` as the base path. `RunOptions.compaction` can enable auto-compaction for that run or use `false` to disable configured auto-compaction. `RunOptions.retry` can enable provider-turn retry for that run or use `false` to disable configured retry. `RunOptions.metadata` is merged with agent/session metadata for assembly, provider requests, and tool contexts. Deprecated `RunOptions.maxToolRounds` narrows `limits.maxToolRounds`. `RunOptions.signal` is bridged into the per-run abort signal passed to assembly, providers, tools, auto-compaction, and retry backoff.
 
 ## Outputs / response / events
 
@@ -160,6 +165,33 @@ await agent.createSession().run("Hi", { model: overrideModel });
 - Runtime events contain messages/content only; do not put secrets in prompts, metadata, provider events, session entries, or docs examples.
 - The event broadcaster is in-memory, live-only, and bounded per subscriber by `SubscribeOptions`. It adds no dependency, timer, filesystem/network discovery, worker, or durable queue.
 
+## Durable interruption
+
+Set `runState` with a host-owned `CheckpointStore`, stable `definitionRevision`, and `interruptBeforeTool: true` to suspend at a persisted pre-side-effect boundary. A suspended result has `status: "suspended"`, a redacted `interruption`, and `runState.version`; it releases session resources before returning.
+
+```ts
+const result = await session.run("Publish draft", {
+  runState: { checkpoints, definitionRevision: "2026-07-20.1", interruptBeforeTool: true },
+});
+if (result.status === "suspended") {
+  await resumeAgentRun(agent, { runId: result.runId, sessionId: result.sessionId }, {
+    decision: "approve", expectedVersion: result.runState!.version!,
+  }, { checkpoints, definitionRevision: "2026-07-20.1" });
+}
+```
+
+Resume requires exact checkpoint ownership, version, agent fingerprint, and revision. Prism CAS-claims approval before work, rechecks normal guardrail/permission/validation/limit paths, and marks a pending tool dispatched before its side effect. `createAgentRunLifecycle()` wraps the same core path for server/MCP hosts: adapters pass only authorized ownership, status returns only `{ state, version }`, and `resolveAgent()` supplies current agent/revision. Remote restart requires both checkpoint and session stores to be durable. A crash after that mark is ambiguous and is never replayed automatically; use host tool idempotency keyed by `runId`/`toolCallId` or resolve it manually. Checkpoints contain bounded redacted state plus session/leaf references, never provider objects, callbacks, signals, credentials, or raw secrets. Only built-in loop options are durable; custom `AgentLoopStrategy` rejects before provider work.
+
+## Secure composition
+
+`createSecureAgent()` is optional; `createAgent()` remains explicit and backward-compatible. Secure composition requires an ID, non-empty definition revision, exact non-empty ownership, redactor, permission and trust policies, finite explicit limits, a host `ToolArgumentValidator`, non-empty schema for every tool, and checkpoints. It builds a duplicate-error registry, rejects missing schemas, always enables durable pre-tool interruption, and reuses normal provider/request policies without discovery or background work.
+
+Per-run options may narrow `limits` and append `guardrails`; they cannot replace secure ownership, redaction, validator, or durable checkpoint policy. Every active tool is trust-checked then permission-checked before validation and its side effect. See [`examples/secure-agent.ts`](../examples/secure-agent.ts).
+
+## Guardrails
+
+`AgentConfig.guardrails` applies typed input, output, tool-input, and tool-output checks to every run. `RunOptions.guardrails` appends checks for one run. Input checks run before session append; configured output checks buffer provider content until allowed, so blocked content is never emitted or stored. See [Guardrails](guardrails.md).
+
 ## Related APIs
 
 - [Public contracts](public-contracts.md): `Agent`, `AgentSession`, `RunOptions`, and `AgentEvent` contracts.