@arnilo/prism 0.0.16 → 0.0.17

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## [0.0.17] - 2026-07-29
+
+### Added
+- Extension lifecycle: `ExtensionKernel.load()` returns `LoadedExtension[]` dispose handles; contribution/provider/model registries gain `unregister(...)`; a failed `setup` unwinds its partial registrations.
+- `MemoryCredentialStoreOptions.allowProviderFallback` for strict provider-scoped credential resolution; `createMemoryCheckpointStore` `maxRecords`/`maxValueBytes` bounds; `ShellToolOptions.envAllowlist` (coding-agent); `ErrorInfo.retryAfterMs` plus `retryAfterMs`-aware `createDefaultRetryPolicy` with `jitter`/`random` options; guardrail `steer_rejected` event; `httpStatusError` provider transport helper wired into anthropic, google, kimi, openai, opencode-go, and the shared OpenAI-compatible transport.
+
+### Changed
+- Durable runs: run-state load now bounds against the 1 MiB hard cap (states saved with a raised `maxStateBytes` resume correctly); agent fingerprint also covers instructions, system-prompt contributions, and skills; resume-after-interrupt is explicit implicit-approval.
+- Retry/backpressure: HTTP provider errors carry numeric codes and `Retry-After` hints; default retry policy applies ±25% jitter.
+- `input_assembly` middleware runs unconditionally (both plain and context-budget paths, any `InputBuilder`); memory session store rejects cross-session `expectedParentId`; context-budget eviction is O(n) instead of O(n²).
+- Guardrails: `interrupt` errors name the stage; `guardrail_failed` records carry the underlying error message in `metadata.error`; steer `block`/`tripwire` drops the message and emits `steer_rejected` instead of failing the run.
+- Default prompt builder omits the `Available tools:` text for tool-capable models (`capabilities.tools === true`).
+- Middleware registry throws on double `next()` and diagnoses conflicting `next(v)` + return; event multiplexer keeps sorted delivery while a consumer is parked; batched run-ledger dead counters removed.
+
+### Breaking (minor, pre-1.0)
+- CLI: `--config`, `--resource`, `--extension`, `--tool` are rejected (`<flag> is not supported in this build`); the dead `CliOptions.config/resources/extensions/tools` fields are removed.
+- `ExtensionKernel.load()` resolves to `LoadedExtension[]` instead of `void`.
+
+See [docs/migration.md](docs/migration.md) for the full 0.0.16 → 0.0.17 notes.
+
 ## [0.0.16] - 2026-07-26
 
 ### Added

package/dist/agent-run-state.js

