@arnilo/prism 0.2.9 → 0.3.1

package/dist/input.js

@@ -41,16 +41,22 @@ export function createDefaultPromptBuilder() {
             // Tool-capable models receive schemas via request.tools; the text list only serves
             // text-only (or unknown-capability) models — duplicating it doubles tool tokens per turn.
             const tools = request.model?.capabilities?.tools === true ? undefined : request.tools;
-            return [
-                ...contextMessages(request.context),
-                ...buildSkillMessages(request.skills, {
-                    disclosure: request.skillsDisclosure,
-                    loaded: request.loadedSkills,
-                    demotedBodies: request.demotedSkillBodies?.length ? new Set(request.demotedSkillBodies) : undefined,
-                }),
-                ...toolMessages(tools),
-                ...request.messages,
-            ];
+            const context = contextMessages(request.context);
+            const skills = buildSkillMessages(request.skills, {
+                disclosure: request.skillsDisclosure,
+                loaded: request.loadedSkills,
+                demotedBodies: request.demotedSkillBodies?.length ? new Set(request.demotedSkillBodies) : undefined,
+            });
+            const declarations = toolMessages(tools);
+            if ((request.inputLayout ?? "cache_aware") === "legacy") {
+                return [...context, ...skills, ...declarations, ...request.messages];
+            }
+            // Default input assembly keeps stable instruction messages at the front. Keep that
+            // boundary ahead of dynamic context/skills; legacy retains the old whole-prompt order.
+            const firstNonSystem = request.messages.findIndex((message) => message.role !== "system");
+            const stable = firstNonSystem < 0 ? request.messages : request.messages.slice(0, firstNonSystem);
+            const dynamic = firstNonSystem < 0 ? [] : request.messages.slice(firstNonSystem);
+            return [...stable, ...context, ...skills, ...declarations, ...dynamic];
         },
     };
 }
