@arnilo/prism 0.0.8 → 0.0.96

package/CHANGELOG.md

@@ -1,12 +1,34 @@
 # Changelog
 
-All notable changes to this project will be documented in this file.
-
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+All notable changes to this project will be documented in this file.
+
+## [0.0.96] - 2026-07-21
+
+### Changed
+
+- Package graph and runtime version pins bumped from 0.0.9 to 0.0.96 for a clean publish tag after the mistaken `v0.0.95` tag and TypeScript 7 / workspace-order CI fixes.
+
 ## Unreleased
 
+## [0.0.9] - 2026-07-21
+
+### Added
+
+- Production coding and browser execution for Release 0.0.9: disposable Docker sandbox, bounded native repository list/search, structured Git/named checks/PR handoff, durable coding-plan/checkpoint composition, and optional `@arnilo/prism-browser` with egress/side-effect/upload/download/screenshot policy.
+- Versioned all 32 first-party manifests and exact internal ranges to 0.0.9 (adds `@arnilo/prism-browser` to the publishable graph; browser stays out of `@arnilo/prism-code` and activates only through explicit install or `@arnilo/prism-all`).
+- Added network-free coding/browser adversarial evaluation fixtures, `scripts/benchmark-0.0.9.mjs`, and protected Docker/Playwright gates via `.github/workflows/sandbox-browser.yml`.
+- Office execution remains outside Prism packaging by product decision (host-selected skills/instructions only).
+- `tryParseJsonObjectArguments` and `toolCallFromArgumentsText` for recoverable streamed tool-call argument parsing.
+
+### Fixed
+
+- Malformed streamed tool-call arguments (id+name present) become failed/`tool_execution_blocked` tool results (`invalid_arguments` / `invalid_json_arguments`) instead of terminal `ProviderTransportError`, so models can self-correct within existing turn budgets.
+- Incomplete tool-call deltas (missing id/name) fail with typed `ProviderTransportError` / `ErrorInfo.code: "incomplete_delta"` instead of a bare `Error("Incomplete tool call delta...")`; openai-compatible streams no longer emit `done` alongside leftover incomplete deltas.
+- Empty/whitespace-only call-free artifact candidates (including thinking-only output) are `parse_error` through the revision budget; `generate-validate-revise` session runs no longer resolve `succeeded` without `artifact_finished`.
+
 ## [0.0.8] - 2026-07-20
 
 ### Added

package/dist/agent-loops.js

@@ -111,9 +111,13 @@ export function generateValidateReviseLoop(opts) {
                     .filter((b) => b.type === "text")
                     .map((b) => b.text)
                     .join("");
-                const parsed = opts.parser
-                    ? await opts.parser(text, artifactCtx)
-                    : { ok: true, value: text };
+                // Empty/whitespace-only call-free output is a parse failure (thinking-only
+                // models must not succeed with an empty artifact via the identity parser).
+                const parsed = text.trim() === ""
+                    ? { ok: false, error: "no artifact text in model output" }
+                    : opts.parser
+                        ? await opts.parser(text, artifactCtx)
+                        : { ok: true, value: text };
                 // Parse failure consumes revision budget like a validation failure; the
                 // repairer receives `undefined` value plus a synthetic parse issue.
                 const parseFailure = !parsed.ok || parsed.value === undefined

package/dist/agents.js

@@ -274,6 +274,8 @@ class RuntimeAgentSession {
             };
             // ponytail: LoopContext binds existing private helpers; loop orchestrates only.
             let assembledTurn = false;
+            let artifactFinished = false;
+            let artifactFailedInfo;
             const ctx = {
                 sessionId: this.id,
                 runId,
@@ -368,6 +370,16 @@ class RuntimeAgentSession {
                 emit: (event) => {
                     if (event.type === "turn_started")
                         this.activeLoopTurn = event.turn;
+                    if (event.type === "artifact_finished")
+                        artifactFinished = true;
+                    if (event.type === "artifact_failed") {
+                        const first = event.result.errors?.[0];
+                        const reason = event.result.metadata?.reason;
+                        artifactFailedInfo = {
+                            message: first?.message ?? "artifact failed",
+                            code: typeof reason === "string" || typeof reason === "number" ? reason : "artifact_failed",
+                        };
+                    }
                     this.emit(event);
                 },
             };
@@ -380,6 +392,9 @@ class RuntimeAgentSession {
                 });
             }
             const loopUsage = await loop.run(ctx);