@@ -9,16 +9,25 @@ const MAX_PROPERTIES = 256;
 export function agentFingerprint(agent, revision) {
     const config = agent.config;
     const tools = !config.tools ? [] : "list" in config.tools ? config.tools.list() : config.tools;
+    const skills = !config.skills ? [] : "list" in config.skills ? config.skills.list() : config.skills;
     const guardrails = [
         ...(config.guardrails?.input ?? []),
         ...(config.guardrails?.output ?? []),
         ...(config.guardrails?.toolInput ?? []),
         ...(config.guardrails?.toolOutput ?? []),
     ];
+    const systemPrompt = config.systemPrompt === false || config.systemPrompt === undefined
+        ? (config.systemPrompt ?? null)
+        : (Array.isArray(config.systemPrompt) ? config.systemPrompt : [config.systemPrompt]).map((c) => ({ id: c.id, text: c.text }));
     const value = JSON.stringify({
         id: config.id ?? config.name ?? "agent",
         revision,
         model: config.model,
+        // Instructions/prompt text shapes agent behavior as much as the tool set; a change
+        // without a definitionRevision bump must not resume stale durable runs silently.
+        instructions: config.instructions ?? null,
+        systemPrompt,
+        skills: skills.map((skill) => ({ name: skill.name, instructions: skill.instructions, toolNames: skill.toolNames })),
         tools: tools.map((tool) => ({ name: tool.name, parameters: tool.parameters, exclusive: tool.exclusive })),
         guardrails: guardrails.map((guardrail) => ({ name: guardrail.name, stage: guardrail.stage, revision: guardrail.revision })),
         loop: typeof config.loop === "object" && config.loop && "strategy" in config.loop
@@ -111,7 +120,10 @@ export function parseAgentRunState(value, version) {
         !state.deadlineAt) {
         throw new AgentRunStateError("Malformed agent run state");
     }
-    return boundState({ ...state, version }, DEFAULT_MAX_AGENT_RUN_STATE_BYTES);
+    // Load bounds against the hard cap, not the default: the configured maxStateBytes is a
+    // save-side policy knob, while the load-side bound is only a DoS ceiling. States saved
+    // with a raised maxStateBytes must remain resumable.
+    return boundState({ ...state, version }, HARD_MAX_AGENT_RUN_STATE_BYTES);
 }
 function boundState(state, maxBytes) {
     checkShape(state, 0);

package/dist/agents.js

@@ -346,15 +346,17 @@ class RuntimeAgentSession {
                 redactor: this.activeRedactor,
                 emit: (event) => this.emit(event),
             });
-            if (inputGuardrails.terminal?.action === "interrupt" && this.activeDurable) {
-                if (!resumed) {
-                    const interruption = { kind: "input_guardrail", reason: inputGuardrails.terminal.reason ?? "Input requires approval" };
-                    throw new AgentRunSuspended(await this.suspendDurable({ runId, model, limits, interruption, messages: inputMessages }), interruption);
-                }
+            // Input-guardrail decision table:
+            // - interrupt + durable + fresh run  → suspend for approval.
+            // - interrupt + durable + resumed run → proceed: resuming IS the operator approval.
+            // - interrupt without durable, or block/tripwire → fail via assertGuardrailsAllowed.
+            const approvedByResume = resumed !== undefined && inputGuardrails.terminal?.action === "interrupt" && this.activeDurable !== undefined;
+            if (inputGuardrails.terminal?.action === "interrupt" && this.activeDurable && !approvedByResume) {
+                const interruption = { kind: "input_guardrail", reason: inputGuardrails.terminal.reason ?? "Input requires approval" };
+                throw new AgentRunSuspended(await this.suspendDurable({ runId, model, limits, interruption, messages: inputMessages }), interruption);
             }
-            else {
+            if (inputGuardrails.terminal && !approvedByResume)
                 assertGuardrailsAllowed(inputGuardrails);
-            }
             for (const message of inputMessages)
                 await this.appendMessage(message, runId);
             await this.autoCompact(runId, options, controller.signal, inputMessages);
@@ -1049,7 +1051,22 @@ class RuntimeAgentSession {
                 redactor: this.activeRedactor,
                 emit: (event) => this.emit(event),
             });
-            assertGuardrailsAllowed(inputGuardrails);
+            // Mid-run steer: a terminal decision drops the message (never enters history or
+            // the session store) and the run continues. Run-start input blocking still fails
+            // the run — only the blast radius of steered input is narrowed.
+            const terminal = inputGuardrails.terminal;
+            if (terminal) {
+                if (terminal.action === "interrupt")
+                    throw new GuardrailError(terminal);
+                this.emit({
+                    type: "steer_rejected",
+                    sessionId: this.id,
+                    runId,
+                    message: this.activeRedactor ? this.activeRedactor.redact(message) : message,
+                    record: terminal,
+                });
+                continue;
+            }
             this.history.push(message);
             await this.appendMessage(message, runId);
         }
@@ -1324,11 +1341,25 @@ function withoutTrailingInput(messages, input) {
     const next = [...messages];
     for (let i = input.length - 1; i >= 0; i -= 1) {
         const last = next.at(-1);
-        if (last && JSON.stringify(last) === JSON.stringify(input[i]))
+        if (last && stableMessageKey(last) === stableMessageKey(input[i]))
             next.pop();
     }
     return next;
 }
+// Key-order-insensitive comparison: a redacted-then-reassembled message with reordered
+// keys must still dedupe against the trailing input, or auto-compaction duplicates it.
+function stableMessageKey(value) {
+    if (Array.isArray(value))
+        return `[${value.map(stableMessageKey).join(",")}]`;
+    if (value !== null && typeof value === "object") {
+        const record = value;
+        return `{${Object.keys(record)
+            .sort()
+            .map((key) => `${JSON.stringify(key)}:${stableMessageKey(record[key])}`)
+            .join(",")}}`;
+    }
+    return JSON.stringify(value) ?? "null";
+}
 function bridgeAbort(signal, controller) {
     if (!signal)
         return () => undefined;
@@ -1346,9 +1377,10 @@ function throwIfAbortedSignal(signal) {
     if (signal?.aborted)
         throw signal.reason instanceof Error ? signal.reason : new Error("Agent run aborted");
 }
+const jsonTextEncoder = new TextEncoder();
 function jsonBytes(value) {
     try {
-        return new TextEncoder().encode(JSON.stringify(value)).byteLength;
+        return jsonTextEncoder.encode(JSON.stringify(value)).byteLength;
     }
     catch {
         throw new TypeError("Provider request or event must be JSON-serializable for run limits");

package/dist/checkpoints.d.ts

@@ -6,6 +6,10 @@ export declare class CheckpointConflictError extends Error {
 }
 export interface MemoryCheckpointStoreOptions {
     readonly maxPageSize?: number;
+    /** Capacity bound: least-recently-saved records are evicted past this count (default 10_000). */
+    readonly maxRecords?: number;
+    /** Per-record bound on the JSON-encoded value in bytes (default 1 MiB); oversized values are rejected. */
+    readonly maxValueBytes?: number;
 }
 /** In-process reference implementation of the generic checkpoint contract. */
 export declare function createMemoryCheckpointStore(options?: MemoryCheckpointStoreOptions): CheckpointStore;

package/dist/checkpoints.js

@@ -6,10 +6,14 @@ export class CheckpointConflictError extends Error {
         this.name = "CheckpointConflictError";
     }
 }
+const DEFAULT_MAX_CHECKPOINT_RECORDS = 10_000;
+const DEFAULT_MAX_CHECKPOINT_VALUE_BYTES = 1024 * 1024;
 /** In-process reference implementation of the generic checkpoint contract. */
 export function createMemoryCheckpointStore(options = {}) {
     const records = new Map();
     const maxPageSize = Math.max(1, options.maxPageSize ?? 500);
+    const maxRecords = Math.max(1, options.maxRecords ?? DEFAULT_MAX_CHECKPOINT_RECORDS);
+    const maxValueBytes = Math.max(1, options.maxValueBytes ?? DEFAULT_MAX_CHECKPOINT_VALUE_BYTES);
     return {
         async saveCheckpoint(input) {
             throwIfAborted(input.signal);
@@ -32,6 +36,9 @@ export function createMemoryCheckpointStore(options = {}) {
             }
             const now = new Date().toISOString();
             const value = cloneJson(input.value, "Checkpoint value");
+            if (new TextEncoder().encode(JSON.stringify(value)).length > maxValueBytes) {
+                throw new RangeError(`Checkpoint value exceeds maxValueBytes (${maxValueBytes})`);
+            }
             const metadata = input.metadata === undefined ? undefined : cloneJson(input.metadata, "Checkpoint metadata");
             const record = {
                 namespace: input.namespace,
@@ -45,7 +52,12 @@ export function createMemoryCheckpointStore(options = {}) {
                 updatedAt: now,
                 ...(metadata === undefined ? {} : { metadata }),
             };
+            // delete+set moves an updated record to the end, keeping Map order = least- to
+            // most-recently-saved, so capacity eviction is O(1) off the front.
+            records.delete(id);
             records.set(id, record);
+            while (records.size > maxRecords)
+                records.delete(records.keys().next().value);
             return record;
         },
         async loadCheckpoint(input) {

package/dist/cli-runner.d.ts

@@ -9,10 +9,6 @@ export interface CliOptions {
     readonly provider?: string;
     readonly model?: string;
     readonly session?: string;
-    readonly config: readonly string[];
-    readonly resources: readonly string[];
-    readonly extensions: readonly string[];
-    readonly tools: readonly string[];
     readonly system?: string;
     readonly context: readonly string[];
     readonly compact?: number;
@@ -67,7 +63,7 @@ export interface CliRuntime {
     /** Working directory for relative `prism init` destinations (tests). */
     readonly cwd?: string;
 }
-export declare const usage = "Usage: prism [--mode print|json|rpc] [-p prompt] [options]\n       prism init <dir> [--provider <name>] [--with-workflows] [--with-evals] [--force]\n\nOptions:\n  -p, --prompt <text>        Prompt to run in print/json mode\n  --provider <name>          Explicit provider id (mock is built in for smoke tests)\n  --model <name>             Explicit model name\n  --session <id>             Session id\n  --config <path>            Explicit config path (recorded, not auto-loaded)\n  --resource <uri>           Explicit resource URI (recorded, not auto-loaded)\n  --extension <name>         Explicit extension name (recorded, not auto-loaded)\n  --tool <name>              Explicit tool name (recorded, not auto-enabled)\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> [--provider <name>] [--with-workflows] [--with-evals] [--force]\n\nOptions:\n  -p, --prompt <text>        Prompt to run in print/json mode\n  --provider <name>          Explicit provider id (mock is built in for smoke tests)\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 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

@@ -19,10 +19,6 @@ Options:
   --provider <name>          Explicit provider id (mock is built in for smoke tests)
   --model <name>             Explicit model name
   --session <id>             Session id
-  --config <path>            Explicit config path (recorded, not auto-loaded)
-  --resource <uri>           Explicit resource URI (recorded, not auto-loaded)
-  --extension <name>         Explicit extension name (recorded, not auto-loaded)
-  --tool <name>              Explicit tool name (recorded, not auto-enabled)
   --system <text>            System instructions
   --context <text>           Context text
   --compact <entries>        Auto-compaction threshold
@@ -43,10 +39,6 @@ const valueFlags = new Set([
     "--provider",
     "--model",
     "--session",
-    "--config",
-    "--resource",
-    "--extension",
-    "--tool",
     "--system",
     "--context",
     "--compact",
@@ -59,6 +51,9 @@ const valueFlags = new Set([
     "--agents-config",
 ]);
 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 ALL_KINDS = ["skill", "tool", "context", "instructions"];
 export function parseCliArgs(argv) {
     let mode = "print";
@@ -78,10 +73,6 @@ export function parseCliArgs(argv) {
     let agentsMdFile;
     let systemMdFile;
     let agentsConfig;
-    const config = [];
-    const resources = [];
-    const extensions = [];
-    const tools = [];
     const context = [];
     const instructions = [];
     const injectorFiles = [];
@@ -92,6 +83,8 @@ export function parseCliArgs(argv) {
             continue;
         }
         const name = flag === "-p" ? "--prompt" : flag;
+        if (unsupportedFlags.has(name))
+            throw new CliUsageError(`${name} is not supported in this build`);
         if (boolFlags.has(name)) {
             switch (name) {
                 case "--discover":
@@ -133,18 +126,6 @@ export function parseCliArgs(argv) {
             case "--session":
                 session = value;
                 break;
-            case "--config":
-                config.push(value);
-                break;
-            case "--resource":
-                resources.push(value);
-                break;
-            case "--extension":
-                extensions.push(value);
-                break;
-            case "--tool":
-                tools.push(value);
-                break;
             case "--system":
                 system = value;
                 break;
@@ -183,10 +164,6 @@ export function parseCliArgs(argv) {
         provider,
         model,
         session,
-        config,
-        resources,
-        extensions,
-        tools,
         system,
         context,
         compact,

package/dist/context-budget.js

@@ -61,16 +61,19 @@ export function applyContextBudget(options) {
     const skills = [...(options.skills ?? [])].filter((skill) => skill.instructions);
     const tools = options.tools ? [...options.tools] : undefined;
     const omitted = [];
-    const cost = () => measureAll(groups, context, skills, tools);
-    while (overBudget(cost(), budget)) {
+    // Measure once, then subtract each dropped item's own estimate (dropNext computes it
+    // with the same estimators) — avoids an O(n²) re-scan of the full keep-set per drop.
+    const kept = measureAll(groups, context, skills, tools);
+    while (overBudget(kept, budget)) {
         const drop = dropNext(groups, context, skills, layout);
         if (!drop) {
             throw new ContextBudgetError();
         }
+        kept.tokens -= drop.tokenEstimate;
+        kept.bytes -= drop.byteLength;
         if (omitted.length < HARD_MAX_CONTEXT_BUDGET_OMISSIONS)
             omitted.push(drop);
     }
-    const kept = cost();
     const reportOmissions = omitted.slice(0, DEFAULT_MAX_CONTEXT_BUDGET_OMISSIONS);
     return {
         groups,

package/dist/contracts.d.ts

@@ -15,6 +15,9 @@ export interface ErrorInfo {
     readonly name?: string;
     readonly message: string;
     readonly code?: string | number;
+    /** Provider backpressure hint (e.g. from a `Retry-After` header); retry policies
+     *  honor it capped at their own `maxDelayMs`. */
+    readonly retryAfterMs?: number;
     readonly cause?: unknown;
 }
 export type { AudioContent, DocumentContent, FileContent } from "./content.js";
@@ -749,6 +752,13 @@ export type AgentEvent = {
     readonly sessionId: string;
     readonly runId: string;
     readonly size: number;
+} | {
+    /** A steered message was dropped by a terminal input guardrail; the run continues without it. */
+    readonly type: "steer_rejected";
+    readonly sessionId: string;
+    readonly runId: string;
+    readonly message: Message;
+    readonly record: GuardrailRecord;
 } | {
     readonly type: "event_subscriber_overflow";
     readonly sessionId: string;
@@ -937,6 +947,9 @@ export interface PromptBuildRequest {
     readonly context?: readonly ContextBlock[];
     readonly skills?: readonly Skill[];
     readonly tools?: readonly ToolDefinition[];
+    /** Model being prompted; lets builders adapt composition to declared capabilities
+     *  (e.g. the default builder omits the `Available tools:` text for tool-capable models). */
+    readonly model?: ModelConfig;
     readonly metadata?: Readonly<Record<string, unknown>>;
     readonly signal?: AbortSignal;
 }

package/dist/contributions.d.ts

@@ -4,6 +4,8 @@ import { type ProviderRegistry } from "./providers.js";
 import { type DuplicateRegistrationOptions } from "./registry-options.js";
 export interface ContributionRegistry<T> {
     register(key: string, contribution: T): void;
+    /** Remove a contribution; returns false when the key was not registered. */
+    unregister(key: string): boolean;
     get(key: string): T | undefined;
     resolve(key: string): T;
     list(): readonly T[];

package/dist/contributions.js

@@ -9,6 +9,9 @@ export function createContributionRegistry(options = {}) {
             assertCanRegister(byKey, key, label, key, options.duplicate);
             byKey.set(key, contribution);
         },
+        unregister(key) {
+            return byKey.delete(key);
+        },
         get(key) {
             return byKey.get(key);
         },

package/dist/credentials.d.ts

@@ -10,7 +10,13 @@ export interface MemoryCredentialStore extends CredentialResolver {
     delete(request: Pick<CredentialRequest, "name" | "provider">): boolean;
     clear(): void;
 }
-export declare function createMemoryCredentialStore(initial?: readonly CredentialRecord[]): MemoryCredentialStore;
+export interface MemoryCredentialStoreOptions {
+    /** When true (default, backward compatible), a provider-scoped request falls back to a
+     *  providerless record of the same name — that record is then served to EVERY provider.
+     *  Set false for exact-match-only resolution (strict provider scoping). */
+    readonly allowProviderFallback?: boolean;
+}
+export declare function createMemoryCredentialStore(initial?: readonly CredentialRecord[], options?: MemoryCredentialStoreOptions): MemoryCredentialStore;
 export declare function createChainedCredentialResolver(resolvers: readonly CredentialResolver[]): CredentialResolver;
 export declare function createExplicitCredentialResolver(sources: readonly CredentialResolverSource[]): CredentialResolver;
 export declare function createEnvCredentialResolver(env: Readonly<Record<string, string | undefined>>, map: Readonly<Record<string, string>>): CredentialResolver;

package/dist/credentials.js

@@ -1,5 +1,6 @@
-export function createMemoryCredentialStore(initial = []) {
+export function createMemoryCredentialStore(initial = [], options = {}) {
     const records = new Map();
+    const allowProviderFallback = options.allowProviderFallback ?? true;
     const key = (name, provider) => `${provider ?? ""}\u0000${name}`;
     const store = {
         set(record) {
@@ -12,7 +13,10 @@ export function createMemoryCredentialStore(initial = []) {
             records.clear();
         },
         resolve(request) {
-            return records.get(key(request.name, request.provider)) ?? records.get(key(request.name));
+            const exact = records.get(key(request.name, request.provider));
+            if (exact !== undefined || !allowProviderFallback || request.provider === undefined)
+                return exact;
+            return records.get(key(request.name));
         },
     };
     for (const record of initial)

package/dist/event-multiplexer.js

@@ -13,10 +13,21 @@ export function createEventMultiplexer(options = {}) {
         isClosed = true;
     else
         options.signal?.addEventListener("abort", abort, { once: true });
+    // With compare set, publish always enqueues and the parked consumer is woken with
+    // this token instead of a value, so every event drains through the sorted queue —
+    // delivery order follows the comparator even when the consumer is caught up.
+    const WAKE = Symbol("wake");
+    const wakeWaiter = () => {
+        if (!waiter)
+            return;
+        const resolve = waiter;
+        waiter = undefined;
+        resolve({ value: WAKE, done: false });
+    };
     function publish(event) {
         if (isClosed)
             return;
-        if (waiter) {
+        if (!options.compare && waiter) {
             const resolve = waiter;
             waiter = undefined;
             resolve({ value: event, done: false });
@@ -24,6 +35,7 @@ export function createEventMultiplexer(options = {}) {
         }
         if (queue.length < maxQueuedEvents) {
             queue.push(event);
+            wakeWaiter();
             return;
         }
         droppedEvents += 1;
@@ -41,6 +53,7 @@ export function createEventMultiplexer(options = {}) {
         if (overflow === "drop_newest") {
             if (notice !== undefined)
                 queue[queue.length - 1] = notice;
+            wakeWaiter();
             return;
         }
         queue.shift();
@@ -50,6 +63,7 @@ export function createEventMultiplexer(options = {}) {
                 queue.shift();
         }
         queue.push(event);
+        wakeWaiter();
     }
     function observe(source, map) {
         if (isClosed)
@@ -115,6 +129,8 @@ export function createEventMultiplexer(options = {}) {
             });
             if (next.done)
                 return;
+            if (next.value === WAKE)
+                continue;
             yield next.value;
         }
     }

package/dist/extensions.d.ts

@@ -26,11 +26,17 @@ export interface ExtensionEventBus {
     on(type: ExtensionLifecycleEventName | string, handler: ExtensionEventHandler): () => void;
     emit(event: ExtensionEvent): Promise<void>;
 }
+export interface LoadedExtension {
+    readonly name: string;
+    /** Remove this extension's registry contributions and middleware/event subscriptions.
+     *  Best-effort and idempotent; side effects outside the registries are NOT unwound. */
+    dispose(): void;
+}
 export interface ExtensionKernel {
     readonly registries: ContributionRegistries;
     readonly middleware: MiddlewareRegistry;
     readonly events: ExtensionEventBus;
-    load(extensions: readonly Extension[]): Promise<void>;
+    load(extensions: readonly Extension[]): Promise<LoadedExtension[]>;
 }
 export declare function createExtensionEventBus(options?: Pick<ExtensionKernelOptions, "errorPolicy" | "secrets">): ExtensionEventBus;
 export declare function createExtensionKernel(options?: ExtensionKernelOptions): ExtensionKernel;

package/dist/extensions.js

@@ -45,90 +45,148 @@ export function createExtensionKernel(options = {}) {
     const middleware = options.middleware ?? createMiddlewareRegistry({ ...options, onError: events.emit });
     const errorPolicy = options.errorPolicy ?? "event";
     const secrets = options.secrets ?? [];
-    const api = {
+    // Per-extension tracked API: every registration records an undo so a dispose handle
+    // (or a failed setup) can unwind exactly what that extension added.
+    const createApi = (track) => ({
         registries,
         middleware,
-        on: events.on,
+        on(type, handler) {
+            const off = events.on(type, handler);
+            track?.(off);
+            return off;
+        },
         emit: events.emit,
-        use: middleware.use,
+        use(hook, mw) {
+            const off = middleware.use(hook, mw);
+            track?.(off);
+            return off;
+        },
         registerProvider(provider) {
             registries.providers.register(provider);
+            track?.(() => registries.providers.unregister(provider.id));
         },
         registerModel(model) {
             registries.models.register(model);
+            track?.(() => registries.models.unregister(model.provider, model.model));
         },
         registerTool(tool) {
             registries.tools.register(tool.name, tool);
+            track?.(() => registries.tools.unregister(tool.name));
         },
         registerContextProvider(provider) {
             registries.contextProviders.register(provider.name, provider);
+            track?.(() => registries.contextProviders.unregister(provider.name));
         },
         registerSkill(skill) {
             registries.skills.register(skill.name, skill);
+            track?.(() => registries.skills.unregister(skill.name));
         },
         registerCommand(command) {
             registries.commands.register(command.name, command);
+            track?.(() => registries.commands.unregister(command.name));
         },
         registerAgent(agent) {
             registries.agents.register(agent.name, agent);
+            track?.(() => registries.agents.unregister(agent.name));
         },
         registerInputBuilder(builder) {
             registries.inputBuilders.register(builder.name, builder);
+            track?.(() => registries.inputBuilders.unregister(builder.name));
         },
         registerPromptBuilder(builder) {
             registries.promptBuilders.register(builder.name, builder);
+            track?.(() => registries.promptBuilders.unregister(builder.name));
         },
         registerCompactionStrategy(strategy) {
             registries.compactionStrategies.register(strategy.name, strategy);
+            track?.(() => registries.compactionStrategies.unregister(strategy.name));
         },
         registerRetryPolicy(policy) {
             registries.retryPolicies.register(policy.name, policy);
+            track?.(() => registries.retryPolicies.unregister(policy.name));
         },
         registerStoreFactory(factory) {
             registries.storeFactories.register(factory.name, factory);
+            track?.(() => registries.storeFactories.unregister(factory.name));
         },
         registerResourceLoader(key, loader) {
             registries.resourceLoaders.register(key, loader);
+            track?.(() => registries.resourceLoaders.unregister(key));
         },
         registerSettingsProvider(key, provider) {
             registries.settingsProviders.register(key, provider);
+            track?.(() => registries.settingsProviders.unregister(key));
         },
         registerCredentialResolver(key, resolver) {
             registries.credentialResolvers.register(key, resolver);
+            track?.(() => registries.credentialResolvers.unregister(key));
         },
         registerProviderPackage(providerPackage) {
             registries.providerPackages.register(providerPackage.name, providerPackage);
+            track?.(() => registries.providerPackages.unregister(providerPackage.name));
         },
         registerAuthMethod(method) {
-            registries.authMethods.register(authMethodKey(method), method);
+            const key = authMethodKey(method);
+            registries.authMethods.register(key, method);
+            track?.(() => registries.authMethods.unregister(key));
         },
         registerProviderRequestPolicy(policy) {
             registries.providerRequestPolicies.register(policy.name, policy);
+            track?.(() => registries.providerRequestPolicies.unregister(policy.name));
         },
         registerSystemPromptContribution(contribution) {
-            registries.systemPromptContributions.register(systemPromptContributionKey(contribution), contribution);
+            const key = systemPromptContributionKey(contribution);
+            registries.systemPromptContributions.register(key, contribution);
+            track?.(() => registries.systemPromptContributions.unregister(key));
         },
         registerInstructionInjector(injector) {
             registries.instructionInjectors.register(injector.name, injector);
+            track?.(() => registries.instructionInjectors.unregister(injector.name));
         },
+    });
+    const unwind = (undo) => {
+        for (const fn of undo.reverse()) {
+            try {
+                fn();
+            }
+            catch {
+                // best-effort: one stuck undo must not block the rest
+            }
+        }
     };
     return {
         registries,
         middleware,
         events,
         async load(extensions) {
+            const loaded = [];
             for (const extension of extensions) {
+                const undo = [];
                 try {
                     await assertPermission(options.permission, { kind: "extension", action: "setup", target: extension.name });
                     await assertExtensionLoadPolicy(options.loadPolicy, extension);
-                    await extension.setup(api);
+                    await extension.setup(createApi((fn) => undo.push(fn)));
                 }
                 catch (error) {
+                    // A failed setup must not leave partial contributions behind.
+                    unwind(undo);
                     if (errorPolicy === "throw")
                         throw error;
                     await events.emit(extensionError(error, extension.name, secrets));
+                    continue;
                 }
+                let disposed = false;
+                loaded.push({
+                    name: extension.name,
+                    dispose() {
+                        if (disposed)
+                            return;
+                        disposed = true;
+                        unwind(undo);
+                    },
+                });
             }
+            return loaded;
         },
     };
 }