@@ -165,6 +171,7 @@ export async function assembleProviderInput(options) {
     const promptRequest = options.middleware
         ? await options.middleware.run("prompt_build", {
             messages,
+            inputLayout: layout,
             context,
             skills,
             skillsDisclosure: options.skillsDisclosure,
@@ -176,6 +183,7 @@ export async function assembleProviderInput(options) {
         })
         : {
             messages,
+            inputLayout: layout,
             context,
             skills,
             skillsDisclosure: options.skillsDisclosure,
@@ -185,7 +193,7 @@ export async function assembleProviderInput(options) {
             metadata: options.metadata,
             signal: options.signal,
         };
-    const providerMessages = await promptBuilder.build({ ...promptRequest, tools, model: options.model });
+    const providerMessages = await promptBuilder.build({ ...promptRequest, inputLayout: layout, tools, model: options.model });
     assertMessagesSupportModelCapabilities(options.model, providerMessages);
     const metadata = budgetReport ? { ...options.metadata, [CONTEXT_BUDGET_REPORT_METADATA_KEY]: budgetReport } : options.metadata;
     return {

package/dist/node/session-store-jsonl.js

@@ -14,7 +14,9 @@ export function createJsonlSessionStore(pathOrOptions) {
     const idempotencySeen = new Set();
     return {
         append(entry, appendOptions) {
-            appendChain = appendChain.then(async () => {
+            const operation = appendChain
+                .catch(() => undefined)
+                .then(async () => {
                 if (options.createDirectory !== false)
                     await mkdir(dirname(path), { recursive: true });
                 const readResult = await readJsonlSessionEntries(path);
@@ -29,7 +31,8 @@ export function createJsonlSessionStore(pathOrOptions) {
                 if (dedupKey !== undefined && idempotencySeen.has(dedupKey)) {
                     throw new SessionAppendConflictError({ code: SESSION_APPEND_CONFLICT_CODE, idempotencyDuplicate: true });
                 }
-                if (appendOptions?.expectedParentId !== undefined && !entries.some((existing) => existing.id === appendOptions.expectedParentId)) {
+                if (appendOptions?.expectedParentId !== undefined &&
+                    !entries.some((existing) => existing.id === appendOptions.expectedParentId)) {
                     throw new SessionAppendConflictError({ code: SESSION_APPEND_CONFLICT_CODE, expectedParentId: appendOptions.expectedParentId });
                 }
                 if (entries.some((existing) => existing.id === entry.id))
@@ -38,7 +41,8 @@ export function createJsonlSessionStore(pathOrOptions) {
                     idempotencySeen.add(dedupKey);
                 await appendFile(path, `${JSON.stringify(entry)}\n`, "utf8");
             });
-            return appendChain;
+            appendChain = operation.catch(() => undefined);
+            return operation;
         },
         async list(sessionId) {
             return (await readEntries(path)).filter((entry) => entry.sessionId === sessionId);

package/dist/providers/openai-compatible.js

@@ -1,6 +1,7 @@
 import { resolveCredentialValue } from "../credentials.js";
 import { providerDone, providerError, providerTextDelta, providerThinkingDelta, providerToolCall, providerToolCallDelta, providerUsage, toolCallFromArgumentsText, } from "../provider-events.js";
 import { assertStructuredOutputRequestSupported } from "../structured-output.js";
+import { trimTrailingSlashes } from "../trim-trailing-slashes.js";
 import { applyOpenAIChatStructuredOutput, assertOpenAIChatMessage, mapOpenAIChatUsage, serializeOpenAIChatMessage, serializeOpenAITool, } from "./openai-primitives.js";
 import { httpStatusError, ProviderTransportError, readBoundedResponseText, readSseEvents } from "./transport.js";
 /**
@@ -100,7 +101,7 @@ export function createOpenAICompatibleProvider(options) {
             try {
                 const url = typeof options.chatCompletionsUrl === "function"
                     ? options.chatCompletionsUrl(request)
-                    : (options.chatCompletionsUrl ?? `${options.baseUrl.replace(/\/+$/, "")}/chat/completions`);
+                    : (options.chatCompletionsUrl ?? `${trimTrailingSlashes(options.baseUrl)}/chat/completions`);
                 const authStyle = options.authStyle ?? "bearer";
                 const headers = {
                     ...Object.fromEntries(Object.entries(request.options?.headers ?? {}).filter((entry) => typeof entry[1] === "string")),

package/dist/providers/openai-primitives.js

@@ -1,3 +1,4 @@
+import { canonicalizeJsonSchema } from "./schema.js";
 export function assertOpenAIChatMessage(message, path) {
     if (!message || typeof message !== "object") {
         throw new Error(`Invalid provider message at ${path}: expected object`);
@@ -46,7 +47,7 @@ export function serializeOpenAITool(tool) {
         function: {
             name: tool.name,
             description: tool.description,
-            parameters: tool.parameters ?? { type: "object" },
+            parameters: canonicalizeJsonSchema(tool.parameters ?? { type: "object" }),
         },
     };
 }

package/dist/providers/schema.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Deterministic JSON Schema clone for tool/function parameters.
+ * Sorts object keys and unordered `required` names. Leaves semantic arrays
+ * (`prefixItems`, `examples`, `enum`, tuple `items`) in caller order.
+ * Does not resolve `$ref`, mutate input, or enforce schema bounds.
+ */
+export declare function canonicalizeJsonSchema(value: unknown): unknown;

package/dist/providers/schema.js

@@ -0,0 +1,25 @@
+/**
+ * Deterministic JSON Schema clone for tool/function parameters.
+ * Sorts object keys and unordered `required` names. Leaves semantic arrays
+ * (`prefixItems`, `examples`, `enum`, tuple `items`) in caller order.
+ * Does not resolve `$ref`, mutate input, or enforce schema bounds.
+ */
+export function canonicalizeJsonSchema(value) {
+    if (Array.isArray(value))
+        return value.map(canonicalizeJsonSchema);
+    if (!value || typeof value !== "object")
+        return value;
+    return Object.fromEntries(Object.entries(value)
+        .sort(([left], [right]) => compareKey(left, right))
+        .map(([key, item]) => [key, key === "required" ? canonicalizeRequired(item) : canonicalizeJsonSchema(item)]));
+}
+function canonicalizeRequired(item) {
+    if (Array.isArray(item) && item.every((entry) => typeof entry === "string")) {
+        return [...item].sort(compareKey);
+    }
+    return canonicalizeJsonSchema(item);
+}
+function compareKey(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+//# sourceMappingURL=schema.js.map

package/dist/testing/provider-conformance.d.ts

@@ -38,6 +38,16 @@ export declare function assertProviderStreamConforms(options: ProviderStreamConf
 export declare function assertAbortIsObserved(options: ProviderAbortConformanceOptions): Promise<void>;
 export declare function assertToolCallDeltasReconstruct(events: readonly ProviderEvent[], expected: readonly ToolCallDeltaExpectation[]): readonly ToolCallContent[];
 export declare function assertSerializedRequestCoversContent(request: ProviderRequest, body: unknown, options?: SerializedContentCoverageOptions): void;
+export declare function assertCanonicalToolParameters(serialized: unknown, original: unknown): void;
 export declare function assertProviderOwnedHeadersWin(captured: Headers, options: ProviderHeaderOwnershipConformanceOptions): void;
 export declare function assertNoSecretLeak(events: readonly ProviderEvent[], secrets: readonly string[]): void;
+/**
+ * Implicit/none-cache providers must serialize no foreign cache fields: implicit
+ * caching works by byte-stable prefix reuse, not request payloads. `allowed` names
+ * fields the provider documents for that route (e.g. `cachedContent` via the host
+ * `extra.cachedContent` escape hatch on Gemini).
+ */
+export declare function assertNoForeignCacheFields(body: unknown, allowed?: readonly string[]): void;
+/** Provider construction and setup must perform zero network calls; discovery and streams are caller-gated. */
+export declare function assertNoFetches(calls: readonly unknown[]): void;
 export declare function assertUsageAccounting(events: readonly ProviderEvent[], expected: Usage): Usage;

package/dist/testing/provider-conformance.js

@@ -1,4 +1,5 @@
 import { reconstructToolCallDeltas } from "../provider-events.js";
+import { canonicalizeJsonSchema } from "../providers/schema.js";
 export async function collectProviderEvents(provider, request) {
     const events = [];
     for await (const event of provider.generate(request))
@@ -63,6 +64,12 @@ export function assertSerializedRequestCoversContent(request, body, options = {}
         }
     }
 }
+export function assertCanonicalToolParameters(serialized, original) {
+    const expected = canonicalizeJsonSchema(original ?? { type: "object" });
+    if (JSON.stringify(serialized) !== JSON.stringify(expected)) {
+        throw new Error("Tool parameters were not canonicalized");
+    }
+}
 export function assertProviderOwnedHeadersWin(captured, options) {
     const ownedLower = {};
     for (const [name, expected] of Object.entries(options.owned))
@@ -89,6 +96,36 @@ export function assertNoSecretLeak(events, secrets) {
             throw new Error(`Secret leaked into provider events: ${secret.slice(0, 8)}...`);
     }
 }
+/** Known cache wire fields across protocols; any of these in a request body is an explicit cache control. */
+const CACHE_WIRE_FIELDS = [
+    "cache_control",
+    "prompt_cache_key",
+    "prompt_cache_retention",
+    "prompt_cache_options",
+    "prompt_cache_breakpoint",
+    "cachedContent",
+    "cachePoint",
+];
+/**
+ * Implicit/none-cache providers must serialize no foreign cache fields: implicit
+ * caching works by byte-stable prefix reuse, not request payloads. `allowed` names
+ * fields the provider documents for that route (e.g. `cachedContent` via the host
+ * `extra.cachedContent` escape hatch on Gemini).
+ */
+export function assertNoForeignCacheFields(body, allowed = []) {
+    const bodyText = JSON.stringify(body);
+    for (const field of CACHE_WIRE_FIELDS) {
+        if (allowed.includes(field))
+            continue;
+        if (bodyText.includes(field))
+            throw new Error(`Serialized request carries foreign cache field "${field}"`);
+    }
+}
+/** Provider construction and setup must perform zero network calls; discovery and streams are caller-gated. */
+export function assertNoFetches(calls) {
+    if (calls.length > 0)
+        throw new Error(`Provider fetched ${calls.length} time(s) outside caller-gated discovery/stream`);
+}
 export function assertUsageAccounting(events, expected) {
     const usage = [...events].reverse().find((event) => (event.type === "done" && event.usage) || event.type === "usage");
     const actual = usage?.type === "usage" ? usage.usage : usage?.usage;

package/dist/trim-trailing-slashes.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Trims trailing "/" characters with a linear index scan.
+ *
+ * Shared replacement for `value.replace(/\/+$/, "")` (CodeQL js/polynomial-redos):
+ * no regex is evaluated, so hostile long inputs cannot backtrack. Semantics are
+ * identical — only trailing "/" characters (U+002F) are removed; "" and "/" stay "".
+ */
+export declare function trimTrailingSlashes(value: string): string;

package/dist/trim-trailing-slashes.js

@@ -0,0 +1,14 @@
+/**
+ * Trims trailing "/" characters with a linear index scan.
+ *
+ * Shared replacement for `value.replace(/\/+$/, "")` (CodeQL js/polynomial-redos):
+ * no regex is evaluated, so hostile long inputs cannot backtrack. Semantics are
+ * identical — only trailing "/" characters (U+002F) are removed; "" and "/" stay "".
+ */
+export function trimTrailingSlashes(value) {
+    let end = value.length;
+    while (end > 0 && value.charCodeAt(end - 1) === 47)
+        end -= 1;
+    return value.slice(0, end);
+}
+//# sourceMappingURL=trim-trailing-slashes.js.map

package/docs/0.1.0-readiness.md

@@ -1,6 +1,6 @@
 # 0.1.0 / 1.0 Readiness Gates
 
-Status: **0.2.8** is the current release line (the 0.2.x review-remediation line: fail-closed runtime/sandbox security, provider completion and outbound trust boundaries, concurrent-state/durability integrity, build/coverage/release-evidence integrity, package/documentation/compatibility truth, maintainability and bounded performance, fully featured coding-agent readiness, enterprise ERP production readiness, ACP adoption fixes); **0.1.7** was the terminal 0.1.x baseline; **1.0** readiness remains operator-gated, not automatic.
+Status: **0.3.0** is the current release line (the final 0.3.x lockstep cut: Linux desktop wrapper, coding/ACP closeouts, and independent package versions with Decision B `^0.3.0` ranges); **0.1.7** was the terminal 0.1.x baseline; **1.0** readiness remains operator-gated, not automatic.
 
 This page distills runnable readiness gates into one command-per-gate table.
 The **Last evidence** column records the 0.1.0-tree snapshot (plan 012 Tasks
@@ -20,16 +20,16 @@ Historical release lines (0.0.16 floor → 0.0.27 Phase 10 ACP interop → 0.1.0
 keep their per-phase evidence in the pages above; this page records the 0.2.6
 snapshot (plan 026) with the 0.1.x tables below as the historical record.
 
-## Current line (0.2.9)
+## Current line (0.3.1)
 
 | Item | Status |
 |---|---|
-| Published graph | **55** publishable manifests at exact **0.2.9** (root + 54 workspace packages: 17 provider adapters + 10 `prism-*` family/profile + 27 capability; generated by `node scripts/package-truth.mjs` → `scripts/package-truth.json`) |
-| Current-line cut | The 0.2.x review-remediation line, additive-only vs the frozen 0.1.x contract: 0.2.0 fail-closed runtime/sandbox, 0.2.1 trust boundaries, 0.2.2 concurrent-state, 0.2.3 evidence integrity, 0.2.4 package truth, 0.2.5 maintainability, 0.2.6 coding-agent readiness, 0.2.7 ERP, 0.2.8 ACP adoption fixes, plus 0.2.9 provider adoption (DeepSeek / xAI SuperGrok OAuth / ClinePass), `@arnilo/prism-impeccable`, Ponytail 4.9.0, Caveman v2.1 extras |
-| Upgrade path | `docs/migration.md` `0.2.8 → 0.2.9` (additive; no store migration; rollback = restore 0.2.8 manifests/tag); store-compatible throughout 0.2.x |
-| Compat promise | Additive-only vs the frozen 0.1.x contract; `scripts/compat-baseline` regenerated at 0.2.9 (version literal + additive provider/OAuth/impeccable exports), zero breaking deltas |
-| Security policy | `npm audit --audit-level=moderate` 0 at 0.2.9; threat-suites legs (phase8–11 + phase20–26) green; SuperGrok live login `PRISM_LIVE_XAI_OAUTH` is protected, never a silent pass |
-| Docs freeze | tripwires green including the canonical manifest-count tripwire (50/49/14/9/26), the plan 024 package-truth tests (generator reproducibility + artifact equality + closure asserts + derived docs truth), the plan 025 bounded-accumulation near-limit probe, and the plan 026 freeze tripwires (per-task markers, threat T1–T8 test mapping, exit gate green) |
+| Release graph | **56** publishable manifests at exact **0.3.0** (root + 55 workspace packages: 17 provider adapters + 10 `prism-*` family/profile + 28 capability; generated by `node scripts/package-truth.mjs` → `scripts/package-truth.json`; npm publication remains the operator handoff) |
+| Current-line cut | The 0.3.x line starts with the final lockstep cut: optional host-owned Linux desktop control, coding/ACP tool closeouts, and independent package publication after the cut; live canaries and delegated agents remain later demand-gated work |
+| Upgrade path | `docs/migration.md` `0.2.9 → 0.3.0` (additive; no store migration; rollback = restore 0.2.9 manifests/tag); internal first-party ranges become `^0.3.0` |
+| Compat promise | Additive-only vs the frozen 0.2.9 baseline; package peers use Decision B's `^0.3.0` caret window and `scripts/compat-baseline` remains the reviewed declaration gate |
+| Security policy | `npm audit --audit-level=moderate` 0 target at 0.3.0; desktop admission remains deny-by-default, mutators require approval + `ExecutionPolicy`, and package tags publish only changed packages |
+| Docs freeze | tripwires green including the 56-package truth graph, Decision B range policy, the plan 030 freeze/release tests, coding/ACP tool regressions, and the host-owned desktop wrapper's fail-closed package/docs gates |
 | 0.1.x line | **0.1.7** (plan 019) is the terminal 0.1.x baseline; the 0.1.1 table below keeps the plan 013 snapshot; the 0.1.0 table keeps the plan 012 snapshot; the **0.0.16** values remain the historical network-free floor |
 
 ## Previous line (0.1.1)

package/docs/acp.md

@@ -46,7 +46,7 @@ In-stream `SessionUpdate`s:
 | Assistant text | `agent_message_chunk` |
 | Assistant thinking | `agent_thought_chunk` (same `messageId` scheme as text; through the shared redactor and byte caps) |
 | Tool lifecycle | `tool_call` / `tool_call_update` (title/status/content) — `tool_call.kind` comes from the session's tool registry `kind` metadata when present (B4), else the name heuristic |
-| Tool result, projected | `tool_call_update` with `locations` (≤ `acpLocationsPerUpdate`) and/or a `diff` block (≤ `acpDiffBytes`) — only from `AgUiProjection.toolLocations`/`toolDiff` allow-lists, at `finish()`. `toolResult` may return a string (text content) or `{ type: "image", data, mimeType }` (F8) — the mapper wraps the image as `{ type: "content", content: { type: "image", data, mimeType } }` and drops payloads over `acpImageBytes` (never truncated). Opt-in turnkey: `createCodingToolProjection()` (F7) recognizes first-party `edit` (path + unified patch as `newText`, `firstChangedLine` location) and `write` (path location only — result has no file body) results; default remains deny-by-default. |
+| Tool result, projected | `tool_call_update` with `locations` (≤ `acpLocationsPerUpdate`) and/or a `diff` block (≤ `acpDiffBytes`) — only from `AgUiProjection.toolLocations`/`toolDiff` allow-lists, at `finish()`. `toolResult` may return a string (text content) or `{ type: "image", data, mimeType }` (F8) — the mapper wraps the image as `{ type: "content", content: { type: "image", data, mimeType } }` and drops payloads over `acpImageBytes` (never truncated). Opt-in turnkey: `createCodingToolProjection()` (F7) recognizes first-party `edit` (path + unified patch as `newText`, `firstChangedLine` location), `write` and `delete` (metadata path locations), and `move` (destination `metadata.to` location) results; moves never emit diffs, and default remains deny-by-default. |
 | Provider usage | `usage_update` (only when the `capabilities.usage.contextWindow` seam reports a valid window — absent/undefined/throw ⇒ the update is omitted, never `size = used`) |
 | Run-level failure | No transcript chunk — the `session/prompt` request rejects with `ERR_PRISM_ACP_RUN` (redacted, byte-capped message). Retryable provider-turn failures stay silent and may recover; only a terminal `error` event fails the request. |
 | Run stop reason | `session/prompt` returns the SDK `StopReason` (F4): `cancelled` when the run was aborted, `max_turn_requests` for the tool-round ceiling (`finishReason: "turn_limit"`), `max_tokens` for `"token_limit"`, `refusal` for `"refusal"`, else `end_turn`. The generic `finishReason` field is set on `agent_finished` by loop strategies (single-shot records `turn_limit` at the `maxToolRounds` ceiling); `token_limit`/`refusal` have no core producer yet — the mapping is ready. |
@@ -112,7 +112,8 @@ const agent = createPrismAcpAgent({
 
 - **Seam = capability.** Wiring `sessions.load` advertises `loadSession`; removing it withdraws the method. There is no separate capability flag to keep in sync — the freeze manifest's advertise-when matrix is enforced by construction and asserted by `scripts/phase10-conformance.test.mjs`.
 - **Transcript replay (F2).** When `sessions.transcript` is wired, `session/load` and `session/resume` replay `user_message_chunk`/`agent_message_chunk` text chunks (from `SessionEntry`s with `kind: "message"` and a user/assistant role, text blocks only) before returning `sessionState`. Each chunk passes the shared redactor and is truncated at `maxTextBytes`; replay stops at `maxReplayEvents` chunks and counts against the stream event/byte caps (an oversized transcript fails the load/resume request closed). Absent seam = no replay, behavior unchanged.
-- **Client fs/terminal are adapters, not a second implementation.** `AcpClientFilesystem` / `AcpClientTerminals` wrap the client's `fs/*` and `terminal/*` methods behind the Phase 9 `ProcessSession`-flavored interfaces; the agent pre-generates the session id so terminal requests can carry it. Host repo operations remain default when the client fs is absent.
+- **Client fs/terminal are adapters, not a second implementation.** `AcpClientFilesystem` / `AcpClientTerminals` wrap the client's `fs/*` and `terminal/*` methods behind the Phase 9 `ProcessSession`-flavored interfaces; the agent pre-generates the session id so terminal requests can carry it. `createAcpFilesystemOperations` from `@arnilo/prism-coding-agent` maps that filesystem seam onto the coding tools' `read`/`write`/`edit` operations. This editor-buffer mode is intentionally hybrid: `repo_list`, `repo_search`, `glob`, `delete`, and `move` remain disk-backed unless the host supplies separate operations; binary/image/document handling never falls back to local disk. Host repo operations remain default when the client fs is absent.
+- **Spawnable ACP coding registry (Task 6).** `@arnilo/prism-acp-agent` wires `createAcpClientFilesystem` and creates a separate coding tool registry per ACP session when the client advertises `fs/read_text_file` or `fs/write_text_file`. That session's `read`/`write`/`edit` operations use editor buffers; without fs advertisement, the existing disk registry is used. `shell`, repository search/list/glob, `delete`, and `move` remain disk-backed in this hybrid mode. Durable approvals resolve the same per-session agent, so one session cannot resume through another session's buffer adapter.
 - **Modes and config options are a pure host overlay.** The agent stores only a thin per-session registry; `apply`/`onChange` hooks narrow the host's own behavior. Mode switches can narrow or host-authorized widen — never a parallel policy evaluator, never a client-enabled tool.
 - **Lifecycle wiring.** Pass your `createCodingLifecycleEmitter()` as `coding.lifecycle`; `file_changed` etc. then flow to streaming sessions. `configuration_changed` broadcasts `config_option_update` (agent-message fallback if the SDK rejects the kind).
 - **Stream budgets.** Every lifecycle update counts against the same per-run stream event/byte budget as prompt updates; overflowing closes the update, never the run.
@@ -151,7 +152,7 @@ const agent = createPrismAcpAgent({
 - **Deny-closed by default.** Unknown mode ids, unadvertised methods, unprojected lifecycle events, oversize diffs/locations/media, thrown projection hooks, and failed elicitation all fail closed. Raw tool arguments/results are never sent unless a projection allow-list says otherwise.
 - **Slash commands (F9).** `commands.list` is a host-owned slash-command list (not derived from the tool registry). The agent emits `available_commands_update` on session start (`session/new`, `session/load`, `session/resume`). Mid-session refresh is not in this release — re-list by starting a session. Names, descriptions, and input hints pass the shared redactor; the list is sliced at `acpCommandsPerUpdate`. Absent seam or a thrown list ⇒ no update.
 - **Projected images (F8).** `AgUiProjection.toolResult` may return `{ type: "image", data, mimeType }` (return-type widening — existing string returns stay valid). The mapper emits `{ type: "content", content: { type: "image", data, mimeType } }` (SDK v1 `ToolCallContent` has no top-level image variant). `data` is the host-supplied base64; it is not redacted and not truncated — payloads over `acpImageBytes` are dropped. Default (no hook / non-image return) emits no image.
-- **Coding-tool projection (F7).** `createCodingToolProjection({ maxDiffBytes? })` is an opt-in `AgUiProjection` for first-party `@arnilo/prism-coding-agent` `edit`/`write` results: `edit` → `toolDiff` (`path` + unified `patch` as `newText`) and `toolLocations` (`path` + `firstChangedLine`); `write` → `toolLocations` (`path` only — write metadata has no file body, so no honest diff; use `file_changed` + `fileDiff` when bodies are needed). Pass as `projection: createCodingToolProjection()` on the agent/mapper. Mapper still redacts and enforces `acpDiffBytes` / `acpLocationsPerUpdate`; optional `maxDiffBytes` pre-truncates the patch so a slightly-oversize edit is shortened instead of dropped. Without the factory, behavior is unchanged (deny-by-default).
+- **Coding-tool projection (F7).** `createCodingToolProjection({ maxDiffBytes? })` is an opt-in `AgUiProjection` for first-party `@arnilo/prism-coding-agent` results: `edit` → `toolDiff` (`path` + unified `patch` as `newText`) and `toolLocations` (`path` + `firstChangedLine`); `write` and `delete` → `toolLocations` (`path` only); `move` → destination `toolLocations` (`metadata.to`, with `from` fallback). No delete/move diff is fabricated. Pass as `projection: createCodingToolProjection()` on the agent/mapper. Mapper still redacts and enforces `acpDiffBytes` / `acpLocationsPerUpdate`; optional `maxDiffBytes` pre-truncates the patch so a slightly-oversize edit is shortened instead of dropped. Without the factory, behavior is unchanged (deny-by-default).
 - **No secrets.** Updates carry no raw file bodies, terminal output is capped by the Phase 9 chunk budget, and the shared redactor is applied before anything leaves the host. `permission_denied` never includes raw args.
 - **Performance.** The adapter is O(1) per update with no unbounded buffering; p95 targets (fs round trip 250 ms, mode switch 250 ms, terminal chunk ack 1000 ms, prompt first update 2000 ms, prompt end 30 s) are recorded by `scripts/benchmark-0.0.27.mjs` and gated in `scripts/budgets.json` `phase10`.
 
@@ -163,3 +164,4 @@ const agent = createPrismAcpAgent({
 - [Host security guide](host-security.md): fail-closed checklist rows for ACP boundaries (authorize, ownership, redaction, untrusted MCP).
 - [Migration guide](migration.md): 0.0.26 → 0.0.27 advertise/surface changes for hosts that parsed the old `initialize`.
 - [AG-UI adoption evaluation](ag-ui-adoption.md): the underlying input/event/capability matrix.
+- [Obscura browser engine](obscura.md): optional binary-backed generic tools behind the session prompt loop.

package/docs/ag-ui.md

@@ -44,7 +44,9 @@ The handler accepts only `POST` JSON validated with official AG-UI `RunAgentInpu
 
 ## Outputs / response / events
 
-The handler returns `text/event-stream`, one `data: <AG-UI event>\n\n` frame per output. Mapper lifecycle is ordered: `RUN_*`, `STEP_*`, `TEXT_MESSAGE_*`, and `TOOL_CALL_*` are deterministic Prism mappings. Host projectors may additionally prove and emit `STATE_SNAPSHOT`/`STATE_DELTA`, `MESSAGES_SNAPSHOT`, `ACTIVITY_*`, current `REASONING_*`, `RAW`, and named `CUSTOM` values. All values revalidate against official `EventSchemas`; deprecated `THINKING_*` and convenience chunk events are not produced. Active message/tool/reasoning/step sequences close before error, interruption, or finish.
+The handler returns `text/event-stream`, one `data: <AG-UI event>\n\n` frame per output. Mapper lifecycle is ordered: `RUN_*`, `STEP_*`, `TEXT_MESSAGE_*`, and `TOOL_CALL_*` are deterministic Prism mappings. Host projectors may additionally prove and emit `STATE_SNAPSHOT`/`STATE_DELTA`, `MESSAGES_SNAPSHOT`, `ACTIVITY_*`, current `REASONING_*`, `RAW`, and named `CUSTOM` values.
+
+`delegated_agent_step` maps by default to bounded `ACTIVITY_SNAPSHOT` metadata with activity type `prism.delegated_agent_step`; `includeCustomEvents: true` also emits `CUSTOM prism.delegated_agent_step`. The safe payload contains adapter/conversation identifiers, step index/state/kind, duration, token counts, tool/subagent names, and opaque detail references only. Normal assistant text remains `TEXT_MESSAGE_*`; delegated events never duplicate transcript text. Raw event bodies, tool arguments/results, paths, URIs, logs, and hidden thought text remain absent unless a host explicitly supplies a projection. All values revalidate against official `EventSchemas`; deprecated `THINKING_*` and convenience chunk events are not produced. Active message/tool/reasoning/step sequences close before error, interruption, or finish.
 
 A Prism durable `agent_suspended` returns `RUN_FINISHED` with core interrupt id `${runId}:${version}` and a strict `{ decision: "approve" | "deny" }` schema. `projection.interrupt` may attach bounded expiry/metadata or additional host policy interrupts but must retain that core id. Without `interrupts.resume`, one exact entry is required; `cancelled` means deny. An aggregate policy may validate bounded multiple entries, then returns one current-version core decision. Payloads containing `editedArgs`/`args` always deny: Prism does not mutate persisted tool calls. The adapter checks host authorization, selected run, suspended status, and checkpoint version, then calls `AgentRunLifecycle.resumeStream()` once. Claimed/dispatched tools are never replayed.
 
@@ -122,7 +124,7 @@ See runnable network-free [`examples/ag-ui-server.ts`](../examples/ag-ui-server.
 
 All identity, authorization, session/thread mapping, durable checkpoint lookup, persistence selection, replay cursor persistence, transport adaptation, MCP bridge/card configuration, app sandbox DOM, remote A2A task correlation, and optional projection are host-owned. The adapter owns no listener, database, background reconnect loop, credential resolver, or UI state.
 
-`AgUiProjection` is an allow-list. Without a callback, raw tool arguments/results/progress, arbitrary state/patches/transcripts/activity/reasoning/raw events, paths, ACP locations/diffs/terminals/raw I/O, and frontend-supplied tools remain absent. Reasoning signatures do not become AG-UI encrypted values automatically: a host must explicitly provide an already client-encrypted opaque value. `input.project` is also an allow-list: do not merge client state/forwarded props into ownership, identity, tools, permissions, provider options, or media fetch policy.
+`AgUiProjection` is an allow-list. Without a callback, raw tool arguments/results/progress, arbitrary state/patches/transcripts/activity/reasoning/raw events, delegated raw event bodies, paths, ACP locations/diffs/terminals/raw I/O, and frontend-supplied tools remain absent. Reasoning signatures do not become AG-UI encrypted values automatically: a host must explicitly provide an already client-encrypted opaque value. `input.project` is also an allow-list: do not merge client state/forwarded props into ownership, identity, tools, permissions, provider options, or media fetch policy.
 
 ### Reasoning encrypted-value helper (FR-3)
 
@@ -219,7 +221,9 @@ Defaults / hard caps: request 64 KiB / 1 MiB; input 128 / 1024 messages, 32 / 25
 - [A2A interoperability](a2a.md): remote agent-to-agent tasks, not frontend protocol mapping.
 - [AG-UI adoption evaluation](ag-ui-adoption.md): official 0.0.57 event/input matrix and shipped explicit MCP/MCP Apps/A2A handshakes.
 - [ACP coding-host interop](acp.md): the full ACP reference — seam-based capability advertisement, session modes/config, MCP select, fs/terminal adapters, lifecycle mapping, elicitation, and caps.
+- [Obscura browser engine](obscura.md): optional binary-backed generic tools selectable through the MCP adapter.
 - [MCP bridge/server](mcp-tools.md): `mcpApps` negotiation, bounded resources, and remote tool trust.
 - [A2A interoperability](a2a.md): verified rich task client and remote task lifecycle.
 - [Host security guide](host-security.md): authorization, ownership, redaction, and credential boundaries.
+- [Antigravity delegated agent](antigravity-agent.md): delegated Antigravity CLI execution with timeline step projection.
 - [Work artifacts and review](work-artifacts-and-review.md): durable artifact service that produces the co-work approval/progress/download-link events projected here.

package/docs/agent-events.md

@@ -2,7 +2,7 @@
 
 ## What it does
 
-`AgentEvent` is the single observable stream every `AgentSession` run emits. Subscribers receive normalized, redacted, in-order events covering agent lifecycle, assistant message streaming, tool execution, queue updates, subscriber overflow, compaction, retry, artifact validation/refinement, and terminal errors. The stream is in-memory, live-only, and bounded per subscriber by `SubscribeOptions`; there is no durable queue, no background work, and no extra dependency.
+`AgentEvent` is the single observable stream every `AgentSession` run emits. Subscribers receive normalized, redacted, in-order events covering agent lifecycle, assistant message streaming, delegated-agent activity, tool execution, queue updates, subscriber overflow, compaction, retry, artifact validation/refinement, and terminal errors. The stream is in-memory, live-only, and bounded per subscriber by `SubscribeOptions`; there is no durable queue, no background work, and no extra dependency.
 
 Events are emitted by the runtime and by loops through `LoopContext.emit`, both of which route through `redactAgentEvent(event, activeRedactor)` so every payload is secret-redacted before subscribers observe it.
 
@@ -56,6 +56,7 @@ const subscription = session.subscribe({ maxQueuedEvents: 256, overflow: "close"
 for await (const event of subscription) {
   switch (event.type) {
     case "message_delta": // append event.content
+    case "delegated_agent_step": // render bounded external activity
     case "tool_execution_started": // …
     case "artifact_failed": // budget exhausted
       break;
@@ -71,6 +72,7 @@ The `AgentEvent` union (grouped by concern):
 | Turns | `turn_started`, `turn_finished` |
 | Provider turns | `provider_turn_started`, `provider_turn_finished` |
 | Assistant messages | `message_started`, `message_delta`, `message_finished` |
+| Delegated agents | `delegated_agent_step` |
 | 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`, `steer_rejected` |
@@ -95,6 +97,11 @@ Agent / turn / message events:
 | `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) |
+| `delegated_agent_step` | `sessionId`, `runId`, `adapterId`, `externalConversationId` (≤512 UTF-8 bytes), `stepIndex`, `state`, `kind`, optional `durationMs`, token-only `usage`, `toolName`, `subagentType`, and opaque `detail` references |
+
+`delegated_agent_step` is a safe timeline event for an adapter-owned loop. `kind` is one of `assistant`, `tool`, `subagent`, `checkpoint`, or `unknown`; unknown external step kinds normalize to `unknown`. It never carries raw arguments, results, paths, URIs, logs, event bodies, or hidden thought text. `thinkingTokens` is a count only. The constructor and existing event-source default cap keep serialized events at 64 KiB.
+
+Adapters should call `createDelegatedAgentStep({ sessionId, runId, adapterId, externalConversationId, stepIndex, state, kind, usage })` rather than forwarding external JSON. The constructor allow-lists fields and fails closed on malformed or oversized identifiers/counters.
 
 `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.
 

package/docs/agent-loops.md

@@ -128,6 +128,8 @@ Optional steer hooks on `LoopContext` (0.0.11): `hasPendingSteers?()` / `applyPe
 
 The snapshot is stored as `loopState: { name, revision, snapshot }` on the durable run state and cleared when the run reaches a terminal status. On resume, a name/revision mismatch between the stored `loopState` and the resolved strategy fails closed (`ERR_PRISM_LOOP_REVISION`), and the fingerprint check independently rejects any loop drift. 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()`.
 
+A strategy returned by `generateValidateReviseLoop()` is safe to reuse across sequential runs. Its built-in state is scoped to `(sessionId, runId)`; a new non-restored run resets attempts, artifact phase, saved schema, and pending repair messages, while a restored run keeps the checkpointed state. Arbitrary custom strategies are not cloned or reset automatically.
+
 ## 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.
@@ -231,6 +233,7 @@ await session.run(input, { loop: twoShotLoop });
 - `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 `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.
+- In a parallel single-shot batch, the worker pool stops claiming calls after the first dispatch error or abort, waits for every already-claimed worker with `Promise.allSettled`, appends no buffered tool-result rows for a failed batch, then rethrows the first failure. Already-claimed side effects may finish and are not rolled back; successful batches still append results in original call order. The round-level `chargeToolRound` approval gate runs before workers, so approval suspension starts no worker.
 - 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 host-domain-free boundary is guarded by tests: `src/` imports no host-domain 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/agent-session-runtime.md

@@ -221,6 +221,7 @@ Per-run options may narrow `limits` and append `guardrails`; they cannot replace
 - [Session stores and branching](session-stores-and-branching.md): `SessionStore`, memory store, branch helpers, and context rebuild.
 - [Compaction and retry policies](compaction-and-retry.md): compaction strategy/config APIs used by `session.compact()` and auto-compaction, plus retry policy/config APIs.
 - [Tools](tools.md): host-owned tool harness used by the bounded runtime tool loop.
+- [Obscura browser engine](obscura.md): optional binary-backed tool array that composes into `createAgent({ tools })` with no host branch.
 - [Middleware hooks](middleware-hooks.md): hooks that configured assembly/runtime can run.
 - [CLI/RPC](cli-rpc.md): terminal and JSONL adapters over this runtime.
 - [Workflows](workflows.md): optional DAG orchestration that calls `AgentSession.run()` for agent nodes.