@arnilo/prism 0.0.5 → 0.0.6

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

@@ -1,4 +1,5 @@
 import { isJsonObject } from "./config.js";
+import { createId } from "./ids.js";
 import { errorToErrorInfo, redactRunLedgerRecord, redactSecrets } from "./redaction.js";
 import { assertCanRegister } from "./registry-options.js";
 import { assertPermission } from "./security.js";
@@ -149,9 +150,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

@@ -100,28 +100,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 +188,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 RunOptions.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 RunOptions.maxToolRounds. */
+      readonly toolCalls?: "disabled" | "bounded";
     };
 ```
 
@@ -112,7 +115,7 @@ Host callback contracts (all generic over host `T`):
 
 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,17 +201,17 @@ 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.
+- `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.
+- `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/`.
 

package/docs/coding-agent-tools.md

@@ -15,6 +15,8 @@
 | `createAllTools(cwd, options?)` | Every tool the package provides (currently identical to `createCodingTools`). |
 | `detectSupportedImageMimeType(buf)` / `detectSupportedImageMimeTypeFromFile(path)` | Magic-byte image MIME detection (PNG/JPEG/GIF/WebP/BMP) used by `read`. |
 | `DEFAULT_MAX_IMAGE_BYTES` | Default `read` image size ceiling (10 MB). |
+| `DEFAULT_*` / `HARD_*` coding limit constants | Published text-scan, image, write/edit, shell timeout, display, and total-output ceilings. |
+| `ReadTextOptions` / `ReadTextResult` | Bounded text-page contract required by custom `ReadOperations`. |
 | `TransformImage` / `TransformImageInput` | Types for the optional `read` `transformImage` callback. |
 | `withFileMutationQueue(path, fn)` | Per-path serialization primitive re-exported for hosts. |
 
@@ -65,7 +67,7 @@ Run a shell command and return combined stdout+stderr.
 | Field | Type | Purpose |
 | --- | --- | --- |
 | `command` | `string` | Shell command to execute (required). |
-| `timeout` | `number` | Timeout in **seconds** (optional; no default). |
+| `timeout` | `number` | Timeout in **seconds** (optional; defaults to 600, hard maximum 3600). |
 
 **Outputs:** a `ToolResult` whose `content[0]` is a `TextContent` with the combined output. Non-zero exit is **not** a tool error: it is returned as a normal result with `[Command exited with code N]` appended to the content and `exitCode` in metadata. Timeout and abort are error results that still carry the partial output captured so far.
 
@@ -75,9 +77,11 @@ Run a shell command and return combined stdout+stderr.
 | --- | --- | --- |
 | `exitCode` | always | Process exit code, or `null` when the process was killed by timeout/abort. |
 | `truncation` | always | `TruncationResult` from the bounded output accumulator. |
-| `fullOutputPath?` | truncated only | Path to the spilled temp file holding the full output. |
+| `fullOutputPath?` | successful and truncated only | Host-owned path to retained output. Failed/aborted/timed-out/output-limited calls remove unpublished spills. |
+| `totalOutputBytes` | shell executed | Raw bytes retained, never above `maxTotalOutputBytes`. |
+| `outputLimitExceeded` / `outputStorageFailed` | shell executed | Attributable resource failure flags. |
 
-Shell resolution honors `options.shellPath` → `SHELL` env → `/bin/bash` → `sh`, and the process group is killed on timeout/abort (`process.kill(-pid)` on Unix, `taskkill /F /T` on Windows).
+Shell resolution honors `options.shellPath` → `SHELL` env → `/bin/bash` → `sh`. The process group is killed on timeout, caller abort, spill failure, or total-output overflow (`process.kill(-pid)` on Unix, `taskkill /F /T` on Windows). Combined output defaults to a 64 MiB total cap (1 GiB hard cap). Spill files use random exclusive creation and Unix mode `0600`; hosts own and must delete a successful result's `fullOutputPath` after consumption.
 
 ### `read`
 
@@ -91,7 +95,7 @@ Read a text or image file.
 | `offset` | `number` | Line to start reading from (1-indexed). |
 | `limit` | `number` | Maximum number of lines to read. |
 
