@arnilo/prism 0.5.4 → 0.5.6

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+## [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
+- **Byte limits are per-frame, not cumulative.** `maxRequestBytes`/`maxResponseBytes` now compare each individual provider frame (request payload, streamed event) against the cap instead of a run-lifetime byte sum, so long autonomous coding runs (many megabyte-scale frames, each far under 64 MiB) no longer trip `Run limit exceeded: maxRequestBytes` after ~40 turns. HARD stays per-frame process safety — one giant frame still fails, 40 legal frames never do. Cumulative byte counters remain in snapshots/telemetry; token/turn/wall/cost axes stay cumulative.
+
 ## [0.5.4] - 2026-09-08 (plan 067)
 
 ### Changed

package/README.md

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

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

@@ -1,4 +1,4 @@
-import type { Extension, ExtensionEvent, ExtensionLifecycleEventName } from "./contracts.js";
+import type { CommandDefinition, ContextProvider, Extension, ExtensionEvent, ExtensionLifecycleEventName, InstructionInjector, Skill, ToolDefinition } from "./contracts.js";
 import { type ContributionRegistries } from "./contributions.js";
 import { type MiddlewareRegistry } from "./middleware.js";
 import { type PermissionPolicy } from "./security.js";
@@ -40,3 +40,20 @@ export interface ExtensionKernel {
 }
 export declare function createExtensionEventBus(options?: Pick<ExtensionKernelOptions, "errorPolicy" | "secrets">): ExtensionEventBus;
 export declare function createExtensionKernel(options?: ExtensionKernelOptions): ExtensionKernel;
+/** Host-owned activation: copy contributed entries into the `createAgent()`
+ *  fields that accept plain arrays. Contributions stay inert until the host
+ *  passes the returned fields into runtime config. Array slots only —
+ *  single-slot builders (`inputBuilder`/`promptBuilder`), `compaction`,
+ *  `retry`, provider/model selection, and skill activation remain host-owned
+ *  decisions; `commands` are for host RPC surfaces, not an `AgentConfig` field. */
+export interface ActivatedKernelConfig {
+    readonly tools: readonly ToolDefinition[];
+    readonly skills: readonly Skill[];
+    readonly instructionInjectors: readonly InstructionInjector[];
+    readonly context: readonly ContextProvider[];
+    /** For host command surfaces (CLI/RPC/UI); not part of `AgentConfig`. */
+    readonly commands: readonly CommandDefinition[];
+    /** The kernel middleware registry itself; runs only when passed to runtime config. */
+    readonly middleware: MiddlewareRegistry;
+}
+export declare function activateKernel(kernel: ExtensionKernel): ActivatedKernelConfig;

package/dist/extensions.js

@@ -190,6 +190,16 @@ export function createExtensionKernel(options = {}) {
         },
     };
 }