+            if (loop.name === "generate-validate-revise" && !artifactFinished) {
+                throw Object.assign(new Error(artifactFailedInfo?.message ?? "artifact loop ended without a validated artifact"), { name: "ArtifactFailed", code: artifactFailedInfo?.code ?? "artifact_failed" });
+            }
             usage = runUsage.value() ?? loopUsage;
             if (usage && this.activeLedger) {
                 const usageRecord = {
@@ -999,7 +1014,7 @@ function policyList(policies) {
     return "apply" in policies ? [policies] : policies;
 }
 function errorFromInfo(error) {
-    return Object.assign(new Error(error.message), { name: error.name ?? "Error", cause: error.cause });
+    return Object.assign(new Error(error.message), { name: error.name ?? "Error", cause: error.cause, code: error.code });
 }
 class ProviderTurnFailure extends Error {
     info;

package/dist/contracts.d.ts

@@ -49,6 +49,8 @@ export interface ToolCallContent {
     readonly id: string;
     readonly name: string;
     readonly arguments: JsonObject;
+    /** Set when streamed arguments failed JSON parse; dispatch blocks without execute(). */
+    readonly argumentsError?: ErrorInfo;
 }
 export interface ToolResultContent {
     readonly type: "tool_result";

package/dist/index.d.ts

@@ -60,7 +60,7 @@ export { createMockProvider } from "./mock-provider.js";
 export { createMemorySessionStore, createSessionEntry, getSessionBranchEntries, listSessionBranches, rebuildSessionContext } from "./session-stores.js";
 export type { CreateSessionEntryOptions, SessionBranch, SessionBranchOptions, SessionContextSnapshot } from "./session-stores.js";
 export type { MockProviderOptions } from "./mock-provider.js";
-export { providerContentDelta, providerDone, providerError, providerTextDelta, providerThinkingDelta, providerToolCall, providerToolCallDelta, providerUsage, toolCallContent, } from "./provider-events.js";
+export { providerContentDelta, providerDone, providerError, providerTextDelta, providerThinkingDelta, providerToolCall, providerToolCallDelta, providerUsage, toolCallContent, toolCallFromArgumentsText, } from "./provider-events.js";
 export type { ProviderResolver } from "./contracts.js";
 export { createProviderRegistry, createProviderResolver } from "./providers.js";
 export type { ProviderRegistry, ProviderRegistryOptions } from "./providers.js";
@@ -83,5 +83,5 @@ export type { DispatchToolCallOptions, ToolArgumentValidationError, ToolArgument
 export type { DuplicateRegistrationOptions, DuplicateRegistrationPolicy } from "./registry-options.js";
 export { dispatchToolCallsInOrder, generateValidateReviseLoop, isAgentLoopOptions, resolveLoop, resolveToolConcurrency, singleShotLoop } from "./agent-loops.js";
 export declare const name = "prism";
-export declare const version = "0.0.8";
+export declare const version = "0.0.96";
 export declare const description = "Agent harness for AI providers, agents, sessions, and tools.";

package/dist/index.js

@@ -33,7 +33,7 @@ export { createMiddlewareRegistry } from "./middleware.js";
 export { assembleProviderInput, createDefaultInputBuilder, createDefaultPromptBuilder, renderPromptTemplate, resolveContextProviders } from "./input.js";
 export { createMockProvider } from "./mock-provider.js";
 export { createMemorySessionStore, createSessionEntry, getSessionBranchEntries, listSessionBranches, rebuildSessionContext } from "./session-stores.js";
-export { providerContentDelta, providerDone, providerError, providerTextDelta, providerThinkingDelta, providerToolCall, providerToolCallDelta, providerUsage, toolCallContent, } from "./provider-events.js";
+export { providerContentDelta, providerDone, providerError, providerTextDelta, providerThinkingDelta, providerToolCall, providerToolCallDelta, providerUsage, toolCallContent, toolCallFromArgumentsText, } from "./provider-events.js";
 export { createProviderRegistry, createProviderResolver } from "./providers.js";
 export { createSecretRedactor, errorToErrorInfo, redactAgentEvent, redactMessage, redactProviderRequest, redactRunLedgerRecord, redactSecrets, redactSessionEntry } from "./redaction.js";
 export { assertPermission, assertTrusted, checkPermission, createStaticPermissionPolicy, createStaticTrustPolicy, denialToErrorInfo, isTrusted, PermissionDeniedError, TrustDeniedError } from "./security.js";
@@ -45,6 +45,6 @@ export { assertGuardrailsAllowed, GuardrailError, MAX_GUARDRAIL_CONCURRENCY, run
 export { createRunLimitTracker, DEFAULT_RUN_LIMITS, HARD_MAX_RUN_COST, HARD_RUN_LIMITS, RunLimitError, RunLimitTracker, resolveRunLimits } from "./run-limits.js";
 export { dispatchToolCallsInOrder, generateValidateReviseLoop, isAgentLoopOptions, resolveLoop, resolveToolConcurrency, singleShotLoop } from "./agent-loops.js";
 export const name = "prism";
-export const version = "0.0.8";
+export const version = "0.0.96";
 export const description = "Agent harness for AI providers, agents, sessions, and tools.";
 //# sourceMappingURL=index.js.map

package/dist/provider-events.d.ts

@@ -15,3 +15,5 @@ export declare function providerUsage(usage: Usage): ProviderEvent;
 export declare function providerDone(usage?: Usage): ProviderEvent;
 export declare function providerError(error: unknown, secrets?: readonly (string | undefined)[]): ProviderEvent;
 export declare function toolCallContent(id: string, name: string, args?: JsonObject): ToolCallContent;
+/** Build a tool call from streamed arguments text; malformed JSON becomes a blocked call (no throw). */
+export declare function toolCallFromArgumentsText(id: string, name: string, argumentsText: string): ToolCallContent;

package/dist/provider-events.js

@@ -1,3 +1,4 @@
+import { ProviderTransportError, tryParseJsonObjectArguments } from "./providers/transport.js";
 import { errorToErrorInfo } from "./redaction.js";
 export function providerTextDelta(text) {
     return { type: "content_delta", content: { type: "text", text } };
@@ -32,9 +33,10 @@ export function reconstructToolCallDeltas(events) {
         partials.set(event.index, partial);
     }
     return [...partials.entries()].sort(([a], [b]) => a - b).map(([index, partial]) => {
-        if (!partial.id || !partial.name)
-            throw new Error(`Incomplete tool call delta at index ${index}`);
-        return toolCallContent(partial.id, partial.name, parseToolCallArguments(partial.argumentsText, index));
+        if (!partial.id || !partial.name) {
+            throw new ProviderTransportError("incomplete_delta", `Incomplete tool call delta at index ${index}`);
+        }
+        return toolCallFromArgumentsText(partial.id, partial.name, partial.argumentsText);
     });
 }
 export function providerUsage(usage) {
@@ -50,15 +52,21 @@ export function providerError(error, secrets = []) {
 export function toolCallContent(id, name, args = {}) {
     return { type: "tool_call", id, name, arguments: args };
 }
-function parseToolCallArguments(text, index) {
-    try {
-        const value = text ? JSON.parse(text) : {};
-        if (!value || typeof value !== "object" || Array.isArray(value))
-            throw new Error("not object");
-        return value;
-    }
-    catch (error) {
-        throw new Error(`Invalid tool call arguments at index ${index}: ${error instanceof Error ? error.message : String(error)}`);
-    }
+/** Build a tool call from streamed arguments text; malformed JSON becomes a blocked call (no throw). */
+export function toolCallFromArgumentsText(id, name, argumentsText) {
+    const parsed = tryParseJsonObjectArguments(argumentsText, { toolName: name });
+    if (parsed.ok)
+        return toolCallContent(id, name, parsed.value);
+    return {
+        type: "tool_call",
+        id,
+        name,
+        arguments: {},
+        argumentsError: {
+            name: parsed.error.name,
+            message: parsed.error.message,
+            code: parsed.error.code,
+        },
+    };
 }
 //# sourceMappingURL=provider-events.js.map

package/dist/providers/openai-compatible.js

@@ -1,7 +1,7 @@
 import { resolveCredentialValue } from "../credentials.js";
-import { providerDone, providerError, providerTextDelta, providerThinkingDelta, providerToolCall, providerToolCallDelta, providerUsage, toolCallContent, } from "../provider-events.js";
+import { providerDone, providerError, providerTextDelta, providerThinkingDelta, providerToolCall, providerToolCallDelta, providerUsage, toolCallFromArgumentsText, } from "../provider-events.js";
 import { assertOpenAIChatMessage, applyOpenAIChatStructuredOutput, mapOpenAIChatUsage, serializeOpenAIChatMessage, serializeOpenAITool, } from "./openai-primitives.js";
-import { parseJsonObjectArguments, readBoundedResponseText, readSseData, } from "./transport.js";
+import { ProviderTransportError, readBoundedResponseText, readSseData, } from "./transport.js";
 import { assertStructuredOutputRequestSupported } from "../structured-output.js";
 export function createOpenAICompatibleProvider(options) {
     const providerId = options.id ?? "openai-compatible";
@@ -64,10 +64,13 @@ export function createOpenAICompatibleProvider(options) {
                         }
                     }
                 }
+                const incomplete = [...tools.entries()].find(([, call]) => !call.id || !call.name);
+                if (incomplete) {
+                    yield providerError(new ProviderTransportError("incomplete_delta", `Incomplete tool call delta at index ${incomplete[0]}`), secrets);
+                    return;
+                }
                 for (const call of tools.values()) {
-                    if (call.id && call.name) {
-                        yield providerToolCall(toolCallContent(call.id, call.name, parseJsonObjectArguments(call.argumentsText, { toolName: call.name })));
-                    }
+                    yield providerToolCall(toolCallFromArgumentsText(call.id, call.name, call.argumentsText));
                 }
                 yield providerDone();
             }

package/dist/providers/transport.d.ts

@@ -14,7 +14,7 @@ export interface SseEvent {
     readonly data: string;
     readonly comments?: readonly string[];
 }
-export type ProviderTransportErrorCode = "sse_buffer_overflow" | "sse_event_overflow" | "response_body_overflow" | "aborted" | "invalid_json_arguments";
+export type ProviderTransportErrorCode = "sse_buffer_overflow" | "sse_event_overflow" | "response_body_overflow" | "aborted" | "invalid_json_arguments" | "incomplete_delta";
 export declare class ProviderTransportError extends Error {
     readonly code: ProviderTransportErrorCode;
     readonly limitBytes?: number;
@@ -36,5 +36,14 @@ export declare function readSseEvents(body: ReadableStream<Uint8Array>, options?
 export declare function readSseData(body: ReadableStream<Uint8Array>, options?: ReadSseEventsOptions): AsyncGenerator<string>;
 /** Read a response body with a hard byte ceiling; redacts optional secrets. */
 export declare function readBoundedResponseText(response: Response, options?: ReadBoundedResponseTextOptions): Promise<string>;
+export type ParseJsonObjectArgumentsResult = {
+    readonly ok: true;
+    readonly value: JsonObject;
+} | {
+    readonly ok: false;
+    readonly error: ProviderTransportError;
+};
+/** Parse streamed tool arguments without throwing; prefer this for recoverable tool-call recovery. */
+export declare function tryParseJsonObjectArguments(text: string, options?: ParseJsonObjectArgumentsOptions): ParseJsonObjectArgumentsResult;
 /** Parse streamed tool arguments as a JSON object; throws {@link ProviderTransportError} on invalid input. */
 export declare function parseJsonObjectArguments(text: string, options?: ParseJsonObjectArgumentsOptions): JsonObject;

package/dist/providers/transport.js

@@ -197,25 +197,41 @@ export async function readBoundedResponseText(response, options) {
         }
     }
 }
-/** Parse streamed tool arguments as a JSON object; throws {@link ProviderTransportError} on invalid input. */
-export function parseJsonObjectArguments(text, options) {
+/** Parse streamed tool arguments without throwing; prefer this for recoverable tool-call recovery. */
+export function tryParseJsonObjectArguments(text, options) {
     const maxBytes = options?.maxBytes ?? DEFAULT_MAX_ARGUMENT_BYTES;
     const suffix = options?.toolName ? ` for tool ${options.toolName}` : "";
     if (!text)
-        return {};
+        return { ok: true, value: {} };
     if (byteLength(text) > maxBytes) {
-        throw new ProviderTransportError("invalid_json_arguments", `Tool arguments${suffix} exceeded ${maxBytes} bytes`, maxBytes);
+        return {
+            ok: false,
+            error: new ProviderTransportError("invalid_json_arguments", `Tool arguments${suffix} exceeded ${maxBytes} bytes`, maxBytes),
+        };
     }
     let parsed;
     try {
         parsed = JSON.parse(text);
     }
-    catch (error) {
-        throw new ProviderTransportError("invalid_json_arguments", `Invalid tool arguments JSON${suffix}`);
+    catch {
+        return {
+            ok: false,
+            error: new ProviderTransportError("invalid_json_arguments", `Invalid tool arguments JSON${suffix}`),
+        };
     }
     if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
-        throw new ProviderTransportError("invalid_json_arguments", `Tool arguments${suffix} must be a JSON object`);
+        return {
+            ok: false,
+            error: new ProviderTransportError("invalid_json_arguments", `Tool arguments${suffix} must be a JSON object`),
+        };
     }
-    return parsed;
+    return { ok: true, value: parsed };
+}
+/** Parse streamed tool arguments as a JSON object; throws {@link ProviderTransportError} on invalid input. */
+export function parseJsonObjectArguments(text, options) {
+    const result = tryParseJsonObjectArguments(text, options);
+    if (!result.ok)
+        throw result.error;
+    return result.value;
 }
 //# sourceMappingURL=transport.js.map

package/dist/tools.js

@@ -176,6 +176,8 @@ async function checkCall(call, options, startedAt) {
         return blocked(call, context, "unknown_tool", { message: `Unknown tool: ${call.name}` }, options, startedAt);
     if (filterTools([tool], options.filter).length === 0)
         return blocked(call, context, "tool_denied", { message: `Tool denied: ${call.name}` }, options, startedAt);
+    if (call.argumentsError)
+        return blocked(call, context, "invalid_arguments", call.argumentsError, options, startedAt);
     if (!isJsonObject(call.arguments))
         return blocked(call, context, "invalid_arguments", { message: "Tool arguments must be a JSON object" }, options, startedAt);
     return undefined;

package/docs/agent-events.md

@@ -67,7 +67,7 @@ Agent / turn / message events:
 | `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) |
 
-`message_delta.content.type === "tool_call_delta"` carries `{ index, id?, name?, argumentsText? }`. Treat it as a streaming fragment. The runtime reconstructs and persists a final `tool_call` before executing tools.
+`message_delta.content.type === "tool_call_delta"` carries `{ index, id?, name?, argumentsText? }`. Treat it as a streaming fragment. The runtime reconstructs and persists a final `tool_call` before executing tools. Deltas missing `id`/`name` at stream end fail the provider turn with `ErrorInfo.code: "incomplete_delta"` (typed `ProviderTransportError`); they never throw a bare `Error`. Malformed JSON with id+name present recovers as a blocked tool result (`invalid_json_arguments`) instead.
 
 Tool execution events:
 
@@ -127,7 +127,8 @@ turn_started → message_started → message_delta* → message_finished → tur
 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.
+- Empty/whitespace-only call-free text (including thinking-only content) emits `artifact_validation_*` with `metadata.reason: "parse_error"` before any host parser runs.
+- Single-shot runs emit zero artifact events. Session runs with `generate-validate-revise` require `artifact_finished` to resolve `succeeded`.
 - **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

package/docs/agent-loops.md

@@ -89,7 +89,7 @@ Host callback contracts (all generic over host `T`):
 
 | Contract | Shape |
 | --- | --- |
-| `ArtifactParser<T>` | `(text: string, ctx: ArtifactContext) => ArtifactParseResult<T> \| Promise<...>` — parse assistant text to a typed value. A parse failure (`ok: false` or missing `value`) consumes revision budget exactly like a validation failure: the repairer receives `value: undefined` plus a synthetic failure (`errors[0].message` = the parse error, `metadata.reason: "parse_error"`), and budget exhaustion ends with terminal `artifact_failed`. |
+| `ArtifactParser<T>` | `(text: string, ctx: ArtifactContext) => ArtifactParseResult<T> \| Promise<...>` — parse assistant text to a typed value. Empty/whitespace-only call-free text is rejected before the parser (`metadata.reason: "parse_error"`, message `no artifact text in model output`) so thinking-only/reasoning-only turns cannot succeed via the identity parser. A parse failure (`ok: false` or missing `value`) consumes revision budget exactly like a validation failure: the repairer receives `value: undefined` plus a synthetic failure (`errors[0].message` = the parse error, `metadata.reason: "parse_error"`), and budget exhaustion ends with terminal `artifact_failed`. |
 | `ArtifactValidator<T>` | `(value: T, ctx: ArtifactContext) => ArtifactValidation \| Promise<...>` — return `{ ok: true }` or `{ ok: false, errors }`. |
 | `ArtifactRepairer<T>` | `(value: T \| undefined, failure: ArtifactValidation, ctx: ArtifactContext) => AgentInput \| Promise<...>` — build the revision follow-up input. |
 | `ArtifactValidation` | `{ ok: boolean; errors?: readonly { path?: string; message: string }[]; metadata?: ... }`. |
@@ -119,7 +119,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`. 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.
+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. Session runs using `generate-validate-revise` resolve `succeeded` only after `artifact_finished`; terminal `artifact_failed` (including empty/thinking-only parse exhaustion) fails the run with `AgentRunError` (`error.code` from `result.metadata.reason`, e.g. `parse_error`).
 
 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`.
 

package/docs/browser-automation.md

@@ -0,0 +1,124 @@
+# Browser automation
+
+## What it does
+
+`@arnilo/prism-browser` exposes exactly four exclusive model-facing tools—`browser_open`, `browser_snapshot`, `browser_act`, and `browser_close`—over a host-supplied Playwright `Browser`. Prism creates one non-persistent `BrowserContext` per run, serializes actions, returns bounded AI-mode accessibility snapshots with snapshot-scoped refs, enforces egress/side-effect/upload/download/screenshot policy, and closes context/pages/listeners/quarantined downloads on close, abort, or manager disposal.
+
+## When to use it
+
+Use when an agent must interact with JavaScript-heavy or authenticated pages that search/fetch cannot cover. Prefer `@arnilo/prism-web-tools` for ordinary public retrieval. Do not use this package as a browser launcher, MCP proxy, visual planner, CDP console, or persistent profile manager.
+
+## Inputs / request
+
+| Tool | Model-visible input | Host-only construction input |
+| --- | --- | --- |
+| `browser_open` | optional absolute `http(s)` `url` | host Playwright `Browser` or `BrowserManager`, limits, `ExecutionPolicy`, `networkPolicy`, uploads/downloads |
+| `browser_snapshot` | optional `pageId` | same manager/context |
+| `browser_act` | `action` plus action-specific fields (`target`, `snapshotId`, `url`, `text`, `values`, `paths`, `downloadId`, `dialogResponse`, `pageId`, `clip`, …) | policy checked before side effects |
+| `browser_close` | none | closes only the run-owned context, never the host Browser process |
+
+`createBrowserTools({ browser, executionPolicy?, limits?, networkPolicy?, uploads?, downloads?, beforeSideEffect? })` builds the four tools. `createBrowserManager(...)` exposes host lifecycle helpers `closeRun(runId)` / `close()` and `listDownloads(runId)`.
+
+Targets accepted by `browser_act`: snapshot `ref`, `role`(+`name`), `label`, `testId`, or `text`. CSS, XPath, selector strings, `page.evaluate`, CDP/devtools, extensions, and persistent/local profiles are unsupported.
+
+`browser_act` actions: `navigate`, `click`, `type`, `fill`, `select`, `check`, `uncheck`, `scroll`, `wait`, `dialog`, `select_page`, `upload`, `screenshot`, `download_release`.
+
+## Outputs / response / events
+
+`browser_open` returns run/page ids and URL. `browser_snapshot` returns `snapshotId`, URL/title, bounded AI-mode aria YAML (`ariaSnapshot({ mode: "ai" })`), ref count, and truncation metadata. Refs are valid only for that snapshot id and become stale after navigation or mutation. `browser_act` returns the action, active page id, and URL; `screenshot` also returns bounded `ImageContent`; `download_release` returns quarantine metadata after host approval. `browser_close` is idempotent. Results mark `trust: "untrusted_external"`; page text must never alter tools, permissions, credentials, or policy.
+
+## Request/response example
+
+```json
+{
+  "tool": "browser_snapshot",
+  "arguments": {},
+  "result": {
+    "snapshotId": "snap_ab12…",
+    "pageId": "page_1",
+    "url": "https://example.com/",
+    "title": "Example",
+    "refCount": 12,
+    "ariaSnapshot": "- main [ref=e8]:\n  - button \"Submit\" [ref=e12]"
+  }
+}
+```
+
+```json
+{
+  "tool": "browser_act",
+  "arguments": {
+    "action": "click",
+    "target": { "ref": "e12" },
+    "snapshotId": "snap_ab12…"
+  }
+}
+```
+
+## Implementation example
+
+```ts
+import { chromium } from "playwright-core";
+import {
+  createBrowserManager,
+  createBrowserTools,
+  createSharedSandboxBrowserOptions,
+} from "@arnilo/prism-browser";
+import { assertBrowserSandboxNetwork } from "@arnilo/prism-coding-security";
+
+assertBrowserSandboxNetwork({
+  mode: "custom",
+  name: "prism-egress",
+  browserEgress: { proxyEndpoint: "http://127.0.0.1:3128", denyDirectEgress: true },
+});
+
+const aligned = createSharedSandboxBrowserOptions({
+  workspaceRoot: "/workspace",
+  downloadsRoot: "/downloads",
+  containedProxyAttestation: {
+    proxyEndpoint: "http://127.0.0.1:3128",
+    denyDirectEgress: true,
+  },
+  approveDownloadRelease: async (meta) => meta.bytes < 1_000_000,
+});
+
+const browser = await chromium.launch({ headless: true });
+const manager = createBrowserManager({
+  browser,
+  ...aligned,
+  limits: { maxPages: 4, maxActions: 100, maxSnapshotBytes: 256 * 1024 },
+});
+const tools = createBrowserTools({ manager, executionPolicy });
+
+// On run terminal / abort / cancel:
+await manager.closeRun(runId);
+await manager.close();
+await browser.close();
+```
+
+## Extension and configuration notes
+
+- Compatibility line: `playwright-core@1.61.0` optional peer. Hosts pin browser binaries/images; Prism package install downloads nothing.
+- Default/hard caps: pages 4/16; actions 100/256; queued actions 16/64; snapshot refs 2k/10k; depth 30/100; snapshot bytes 256 KiB/2 MiB; navigation 30s/120s; action 10s/60s; wait 30s/120s; run wall 20min/30min; popups 4/16; dialogs 16/64; close grace 5s/30s; network requests 1k/10k; redirects/request 10/32; WebSockets 8/32; screenshots 16/64 with 16/64 megapixels and 10 MiB/32 MiB encoded; uploads 8/32 files, 16 MiB/64 MiB each, 64 MiB/256 MiB aggregate; downloads 8/32 files, 32 MiB/256 MiB each, 64 MiB/512 MiB aggregate.
+- Contexts use `serviceWorkers: "block"` and install `BrowserContext.route()` for every visible HTTP(S)/WebSocket request. `acceptDownloads` is enabled only when `downloads` is configured.
+- `networkPolicy` defaults to `requireContainedProxy: true` (fail closed). Hosts must supply `containedProxyAttestation: { proxyEndpoint, denyDirectEgress: true }`. Private/loopback/link-local, `file`/`data`/`blob`/`javascript`/`devtools` schemes are denied by default. Playwright routing is defense in depth — production DNS/private egress is a host firewall/proxy.
+- Uploads require absolute paths under `uploads.roots` (realpath-contained; symlink escapes rejected). Downloads stream into `downloads.quarantine` with SHA-256/MIME/name metadata; `download_release` requires host `approveRelease`. Screenshots return bounded `ImageContent`.
+- Observation (`snapshot`, `wait`, open-without-url, `close`) vs mutation/high-impact (`navigate`, click/form, dialog accept, upload, download release, popup select) is classified for `ExecutionPolicy` / `beforeSideEffect`.
+- `createSharedSandboxBrowserOptions()` aligns browser uploads/downloads with Task 1 sandbox `/workspace` and `/downloads`. `assertBrowserSandboxNetwork()` in `@arnilo/prism-coding-security` fails closed for custom Docker networks without browser egress attestation.
+- Raw CSS is absent from production defaults. Ref resolution uses Playwright’s built-in `aria-ref=` selector with a package-owned snapshot ref table for staleness checks.
+
+## Security and performance notes
+
+Import is inert. Construction fails clearly when neither `browser` nor `manager` is supplied. Browser installation, launch, version, and control endpoint are host-owned. Prism never exposes `page.evaluate`, init scripts, CDP, extensions, persistent profiles, or model-supplied Playwright launch options. Secrets and storage state must not appear in snapshots, tool results, logs, or checkpoints. Finite caps charge before context/page/action/queue/snapshot/network/artifact retention; snapshots retain no unbounded DOM, console, request, response, or trace history. Unreleased downloads are deleted on context close.
+
+Default tests use fake Playwright APIs only. Protected live gate: `PRISM_LIVE_PLAYWRIGHT=1` (or `PRISM_TEST_PLAYWRIGHT=1`) `npm run test:live -w @arnilo/prism-browser` exercises a local loopback hostile HTML fixture for snapshot refs, stale-ref rejection, CSS denial, private/file deny, upload containment, screenshot bounds, and download quarantine/release. Missing browser binaries fail closed when the gate is enabled. Adversarial network-free fixtures live in `eval-fixtures.test.ts`; see [Evaluations](evaluations.md) and `examples/coding-browser-evaluation.ts`.
+
+## Related APIs
+
+- [Tools](tools.md): registry, exclusive dispatch, validation, and ledger.
+- [Web search, fetch, and extraction](web-tools.md): preferred non-interactive retrieval path.
+- [Guardrails](guardrails.md): untrusted external content handling.
+- [Host security](host-security.md): browser endpoint, approval, egress proxy, and artifact trust boundaries.
+- [Performance and resource limits](performance.md): browser ceilings and charging points.
+- [Coding execution approval and sandboxing](coding-security.md): optional shared disposable sandbox for coding+browser.
+- [Migration](migration.md): additive optional package activation.