-**Outputs:** text files become a single `TextContent`, truncated to `maxLines`/`maxBytes` (defaults 2000 lines / 50 KB) with a `Use offset=N to continue` footer when more remains. Image files (PNG/JPEG/GIF/WebP/BMP by **magic bytes**, not extension) become `[TextContent note, ImageContent]` with base64 `data` and `mimeType`. Oversize images are rejected by `stat` (when available) or `buffer.length` against `maxImageBytes` (default 10 MB) before base64 encoding. An optional `transformImage` callback lets hosts resize or re-encode images without adding image-processing dependencies to the base package. Read failures (missing file, offset beyond end, oversize image, abort) are error results.
+**Outputs:** text files are scanned incrementally until one requested page, `maxLines`/`maxBytes`, EOF, or `maxScanBytes` (default 64 MiB scanned per call; 1 GiB hard cap). The default path never loads the complete file and returns a `Use offset=N to continue` footer when more remains. Exact total line count is reported only when EOF was already reached in the bounded scan. Image files (PNG/JPEG/GIF/WebP/BMP by **magic bytes**, not extension) become `[TextContent note, ImageContent]` with base64 `data` and `mimeType`. Oversize images are rejected by `stat` (when available) or `buffer.length` against `maxImageBytes` (default 10 MB) before base64 encoding. An optional `transformImage` callback lets hosts resize or re-encode images without adding image-processing dependencies to the base package. Read failures (missing file, offset beyond end, oversize image, abort) are error results.
 
 `read` tool options (via `createReadTool(cwd, options)` or `ToolsOptions.read`):
 
@@ -100,8 +104,9 @@ Read a text or image file.
 | `maxImageBytes` | `DEFAULT_MAX_IMAGE_BYTES` (10 MB) | Reject image reads larger than this many bytes. |
 | `transformImage` | — | Host callback `( { buffer, mimeType } ) => Promise<Buffer>` run after read, before base64. |
 | `autoResizeImages` | — | **Deprecated.** Ignored unless `transformImage` is also set (use `transformImage` instead). |
