@arnilo/prism 0.5.5 → 0.6.0

package/CHANGELOG.md

@@ -1,3 +1,49 @@
+## [0.6.0] - 2026-09-12 (plans 070, 071)
+
+> **0.5.7 was never published.** This release folds that cut's content (durable concurrent tool rounds, strict-provider tool results, host-tunable knobs, peer/options truth, the dependency refresh, and the module splits) together with the 0.6.0 changes below, so a host on 0.5.6 upgrades once. See [docs/migrate-to-0.6.md](docs/migrate-to-0.6.md).
+
+### Fixed
+- **Concurrent tool dispatch dropped sibling results.** With `toolConcurrency > 1` a failed or aborted call threw before the round's results were appended, so every successful sibling result was lost and the next provider request carried unanswered `tool_use` blocks. Results are now persisted before the round fails: successes as-is, the failing call as a real redacted `tool_execution_failed` error, and calls that never started as `tool_call_not_dispatched`. Run-level control errors (`ERR_PRISM_AGENT_RUN_SUSPENDED`, `ERR_PRISM_DELEGATION_SUSPENDED`, `ERR_PRISM_LOOP_*`) still skip synthetic results so durable recovery re-dispatches instead of double-appending.
+- **Content-less tool results serialized as an empty payload.** A `ToolResult` with no `content`/`result` now folds to `EMPTY_TOOL_RESULT_TEXT` (`(tool completed with no output)`) through the shared `serializeToolResultJson` seam (OpenAI-compatible, Alibaba, DeepSeek, Kimi/Moonshot, NeuralWatt, OpenCode-Go), so strict providers stop rejecting zero-length tool payloads.
+- **A failing coverage child hid its own error.** `npm run test:coverage` reported a crashed or failed workspace suite as a bare `no coverage data (suite failed)`, with the child's output discarded (the diagnostic gap that made a one-off `@arnilo/prism-memory` flake unreadable). The summary now prints the child's output tail under the failing row and records `status`/`exitCode`/`tail` on its artifact row — redacted through the public `createSecretRedactor` (repo root and home become placeholders, credential-shaped env values become `[REDACTED]`) and char-bounded (last 40 lines, 8 KiB) so one pathological line cannot bloat the artifact. Passing rows are byte-identical to before.
+- **Memory patch merge aliased caller objects.** `packages/memory`'s `mergeJsonObjects` deep-merged in place; it now delegates to core `mergeConfigLayers` (deep copy, strict JSON validation — `undefined`/`Date`/function values fail closed — with the `MemoryValidationError` taxonomy preserved).
+- **`redactSecrets` was O(n·m) in needles.** A guarded single-pass alternation fast path handles large inputs (≥16 KiB, 2–32 non-overlapping needles) with byte-identical output (~13× faster on 1 MiB transcripts); the ordered loop remains the fallback for overlapping needle sets and small inputs.
+- **Peer manifest resolution broke for packages that do not export `./package.json`** (e.g. `@dietrichgebert/ponytail`): upstream resolvers now resolve the package entry point and walk up to the manifest.
+
+### Added
+- **Host-tunable context assembly:** `AssembleProviderInputOptions.tokenEstimator?: (text: string) => number` replaces the built-in UTF-16/4 heuristic for eviction accounting (byte caps stay estimator-independent).
+- **Host-tunable session snapshot cache:** `AgentSessionConfig.snapshotCacheTtlMs` — `DEFAULT_SNAPSHOT_CACHE_TTL_MS` (1000), `HARD_MAX_SNAPSHOT_CACHE_TTL_MS` (30000), `0` disables the branch-rebuild cache.
+- **Host-tunable memory-session search caps:** `createMemorySessionStore(entries, { search: { maxLinearSessions, maxLinearEntries, maxLinearBytes } })`, validated against the same hard bounds as the defaults.
+- **SSRF allow-list:** `SsrfPolicy.allowedCidrs` accepts IPv4 and IPv6 CIDR entries so a host can explicitly reach a private range; hostname denials (metadata endpoints), credential checks, and the fail-closed unparseable-CIDR behavior are unchanged.
+- **Browser run lifetime:** `BrowserLimitOptions.idleRunTtlMs` (default `0`, `HARD_IDLE_RUN_TTL_MS` 30 min) reaps runs with nothing queued; any interaction resets the idle clock.
+- **Host onboarding docs:** [`docs/peer-dependencies.md`](docs/peer-dependencies.md) (every third-party peer declaration with range, optionality, subpath, install line, and network footprint) and [`docs/options-index.md`](docs/options-index.md) (123 public option/limits/config surfaces routed to the page that documents them), both gated by `live-doc-check` against the manifests and the source.
+- **Real-peer and ACP round-trip coverage:** contract smoke tests for the `@dietrichgebert/ponytail` and `@nanonets/graft` layouts, and stdio round-trip tests driving a spawned ACP agent with the real `@agentclientprotocol/sdk` client (spawn→close, mode negotiation, config options, refused/cancelled permissions).
+- **Release-truth gates:** `scripts/version-literal-gate.test.mjs` asserts every release-claim surface (manifests, internal ranges, `package-lock.json`, the `src/index.ts` version constant, the `docs/index.md` current line, `release.yml` tag lists, `scripts/package-truth.json`) equals the root manifest, so a half-finished cut fails the suite instead of shipping; `scripts/workflow-liveness.test.mjs` resolves every workflow script/workspace/`uses:` reference and requires 40-hex SHA pins for actions; `scripts/wiki-scratch-isolation.test.mjs` proves the memory wiki suites leave tracked fixtures and the repository root untouched; `scripts/run-all-tests.mjs` runs every test stage without short-circuiting, and the startup import budget now asserts a machine-relative ratio (absolute 250 ms ceiling only off-load) so a busy machine no longer reports a false regression.
+
+### Changed
+- **Node floor raised to `>=22`** in all ten publishable packages (`@types/node` `^20.19.0` → `^22.20.0`; the `node20-compat` release leg becomes `node22-compat` on Node 22). Node 20 is upstream EOL since 2026-04-30; Node 24 stays the CI default. This is the host-breaking support-matrix change that the unreleased 0.5.7 deliberately deferred to a minor.
+- **Dependency refresh:** `pg` 8.23, `playwright-core` 1.63.0, `zod` ^4.6.2, `@ai-sdk/provider` 4.0.13 (`@ai-sdk/openai` 4.0.65 with a new supported-version matrix entry), `@office-open/*` 0.14.5 (adapters use the `*Sync` parse variants), `@biomejs/biome` 2.5.13, `@agentclientprotocol/sdk` exact-pinned 1.4.0, and the `@arnilo/prism-memory` `@nanonets/graft` peer range widened to `^0.16.0 || ^0.18.0`.
+- **Examples are Node-20-floor safe:** four runnable examples used `import.meta.main` (Node ≥22.18/≥24.2) on a Node-20 floor; they now use the house `import.meta.url` + `process.argv[1]` guard.
+- **Release gate:** lockstep cuts now require every internal `@arnilo/*` range to be the cut version exactly (`0.6.0` or `^0.6.0`) instead of merely satisfying it, so one release line cannot resolve two first-party minors.
+- **Test/coverage tooling:** the npm test chain runs every stage through `scripts/run-all-tests.mjs` (no short-circuit, one summary), coverage discovery finds nested `dist/**/__tests__` in all 9 workspace packages, `coverage-thresholds.json` may no longer name retired packages, and protected legs use one blocked-gate shape (`scripts/blocked-gate.mjs`) with env **names** only in the release evidence.
+- **Internal structure, additive-only surface:** `runtime/server/artifacts.ts` split into four modules, `enterprise/postgres/model-router.ts` split into a directory (`util`/`circuit`/`capacity`/`reservations`/`expiry`/`state-store`), MCP OAuth discovery extracted to `oauth-metadata.ts`, one abort-aware `Semaphore` shared across `@arnilo/prism-coding-tools` (sandbox error types preserved), shared upstream persona primitives in `@arnilo/prism-coding-tools/src/upstream/`, shared provider HTTP retry primitives (`@arnilo/prism-providers/src/shared/retry-http.ts`), and the `content.ts` ↔ `pinned-fetch.ts` ESM cycle broken via the leaf module `src/media-types.ts`. Compat baselines were regenerated (`--update-baseline`): **69 added declarations, zero removals** — the five new host-tunable surfaces plus the helpers the moved modules now export from their new files.
+
+### Removed
+- **`@arnilo/prism-office` optional `playwright-core` peer** (test-only: `/diagrams` drives a host-supplied iframe). Hosts no longer install a browser for office; see [`docs/peer-dependencies.md`](docs/peer-dependencies.md).
+
+### Notes
+- **Lockstep `0.5.6` → `0.6.0` bump:** all 10 publishable manifests move to `0.6.0` with internal ranges `^0.6.0`; the predecessor published release is **0.5.6** (0.5.7 was never published and is superseded by this cut).
+- **Retired-gate and test-truth fixes** landed in the same window (plans 070/071): frozen-era version markers derive from the root manifest, retired doc paths resolve through the frozen lineage, the packed-consumer enterprise journey no longer inherits a Postgres env var (the `pg` peer is not installed in a packed consumer), the `sandbox-browser` workflow references live packages again, the secret scan is operator-independent (tracked files only), the LSP restart-budget test awaits the exhaustion transition instead of racing a write, and the release workflow tag lists carry every published tag.
+
+## [0.5.6] - 2026-09-09 (plan 069)
+
+### Added
+- **Trusted extension activation**: `activateKernel(kernel)` / `ActivatedKernelConfig` turn a loaded extension kernel into ready-to-spread `AgentConfig` contributions (tools, skills, context, middleware, commands, instruction injectors). No auto-picked single-slot builders/providers.
+- **CLI `--extension`**: repeatable flag loads trusted extension packages — cwd-relative paths (realpath-contained) or `PRISM_EXTENSION_ALLOWLIST` specifiers — and merges their contributions into the run. Modules must export `createExtension()`, a default function, or a default `{name, setup}` object; `--config`/`--resource`/`--tool` stay rejected.
+- **Wiki ingest**: `ingestWikiSource`, `/wiki-ingest` command, `wiki_ingest` tool, and `prism-wiki ingest` stage one external source (text, file, image, PDF; URL via a host `fetchUrl` hook with `assertSsrfAllowedUrl` first) into `raw/ingest/<utc>-<slug>/` as an immutable `source.*` + UTF-8 `extract.md`, then return a Karpathy/OKF filing brief (`metadata.trust: "untrusted_external"`). Compressed PDF/DOCX ride an optional host `extractDocument` hook. Caps: 32 MiB input / 2 MiB extract.
+- **Ingest filing protocol**: `wiki-maintainer` skill + scaffolded `SCHEMA.md` gained the ten-step ingest procedure (catalog-first, integrate-don't-duplicate, OKF v0.2 frontmatter with `sources[].id` footnotes, index/log sync, raw layer read-only, one source per ingest).
+- **Graft graph commands**: `/graft-init` (non-interactive `graft init --no-global`, host `initAgents`/`initYes`), `/graft-build-deep` (`build --deep` with host-configured `deepModel` — provider/model/base-url on argv, `GRAFT_API_KEY` env-only, never on argv, fails closed unconfigured) alongside the keyless `/graft-build`. New `runGraftExit` exit-code runner (build/init are plain text, not JSON) with separate `buildBudgetMs` (120s) / `deepBuildBudgetMs` (600s) / `buildMaxResultBytes` (2 MiB) budgets.
+
 ## [0.5.5] - 2026-09-08
 
 ### Fixed

package/README.md

@@ -162,16 +162,16 @@ printf '{"id":"1","command":"prompt","params":{"input":"Hi"}}\n' \
 
 | package | version | notes |
 | --- | --- | --- |
-| `@arnilo/prism` | 0.5.5 | core — runtime, CLI/RPC, templates, docs |
-| `@arnilo/prism-coding-tools` | 0.5.5 | family — /agent, /security, /document-reader, /openapi, /computer-use-linux, /dev, /caveman, /ponytail, /impeccable subpaths |
-| `@arnilo/prism-core` | 0.5.5 | family — /runtime, /sessions, /governance, /credentials, /enterprise, /work, /validation subpaths |
-| `@arnilo/prism-providers` | 0.5.5 | family — all provider adapters as `/<adapter>` subpaths |
-| `@arnilo/prism-acp-agent` | 0.5.5 | capability — ACP adapter |
-| `@arnilo/prism-ag-ui` | 0.5.5 | capability — AG-UI/A2A/A2UI adapter |
-| `@arnilo/prism-mcp` | 0.5.5 | capability — MCP client/server/OAuth interop |
-| `@arnilo/prism-memory` | 0.5.5 | capability — memory plus /rag, /compaction/*, /graft, /wiki subpaths |
-| `@arnilo/prism-office` | 0.5.5 | capability — /documents, /sheets, /diagrams subpaths |
-| `@arnilo/prism-web-tools` | 0.5.5 | capability — Brave/Exa/Firecrawl plus peer-gated /browser and /obscura subpaths |
+| `@arnilo/prism` | 0.6.0 | core — runtime, CLI/RPC, templates, docs |
+| `@arnilo/prism-coding-tools` | 0.6.0 | family — /agent, /security, /document-reader, /openapi, /computer-use-linux, /dev, /caveman, /ponytail, /impeccable subpaths |
+| `@arnilo/prism-core` | 0.6.0 | family — /runtime, /sessions, /governance, /credentials, /enterprise, /work, /validation subpaths |
+| `@arnilo/prism-providers` | 0.6.0 | family — all provider adapters as `/<adapter>` subpaths |
+| `@arnilo/prism-acp-agent` | 0.6.0 | capability — ACP adapter |
+| `@arnilo/prism-ag-ui` | 0.6.0 | capability — AG-UI/A2A/A2UI adapter |
+| `@arnilo/prism-mcp` | 0.6.0 | capability — MCP client/server/OAuth interop |
+| `@arnilo/prism-memory` | 0.6.0 | capability — memory plus /rag, /compaction/*, /graft, /wiki subpaths |
+| `@arnilo/prism-office` | 0.6.0 | capability — /documents, /sheets, /diagrams subpaths |
+| `@arnilo/prism-web-tools` | 0.6.0 | capability — Brave/Exa/Firecrawl plus peer-gated /browser and /obscura subpaths |
 <!-- generated:package-truth:inventory end -->
 
 ## Scripts

package/dist/agent-approval.js

@@ -37,8 +37,9 @@ export function assertValidAgentRunResume(resume) {
     if (!Number.isSafeInteger(resume.expectedVersion) || resume.expectedVersion <= 0) {
         throw invalid("Resume expectedVersion must be a positive safe integer");
     }
+    const decisions = resume.decisions;
     const hasDecision = resume.decision !== undefined;
-    const hasDecisions = resume.decisions !== undefined;
+    const hasDecisions = decisions !== undefined;
     if (hasDecision && hasDecisions)
         throw invalid("Resume accepts exactly one of decision or decisions");
     if (!hasDecision && !hasDecisions)
@@ -49,7 +50,6 @@ export function assertValidAgentRunResume(resume) {
         }
         return;
     }
-    const decisions = resume.decisions;
     if (!Array.isArray(decisions))
         throw invalid("Decision batch must be an array");
     if (decisions.length === 0)
@@ -242,10 +242,11 @@ export function decisionScopesEqual(a, b) {
         return false;
     if (a.actionConstraints === undefined || b.actionConstraints === undefined)
         return a.actionConstraints === b.actionConstraints;
-    const keys = Object.keys(a.actionConstraints);
-    return (keys.length === Object.keys(b.actionConstraints).length &&
-        keys.every((key) => key in b.actionConstraints &&
-            canonicalToolEffectJson(a.actionConstraints[key]) === canonicalToolEffectJson(b.actionConstraints[key])));
+    const aConstraints = a.actionConstraints;
+    const bConstraints = b.actionConstraints;
+    const keys = Object.keys(aConstraints);
+    return (keys.length === Object.keys(bConstraints).length &&
+        keys.every((key) => key in bConstraints && canonicalToolEffectJson(aConstraints[key]) === canonicalToolEffectJson(bConstraints[key])));
 }
 export function nestedOutcomeToolResult(outcome, toolCallId, name) {
     return outcome.status === "completed"

package/dist/agent-loops.js

@@ -1,6 +1,7 @@
 import { AgentLoopStateError } from "./contracts.js";
 import { createId } from "./ids.js";
 import { inputMessages, toToolResultMessage } from "./input.js";
+import { errorToErrorInfo } from "./redaction.js";
 import { artifactStructuredOutputRequest, withoutStructuredOutput } from "./structured-output.js";
 function throwIfAborted(signal) {
     if (signal.aborted)
@@ -207,12 +208,13 @@ export function generateValidateReviseLoop(opts) {
                         : { ok: true, value: text };
                 // Parse failure consumes revision budget like a validation failure; the
                 // repairer receives `undefined` value plus a synthetic parse issue.
-                const parseFailure = !parsed.ok || parsed.value === undefined
-                    ? { ok: false, errors: [{ path: "$", message: parsed.error ?? "artifact parse failed" }], metadata: { reason: "parse_error" } }
-                    : undefined;
+                const candidate = parsed.ok && parsed.value !== undefined ? { ok: true, value: parsed.value } : undefined;
                 const attempt = ++attempts;
                 ctx.emit({ type: "artifact_validation_started", sessionId: ctx.sessionId, runId: ctx.runId, turn, attempt });
-                const result = parseFailure ?? (await opts.validator(parsed.value, artifactCtx));
+                const result = candidate
+                    ? await opts.validator(candidate.value, artifactCtx)
+                    : { ok: false, errors: [{ path: "$", message: parsed.error ?? "artifact parse failed" }], metadata: { reason: "parse_error" } };
+                const parseFailure = candidate ? undefined : result;
                 ctx.emit({ type: "artifact_validation_finished", sessionId: ctx.sessionId, runId: ctx.runId, turn, attempt, result });
                 if (result.ok) {
                     ctx.emit({ type: "artifact_finished", sessionId: ctx.sessionId, runId: ctx.runId, turn, attempt, result });
@@ -271,39 +273,76 @@ export async function dispatchToolCallsInOrder(calls, ctx) {
     let nextIndex = 0;
     let stopped = false;
     let firstFailure;
-    const recordFailure = (error) => {
+    let failureIndex = -1;
+    const recordFailure = (error, index) => {
         if (stopped)
             return;
         stopped = true;
         firstFailure = error;
+        failureIndex = index;
     };
     const workers = Array.from({ length: concurrency }, async () => {
         for (;;) {
             if (stopped)
                 return;
+            let index = -1;
             try {
                 throwIfAborted(ctx.signal);
-                const index = nextIndex;
+                index = nextIndex;
                 nextIndex += 1;
                 if (index >= calls.length)
                     return;
                 results[index] = await ctx.dispatchToolCall(calls[index]);
             }
             catch (error) {
-                recordFailure(error);
+                recordFailure(error, index >= 0 && index < calls.length ? index : -1);
                 return;
             }
         }
     });
     await Promise.allSettled(workers);
+    // Persist before rethrowing: a stopped batch must not leave the branch with `tool_call`
+    // ids that never got a `tool_result` (providers reject that history on the next turn).
+    // ponytail: synthetic rows carry `errorToErrorInfo` output only — no cause chain; the
+    // store redacts entries again at `appendEntry`, and `ctx.history` mirrors the run error.
+    const claimed = Math.min(nextIndex, calls.length);
+    for (let index = 0; index < calls.length; index += 1) {
+        const result = results[index];
+        if (result) {
+            await appendToolResultMessage(result, ctx);
+            continue;
+        }
+        // Suspension/loop-state errors are not tool outcomes: their machinery appends the real
+        // result on resume, so a synthetic row here would duplicate it.
+        if (index === failureIndex && isRunControlError(firstFailure))
+            continue;
+        const call = calls[index];
+        if (call === undefined)
+            continue;
+        await appendToolResultMessage(syntheticFailureResult(call, index < claimed ? firstFailure : undefined), ctx);
+    }
     if (stopped)
         throw firstFailure;
-    for (const result of results) {
-        throwIfAborted(ctx.signal);
-        if (!result)
-            continue;
-        await appendToolResultMessage(result, ctx);
+}
+/** Run-level control errors rethrown by `dispatchToolCall` (mirrors `src/tools.ts`). */
+function isRunControlError(error) {
+    const code = error?.code;
+    return (typeof code === "string" &&
+        (code === "ERR_PRISM_AGENT_RUN_SUSPENDED" || code === "ERR_PRISM_DELEGATION_SUSPENDED" || code.startsWith("ERR_PRISM_LOOP_")));
+}
+function syntheticFailureResult(call, failure) {
+    if (failure === undefined) {
+        return {
+            toolCallId: call.id,
+            name: call.name,
+            error: {
+                code: "tool_call_not_dispatched",
+                message: "Tool call was not dispatched: the batch stopped after an earlier call failed or the run was aborted.",
+            },
+        };
     }
+    const info = errorToErrorInfo(failure);
+    return { toolCallId: call.id, name: call.name, error: { name: info.name, message: info.message, code: info.code } };
 }
 async function appendToolResultMessage(result, ctx) {
     // Approval-gated calls return a marker instead of a real result; the transcript must not

package/dist/agent-session/session.d.ts

@@ -60,6 +60,7 @@ export declare class RuntimeAgentSession implements AgentSession {
     private ledgerFailure;
     private snapshotGeneration;
     private snapshotCache?;
+    private readonly snapshotCacheTtlMs;
     constructor(config: AgentSessionConfig & {
         readonly agent: Agent;
     });

package/dist/agent-session/session.js

@@ -1,7 +1,7 @@
 /** session (0.2.5 plan 025 Task 1 split). Moved verbatim from agent-session.ts; public surface unchanged behind the barrel. */
 import { policyList } from "../agent-tool-dispatch.js";
 import { createDefaultCompactionStrategy, isCompactionEntryData } from "../compaction.js";
-import { DEFAULT_MAX_PENDING_STEER_BYTES, DEFAULT_MAX_PENDING_STEERS } from "../contracts.js";
+import { DEFAULT_MAX_PENDING_STEER_BYTES, DEFAULT_MAX_PENDING_STEERS, DEFAULT_SNAPSHOT_CACHE_TTL_MS, HARD_MAX_SNAPSHOT_CACHE_TTL_MS, } from "../contracts.js";
 import { GuardrailError, runGuardrails } from "../guardrails.js";
 import { applyDefaultProviderRequestOptions, createProviderRequestPolicyChain, normalizeProviderRequestPolicyResult, } from "../provider-request-policy.js";
 import { redactAgentEvent, redactProviderRequest, redactRunLedgerRecord, redactSecrets, redactSessionEntry } from "../redaction.js";
@@ -78,12 +78,14 @@ export class RuntimeAgentSession {
     ledgerFailure;
     snapshotGeneration = 0;
     snapshotCache;
+    snapshotCacheTtlMs;
     constructor(config) {
         this.id = config.id ?? randomId("session");
         this.agent = config.agent;
         this.metadata = config.metadata;
         this.store = config.store ?? config.agent.config.store ?? createMemorySessionStore();
         this.currentLeafId = config.leafId;
+        this.snapshotCacheTtlMs = resolveSnapshotCacheTtlMs(config.snapshotCacheTtlMs);
     }
     get leafId() {
         return this.currentLeafId;
@@ -470,8 +472,24 @@ export class RuntimeAgentSession {
         const value = reader
             ? await rebuildSessionContext(reader, { sessionId: this.id, leafId: this.currentLeafId })
             : rebuildSessionContext(await this.store.list(this.id), { leafId: this.currentLeafId });
-        this.snapshotCache = { leafId: this.currentLeafId, generation: this.snapshotGeneration, expiresAt: now + 1_000, value };
+        this.snapshotCache = {
+            leafId: this.currentLeafId,
+            generation: this.snapshotGeneration,
+            expiresAt: now + this.snapshotCacheTtlMs,
+            value,
+        };
         return value;
     }
 }
+/**
+ * `snapshotCacheTtlMs` resolution: `0` disables the branch cache (a host that needs a
+ * fresh store read per snapshot), otherwise a safe integer up to the hard cap.
+ */
+function resolveSnapshotCacheTtlMs(value) {
+    const ttl = value ?? DEFAULT_SNAPSHOT_CACHE_TTL_MS;
+    if (!Number.isSafeInteger(ttl) || ttl < 0 || ttl > HARD_MAX_SNAPSHOT_CACHE_TTL_MS) {
+        throw new TypeError(`AgentSessionConfig.snapshotCacheTtlMs must be a safe integer from 0 to ${HARD_MAX_SNAPSHOT_CACHE_TTL_MS}`);
+    }
+    return ttl;
+}
 //# sourceMappingURL=session.js.map

package/dist/agent-tool-dispatch.js

@@ -51,8 +51,9 @@ export async function validateElicitationPayload(agent, state, target, payload,
     // Tool-declared answer-shape validation, re-derived from the current registry (never persisted).
     const call = state.pendingCalls?.find((entry) => entry.call.id === target.toolCallId)?.call;
     const tool = call ? activeTools(agent.config.tools).registry.get(call.name) : undefined;
-    const validate = tool?.elicitation && call
-        ? safeToolElicitationValidate(tool, call.arguments, {
+    const elicitation = tool?.elicitation;
+    const validate = elicitation && call
+        ? safeToolElicitationValidate(elicitation, call.arguments, {
             sessionId: state.sessionId,
             runId: state.runId,
             toolCallId: target.toolCallId ?? "elicitation",
@@ -68,9 +69,9 @@ export async function validateElicitationPayload(agent, state, target, payload,
         }
     }
 }
-function safeToolElicitationValidate(tool, args, context) {
+function safeToolElicitationValidate(elicitation, args, context) {
     try {
-        return tool.elicitation(args, context)?.validate;
+        return elicitation(args, context)?.validate;
     }
     catch {
         return undefined;

package/dist/cli-runner.d.ts

@@ -1,5 +1,6 @@
 import type { Readable, Writable } from "node:stream";
 import type { AgentSession, ContributionFileKind, InstructionInjector, Skill, SystemPromptContribution } from "./contracts.js";
+import { type ActivatedKernelConfig } from "./index.js";
 import type { AgentBundle } from "./node/agent-definitions.js";
 import { type RpcSessionFactory } from "./rpc.js";
 export type CliMode = "print" | "json" | "rpc";
@@ -35,6 +36,12 @@ export interface CliOptions {
     readonly injectorFiles: readonly string[];
     /** Runtime-populated: `--instruction`/`--injector-file` resolved to live injectors. */
     readonly resolvedInstructionInjectors: readonly InstructionInjector[];
+    /** Parsed flag: `--extension <specifier>` (repeatable). Loaded via {@link loadCliExtensions}
+     *  into {@link CliOptions.activatedExtensions} before session creation. */
+    readonly extensions: readonly string[];
+    /** Runtime-populated (not a parsed flag): activated contributions from `--extension` modules
+     *  (`kernel.load()` → `activateKernel()`). Merged into `createAgent()` by `agentSession`. */
+    readonly activatedExtensions?: ActivatedKernelConfig;
     /** Parsed flag: `--no-agents-md` / `--no-system-md` skip the corresponding auto-load. */
     readonly noAgentsMd: boolean;
     readonly noSystemMd: boolean;
@@ -71,7 +78,7 @@ export interface CliRuntime {
     /** Test injection for `prism dev`: overrides `@arnilo/prism-dev` resolution. */
     readonly loadDevCli?: () => Promise<unknown>;
 }
-export declare const usage = "Usage: prism [--mode print|json|rpc] [-p prompt] [options]\n       prism init <dir> [--template <name>] [--list-templates] [--provider <name>] [--with-workflows] [--with-evals] [--force]\n       prism providers add <name> [--base-url <url>] [--env-key <name>] [--model <id>] [--force]\n       prism dev [--port <n>] [--host <addr>]   (loopback inspector; delegates into @arnilo/prism-dev)\n\n\nOptions:\n  -p, --prompt <text>        Prompt to run in print/json mode\n  --provider <name>          Provider id from the init provider catalog ('mock' is built in;\n                             real providers need their @arnilo/prism-providers package +\n                             credential env var)\n  --model <name>             Explicit model name\n  --session <id>             Session id\n  --system <text>            System instructions\n  --context <text>           Context text\n  --compact <entries>        Auto-compaction threshold\n  --max-tool-rounds <n>      Maximum tool rounds\n  --discover                 Enable workspace contribution discovery (opt-in)\n  --discover-kinds <csv>     Kinds to discover (default: skill; skill,tool,context,instructions)\n  --no-discovery             Disable discovery even if --discover is set\n  --agents-config <path>     App config root holding agents/<name>/AGENT.md bundles (opt-in)\n  --no-agents-md             Skip auto-loading <workspaceRoot>/AGENTS.md\n  --no-system-md             Skip auto-loading the global SYSTEM.md layer\n  --agents-md-file <path>    Read AGENTS.md from <path> instead (trust-gated, source: app)\n  --system-md-file <path>    Read SYSTEM.md from <path> instead (source: user)\n  -h, --help                 Show this help\n";
+export declare const usage = "Usage: prism [--mode print|json|rpc] [-p prompt] [options]\n       prism init <dir> [--template <name>] [--list-templates] [--provider <name>] [--with-workflows] [--with-evals] [--force]\n       prism providers add <name> [--base-url <url>] [--env-key <name>] [--model <id>] [--force]\n       prism dev [--port <n>] [--host <addr>]   (loopback inspector; delegates into @arnilo/prism-dev)\n\n\nOptions:\n  -p, --prompt <text>        Prompt to run in print/json mode\n  --provider <name>          Provider id from the init provider catalog ('mock' is built in;\n                             real providers need their @arnilo/prism-providers package +\n                             credential env var)\n  --model <name>             Explicit model name\n  --session <id>             Session id\n  --system <text>            System instructions\n  --context <text>           Context text\n  --compact <entries>        Auto-compaction threshold\n  --max-tool-rounds <n>      Maximum tool rounds\n  --discover                 Enable workspace contribution discovery (opt-in)\n  --discover-kinds <csv>     Kinds to discover (default: skill; skill,tool,context,instructions)\n  --no-discovery             Disable discovery even if --discover is set\n  --extension <specifier>    Load a trusted extension module (repeatable). Relative paths load\n                             from the working directory; package names and absolute paths must\n                             be listed in PRISM_EXTENSION_ALLOWLIST (comma-separated).\n  --agents-config <path>     App config root holding agents/<name>/AGENT.md bundles (opt-in)\n  --no-agents-md             Skip auto-loading <workspaceRoot>/AGENTS.md\n  --no-system-md             Skip auto-loading the global SYSTEM.md layer\n  --agents-md-file <path>    Read AGENTS.md from <path> instead (trust-gated, source: app)\n  --system-md-file <path>    Read SYSTEM.md from <path> instead (source: user)\n  -h, --help                 Show this help\n";
 export declare function parseCliArgs(argv: readonly string[]): CliOptions;
 export declare function runCli(argv: readonly string[], runtime: CliRuntime): Promise<number>;
 export declare function runPromptMode(session: AgentSession, options: CliOptions, stdout: Writable, mode: "print" | "json"): Promise<void>;

package/dist/cli-runner.js

@@ -1,11 +1,12 @@
-import { readFile } from "node:fs/promises";
-import { basename, dirname } from "node:path";
+import { readFile, realpath } from "node:fs/promises";
+import { basename, dirname, isAbsolute, resolve, sep } from "node:path";
 import process from "node:process";
+import { pathToFileURL } from "node:url";
 import { runPrismDevSubcommand } from "./cli-dev.js";
 import { initUsage, loadProvidersCatalog, runInitCommand } from "./cli-init.js";
 import { providerAddUsage, runProviderAddCommand } from "./cli-provider-add.js";
 import { createContributionRegistries, registerDiscoveredContributions } from "./contributions.js";
-import { createAgent, createContributionRegistry, createMockProvider, providerDone, providerTextDelta, resolveInstructionInjectors, } from "./index.js";
+import { activateKernel, createAgent, createContributionRegistry, createExtensionKernel, createMockProvider, providerDone, providerTextDelta, resolveInstructionInjectors, } from "./index.js";
 import { discoverAgentBundles } from "./node/agent-definitions.js";
 import { discoverContributions } from "./node/contribution-discovery.js";
 import { registerDiscoveredInstructionInjectors } from "./node/instruction-injectors.js";
@@ -33,6 +34,9 @@ Options:
   --discover                 Enable workspace contribution discovery (opt-in)
   --discover-kinds <csv>     Kinds to discover (default: skill; skill,tool,context,instructions)
   --no-discovery             Disable discovery even if --discover is set
+  --extension <specifier>    Load a trusted extension module (repeatable). Relative paths load
+                             from the working directory; package names and absolute paths must
+                             be listed in PRISM_EXTENSION_ALLOWLIST (comma-separated).
   --agents-config <path>     App config root holding agents/<name>/AGENT.md bundles (opt-in)
   --no-agents-md             Skip auto-loading <workspaceRoot>/AGENTS.md
   --no-system-md             Skip auto-loading the global SYSTEM.md layer
@@ -56,11 +60,12 @@ const valueFlags = new Set([
     "--agents-md-file",
     "--system-md-file",
     "--agents-config",
+    "--extension",
 ]);
 const boolFlags = new Set(["--discover", "--no-discovery", "--no-agents-md", "--no-system-md"]);
 // Known-but-inert flags: parsed by earlier builds, never wired to any behavior.
 // Rejected loudly (rather than silently ignored) until a CLI-harness plan wires them.
-const unsupportedFlags = new Set(["--config", "--resource", "--extension", "--tool"]);
+const unsupportedFlags = new Set(["--config", "--resource", "--tool"]);
 const ALL_KINDS = ["skill", "tool", "context", "instructions"];
 export function parseCliArgs(argv) {
     let mode = "print";
@@ -83,6 +88,7 @@ export function parseCliArgs(argv) {
     const context = [];
     const instructions = [];
     const injectorFiles = [];
+    const extensions = [];
     for (let i = 0; i < argv.length; i += 1) {
         const flag = argv[i];
         if (flag === "-h" || flag === "--help") {
@@ -163,6 +169,9 @@ export function parseCliArgs(argv) {
             case "--agents-config":
                 agentsConfig = value;
                 break;
+            case "--extension":
+                extensions.push(value);
+                break;
         }
     }
     return {
@@ -180,6 +189,7 @@ export function parseCliArgs(argv) {
         discoverKinds,
         noDiscovery,
         agentsConfig,
+        extensions,
         discoveredSkills: [],
         discoveredInjectors: [],
         discoveredAgents: [],
@@ -317,6 +327,13 @@ export async function runCli(argv, runtime) {
             });
             options = { ...options, systemPromptLayers: layers };
         }
+        // ponytail: 069 — --extension imports trusted modules only (cwd-contained relative paths,
+        // or allow-listed package/absolute specifiers), then activates their array contributions
+        // into the CLI agent. Throw policy: a broken extension is a usage error, not a silent skip.
+        if (options.extensions.length > 0) {
+            const activatedExtensions = await loadCliExtensions(options.extensions);
+            options = { ...options, activatedExtensions };
+        }
         const session = await (runtime.createSession ?? defaultCreateSession)(options);
         await runPromptMode(session, options, runtime.stdout, mode);
         return 0;
@@ -386,6 +403,8 @@ function mockSession(options) {
     return agentSession({ ...options, providerInstance: createMockProvider([providerTextDelta("Hello"), providerDone()]), modelConfig });
 }
 function agentSession(options) {
+    const activated = options.activatedExtensions;
+    const skills = activated ? [...options.discoveredSkills, ...activated.skills] : options.discoveredSkills;
     return createAgent({
         model: options.modelConfig,
         provider: options.providerInstance,
@@ -393,11 +412,13 @@ function agentSession(options) {
         // ponytail: Phase 31 — file layers compose with `instructions` (base) via the existing
         // composeSystemPrompt pipeline; rank order (user<package<app<run) is enforced inside.
         ...(options.systemPromptLayers.length > 0 ? { systemPrompt: options.systemPromptLayers } : {}),
-        // ponytail: discovered skills become selectable via RunOptions.activeSkills (set by runOptions below).
-        ...(options.discoveredSkills.length > 0 ? { skills: createSkillRegistry(options.discoveredSkills) } : {}),
+        // ponytail: discovered/extension skills become selectable via RunOptions.activeSkills (set by runOptions below).
+        ...(skills.length > 0 ? { skills: createSkillRegistry(skills) } : {}),
+        ...(activated ? { tools: activated.tools, context: activated.context, middleware: activated.middleware } : {}),
     }).createSession({ id: options.session });
 }
 function runOptions(options) {
+    const injectors = [...(options.activatedExtensions?.instructionInjectors ?? []), ...options.resolvedInstructionInjectors];
     return {
         ...(options.maxToolRounds !== undefined ? { limits: { maxToolRounds: options.maxToolRounds } } : {}),
         compaction: options.compact ? { thresholdEntries: options.compact } : undefined,
@@ -405,7 +426,7 @@ function runOptions(options) {
         ...(options.discover && !options.noDiscovery && options.discoveredSkills.length > 0
             ? { activeSkills: options.discoveredSkills.map((s) => s.name) }
             : {}),
-        ...(options.resolvedInstructionInjectors.length > 0 ? { instructionInjectors: options.resolvedInstructionInjectors } : {}),
+        ...(injectors.length > 0 ? { instructionInjectors: injectors } : {}),
     };
 }
 // ponytail: resolve --instruction names against discovered injectors (fail-closed) and load
@@ -432,6 +453,75 @@ function positiveInt(value, flag) {
         throw new CliUsageError(`Invalid value for ${flag}: ${value}`);
     return parsed;
 }
+/** Load `--extension` specifiers into one kernel and activate it. Trust model:
+ *  the loaded code is trusted host code (same level as the provider factory
+ *  import in `defaultCreateSession`) — the gates decide WHICH code may load,
+ *  not sandbox what loaded code does.
+ *  - Relative `./`/`../` paths: no allow-list needed, but must `realpath`
+ *    contain inside the working directory (symlinks cannot escape).
+ *  - Bare package names and absolute paths: exact match in
+ *    `PRISM_EXTENSION_ALLOWLIST` (comma-separated), evaluated before `import()`.
+ *  Accepted module shapes: `createExtension()` export, a default function, or
+ *  a default `{ name, setup }` Extension object. */
+async function loadCliExtensions(specifiers) {
+    const allowList = (process.env.PRISM_EXTENSION_ALLOWLIST ?? "")
+        .split(",")
+        .map((entry) => entry.trim())
+        .filter(Boolean);
+    const kernel = createExtensionKernel({ errorPolicy: "throw" });
+    const extensions = [];
+    for (const specifier of specifiers) {
+        extensions.push(await importTrustedExtension(specifier, allowList));
+    }
+    await kernel.load(extensions);
+    return activateKernel(kernel);
+}
+async function importTrustedExtension(specifier, allowList) {
+    if (specifier.includes("\0"))
+        throw new CliUsageError(`Invalid value for --extension: ${specifier}`);
+    const relative = specifier.startsWith("./") || specifier.startsWith("../");
+    let moduleSpecifier;
+    if (relative) {
+        const real = await realpath(resolve(specifier)).catch(() => {
+            throw new CliUsageError(`--extension "${specifier}" does not exist`);
+        });
+        const realCwd = await realpath(process.cwd());
+        if (real !== realCwd && !real.startsWith(realCwd + sep)) {
+            throw new CliUsageError(`--extension "${specifier}" escapes the working directory`);
+        }
+        moduleSpecifier = pathToFileURL(real).href;
+    }
+    else {
+        if (!allowList.includes(specifier)) {
+            throw new CliUsageError(`--extension "${specifier}" is not in PRISM_EXTENSION_ALLOWLIST (package names and absolute paths require it; relative extension paths need ./ or ../)`);
+        }
+        moduleSpecifier = isAbsolute(specifier) ? pathToFileURL(specifier).href : specifier;
+    }
+    let mod;
+    try {
+        mod = await import(moduleSpecifier);
+    }
+    catch (error) {
+        throw new CliUsageError(`--extension "${specifier}" failed to load: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    return extensionFromModule(mod, specifier);
+}
+function extensionFromModule(mod, specifier) {
+    const record = mod;
+    if (typeof record.createExtension === "function")
+        return record.createExtension();
+    if (typeof record.default === "function")
+        return record.default();
+    if (isExtensionObject(record.default))
+        return record.default;
+    throw new CliUsageError(`--extension "${specifier}" must export createExtension(), a default function, or a default { name, setup } extension`);
+}
+function isExtensionObject(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        typeof value.name === "string" &&
+        typeof value.setup === "function");
+}
 function write(stream, text) {
     stream.write(text);
 }

package/dist/content.d.ts

@@ -1,4 +1,7 @@
 import type { ContentBlock, ImageContent, Message, ModelConfig, ResourceLoadContext, ResourceLoader, VideoContent } from "./contracts.js";
+import { type MediaHostAddress, type MediaHostnameResolver, type SsrfPolicy } from "./media-types.js";
+export type { MediaHostAddress, MediaHostnameResolver, SsrfPolicy } from "./media-types.js";
+export { assertSsrfAllowedUrl, MediaContentError } from "./media-types.js";
 /** Known model input capability tags for `ModelCapabilities.input`. */
 export declare const MODEL_INPUT_CAPABILITIES: readonly ["text", "image", "audio", "file", "document", "video"];
 export type ModelInputCapability = (typeof MODEL_INPUT_CAPABILITIES)[number];
@@ -53,21 +56,10 @@ export interface MediaContentBounds {
     readonly maxAudioDurationMs?: number;
     readonly fetchTimeoutMs?: number;
 }
-export interface SsrfPolicy {
-    /** When true (default), deny private/link-local/metadata hostnames and IPs. */
-    readonly denyPrivateHosts?: boolean;
-    /** Optional hostname allow-list. When set, only listed hosts are permitted. */
-    readonly allowedHostnames?: readonly string[];
-}
 export interface MediaMimePolicy {
     /** Reject when magic bytes disagree with declared media type. Default `true`. */
     readonly strictMagicValidation?: boolean;
 }
-export interface MediaHostAddress {
-    readonly address: string;
-    readonly family: 4 | 6;
-}
-export type MediaHostnameResolver = (hostname: string, signal: AbortSignal) => Promise<readonly MediaHostAddress[]>;
 export interface MediaUrlRequest {
     readonly url: URL;
     readonly address: MediaHostAddress;
@@ -103,16 +95,11 @@ export declare class UnsupportedModalityError extends Error {
     readonly model: string;
     constructor(modality: ModelInputCapability, model: ModelConfig);
 }
-export declare class MediaContentError extends Error {
-    readonly code: "ambiguous_source" | "missing_source" | "item_too_large" | "request_too_large" | "too_many_items" | "audio_too_long" | "invalid_base64" | "ssrf_denied" | "redirect" | "fetch_failed" | "fetch_timeout" | "resource_required" | "mime_mismatch" | "unsupported_url_scheme";
-    constructor(code: MediaContentError["code"], message: string, options?: ErrorOptions);
-}
 export declare function contentBlockInputModality(block: ContentBlock): ModelInputCapability | undefined;
 export declare function collectMessageContentBlocks(messages: readonly Message[]): ContentBlock[];
 export declare function assertModelSupportsContentBlocks(model: ModelConfig, blocks: readonly ContentBlock[]): void;
 export declare function assertMessagesSupportModelCapabilities(model: ModelConfig, messages: readonly Message[]): void;
 export declare function assertMediaBlocksWithinBounds(blocks: readonly MediaContentBlock[], bounds?: MediaContentBounds): void;
-export declare function assertSsrfAllowedUrl(url: string, policy?: SsrfPolicy): void;
 export declare function sniffMediaMimeType(bytes: Uint8Array): string | undefined;
 export declare function assertDeclaredMediaTypeMatches(declaredMediaType: string, bytes: Uint8Array, policy?: MediaMimePolicy): void;
 export declare function resolveMediaContentBlock(block: MediaContentBlock, options?: ResolveMediaContentOptions): Promise<ResolvedMediaContent>;