+export function activateKernel(kernel) {
+    return {
+        tools: kernel.registries.tools.list(),
+        skills: kernel.registries.skills.list(),
+        instructionInjectors: kernel.registries.instructionInjectors.list(),
+        context: kernel.registries.contextProviders.list(),
+        commands: kernel.registries.commands.list(),
+        middleware: kernel.middleware,
+    };
+}
 async function assertExtensionLoadPolicy(policy, extension) {
     if (!policy)
         return;

package/dist/index.d.ts

@@ -43,8 +43,8 @@ export type { EventMultiplexer, EventMultiplexerOptions, EventOverflowInfo, Even
 export { createEventMultiplexer, EVENT_MULTIPLEXER_SINGLE_CONSUMER_CODE, EventMultiplexerError } from "./event-multiplexer.js";
 export type { ExecutionAction, ExecutionDecision, ExecutionPolicy, ExecutionRisk } from "./execution-policy.js";
 export { applyExecutionDecision, assertExecutionAllowed, checkExecution, ExecutionDeniedError } from "./execution-policy.js";
-export type { ExtensionErrorPolicy, ExtensionEventBus, ExtensionEventHandler, ExtensionKernel, ExtensionKernelOptions, ExtensionLoadPolicy, LoadedExtension, } from "./extensions.js";
-export { createExtensionEventBus, createExtensionKernel } from "./extensions.js";
+export type { ActivatedKernelConfig, ExtensionErrorPolicy, ExtensionEventBus, ExtensionEventHandler, ExtensionKernel, ExtensionKernelOptions, ExtensionLoadPolicy, LoadedExtension, } from "./extensions.js";
+export { activateKernel, createExtensionEventBus, createExtensionKernel } from "./extensions.js";
 export type { MemoryRunFeedbackStoreOptions, PrepareRunFeedbackOptions, RunFeedbackLimits, RunFeedbackRun, RunFeedbackRunResolver, } from "./feedback.js";
 export { createMemoryRunFeedbackStore, prepareRunFeedback, RunFeedbackError, requireRunFeedbackOwnership, runFeedbackPageLimit, } from "./feedback.js";
 export type { ApplyFieldPolicyOptions, AuditFieldRedaction, AuditFieldRedactorLike, AuditFieldRedactorOptions, FieldPolicy, FieldPolicyAction, FieldPolicyDecision, FieldPolicyInput, ProtectedFieldPolicyOptions, } from "./field-policy.js";
@@ -119,5 +119,5 @@ export { trimTrailingSlashes } from "./trim-trailing-slashes.js";
 export type { ResolvedUseCaseModel, ResolveUseCaseModelInput, UseCaseModelBinding, } from "./use-case-model.js";
 export { resolveUseCaseModel, resolveUseCaseModelBinding, useCaseCredentialProviderId, } from "./use-case-model.js";
 export declare const name = "prism";
-export declare const version = "0.5.4";
+export declare const version = "0.5.6";
 export declare const description = "Agent harness for AI providers, agents, sessions, and tools.";

package/dist/index.js

@@ -22,7 +22,7 @@ export { createDelegatedAgentStep, DelegatedAgentStepError, MAX_DELEGATED_AGENT_
 export { acceptDeviceChunk, assertDeviceAdmit, DEFAULT_DEVICE_MAX_CHUNK_BYTES, DEFAULT_DEVICE_MAX_CONCURRENT_SESSIONS, DevicePolicyError, HARD_DEVICE_MAX_CHUNK_BYTES, HARD_DEVICE_MAX_CONCURRENT_SESSIONS, redactDeviceTelemetry, resolveDevicePolicy, runDevicePolicyConformance, } from "./devices.js";
 export { createEventMultiplexer, EVENT_MULTIPLEXER_SINGLE_CONSUMER_CODE, EventMultiplexerError } from "./event-multiplexer.js";
 export { applyExecutionDecision, assertExecutionAllowed, checkExecution, ExecutionDeniedError } from "./execution-policy.js";
-export { createExtensionEventBus, createExtensionKernel } from "./extensions.js";
+export { activateKernel, createExtensionEventBus, createExtensionKernel } from "./extensions.js";
 export { createMemoryRunFeedbackStore, prepareRunFeedback, RunFeedbackError, requireRunFeedbackOwnership, runFeedbackPageLimit, } from "./feedback.js";
 export { ALLOW_FIELD_POLICY, applyFieldPolicy, createAuditFieldRedactor, createProtectedFieldPolicy, FIELD_POLICY_LIMITS, FieldPolicyError, } from "./field-policy.js";
 export { assertGuardrailsAllowed, GuardrailError, MAX_GUARDRAIL_CONCURRENCY, runGuardrails } from "./guardrails.js";
@@ -66,6 +66,6 @@ export { createToolParameterValidator, createToolRegistry, dispatchToolCall, fil
 export { trimTrailingSlashes } from "./trim-trailing-slashes.js";
 export { resolveUseCaseModel, resolveUseCaseModelBinding, useCaseCredentialProviderId, } from "./use-case-model.js";
 export const name = "prism";
-export const version = "0.5.4";
+export const version = "0.5.6";
 export const description = "Agent harness for AI providers, agents, sessions, and tools.";
 //# sourceMappingURL=index.js.map

package/dist/run-limits.js

@@ -209,8 +209,13 @@ export class RunLimitTracker {
             this.exceed(limit, Number.MAX_SAFE_INTEGER + 1);
         this.counters[counter] = observed;
         const cap = this.limits[limit];
-        if (cap !== null && observed > cap)
-            this.exceed(limit, observed);
+        if (cap === null)
+            return;
+        // Byte caps are per-frame (HARD exists so one giant provider frame cannot OOM the host),
+        // not run-lifetime sums; every other axis stays cumulative.
+        const against = limit === "maxRequestBytes" || limit === "maxResponseBytes" ? delta : observed;
+        if (against > cap)
+            this.exceed(limit, against);
     }
     recordUsage(usage) {
         if (!usage) {

package/docs/cli-rpc.md

@@ -10,7 +10,7 @@ The `prism` bin is a thin adapter over `AgentSession` plus a tiny project scaffo
 - `prism init <dir>`: create a minimal TypeScript project with one selected provider, `.env.example`, and one offline mock test.
 - `prism dev`: boot the loopback dev inspector over the scaffolded agent (delegates into `@arnilo/prism-coding-tools/dev` when resolvable; plan 040 Task 4).
 
-It does not add a TUI, app tools, provider globals, extension discovery, resource discovery, or credential storage. `init` uses Node standard-library filesystem APIs and checked-in templates only — no interactive prompts or template-engine dependency.
+It does not add a TUI, app tools, provider globals, resource discovery, or credential storage, and it never auto-discovers extension packages — `--extension` loads only explicitly named modules (relative paths inside the working directory, or allow-listed package/absolute specifiers). `init` uses Node standard-library filesystem APIs and checked-in templates only — no interactive prompts or template-engine dependency.
 
 ## Live CLI journey (plans/064 Task 5)
 
@@ -115,6 +115,7 @@ Manifests of the negotiation are simple: the agent is loaded from the scaffold c
 | `--discover` | Opt-in workspace contribution discovery (`SKILL.md`/`manifest.json`). Never auto-activates or imports. |
 | `--discover-kinds <csv>` | Kinds to scan; defaults to `skill`. Accepts `skill,tool,context,instructions`. |
 | `--no-discovery` | Hard-disable discovery even if `--discover` is set. |
+| `--extension <specifier>` | Load a trusted extension module (repeatable). Relative `./`/`../` paths must realpath-contain inside the working directory; package names and absolute paths must exactly match an entry in `PRISM_EXTENSION_ALLOWLIST` (comma-separated), checked before `import()`. See the extension loading section below. |
 | `--agents-config <path>` | App config root holding `agents/<name>/AGENT.md` bundles (opt-in). Envelopes only; the host resolves them via `resolveAgentBundle`. The CLI never defaults to the user's home directory. |
 | `--instruction <name>` | Select a registered/discovered instruction injector (repeatable). `--instruction false` disables injectors for the run. Names resolve fail-closed. |
 | `--injector-file <path>` | Load a markdown file as a static `every_turn` injector (repeatable). |
@@ -124,6 +125,19 @@ Manifests of the negotiation are simple: the agent is loaded from the scaffold c
 | `--system-md-file <path>` | Read SYSTEM.md from `<path>` instead — user-owned, `source: "user"` (Phase 31). |
 | `--help` | Print usage. |
 
+### Extension loading (`--extension`)
+
+```bash
+# cwd-relative trusted module (no allow-list needed)
+prism --provider mock --extension ./my-ext.js -p "hello"
+
+# package name or absolute path requires an exact allow-list entry
+PRISM_EXTENSION_ALLOWLIST=@acme/prism-foo \
+  prism --provider mock --extension @acme/prism-foo -p "hello"
+```
+
+Each module must export `createExtension()`, a default function, or a default `{ name, setup }` extension. Loaded modules are trusted host code (same trust level as the provider factory import) — the gates decide which code may load, not what loaded code may do: relative paths fail closed on realpath escape (symlinks cannot leave the working directory), package/absolute specifiers fail closed without an allow-list entry, and a broken or wrong-shaped module is a usage error, not a silent skip. Registered contributions activate through `activateKernel` into the run's agent (tools, skills, injectors, context, middleware); extension skills follow the normal fail-closed skill activation (`RunOptions.activeSkills`). There is no npm marketplace, no `plugin.json`, and no MCP auto-start.
+
 RPC request envelope:
 
 ```ts

package/docs/credential-storage.md

@@ -269,5 +269,5 @@ MCP credentials remain host inputs: resolve them before constructing client `req
 - [Azure OpenAI / Foundry](providers/azure.md) / [Amazon Bedrock](providers/bedrock.md) / [Google Vertex AI](providers/vertex.md): enterprise workload-identity credential callbacks
 - [Web search, fetch, and extraction](web-tools.md): late-bound Brave/Exa/Firecrawl credentials
 - [Security/auth/trust](settings-auth-trust-security.md): host-owned settings/credentials boundaries
-- [Persistence, credentials, and multimodality primitives](persistence-credentials-multimodality-primitives.md): Plan 056 threat model and conformance matrix rows 7–10
+- [Persistence, credentials, and multimodality primitives](history/persistence-credentials-multimodality-primitives.md): Plan 056 threat model and conformance matrix rows 7–10
 - `@arnilo/prism`: `CredentialResolver`, `OAuthCredentialStore`, `createMemoryCredentialStore()`

package/docs/extension-authoring.md

@@ -96,12 +96,11 @@ The `contributed` set is what the extension registered. The `active` set is what
 
 ```ts
 import {
+  activateKernel,
   createAgent,
   createExtensionKernel,
   createMockProvider,
   createContributionRegistries,
-  createSkillRegistry,
-  createToolRegistry,
   providerDone,
   type Extension,
 } from "@arnilo/prism";
@@ -139,19 +138,18 @@ const registries = createContributionRegistries({ duplicate: "error" });
 const kernel = createExtensionKernel({ registries, errorPolicy: "throw" });
 await kernel.load([extension]);
 
-// Host activation: select contributions explicitly.
-const tool = kernel.registries.tools.resolve("acme.echo");
-const skill = kernel.registries.skills.resolve("acme.brief");
+// Host activation: copy the array slots; filter/narrow before createAgent() as needed.
+const activated = activateKernel(kernel);
 const provider = createMockProvider([providerDone()]);
 
 const agent = createAgent({
   model: { provider: "mock", model: "demo" },
   provider,
-  tools: createToolRegistry([tool]),
-  skills: createSkillRegistry([skill]),
-  context: kernel.registries.contextProviders.list(),
+  tools: activated.tools,
+  skills: activated.skills,
+  context: activated.context,
   promptBuilder: kernel.registries.promptBuilders.resolve("acme.prompt"),
-  middleware: kernel.middleware,
+  middleware: activated.middleware,
 });
 
 await agent.createSession().run("Use the Acme extension.", { activeSkills: ["acme.brief"] });
@@ -166,6 +164,7 @@ await agent.createSession().run("Use the Acme extension.", { activeSkills: ["acm
 - `registerSkill()` contributes instructions only. Referenced `toolNames` are checked against host-active tools when the skill is activated.
 - `registerAuthMethod()` and `registerCredentialResolver()` must not contain resolved credential values. Use descriptors/resolvers; the host resolves secrets at the provider/request edge.
 - Middleware from `api.use()` runs only when the host passes `kernel.middleware` into runtime configuration.
+- `activateKernel(kernel)` copies the array slots (`tools`, `skills`, `instructionInjectors`, `context`, `commands`) plus `kernel.middleware` in one call; filter the returned arrays before `createAgent()` when the host wants narrower selection.
 - 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)

package/docs/extensions.md

@@ -42,6 +42,7 @@ createExtensionEventBus(options?: { errorPolicy?: "event" | "throw"; secrets?: r
 - `kernel.events.on(type, handler)` registers ordered event handlers and returns an unsubscribe function.
 - `kernel.events.emit(event)` calls matching handlers in registration order.
 - `kernel.middleware.run(hook, value)` runs matching middleware in registration order.
+- `activateKernel(kernel)` copies the `createAgent()` array slots into one config: `{ tools, skills, instructionInjectors, context, commands, middleware }`. Contributions stay inert until the host passes them into runtime config; single-slot builders, `compaction`/`retry`, provider/model selection, and skill activation remain host-owned decisions.
 - With default `errorPolicy: "event"`, setup/listener/middleware errors become `extension_error` events with redacted `ErrorInfo`.
 - With `errorPolicy: "throw"`, setup/listener/middleware errors reject/throw.
 
@@ -57,7 +58,7 @@ createExtensionEventBus(options?: { errorPolicy?: "event" | "throw"; secrets?: r
 ## Implementation example
 
 ```ts
-import { createAgent, createExtensionKernel, type Extension } from "@arnilo/prism";
+import { activateKernel, createAgent, createExtensionKernel, type Extension } from "@arnilo/prism";
 
 const extension: Extension = {
   name: "demo-extension",
@@ -96,6 +97,17 @@ console.log(kernel.registries.skills.resolve("brief").name); // contributed only
 console.log(kernel.registries.agents.resolve("demo").name); // contributed only; host must create/select before runtime use
 console.log(kernel.registries.systemPromptContributions.resolve("demo-prompt").text); // contributed only; host must select before prompt use
 await kernel.middleware.run("provider_request", { metadata: {} });
+
+// Host activation: copy the array slots into createAgent() fields.
+const activated = activateKernel(kernel);
+const agent = createAgent({
+  model: { provider: "mock", model: "demo" },
+  tools: activated.tools,
+  skills: activated.skills,
+  instructionInjectors: activated.instructionInjectors,
+  context: activated.context,
+  middleware: activated.middleware,
+});
 ```
 
 ## Extension and configuration notes

package/docs/graft.md

@@ -4,7 +4,7 @@
 
 `@arnilo/prism-memory/graft` is an optional subpath 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.
+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-build-deep`, `graft-check`, `graft-viz`, `graft-init`), 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
 
@@ -32,6 +32,9 @@ Zero-code alternative (L0): hosts can skip this package entirely and let agents
 | `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. |
+| `deepModel` | `{ provider: "openai" \| "anthropic" \| "litellm" \| "orcarouter", model: string, apiKey: string, baseUrl?: string }` | no | Model for `graft build --deep` (Graft's own LLM client — **Prism's `Provider` is not Graft's LLM**; they have different protocols). Merged over `providerEnv` as `GRAFT_PROVIDER`/`GRAFT_MODEL`/`GRAFT_API_KEY`/`GRAFT_BASE_URL`; wins on conflict. |
+| `initAgents` / `initYes` / `initWireMcp` | `readonly string[]` / `boolean` / `boolean` | no | `graft init` configuration: agent ids for `--agents`, `--yes`, and whether to wire graft MCP servers (default off — Prism provides its own graft surfaces). `graft-init` refuses to spawn without `initAgents` or `initYes` (the child has no TTY). |
+| `buildBudgetMs` / `deepBuildBudgetMs` / `buildMaxResultBytes` | `number` | no | Budgets for graph builds: structural `build`/`init` default 120000 ms, `--deep` default 600000 ms (the LLM pass over the graph), stdout cap 2 MiB. Ask/grep stay on `retrievalBudgetMs`. |
 | `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). |
@@ -41,7 +44,20 @@ Pull tools (mode includes `pull`): `graft_ask`, `graft_grep`, `graft_callers`, `
 
 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.
+Registered commands: `graft` (`status` \| `build` [deep:true] \| `check` \| `viz` \| `init` dispatch), plus `graft-build`, `graft-build-deep`, `graft-check`, `graft-viz`, `graft-init` aliases.
+
+### Graph builds and init
+
+- `/graft-build` — structural rebuild via `graft build` (tree-sitter pass, no API key, plain-text progress — no `JSON.parse` on this surface).
+- `/graft-build-deep` — `graft build --deep --provider <> --model <> [--base-url <>]` using the host's `deepModel`. Without a configured model it errors before spawning. `GRAFT_API_KEY` rides in the child env, never on argv.
+- `/graft-init` — `graft init --no-global` (never writes user-level state), default `--no-mcp --no-hooks --no-statusline` (opt in via `initWireMcp`), plus `--agents <id>` per `initAgents` and `--yes` when `initYes`. Requires one of the two; non-interactive by design.
+
+```bash
+# structural, no key
+/graft-build
+# deep — host-configured model
+e.g. /graft-build-deep
+```
 
 ## Outputs / response / events
 
@@ -49,7 +65,8 @@ Registered commands: `graft` (`status` \| `build` \| `check` \| `viz` dispatch),
 | --- | --- |
 | `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. |
+| `runGraftJson(cli, argv, options)` / `runGraftExit(cli, argv, options)` / `childEnv(options)` / `childTimeoutMs` / `DEFAULT_MAX_RESULT_BYTES` | Budgeted runners for hosts building custom surfaces — JSON surfaces (`check`/`ask`) vs exit-code surfaces (`build`/`init`). |
+| `deepProviderEnv(deepModel, providerEnv)` | `deepModel` merged over `providerEnv`, filtered to `GRAFT_*`. |
 | `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).
@@ -92,12 +109,15 @@ await kernel.load([
     packageRoot: "./vendor/graft-checkout",
     mode: "both",
     quietStartup: true,
+    deepModel: { provider: "anthropic", model: "claude-sonnet-4-5", apiKey: process.env.ANTHROPIC_API_KEY! },
+    initAgents: ["codex"],
     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.
+// /graft-build-deep runs graft's own LLM pass; /graft-init wires codex, --no-global.
 ```
 
 ## Extension and configuration notes
@@ -105,12 +125,14 @@ await kernel.load([
 - 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-coding-tools`, `@arnilo/prism-core`, or the `prism-all` umbrella (deliberate opt-out, like Caveman/Ponytail) — opt-in install only.
+- Deliberate opt-out from family/umbrella packaging (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`.
+- 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`/`deepModel` pass through. Route secrets like `GRAFT_API_KEY` through the host's credential resolution when populating `deepModel`/`providerEnv`. `deepModel`'s API key reaches the child via env only — never on argv (no `--api-key` flag exists in the surface), so it cannot leak through `ps` or logs.
+- Build/init commands are budgeted separately from retrieval (`buildBudgetMs`, `deepBuildBudgetMs`, `buildMaxResultBytes`); deep builds fail closed without a configured model instead of spawning unconfigured.
+- `graft-init` always passes `--no-global` — it never writes user-level agent state; MCP/hook/statusline wiring stays off unless the host opts in via `initWireMcp`.
 - 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).

package/docs/{0.1.0-readiness.md → history/0.1.0-readiness.md}

@@ -10,11 +10,11 @@ the release tree before cutting 1.0. The decision to cut 1.0 stays with the
 operator after operator-gated legs run in a protected environment and Phase
 12 demand evidence exists.
 
-Evidence trail: [`docs/_evidence/review-coverage-2026-07-26-phase-11.md`](./_evidence/review-coverage-2026-07-26-phase-11.md)
-(addenda 0–9), [`docs/release-and-install.md`](./release-and-install.md),
-[`docs/migration.md`](./migration.md), [`docs/performance.md`](./performance.md),
-[`docs/public-contracts.md`](./public-contracts.md) (frozen 0.1.x contract).
-The per-phase review-coverage evidence archive lives in [`docs/_evidence/`](./_evidence/)
+Evidence trail: [`docs/_evidence/review-coverage-2026-07-26-phase-11.md`](.././_evidence/review-coverage-2026-07-26-phase-11.md)
+(addenda 0–9), [`docs/release-and-install.md`](.././release-and-install.md),
+[`docs/migration.md`](.././migration.md), [`docs/performance.md`](.././performance.md),
+[`docs/public-contracts.md`](.././public-contracts.md) (frozen 0.1.x contract).
+The per-phase review-coverage evidence archive lives in [`docs/_evidence/`](.././_evidence/)
 (plans 067–079, releases 0.0.4–0.0.16; tarball-excluded, kept in-repo for audit).
 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
@@ -82,7 +82,7 @@ material in published artifacts) and exact version-range drift. A genuine break
 requires `--allow-break` **and** a `docs/migration.md` entry mentioning the
 version. The frozen 0.1.x contract (declaration/exports, events, protocol
 payloads, migration checksums, patch-release compatibility promise) is
-published in [docs/public-contracts.md](public-contracts.md).
+published in [docs/public-contracts.md](../public-contracts.md).
 
 **Baseline maintenance:** `scripts/compat-baseline/` must stay committed.
 Regenerate only after review with `node scripts/release.mjs gate --update-baseline`,