-| `maxLines` / `maxBytes` | 2000 / 50 KB | Text head truncation limits. |
-| `operations` | local fs | Pluggable `ReadOperations` backend. |
+| `maxLines` / `maxBytes` | 2000 / 50 KiB | Text page display limits (hard: 100,000 / 1 MiB). |
+| `maxScanBytes` | 64 MiB | Raw bytes scanned to reach one page (hard: 1 GiB). |
+| `operations` | local fs | Pluggable bounded `ReadOperations` backend. |
 | `executionPolicy` | — | Structured pre-execution policy (see [Coding security](coding-security.md)). |
 
 ```ts
@@ -133,7 +138,7 @@ Create or overwrite a file, creating parent directories as needed.
 | `path` | `string` | Path to the file to write (relative or absolute). Required. |
 | `content` | `string` | Content to write (empty string creates an empty file). Required. |
 
-**Outputs:** a `TextContent` confirmation naming the **absolute path** with UTF-8 byte and line counts (e.g. `Successfully wrote 42 bytes (3 lines) to /abs/path.txt`). Write failures and abort are error results. Empty `content` is valid.
+**Outputs:** a `TextContent` confirmation naming the **absolute path** with UTF-8 byte and line counts (e.g. `Successfully wrote 42 bytes (3 lines) to /abs/path.txt`). `maxInputBytes` defaults to 8 MiB (64 MiB hard cap); oversized UTF-8 input fails before policy evaluation, directory creation, or write. Write failures and abort are error results. Empty `content` is valid.
 
 `write` result `metadata`: `{ bytes, lines, path }` (absolute path). Concurrent writes to the same path serialize through `withFileMutationQueue`; writes to different paths run in parallel.
 
@@ -148,7 +153,7 @@ Precise text replacement in an existing file via exact-then-fuzzy matching.
 | `path` | `string` | Path to the file to edit. Required. |
 | `edits` | `Array<{ oldText: string, newText: string }>` | Targeted replacements, each matched against the **original** file (not incrementally). No overlapping/nested edits. Required, non-empty. |
 
-Each `edits[].oldText` must match a unique, non-overlapping region of the original file. Matching is exact first, then fuzzy (unicode normalization / whitespace collapse). A BOM is stripped before matching and re-prepended on write; original line endings are restored.
+Each `edits[].oldText` must match a unique, non-overlapping region of the original file. Matching is exact first, then fuzzy (unicode normalization / whitespace collapse). A BOM is stripped before matching and re-prepended on write; original line endings are restored. Defaults reject targets over 8 MiB, aggregate old/new UTF-8 input over 2 MiB, or more than 100 edits (hard caps: 64 MiB, 16 MiB, and 1,000). Stat and bounded read checks run before matching or mutation.
 
 **Outputs:** a `TextContent` confirmation (`Successfully replaced N block(s) in {path}.`) plus `metadata`. Any failure — missing/unreadable file, no match, duplicate (non-unique) match, overlap, empty `oldText`, no-op edit, or abort — is an error result, and the file is left **unchanged** (the match runs before the write).
 
@@ -156,7 +161,7 @@ Each `edits[].oldText` must match a unique, non-overlapping region of the origin
 
 ## Outputs / response / events
 
-Every tool returns a `ToolResult` with `toolCallId`, `name`, `content` (`readonly ContentBlock[]`), optional `error`, and optional `metadata`. Mutating tools (`shell` with same cwd, `write`, `edit`) serialize per realpath through `withFileMutationQueue` so concurrent calls targeting one file do not interleave. The package emits no events of its own; hosts observe tool execution through the normal Prism `AgentEvent` stream via `dispatchToolCall`.
+Every tool returns a `ToolResult` with `toolCallId`, `name`, `content` (`readonly ContentBlock[]`), optional `error`, and optional `metadata`. `write` and `edit` serialize per realpath through `withFileMutationQueue` so concurrent calls targeting one file do not interleave. `shell` is marked `exclusive`; tool dispatch serializes it at the turn level. The package emits no events of its own; hosts observe tool execution through the normal Prism `AgentEvent` stream via `dispatchToolCall`.
 
 ## Request/response example
 
@@ -208,6 +213,8 @@ const shell = createShellTool("/repo", {
   shellPath: "/bin/bash",
   commandPrefix: "set -euo pipefail",
   maxLines: 500,
+  timeout: 600,
+  maxTotalOutputBytes: 64 * 1024 * 1024,
 });
 
 const remoteWrite = createWriteTool("/repo", {
@@ -220,8 +227,8 @@ const remoteWrite = createWriteTool("/repo", {
 
 ## Extension and configuration notes
 
-- **Pluggable operation backends.** Every tool accepts an `operations` seam so a host can delegate to a remote system (e.g. SSH) while keeping the tool's matching/serialization behavior: `BashOperations` (`shell`), `ReadOperations` (`read`), `WriteOperations` (`write`), `EditOperations` (`edit`).
-- **Per-tool options.** `ShellToolOptions` (`shellPath`, `commandPrefix`, `maxLines`, `maxBytes`, `tempFilePrefix`, `operations`, `spawnHook`, `executionPolicy`); `ReadToolOptions` (`operations`, `maxImageBytes`, `transformImage`, `maxLines`, `maxBytes`, `executionPolicy`; `autoResizeImages` deprecated); `WriteToolOptions` (`operations`, `executionPolicy`); `EditToolOptions` (`operations`, `executionPolicy`).
+- **Pluggable operation backends.** Every tool accepts an `operations` seam. Custom `ReadOperations` must implement bounded `readText` plus `statFile`; custom `EditOperations` must implement `statFile`; read/write methods receive caps/signals. `BashOperations` must stream through `onData` and honor `signal`/`timeout`. A hostile custom backend can still violate its host-owned contract, so isolate it separately.
+- **Per-tool options.** `ShellToolOptions` adds `timeout` and `maxTotalOutputBytes`; `ReadToolOptions` adds `maxScanBytes`; `WriteToolOptions` adds `maxInputBytes`; `EditToolOptions` adds `maxFileBytes`, `maxInputBytes`, and `maxEdits`. Invalid/non-finite/unsafe/above-hard-cap values throw during tool construction; request `timeout` errors before spawn.
 - **Aggregator options.** `ToolsOptions` (`{ executionPolicy?, shell?, read?, write?, edit? }`) threads each sub-object to the matching tool. `createCodingTools()`, `createAllTools()`, and `createReadOnlyTools()` apply the shared policy unless that tool has an explicit per-tool override.
 - **`ToolsOptions`** and the per-tool option types are exported from the package barrel for host configuration.
 - No auto-discovery or manifest registration: import and register explicitly. This package registers no extensions and owns no globals (the mutation queue is a process-wide per-path map — see `ponytail:` note in the source).
@@ -230,10 +237,24 @@ const remoteWrite = createWriteTool("/repo", {
 
 - **Host shell/filesystem access.** These tools run real commands and read/write real files. They provide **no sandbox**. Gate them with Prism `PermissionPolicy` / `ToolValidator` / trust policies before registering them for any provider turn. Shared `executionPolicy` applies to both full and read-only aggregators before filesystem/process side effects. See [Host security guide](host-security.md) and [Security/auth/trust](settings-auth-trust-security.md).
 - **Non-zero exit is not an error.** A failing command is a normal `shell` result (exit code in metadata); only timeout/abort/spawn failures are error results. Do not assume `error == undefined` means the command succeeded.
-- **Bounded output.** `shell`/`read` accumulate output into a rolling tail bounded by `maxLines`/`maxBytes`; oversized output spills to a temp file (`fullOutputPath`), so memory use is bounded regardless of command output size.
+- **Bounded I/O.** `read` streams one page and bounds scan bytes; image/edit reads use stat plus a shared cap-enforcing reader; write/edit inputs are measured before mutation. `shell` retains only a rolling display tail and synchronously spills accepted raw chunks so stream backpressure cannot grow heap; wall time and total raw output remain finite.
 - **Per-path serialization.** Concurrent mutations to the same file serialize; concurrent mutations to different files do not block each other. The queue is a process-wide map — across sessions in one process, same-path writes still serialize (upgrade path: scope per registry if throughput matters).
 - **Bounded image reads.** `read` rejects images over `maxImageBytes` (default 10 MB) by `stat` before read when possible; MIME is detected from magic bytes only. Optional `transformImage` is host-owned — the base package has no image-processing dependency.
 
+### Resource-limit defaults and hard caps
+
+| Boundary | Default | Hard cap | Failure point |
+| --- | ---: | ---: | --- |
+| Display lines / bytes | 2,000 / 50 KiB | 100,000 / 1 MiB | tool construction |
+| Text scan per read | 64 MiB | 1 GiB | bounded scan before more input is retained |
+| Image | 10,000,000 bytes | 32 MiB | stat and bounded read before base64/transform result use |
+| Write UTF-8 input | 8 MiB | 64 MiB | before policy/filesystem mutation |
+| Edit target / input / count | 8 MiB / 2 MiB / 100 | 64 MiB / 16 MiB / 1,000 | before target read/matching/write |
+| Shell wall time | 600 seconds | 3,600 seconds | process-tree kill |
+| Shell total stdout+stderr | 64 MiB | 1 GiB | process-tree kill; spill removal |
+
+Every configurable value is a positive safe integer; Prism rejects rather than clamps invalid values. Limits control resources, not authority: they do not replace root containment, approval, validation, or a sandbox.
+
 ## Related APIs
 
 - [Tools](tools.md): the host-owned tool harness — `createToolRegistry`, `dispatchToolCall`, filtering, and the `ToolDefinition` contract these factories satisfy.

package/docs/coding-security.md

@@ -74,11 +74,11 @@ const tools = createCodingTools(workspaceRoot, {
 
 Policies are ordinary host values: attach one globally through `createCodingTools()`/`createReadOnlyTools()` or per tool. A per-tool policy overrides the shared policy. `SandboxAdapter` is replaceable and host-owned; approval policy and sandboxing are separate layers.
 
-Callback approval remains process-local. For approval that must survive restart, wrap the action in an opted-in workflow `toolNode({ approval: { reason, data?, resumeSchema? } })`. The workflow persists `suspended` state before any tool side effect. After explicit approve, it recomputes the action and invokes this package's current `ExecutionPolicy`; durable approval never populates or bypasses the process-local approval cache. Adapters should emit chunks through `request.onData` as they arrive and honor `request.signal`/`request.timeout`; buffering is unnecessary. Default caching is `none`; use run-scoped caching only when repeated approval within one run is desired, and session scope only when that wider lifecycle is intentional.
+Callback approval remains process-local. For approval that must survive restart, wrap the action in an opted-in workflow `toolNode({ approval: { reason, data?, resumeSchema? } })`. The workflow persists `suspended` state before any tool side effect. After explicit approve, it recomputes the action and invokes this package's current `ExecutionPolicy`; durable approval never populates or bypasses the process-local approval cache. Adapters should emit chunks through `request.onData` as they arrive and honor `request.signal`/`request.timeout`; buffering is unnecessary. Coding-agent composes caller abort with its total-output controller, so ignoring the supplied signal defeats process termination even though Prism stops retaining output at the cap. Default caching is `none`; use run-scoped caching only when repeated approval within one run is desired, and session scope only when that wider lifecycle is intentional.
 
 ## Security and performance notes
 
-Containment resolves symlinks and rejects paths outside roots. Command rules are not a shell parser; shell metacharacters require approval. Approval waits and subprocess execution honor abort/timeouts. Durable workflow denial/cancellation is terminal and attributable; approved resume still fails if roots, command rules, read-only mode, or other policy changed while suspended. Cache keys are fixed-size SHA-256 digests of selected identity plus action shape; caches remain process-local, retain at most 1,000 decisions with oldest-entry eviction, and have no default/global mode. Path checks and cache lookup are local; sandbox latency belongs to the supplied adapter.
+Containment resolves symlinks and rejects paths outside roots. Command rules are not a shell parser; shell metacharacters require approval. Approval waits and subprocess execution honor abort/timeouts. Coding-agent resource ceilings independently bound text scans, image/edit target reads, write/edit payloads, edit counts, shell wall time, and retained/spilled output. Those ceilings reduce exhaustion risk but do not grant path/command authority or make an unsandboxed shell safe. Durable workflow denial/cancellation is terminal and attributable; approved resume still fails if roots, command rules, read-only mode, or other policy changed while suspended. Cache keys are fixed-size SHA-256 digests of selected identity plus action shape; caches remain process-local, retain at most 1,000 decisions with oldest-entry eviction, and have no default/global mode. Path checks and cache lookup are local; sandbox latency belongs to the supplied adapter.
 
 ## Related APIs
 

package/docs/compaction-llm.md

@@ -25,15 +25,16 @@ Key exports:
 | Field | Purpose |
 | --- | --- |
 | `provider` / `summaryProvider` | Explicit `AIProvider`, or factory receiving a resolved credential. |
-| `model` / `summaryModel` | Explicit summary `ModelConfig`. |
+| `model` / `summaryModel` | Summary `ModelConfig`. `summaryModel` wins; `model` is the session/host fallback via `resolveUseCaseModel`. See [Use-case model selection](use-case-model-selection.md). |
 | `credential`, `credentialRequest` | Optional per-call credential resolution for provider factories. |
 | `providerOptions` | Generic `ProviderRequest.options`, including cache fields. |
 | `providerRequestPolicies` | Optional Prism provider request policies applied before the summary call. |
 | `customInstructions` | Additional summary focus appended to prompts. |
-| `thinkingLevel` | Passed as `ProviderRequest.options.extra.thinkingLevel`. |
-| `reserveTokens` | Output budget basis; defaults to `16384`. |
+| `thinkingLevel` | Mapped into `ProviderRequest.options.compat` via `applyThinkingLevel` / `thinkingFamilyForModel` (not inert `extra.thinkingLevel`). See [Thinking and reasoning](thinking-and-reasoning.md). |
+| `reserveTokens` | Output budget basis; defaults to `16384`, hard cap `131072`. |
 | `keepRecentTokens` | Approximate recent-token budget; defaults to `20000`. |
-| `maxSummaryTokens` / `maxOutputTokens` | Computes the summary output budget, writes it to `summaryModel/model.parameters.maxTokens`, and truncates oversized collected summaries. First-party providers serialize that generic field to their real request field (`max_output_tokens` for OpenAI Responses, `max_tokens` for OpenAI-compatible/Anthropic-style providers). |
+| `maxSummaryTokens` / `maxOutputTokens` | Summary retention/request ceiling; default `16384`, hard cap `131072`. `maxSummaryTokens` wins over the compatibility alias. The finite value is written to `model.parameters.maxTokens`; first-party providers map it to their wire field. |
+| `maxErrorBytes` | Retained provider/factory/policy error detail; default `1024`, hard cap `8192`, UTF-8-safe and known-secret redacted. |
 | `maxToolResultChars` | Tool-result JSON truncation limit; defaults to `2000`. |
 | `trackFileOperations`, `includeFileOperations` | Control file path extraction and final summary blocks. |
 | `secrets` | Exact strings to redact from serialized prompts and final summaries. |
@@ -64,7 +65,8 @@ const strategy = createLlmCompactionStrategy({
   model: { provider: "openai", model: "gpt-4.1-mini" },
   keepRecentTokens: 20_000,
   reserveTokens: 16_384,
-  maxOutputTokens: 800,
+  maxSummaryTokens: 800,
+  maxErrorBytes: 1_024,
   providerOptions: { cacheRetention: "short" },
   customInstructions: "Focus on current files and failing tests.",
 });
@@ -102,10 +104,18 @@ const agent = createAgent({ model, provider, compaction: { strategy, thresholdEn
 Registration only contributes an inert strategy. The host must resolve and pass it to runtime config.
 
 ## Security and performance notes
-Preparation is O(n) over branch entries and uses only arrays, strings, and JSON serialization. Output-budget calculation is O(1) and does not add an extra summarization call. The strategy makes only the needed provider call(s): one history summary plus one split-turn prefix summary when needed. It does not discover credentials, read files, start background jobs, or add provider SDK dependencies. Redaction is exact-string only; pass every known secret that may appear in history or provider output.
+Preparation is O(n) over branch entries and uses only arrays, strings, and JSON serialization. Limit options must be positive safe integers at or below their hard caps and reject during strategy creation. Missing output options use a 16,384-token summary ceiling; reserve ratio/model metadata may narrow the provider request, never remove its finite `maxTokens`. A request policy that replaces `maxTokens` with NaN, Infinity, zero, an unsafe integer, or above-hard-cap input fails before provider generation.
+
+Provider deltas are redacted while retained and stop at `maxSummaryTokens * 4` UTF-16 code units without splitting a surrogate pair. Provider iteration is closed/aborted on overflow. A derived finite event ceiling also stops endless empty/non-text deltas. Final history/turn/file composition receives the same cap. Provider error events, generator throws, provider-factory failures, and policy failures expose only bounded redacted detail; host abort remains authoritative.
+
+The strategy makes only the needed provider call(s): one history summary plus one split-turn prefix summary when needed. It does not discover credentials, read files, start background jobs, or add provider SDK dependencies. Redaction is exact-string only; pass every known secret that may appear in history or provider output.
 
 ## Related APIs
-- [Compaction and retry policies](compaction-and-retry.md): core compaction strategy surface.
+
+- [Use-case model selection](use-case-model-selection.md): `summaryModel` vs session `model` fallback.
+- [Thinking and reasoning](thinking-and-reasoning.md): `thinkingLevel` → `compat`.
+- [Compaction and retry policies](compaction-and-retry.md): replaceable compaction strategy boundary and core compaction strategy surface.
+- [Observational memory compaction package](compaction-observational-memory.md): source-backed memory workers with the same use-case binding pattern.
 - [Agent/session runtime](agent-session-runtime.md): `AgentSession.compact()` and opt-in auto-compaction.
 - [Provider layer](provider-layer.md): mock providers and provider request contracts.
 - [Credentials and redaction](credentials-and-redaction.md): exact known-secret redaction behavior.