@arnilo/prism 0.3.0 → 0.3.2

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/rpc.d.ts

@@ -1,5 +1,5 @@
 import type { Readable, Writable } from "node:stream";
-import type { AgentSession, CommandDefinition, InstructionInjector } from "./contracts.js";
+import type { AgentSession, CommandDefinition, CommandDrivers, InstructionInjector } from "./contracts.js";
 import type { ContributionRegistry } from "./contributions.js";
 export type RpcCommandName = "prompt" | "steer" | "followUp" | "abort" | "state" | "messages" | "setModel" | "compact" | "switchSession" | "forkSession" | "cloneSession" | "checkout" | "command";
 export interface RpcRequest {
@@ -10,6 +10,9 @@ export interface RpcRequest {
 export interface RpcSessionFactory {
     createSession(id?: string): AgentSession;
     readonly commands?: readonly CommandDefinition[];
+    /** Host-opt-in driver capabilities forwarded to contributed commands on the
+     *  `command` execution context. Absent ⇒ context shape unchanged. */
+    readonly drivers?: CommandDrivers;
     /** Optional registry for resolving `instructionInjectors` names in `prompt`/`followUp`
      *  params (Phase 30). Names resolve fail-closed. */
     readonly instructionInjectors?: ContributionRegistry<InstructionInjector>;

package/dist/rpc.js

@@ -9,6 +9,7 @@ export async function runRpcServer(options) {
         sessions: new Map([[first.id, first]]),
         commands: new Map((options.commands ?? []).map((command) => [command.name, command])),
         createSession: options.createSession,
+        ...(options.drivers ? { drivers: options.drivers } : {}),
         ...(options.instructionInjectors ? { instructionInjectors: options.instructionInjectors } : {}),
     };
     const activeRuns = new Map();
@@ -181,7 +182,10 @@ async function handleRequest(request, state, stdout, activeRuns) {
             if (!command)
                 throw new Error(`Unknown command: ${name}`);
             const args = objectParam(request.params, "args") ?? {};
-            const result = await command.execute(args, { sessionId: state.current.id });
+            const result = await command.execute(args, 
+            // FEATURE-3 (plan 050 Task 5): host-opt-in drivers forwarded verbatim; the
+            // context carries no `drivers` key when the host supplied none.
+            state.drivers ? { sessionId: state.current.id, drivers: state.drivers } : { sessionId: state.current.id });
             write(stdout, { id: request.id, ok: true, result });
             break;
         }

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

@@ -20,7 +20,7 @@ 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.3.0)
+## Current line (0.3.2)
 
 | Item | Status |
 |---|---|

package/docs/acp.md

@@ -164,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

@@ -221,6 +221,7 @@ 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.

package/docs/agent-definitions.md

@@ -27,7 +27,7 @@ Do not use the bundle loader to discover providers — provider/model packages s
 | --- | --- |
 | `name` | Required agent name. |
 | `description?` | Optional description. |
-| `model?` | `ModelConfig` object, or a `"<provider>/<model>"` string resolved through `registries.models`. |
+| `model?` | `ModelConfig` object, or a `"<provider>/<model>"` string resolved through `registries.models`. Optional at authoring time: when omitted, resolution falls back to `context.overrides.model` (host-injected selection); an explicit definition `model` drives registry resolution, and neither present fails closed with `Agent "<name>" has no model`. |
 | `tools?` | Tool names to activate from the active tool registry / `registries.tools`. Omitted means no active tools unless `activateAllCapabilities: true` is passed for migration. |
 | `skills?` | Skill names resolved via `resolveActiveSkills()`; omitted means no active skills unless `activateAllCapabilities: true` is passed for migration. `toolNames` enforcement applies at activation. |
 | `context?` | Context provider names from `registries.contextProviders`. |

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.

package/docs/browser-automation.md

@@ -122,6 +122,7 @@ Default tests use fake Playwright APIs only. Protected live gate: `PRISM_LIVE_PL
 
 ## Related APIs
 
+- [Obscura browser engine](obscura.md): optional host-installed Obscura headless browser connected with `chromium.connectOverCDP` through `connectObscuraCdp` — its returned browser plugs directly into `createBrowserTools`/`createBrowserManager` as the host-supplied Playwright browser; pages on one Obscura worker share one V8 isolate, and screenshots/PDF need a render-enabled build.
 - [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.

package/docs/coding-agent-tools.md

@@ -417,6 +417,12 @@ Opt-in `ask_user_decision` for ambiguous, high-impact direction choices. Model m
 | Agent durable adapter | `validateAskUserDecisionAgentResume({ request, answer })` — same validation; **no** new `AgentRunInterruption` kinds in 0.0.11 |
 
 Custom-text caps match question defaults (2 KiB / hard 8 KiB). Options default max 6 (hard 16).
+`allowCustom` defaults to `false` on **both** paths when omitted — the tool
+path (`parseAllowCustom`) and the workflow suspend path
+(`toAskUserDecisionSuspendData`) normalize at accept time, so the persisted
+suspension always carries a boolean and survives JSON checkpoint round-trips;
+a non-boolean value throws `allowCustom must be a boolean` at accept time,
+never at resume time.
 
 ```ts
 import { createToolRegistry } from "@arnilo/prism";
@@ -440,7 +446,7 @@ return suspendAskUserDecision({
   question: "Ship sqlite or postgres?",
   options: [/* ≥2 with 3 pros + 3 cons each */],
   selectionMode: "single",
-  allowCustom: false,
+  // allowCustom optional — defaults to false (tool-path parity)
 });
 // resumeWorkflow(..., { validateResume: createAskUserDecisionResumeValidator() })
 ```

package/docs/compaction-and-retry.md

@@ -93,6 +93,8 @@ createDefaultRetryPolicy(options?: DefaultRetryPolicyOptions): RetryPolicy
 
 `session.compact(options?)` emits `compaction_started`, runs the strategy on the current branch, runs `middleware.run("compaction", { context, result })` when middleware is configured, appends one standard `kind: "compaction"` entry under the current leaf, emits `compaction_finished`, and returns the appended result. Manual compaction rejects while a run is active.
 
+> **Contract — compact at the task boundary.** `session.compact()` throws `Error("Agent session already has an active run")` while `run()`/`stream()` is in flight. Intended model: one `run()` per task, then compact. Do not design mid-run compaction. Auto-compaction (when `thresholdEntries` is set) already runs **before** provider input, not during the turn. Live demo: [`examples/autonomous-coding-loop.ts`](../examples/autonomous-coding-loop.ts) (`compact` node after execute/validate/gate).
+
 Auto-compaction checks at most once per `run()`, after input/model-change entries are appended and before provider input assembly. It runs only when `AgentConfig.compaction` or `RunOptions.compaction` supplies `thresholdEntries`, and it is skipped by `RunOptions.compaction: false`.
 
 `rebuildSessionContext()` detects the latest compaction entry on a branch. Its returned `entries` still contains the raw full branch, while `messages` contains only messages after the compaction boundary plus `keepEntryIds`, and `summaries` contains the compaction summary plus later summary entries.
@@ -170,6 +172,7 @@ The default strategy does not call a provider. Hosts that need model-generated s
 - [Session stores and branching](session-stores-and-branching.md): branch entries, compaction entries, and `rebuildSessionContext()` behavior.
 - [Input and prompt assembly](input-and-prompt-assembly.md): compacted summaries become default summary messages for provider input.
 - [Agent/session runtime](agent-session-runtime.md): `session.compact()`, opt-in auto-compaction, `RunOptions.retry`, and `retry_scheduled` runtime behavior.
+- Example: [`examples/autonomous-coding-loop.ts`](../examples/autonomous-coding-loop.ts) — task-boundary compact after each iteration.
 - [Middleware hooks](middleware-hooks.md): `compaction` and `retry` middleware payload timing.
 - [Contribution registries](contribution-registries.md): compaction strategy and retry policy contributions.
 - [Configuration and manifests](configuration-and-manifests.md): `compactionStrategy` and `retryPolicy` manifest contribution kinds.

package/docs/compaction-observational-memory.md

@@ -166,6 +166,52 @@ The runtime requires host-supplied `session`, an `appendEntry` callback bound to
 
 `createObservationalMemoryExtension()` registers only inert contributions. It does not start workers, compact sessions, read settings, resolve credentials, call providers, or execute tools/commands during setup.
 
+## Cross-session / delegation-tree recall (opt-in pattern)
+
+Default is per-session: `attach()` + `appendEntry` bind one store/branch, and `recallObservationalMemory(entries, id)` / `createRecallMemoryTool({ getEntries })` see only the entries the host passes for that session. Supervisor children therefore produce observations the parent cannot recall. That is acceptable for v1 — the parent transcript already contains `delegate()` results, so parent OM covers milestones. There is no package primitive for a shared workspace scope (a namespaced multi-tenant store key is out of scope).
+
+Hosts that need parent recall of child *source* work compose it themselves: wrap the shared `SessionStore.append` so eligible child messages (`isEligibleObservationSourceEntry`) are copied onto a workspace (or parent) session with a **new entry id** and that session's `sessionId`/`parentId`. Parent OM then observes those copies and mints **new** observation ids. Child OM, if attached, stays on the child session with its own ids.
+
+```ts
+import { createId, type SessionStore } from "@arnilo/prism";
+import { isEligibleObservationSourceEntry } from "@arnilo/prism-compaction-observational-memory";
+
+function funnelChildMessagesToWorkspace(store: SessionStore, workspaceSessionId: string): SessionStore {
+  return {
+    async append(entry, options) {
+      await store.append(entry, options);
+      if (entry.sessionId === workspaceSessionId) return;
+      if (!isEligibleObservationSourceEntry(entry)) return;
+      const leaf = (await store.list(workspaceSessionId)).at(-1);
+      await store.append({
+        ...entry,
+        id: createId("entry"),
+        sessionId: workspaceSessionId,
+        parentId: leaf?.id,
+      });
+    },
+    list: (sessionId) => store.list(sessionId),
+    get: (id) => store.get?.(id) ?? Promise.resolve(undefined),
+    searchSessions: (query) => store.searchSessions?.(query) ?? Promise.reject(new Error("searchSessions unsupported")),
+    readBranchPath: store.readBranchPath?.bind(store),
+  };
+}
+```
+
+Wire the wrapped store into both the parent session and each supervisor child factory (`createAgent({ store })`). Parent `attach({ appendEntry: (entry, options) => store.append(entry, options) })` and `createRecallMemoryTool({ getEntries: () => parentSession.entries() })` then see funneled child messages plus parent-minted observations. Recreate the parent session with the store `leafId` after a restart so the workspace branch is the one that received the copies. [`examples/autonomous-coding-loop.ts`](../examples/autonomous-coding-loop.ts) shows parent OM attach/compact/recall in the supervisor loop; it records child outcomes on the parent session (same recall, no extra store wrap).
+
+Rules that keep exact-id recall unambiguous:
+
+- Recall always takes **one** branch (`session.entries()` / `getEntries(sessionId)`). Never concatenate parent + child lists into one `recallObservationalMemory()` call.
+- Copies mint a new `entry.id`. `createMemorySessionStore` rejects duplicate ids globally; JSONL/DB adapters do too.
+- Do **not** rewrite the child's OM `appendEntry` onto the workspace session. After each memory append the runtime checks the entry is visible at the **child** leaf and fails closed on a session/store mismatch. Funnel messages; let parent OM observe them.
+- Do **not** copy `om.*` custom entries across. Their `sourceEntryIds` point at the origin session and would dangle on the workspace branch.
+- Serialize funnel copies if concurrent children share the workspace tip (the sketch's `list().at(-1)` is not a lock).
+
+Cost: the workspace branch grows with every funneled child message; parent `compactAfterTokens` / observation-pool caps still apply but fire sooner. Keep the per-session default unless parent recall of child sources is required.
+
+Ownership: funnel only within the `OwnershipScope` already on the parent agent/store. Child factories receive that ownership from the supervisor; do not share a store across tenants or identities. Observations never leave the store the host scoped.
+
 ## Security and performance notes
 
 - Recall is exact-id only; there is no semantic search, vector store, or transcript browser.
@@ -187,6 +233,7 @@ The runtime requires host-supplied `session`, an `appendEntry` callback bound to
 - [Compaction and retry policies](compaction-and-retry.md): replaceable compaction strategy boundary.
 - [LLM compaction package](compaction-llm.md): existing optional compaction-package pattern.
 - [Session stores and branching](session-stores-and-branching.md): branch entries that observational memory reads and appends to.
+- [Supervisor delegation](supervisors.md): child sessions whose messages this page's opt-in funnel can copy onto a workspace branch.
 - [Extensions](extensions.md): inert registration pattern for optional package contributions.
 - [Tools](tools.md): host activation and dispatch for optional recall tool contributions.
 - [CLI/RPC](cli-rpc.md): command contributions through explicitly wired RPC hosts.

package/docs/database-persistence.md

@@ -389,7 +389,7 @@ For document or wide-column stores, map the relational tables above to the store
 - **Branches:** In document stores, a branch can be a lightweight document keyed by `leaf_entry_id` that points to the session and root. Rebuild still walks `parent_id` links in entries.
 - **Retention:** Use TTL columns or scheduled map-reduce/streaming jobs. TTL on `expires_at` or entry timestamps is the simplest NoSQL implementation.
 
-The Node JSONL session store is a single-process development adapter. It has no cross-process locking, no migrations, no retention enforcement, and no tenant isolation. Do not use it as a production multi-writer store.
+The Node JSONL session store is a single-process development adapter. It has no cross-process locking, no migrations, no retention enforcement, and no tenant isolation. Do not use it as a production multi-writer store. Appends serialize per instance; a rejected append (conflict, duplicate, corrupt file) does not poison later appends on that instance. The rejected write is not committed.
 
 ## Request/response example
 

package/docs/extension-authoring.md

@@ -168,6 +168,48 @@ await agent.createSession().run("Use the Acme extension.", { activeSkills: ["acm
 - Middleware from `api.use()` runs only when the host passes `kernel.middleware` into runtime configuration.
 - Provider packages, provider request policies, system prompt contributions, instruction injectors, builders, strategies, commands, store factories, resource loaders, settings providers, and credential resolvers are all inert until host code selects or invokes them.
 
+### Host driver hooks (opt-in)
+
+A contributed command can act — start a session run, start a workflow, steer
+an active run — only when the **host** injects driver capabilities into the
+execution context. Drivers are never package-supplied: a command that wants
+them guards on `context.drivers` and degrades gracefully when the host
+supplies none. Commands stay inert data in hosts without drivers, and the
+context shape is unchanged (no `drivers` key at all).
+
+```ts
+// Host opt-in (e.g. RPC session factory):
+await runRpcServer({
+  stdin,
+  stdout,
+  createSession,
+  commands,
+  drivers: {
+    startRun: (input, options) => session.run(input, options),
+    startWorkflow: (workflow, input, options) => runWorkflow(workflow, input, options),
+    steer: (runId, input) => session.steer(runId, input),
+  },
+});
+
+// Contributed command (host-opt-in capability use):
+registerCommand({
+  name: "acme.start",
+  async execute(args, context) {
+    if (!context.drivers?.startWorkflow) {
+      return { name: "acme.start", error: { message: "host did not supply workflow drivers" } };
+    }
+    const run = await context.drivers.startWorkflow(workflowFor(args), args.input);
+    return { name: "acme.start", value: { runId: run.runId, status: run.status } };
+  },
+});
+```
+
+`CommandDrivers` is typed (`startRun` / `startWorkflow` / `steer`) and exported
+from the core contracts surface. Driver errors surface through the command's
+normal error path — commands map failures to `CommandResult.error`
+(`ErrorInfo`) or let the host error envelope carry them. Driver presence does
+not affect command `metadata.trust` labeling.
+
 ## Security and performance notes
 
 - Prism does not sandbox extension code. Hosts should load only trusted packages or run untrusted packages in their own sandbox/process before calling Prism APIs.

package/docs/graft.md

@@ -0,0 +1,125 @@
+# Graft context-graph integration
+
+## What it does
+
+`@arnilo/prism-graft` is an optional package that wires [nanonets/graft](https://github.com/nanonets/graft) — a repository context-graph CLI (`graft/` directory, INDEX.md orientation, symbol-level wiring graph) — into Prism contribution contracts.
+
+It registers six pull tools backed by the graft CLI (`--json`, argv-safe), a push-mode retrieval-pack context provider plus first-turn orientation injector carried on the `graft` skill, commands (`graft`, `graft-build`, `graft-check`, `graft-viz`), and an edit-watch middleware that computes blast radius after mutating tool calls. Import is inert; a missing graft CLI fails closed at `setup` with a bounded redacted error.
+
+## When to use it
+
+Use it when a host wants agents to locate code by architecture, callers, and coupling before grep-spelunking. Three modes:
+
+- `"pull"` (default) — register the tools; the agent decides when to query.
+- `"push"` — per-turn retrieval pack (pointers only) + first-turn orientation, injected automatically.
+- `"both"` — everything.
+
+Install optional peer `@nanonets/graft@^0.13.0` **or** pass `packageRoot`/`cliPath` explicitly. Pair with progressive disclosure: the `graft` skill body stays small; tool schemas carry the details. Graft complements indexed code search (`repository_search`): graph/semantic locators vs literal search — neither replaces the other.
+
+Zero-code alternative (L0): hosts can skip this package entirely and let agents call `graft <command> --json` through their shell tool, optionally seeding context with graft's own generated instruction files. This package exists for native-tool ergonomics, budgeted subprocesses, session persistence, and push mode.
+
+## Inputs / request
+
+`createGraftExtension(options)`:
+
+| Field | Type | Required | Purpose |
+| --- | --- | --- | --- |
+| `cliPath` / `packageRoot` | `string` | no | Explicit stub/binary or checkout root with a manifest-declared bin; default resolves optional peer `@nanonets/graft`. Relative paths rejected; explicit paths existence-checked at resolve time. |
+| `mode` | `"pull" \| "push" \| "both"` | no | Surface selection. Default `pull`. |
+| `projectDir` | `string` | no | Directory graft operates on. Default `process.cwd()` at setup. |
+| `retrievalBudgetMs` | `number` | no | Wall-clock budget per CLI child call (default 8000). |
+| `maxResultBytes` | `number` | no | Stdout cap before parsing (default 512 KiB). |
+| `maxPromptChars` | `number` | no | Prompts longer than this never become ask argv (default 4096). |
+| `allowUpstreamTelemetry` | `boolean` | no | Default false → children run with `DO_NOT_TRACK=1`. |
+| `providerEnv` | `Record<string, string>` | no | Explicit graft provider settings (`GRAFT_API_KEY`, …). Never inherited from host env; only `GRAFT_*` keys reach the child. |
+| `editToolNames` | `readonly string[]` | no | Tools triggering blast-radius lookup. Default `write`, `edit`, `move`. |
+| `quietStartup`, `hideStatus` | `boolean` | no | Suppress startup status events / status reporting. |
+| `appendEntry` | `(entry, opts?) => Promise<void>` | yes | Host session append (OM attach pattern). |
+| `getEntries` | `() => readonly SessionEntry[] \| Promise<...>` | yes | Current branch entries for state restore. |
+
+Pull tools (mode includes `pull`): `graft_ask`, `graft_grep`, `graft_callers`, `graft_skeleton`, `graft_map`, `graft_blast`.
+
+Push surfaces (mode includes `push`): skill `graft` carrying context provider `graft-context` (per-turn pointers-only pack, gated: ≥12-char prompt, dedup by seen node ids, 32 KiB block ceiling) and instruction injector `graft-orient` (`first_turn`, byte-capped INDEX.md cut + staleness banner).
+
+Registered commands: `graft` (`status` \| `build` \| `check` \| `viz` dispatch), plus `graft-build`, `graft-check`, `graft-viz` aliases.
+
+## Outputs / response / events
+
+| Export | Purpose |
+| --- | --- |
+| `createGraftExtension(options)` | Returns an inert `Extension` until `kernel.load([...])`; emits `graft:loaded` on setup. |
+| `resolveGraftCli(options)` | Fail-closed CLI resolution (`explicit` → command+argv, `peer-bin` → node + manifest bin). |
+| `runGraftJson(cli, argv, options)` / `childEnv(options)` / `childTimeoutMs` / `DEFAULT_MAX_RESULT_BYTES` | Shared budgeted JSON runner for hosts building custom surfaces. |
+| `readBoundedFile` / `redactPaths` / `GraftResolveError` | Bounded-read and redaction helpers. |
+
+Events: `graft:status` (check/build outcomes), `graft:dirty` (post-edit, repo-relative path + optional `staleCountEstimate`), `graft:loaded` (mode + cliKind metadata).
+
+Session custom entry shape (`data.type === "graft-state"`, CAS via `expectedParentId`):
+
+```json
+{ "kind": "custom", "data": { "type": "graft-state", "freshness": { "checkedAt": "...", "fresh": true }, "seen": ["node-a"], "savedTokensApprox": 120 } }
+```
+
+The graph never rebuilds itself mid-session (no auto-rebuild): after edits, ask/grep results may lag one turn; graft self-refreshes on the next indexed query, or run `/graft build` for an immediate refresh. The skill text states this contract to the agent.
+
+## Request/response example
+
+Tool call (pull):
+
+```json
+{ "name": "graft_ask", "arguments": { "query": "where is auth handled?", "count": 3 } }
+→ { "nodes": [{ "id": "auth-guard", "title": "requireAuth", "path": "src/auth.ts", "line": 41 }] }
+```
+
+Status event:
+
+```json
+{ "type": "graft:status", "extension": "@arnilo/prism-graft", "metadata": { "fresh": true, "missing": 0, "stale": 2 } }
+```
+
+## Implementation example
+
+See [`examples/graft-extension.ts`](../examples/graft-extension.ts) — network-free demo against the package fixture stub: one pull-tool call, one push turn with pack injection + dedup, one simulated edit producing blast radius, and the `DO_NOT_TRACK` child-env guard.
+
+```ts
+import { createExtensionKernel, createMemorySessionStore } from "@arnilo/prism";
+import { createGraftExtension } from "@arnilo/prism-graft";
+
+const store = createMemorySessionStore();
+const kernel = createExtensionKernel({ errorPolicy: "throw" });
+await kernel.load([
+  createGraftExtension({
+    packageRoot: "./vendor/graft-checkout",
+    mode: "both",
+    quietStartup: true,
+    appendEntry: async (entry, options) => store.append(entry, options),
+    getEntries: async () => store.list("s1"),
+  }),
+]);
+// Pull: dispatch graft_ask/… tools. Push: runs assemble the skill-carried
+// provider + graft-orient injector. Edits: middleware emits graft:dirty.
+```
+
+## Extension and configuration notes
+
+- Import alone registers nothing (`sideEffects: false`); no timers, watchers, or network. The only child processes are budgeted graft CLI calls.
+- Retrieval happens in-process via Prism primitives (context provider, injector, tool_result middleware) — no external hook shims.
+- Ask result shape is parsed tolerantly (`nodes|results|matches|hits`) because graft is pre-1.0; formatters emit pointers (`title` + `file:line` + `[[wikilink]]`), never source bodies.
+- Not included in `@arnilo/prism-code`, `@arnilo/prism-sdk`, or the `prism-all` umbrella (deliberate opt-out, like Caveman/Ponytail) — opt-in install only.
+- Multi-repo layouts work as upstream graft defines them (workspaces, submodules with `--follow-submodules`, sibling repos); point `projectDir` at the graft root that owns the target repo.
+
+## Security and performance notes
+
+- Telemetry default-off: children always get `DO_NOT_TRACK=1` unless `allowUpstreamTelemetry` is true; child env is fixed-base — host env vars are never inherited, and only explicit `GRAFT_*` keys from `providerEnv` pass through. Route secrets like `GRAFT_API_KEY` through the host's credential resolution when populating `providerEnv`.
+- Upstream output is untrusted: stdout capped (`maxResultBytes`), prompts capped (`maxPromptChars`), injected packs bounded (32 KiB), orientation cut byte-capped (8 KiB); error paths are logged redacted (absolute paths/home dirs).
+- Every CLI call is wall-clock-budgeted (`retrievalBudgetMs`, minus fixed overhead for the timeout math) and every failure degrades silently: pull tools return structured errors, the push pack contributes nothing, edit-watch passes the tool result through untouched.
+- No background workers; state persists through two CAS appends per turn at most (freshness patch, seen-set/saved-tokens update).
+
+## Related APIs
+
+- [Ponytail behavior integration](ponytail.md): same adapter pattern (optional peer/upstream path, fail-closed setup, session custom entries).
+- [Caveman behavior integration](caveman.md): complementary terse-communication mode package.
+- [Indexed code search](indexed-code-search.md): literal `repository_search` seam — complement, not overlap.
+- [Context and skills](context-and-skills.md): progressive catalog + `load_skill`; skill-carried context providers.
+- [Instruction injection](instruction-injection.md): injector seams (`graft-orient` rides `first_turn`).
+- [Extension kernel and event bus](extensions.md): explicit `kernel.load`, extension events.

package/docs/host-security.md

@@ -155,6 +155,7 @@ Wire those values where they matter: provider adapters receive the resolved cred
 - Optional `@arnilo/prism-browser` requires a host-supplied Playwright Browser (`playwright-core@1.61.0` peer). Import is inert. One non-persistent context belongs to one run; actions serialize; refs are snapshot-scoped; CSS/evaluate/CDP/persistent profiles are denied. Context routing + `serviceWorkers: "block"` deny file/data/blob/devtools/private/loopback by default and require contained-proxy attestation for external egress (Playwright routing is defense in depth, not DNS containment). Uploads are realpath-rooted; downloads quarantine with hash/MIME until host `approveRelease`; screenshots return bounded `ImageContent`. Observation vs mutation/high-impact actions map to `ExecutionPolicy`. Treat snapshot/page text as untrusted external content. Close contexts with `browser_close` or `manager.closeRun(runId)` on abort/terminal. Browser control endpoint, binary/image pin, and real egress firewall/proxy remain host-owned. Shared sandbox: `createSharedSandboxBrowserOptions()` + `assertBrowserSandboxNetwork()`.
 - Browser verified-state checkpoints (0.0.14, `createBrowserCheckpointLedger()`) store URL + domain-state hash + host data refs only — never serialized browser internals (cookies/storage/contexts). After any resume/interruption the ledger fails closed (`assertVerifiedBeforeSideEffect`) until the host reloads + verifies, so side effects never replay on stale state.
 - Device adapters (0.0.14, `resolveDevicePolicy`/`assertDeviceAdmit`) are deny-by-default: admission fails closed without explicit `enabled`, an explicit sandbox, approval (when required), an under-budget session count, and shared `RunLimits`. Stream chunks over the frozen cap are dropped with a marker; telemetry is redacted before emit/persist. No vendor voice/desktop package ships in 0.0.14 (demand-gated 0.1.x); device adapters cannot broaden consent/memory/network/file/browser/connector/tool permissions (gate 8).
+- Optional `@arnilo/prism-wiki` tools treat agent-supplied input as untrusted at the first-party `.wiki/` filesystem boundary. `wiki_read_page` enforces lexical containment (`path.relative` with separator-aware `..`/absolute checks) plus `fs.realpath` containment for the wiki root and every successfully read file, so sibling-prefix (`.wiki-evil`), `..`, absolute, alternate-separator, and symlink escapes are denied before content is returned; missing contained pages report `found: false` while denied paths throw an access-denied error (never mapped to not-found). `wiki_record_insight` rejects empty titles/content, caps titles at 200 characters and content at 65,536 bytes, and collapses control characters and newlines in titles to single-line display text before any page/frontmatter/index/log write, so titles cannot inject Markdown headings, index entries, or log entries; slugs are allow-listed to `[a-z0-9-_]` with a non-empty fallback. See [LLM Wiki](wiki.md).
 - `@arnilo/prism-credentials-node` rejects oversized/malformed envelopes and excessive scrypt work before KDF allocation, uses async scrypt, and requires restrictive existing/new Unix vault modes. Keep vault ownership and parent-directory access host-controlled; review before `chmod 600`, never auto-weaken a file policy. Keychain calls use abort-aware native async work with finite timeout/payload caps and sanitized errors. OS prompts, service availability, and whether a native backend promptly honors cancellation remain host/platform boundaries; no plaintext fallback is attempted.
 - LLM compaction always sends finite summary `maxTokens`, retains bounded deltas/events, and bounds/redacts provider/factory/policy error detail. Observational-memory workers cap turns, calls, arguments, results, transcript, and surfaced errors; unknown tools fail before execution, while invalid results can only be rejected after a host tool returns and may therefore follow side effects. Pass all known provider/credential/tool secrets into compaction/runtime options; exact replacement is not secret discovery.
 - Default remote-media loading resolves every DNS answer, rejects the hostname if any address is non-public, and pins one validated address through the request. Explicit `allowedHostnames` can trust private destinations. A host-supplied `fetch` owns DNS/rebinding/proxy/redirect safety; a custom `requestUrl` must connect to its supplied validated address.
@@ -172,7 +173,7 @@ Wire those values where they matter: provider adapters receive the resolved cred
 - License inventory: 160 locked third-party packages; all declare permissive MIT, ISC, BSD, Apache-2.0, or compatible dual licenses. No GPL, AGPL, SSPL, or missing lockfile license metadata.
 - Install scripts: only `better-sqlite3@12.11.1` runs an install script (`prebuild-install || node-gyp rebuild --release`), required by the explicitly installed SQLite adapter. Core and other optional packages add no install hook.
 - Secret scan: source, tests, docs, workflow files, package metadata, built tests, packed-install canary, and tarball deny-list checks found no private-key block or common live-token prefix. Runtime redaction fixtures cover requests, events, ledgers, stores, checkpoints, provider/OAuth errors, and credential ciphertext.
-- Threat suites pass for parameterized SQL/tenant isolation, HTTP URL/SSRF rejection, realpath/symlink containment, shell-metacharacter approval, schema prototype-pollution/remote-reference bounds, OAuth polling/abort/redaction, credential tamper/wrong-key/KDF floors, MCP result bounds/timeouts, and coding approval/path policy.
+- Threat suites pass for parameterized SQL/tenant isolation, HTTP URL/SSRF rejection, realpath/symlink containment, shell-metacharacter approval, schema prototype-pollution/remote-reference bounds, OAuth polling/abort/redaction, credential tamper/wrong-key/KDF floors, MCP result bounds/timeouts, and coding approval/path policy. `security:threat-suites` also gates CodeQL-remediation regressions (plan 038): linear `trimTrailingSlashes`/parsers with no environment regex evaluation, single-pass HTML sanitization, crypto (not `Math.random`) fixture identifiers, and no clear-text error logging on password-handling paths.
 
 PostgreSQL TLS/network policy, MCP endpoint trust/credentials and egress policy beyond package origin/DNS pinning, provider base URLs, OS keychain availability, process sandboxing, workflow tenant identity, and ANSI/control-sequence sanitization in any host terminal renderer remain host boundaries. Prism 0.0.4 ships JSON-line RPC, not an interactive TUI; hosts must render untrusted model/tool text safely. Credential-gated PostgreSQL/provider/keychain tests are separate operator/CI gates, not silently replaced by mocks.
 
@@ -213,6 +214,7 @@ PostgreSQL TLS/network policy, MCP endpoint trust/credentials and egress policy
 - **Named threat-suites leg.** `npm run security:threat-suites` aggregates the Phase 8–11 conformance suites (durable-loop/HITL approval, coding sandbox/egress/forge, ACP protocol, OIDC/OPA/MCP-OAuth/OpenAPI/artifact) into one named 0.1.0 security evidence leg — same scripts as `npm test`, no rewrite; the Phase 7 tenant-isolation suite is its protected counterpart under `npm run test:postgres` (missing `PRISM_TEST_POSTGRES_URL` is a named blocked gate).
 - **Supply-chain negative fixtures.** `scripts/release-gate.test.mjs` verifies the tarball deny list rejects tampered content (plans/reviews/maps/tests), unexpected file types and credential material (native binaries, `.pem`/`.key`/`.p12`), and that a provenance flag suppressed in CI is detectable in the `release.mjs` publish dry-run arguments (`--provenance` mandatory under `GITHUB_ACTIONS`, never claimed on local OIDC-less publishes).
 - **Mandatory gate stack.** CodeQL/SAST, PR dependency review (fail on high), secret scan (source + unpacked tarballs), SPDX SBOM + license policy, tarball allow/deny content checks, and provenance (npm OIDC + GitHub build attestations on tarballs and SBOM) all run in `security.yml`/`release.yml`; evidence for the 0.1.0 tree is recorded in [0.1.0 readiness](0.1.0-readiness.md).
+- **CodeQL query suite.** `.github/codeql/codeql-config.yml` selects the `security-extended` suite for `javascript-typescript` (with the default suite) on push/PR/schedule in `security.yml` (10-minute job bound; measured runtime ~3m22s on the audited SHA, last successful main run `33059128198`). The ignore list covers only generated `dist`, `node_modules`, and release/security artifact directories — first-party packages, threat suites, and fixtures that ship or execute are always scanned, so new alerts enter the same plan-038 ledger/remediation loop (config + guardrails asserted in `scripts/phase38-codeql-regression.test.mjs`). Local Task 6 gates (typecheck/lint/format/threat suites/audit/secret scan/SBOM) pass on the remediations; GitHub `state=open` stays non-zero until those remediations are the analyzed head. Groups G (`js/insufficient-password-hash` on RFC 7636 S256) and H (`js/incomplete-url-substring-sanitization` on a negative docs assertion) are maintainer-reviewed false positives queued for narrow dismissal after that analyze, not code changes.
 - **Live canaries are blocked gates, not skips.** The `live-canaries` and `sandbox-browser` workflows always set their gate env (`PRISM_LIVE_CANARIES=1`), so absent credentials fail the job loudly with a named owner (the workflow + dispatching operator) and retained `canary-report.json` evidence; the local silent-skip path exists only when the gate env is not set.
 
 ## Distributed events and tool effects