@arnilo/prism 0.0.1 → 0.0.2

package/dist/rpc.d.ts

@@ -1,6 +1,7 @@
 import type { Readable, Writable } from "node:stream";
-import type { AgentSession, CommandDefinition } from "./contracts.js";
-export type RpcCommandName = "prompt" | "steer" | "followUp" | "abort" | "state" | "messages" | "setModel" | "compact" | "switchSession" | "forkSession" | "cloneSession" | "command";
+import type { AgentSession, CommandDefinition, InstructionInjector } from "./contracts.js";
+import type { ContributionRegistry } from "./contributions.js";
+export type RpcCommandName = "prompt" | "steer" | "followUp" | "abort" | "state" | "messages" | "setModel" | "compact" | "switchSession" | "forkSession" | "cloneSession" | "checkout" | "command";
 export interface RpcRequest {
     readonly id: string | number;
     readonly command: RpcCommandName;
@@ -9,6 +10,9 @@ export interface RpcRequest {
 export interface RpcSessionFactory {
     createSession(id?: string): AgentSession;
     readonly commands?: readonly CommandDefinition[];
+    /** Optional registry for resolving `instructionInjectors` names in `prompt`/`followUp`
+     *  params (Phase 30). Names resolve fail-closed. */
+    readonly instructionInjectors?: ContributionRegistry<InstructionInjector>;
 }
 export interface RpcServerOptions extends RpcSessionFactory {
     readonly stdin: Readable;

package/dist/rpc.js

@@ -1,12 +1,15 @@
 import { createInterface } from "node:readline";
 import { errorToErrorInfo } from "./redaction.js";
+import { resolveInstructionInjectors } from "./instruction-injection.js";
 export async function runRpcServer(options) {
     const first = options.createSession();
     const state = {
         current: first,
+        currentHandleId: first.id,
         sessions: new Map([[first.id, first]]),
         commands: new Map((options.commands ?? []).map((command) => [command.name, command])),
         createSession: options.createSession,
+        ...(options.instructionInjectors ? { instructionInjectors: options.instructionInjectors } : {}),
     };
     const activeRuns = new Map();
     const lines = createInterface({ input: options.stdin, crlfDelay: Infinity });
@@ -58,10 +61,14 @@ async function handleRequest(request, state, stdout, activeRuns) {
                 write(stdout, { id: request.id, ok: false, error: errorToErrorInfo(new Error(`Session ${session.id} already has an active run for request ${existing.requestId}`)) });
                 return;
             }
+            // ponytail: Phase 30 — resolve run options (incl. instructionInjectors names) BEFORE opening the
+            // event pump. A fail-closed name resolution throws here, surfaces as an error response via the
+            // outer try/catch, and never strands the event subscription's for-await.
+            const runOpts = runOptions(state, request.params);
             const events = pumpEvents(session, stdout, request.id);
             const promise = (async () => {
                 try {
-                    await session.run(input, runOptions(state, request.params));
+                    await session.run(input, runOpts);
                 }
                 finally {
                     await events;
@@ -82,7 +89,16 @@ async function handleRequest(request, state, stdout, activeRuns) {
             write(stdout, { id: request.id, ok: true, result: { sessionId: state.current.id } });
             break;
         case "state":
-            write(stdout, { id: request.id, ok: true, result: { sessionId: state.current.id, sessions: [...state.sessions.keys()], model: state.model } });
+            write(stdout, { id: request.id, ok: true, result: {
+                    sessionId: state.current.id,
+                    leafId: state.current.leafId,
+                    handleId: state.currentHandleId,
+                    // ponytail: `sessions` kept as a backward-compatible handle-id string list (== sessionId
+                    // for the initial session and clones); `handles` is the branch-handle detail view.
+                    sessions: [...state.sessions.keys()],
+                    handles: [...state.sessions.entries()].map(([handleId, session]) => ({ handleId, sessionId: session.id, leafId: session.leafId })),
+                    model: state.model,
+                } });
             break;
         case "messages":
             write(stdout, { id: request.id, ok: true, result: { sessionId: state.current.id, entries: await state.current.entries() } });
@@ -95,26 +111,37 @@ async function handleRequest(request, state, stdout, activeRuns) {
             write(stdout, { id: request.id, ok: true, result: await state.current.compact() });
             break;
         case "switchSession": {
-            const id = stringParam(request.params, "sessionId") ?? stringParam(request.params, "id");
-            if (!id)
-                throw new Error("switchSession requires params.sessionId");
-            const session = state.sessions.get(id) ?? makeSession(state, id);
+            const handleId = stringParam(request.params, "handleId") ?? stringParam(request.params, "sessionId") ?? stringParam(request.params, "id");
+            if (!handleId)
+                throw new Error("switchSession requires params.handleId (or sessionId)");
+            const session = state.sessions.get(handleId) ?? makeSession(state, handleId);
             state.current = session;
-            write(stdout, { id: request.id, ok: true, result: { sessionId: session.id } });
+            state.currentHandleId = handleId;
+            write(stdout, { id: request.id, ok: true, result: { sessionId: session.id, leafId: session.leafId, handleId } });
             break;
         }
         case "forkSession": {
             const session = state.current.fork({ leafId: stringParam(request.params, "leafId") });
-            state.sessions.set(session.id, session);
+            const handleId = registerSession(state, session);
             state.current = session;
-            write(stdout, { id: request.id, ok: true, result: { sessionId: session.id } });
+            state.currentHandleId = handleId;
+            write(stdout, { id: request.id, ok: true, result: { sessionId: session.id, leafId: session.leafId, handleId } });
             break;
         }
         case "cloneSession": {
             const session = await state.current.clone({ id: stringParam(request.params, "id"), leafId: stringParam(request.params, "leafId") });
-            state.sessions.set(session.id, session);
+            const handleId = registerSession(state, session);
             state.current = session;
-            write(stdout, { id: request.id, ok: true, result: { sessionId: session.id } });
+            state.currentHandleId = handleId;
+            write(stdout, { id: request.id, ok: true, result: { sessionId: session.id, leafId: session.leafId, handleId } });
+            break;
+        }
+        case "checkout": {
+            const leafId = stringParam(request.params, "leafId");
+            if (!leafId)
+                throw new Error("checkout requires params.leafId");
+            await state.current.checkout(leafId);
+            write(stdout, { id: request.id, ok: true, result: { sessionId: state.current.id, leafId: state.current.leafId, handleId: state.currentHandleId } });
             break;
         }
         case "command": {
@@ -142,13 +169,38 @@ function eventEnvelope(event, requestId) {
     const runId = "runId" in event ? event.runId : undefined;
     return { type: "event", id: requestId, sessionId, runId, event };
 }
+function registerSession(state, session, preferredHandleId) {
+    const base = preferredHandleId ?? session.id;
+    // ponytail: branch handles coexist for one sessionId. fork() reuses the sessionId (it is a
+    // branch of the same session, not a copy; clone() is the copy), so on collision we mint a
+    // stable, self-describing handle id (`{sessionId}#2`, `#3`, ...). Clients switch among handles
+    // via the handleId returned by fork/clone/switch; the (sessionId, leafId) pair is read live
+    // from the session so it stays accurate as the leaf advances on append/run.
+    if (!state.sessions.has(base)) {
+        state.sessions.set(base, session);
+        return base;
+    }
+    let n = 2;
+    while (state.sessions.has(`${base}#${n}`))
+        n++;
+    const handleId = `${base}#${n}`;
+    state.sessions.set(handleId, session);
+    return handleId;
+}
 function makeSession(state, id) {
     const session = state.createSession(id);
     state.sessions.set(session.id, session);
     return session;
 }
 function runOptions(state, params) {
-    return { model: modelParam(params) ?? state.model, maxToolRounds: numberParam(params, "maxToolRounds") };
+    const names = stringArrayParam(params, "instructionInjectors");
+    // ponytail: fail-closed — unknown name throws (caller surfaces as RPC error), matching CLI.
+    const injectors = names.length ? resolveInstructionInjectors({ registry: state.instructionInjectors, names }) : undefined;
+    return {
+        model: modelParam(params) ?? state.model,
+        maxToolRounds: numberParam(params, "maxToolRounds"),
+        ...(injectors ? { instructionInjectors: injectors } : {}),
+    };
 }
 function modelParam(params) {
     if (!params)
@@ -172,11 +224,17 @@ function objectParam(params, key) {
     const value = params?.[key];
     return isObject(value) ? value : undefined;
 }
+function stringArrayParam(params, key) {
+    const value = params?.[key];
+    if (!Array.isArray(value))
+        return [];
+    return value.filter((v) => typeof v === "string");
+}
 function isObject(value) {
     return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
 function isCommand(value) {
-    return typeof value === "string" && ["prompt", "steer", "followUp", "abort", "state", "messages", "setModel", "compact", "switchSession", "forkSession", "cloneSession", "command"].includes(value);
+    return typeof value === "string" && ["prompt", "steer", "followUp", "abort", "state", "messages", "setModel", "compact", "switchSession", "forkSession", "cloneSession", "checkout", "command"].includes(value);
 }
 function readRequestId(value) {
     return isObject(value) && (typeof value.id === "string" || typeof value.id === "number") ? value.id : null;

package/dist/session-stores.d.ts

@@ -1,4 +1,4 @@
-import type { Message, SessionEntry, SessionStore } from "./contracts.js";
+import type { Message, SessionBranchRead, BranchReader, SessionEntry, SessionStore } from "./contracts.js";
 export interface CreateSessionEntryOptions extends Omit<SessionEntry, "id" | "timestamp"> {
     readonly id?: string;
     readonly timestamp?: string;
@@ -19,7 +19,9 @@ export interface SessionContextSnapshot {
     readonly summaries: readonly string[];
 }
 export declare function createSessionEntry(options: CreateSessionEntryOptions): SessionEntry;
+export declare function getSessionBranchEntries(reader: BranchReader, query: SessionBranchRead): Promise<readonly SessionEntry[]>;
 export declare function getSessionBranchEntries(entries: readonly SessionEntry[], options?: SessionBranchOptions): readonly SessionEntry[];
 export declare function listSessionBranches(entries: readonly SessionEntry[]): readonly SessionBranch[];
+export declare function rebuildSessionContext(reader: BranchReader, query: SessionBranchRead): Promise<SessionContextSnapshot>;
 export declare function rebuildSessionContext(entries: readonly SessionEntry[], options?: SessionBranchOptions): SessionContextSnapshot;
 export declare function createMemorySessionStore(initialEntries?: readonly SessionEntry[]): SessionStore;

package/dist/session-stores.js

@@ -1,3 +1,4 @@
+import { SESSION_APPEND_CONFLICT_CODE, SessionAppendConflictError } from "./contracts.js";
 export function createSessionEntry(options) {
     const { createId, now, ...entry } = options;
     return {
@@ -6,7 +7,28 @@ export function createSessionEntry(options) {
         timestamp: entry.timestamp ?? (now?.() ?? new Date()).toISOString(),
     };
 }
-export function getSessionBranchEntries(entries, options = {}) {
+// ponytail: max pages the reader path will follow before stopping. Guards against a buggy/
+// malicious reader that never ends `nextCursor`. Ancestor chains are short in practice; bump
+// this if a legitimate branch exceeds it.
+const MAX_BRANCH_PAGES = 64;
+export function getSessionBranchEntries(input, options = {}) {
+    return typeof input === "function" ? readBranchFromReader(input, options) : getSessionBranchEntriesCore(input, options);
+}
+async function readBranchFromReader(reader, query) {
+    const items = [];
+    let cursor;
+    for (let page = 0; page < MAX_BRANCH_PAGES; page++) {
+        const result = await reader(cursor ? { ...query, cursor } : query);
+        items.push(...result.items);
+        cursor = result.nextCursor;
+        if (!cursor)
+            break;
+    }
+    // Reuse the validated in-memory walk: the reader returns the ancestor SET (any order);
+    // indexEntries + the parentId walk order it and still reject missing parents / dupes.
+    return getSessionBranchEntriesCore(items, { leafId: query.leafId });
+}
+function getSessionBranchEntriesCore(entries, options = {}) {
     const index = indexEntries(entries);
     const leafId = options.leafId ?? entries.at(-1)?.id;
     if (!leafId)
@@ -29,8 +51,20 @@ export function listSessionBranches(entries) {
         .filter((entry) => !index.parentIds.has(entry.id))
         .map((entry) => ({ leafId: entry.id, entries: getSessionBranchEntries(entries, { leafId: entry.id }) }));
 }
-export function rebuildSessionContext(entries, options = {}) {
-    const branch = getSessionBranchEntries(entries, options);
+export function rebuildSessionContext(input, options = {}) {
+    if (typeof input === "function") {
+        return rebuildSessionContextFromReader(input, options);
+    }
+    return rebuildSessionContextCore(input, options);
+}
+async function rebuildSessionContextFromReader(reader, query) {
+    // ponytail: pass the drained branch back through the sync core so compaction logic has ONE
+    // code path; the redundant re-walk is O(branch length) and branch chains are short.
+    const branch = await readBranchFromReader(reader, query);
+    return rebuildSessionContextCore(branch, { leafId: query.leafId });
+}
+function rebuildSessionContextCore(entries, options = {}) {
+    const branch = getSessionBranchEntriesCore(entries, options);
     const compaction = [...branch].reverse().find((entry) => entry.kind === "compaction" && entry.summary && isCompactionEntryData(entry.data));
     if (!compaction || !isCompactionEntryData(compaction.data)) {
         return {
@@ -61,11 +95,13 @@ export function rebuildSessionContext(entries, options = {}) {
 export function createMemorySessionStore(initialEntries = []) {
     const byId = new Map();
     const bySession = new Map();
+    const leafBySession = new Map();
+    const idempotencySeen = new Set();
     for (const entry of initialEntries)
         add(entry);
     return {
-        async append(entry) {
-            add(entry);
+        async append(entry, options) {
+            add(entry, options);
         },
         async list(sessionId) {
             return (bySession.get(sessionId) ?? []).map(cloneEntry);
@@ -75,13 +111,38 @@ export function createMemorySessionStore(initialEntries = []) {
             return entry ? cloneEntry(entry) : undefined;
         },
     };
-    function add(entry) {
+    function add(entry, options) {
+        // ponytail: idempotency dedup keyed on (session, key, expectedParentId) so a
+        // run-level key shared across distinct linear appends (each at a different
+        // parentId) does not collapse them; only an exact retry at the same position
+        // deduplicates. DB adapters may enforce stricter per-key uniqueness.
+        const dedupKey = options?.idempotencyKey
+            ? `${entry.sessionId}\u0000${options.idempotencyKey}\u0000${options.expectedParentId ?? ""}`
+            : undefined;
+        if (dedupKey !== undefined && idempotencySeen.has(dedupKey)) {
+            throw new SessionAppendConflictError({ code: SESSION_APPEND_CONFLICT_CODE, idempotencyDuplicate: true });
+        }
+        // expectedParentId is existence validation (the parent must already be in the
+        // store or be undefined for a root). Tip-CAS is intentionally NOT used: prism
+        // allows branching from any existing leaf (checkout + append), so a stale-but-
+        // existing parent is a valid branch, not a conflict. DB adapters may layer
+        // stricter tip-CAS via unique constraints for linear-only sessions.
+        if (options?.expectedParentId !== undefined && !byId.has(options.expectedParentId)) {
+            throw new SessionAppendConflictError({
+                code: SESSION_APPEND_CONFLICT_CODE,
+                expectedParentId: options.expectedParentId,
+                currentLeafId: leafBySession.get(entry.sessionId),
+            });
+        }
         if (byId.has(entry.id))
             throw new Error(`Duplicate session entry id: ${entry.id}`);
+        if (dedupKey !== undefined)
+            idempotencySeen.add(dedupKey);
         byId.set(entry.id, entry);
         const entries = bySession.get(entry.sessionId) ?? [];
         entries.push(entry);
         bySession.set(entry.sessionId, entries);
+        leafBySession.set(entry.sessionId, entry.id);
     }
 }
 function cloneEntry(entry) {

package/dist/skills.d.ts

@@ -1,8 +1,11 @@
 import type { Skill, SkillRegistry, ToolDefinition } from "./contracts.js";
+import { type DuplicateRegistrationOptions } from "./registry-options.js";
 export interface ResolveActiveSkillsOptions {
     readonly registry: SkillRegistry;
     readonly names?: readonly string[];
     readonly tools?: readonly ToolDefinition[];
 }
-export declare function createSkillRegistry(skills?: readonly Skill[]): SkillRegistry;
+export interface SkillRegistryOptions extends DuplicateRegistrationOptions {
+}
+export declare function createSkillRegistry(skills?: readonly Skill[], options?: SkillRegistryOptions): SkillRegistry;
 export declare function resolveActiveSkills(options: ResolveActiveSkillsOptions): readonly Skill[];

package/dist/skills.js

@@ -1,7 +1,9 @@
-export function createSkillRegistry(skills = []) {
+import { assertCanRegister } from "./registry-options.js";
+export function createSkillRegistry(skills = [], options = {}) {
     const byName = new Map();
     const registry = {
         register(skill) {
+            assertCanRegister(byName, skill.name, "skill", skill.name, options.duplicate);
             byName.set(skill.name, skill);
         },
         get(name) {

package/dist/system-prompts.js

@@ -1,4 +1,8 @@
-const sourceRank = new Map([["package", 0], ["app", 1], ["user", 2], ["run", 3]]);
+// ponytail: Phase 31 — `source: "user"` is the global base layer; `source: "app"` sits above package.
+// Behavioral change from Phase 14: `source: "user"` is now the global base (rank 0), not a high-priority caller override.
+// Unknown custom sources sort after package but before app/run so they cannot override host/run layers.
+const sourceRank = new Map([["user", 0], ["package", 1], ["app", 2], ["run", 3]]);
+const unknownSourceRank = 1.5;
 export function composeSystemPrompt(contributions = [], options = {}) {
     const parts = baseParts(options.base);
     if (contributions === false)
@@ -39,7 +43,7 @@ function baseParts(base) {
     return (typeof base === "string" ? [base] : base ?? []).filter((text) => text.length > 0);
 }
 function rank(layer) {
-    return sourceRank.get(layer.source ?? "") ?? 10;
+    return sourceRank.get(layer.source ?? "") ?? unknownSourceRank;
 }
 function joinPrompt(parts) {
     return parts.length ? parts.join("\n\n") : undefined;

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

@@ -0,0 +1,17 @@
+import type { CompactionStrategy } from "../contracts.js";
+export interface CompactionConformanceOptions {
+    /** Secret strings that must not appear in the summary or returned entries. */
+    readonly secrets?: readonly string[];
+    /** When true, asserts the strategy observes an already-aborted signal. */
+    readonly exerciseAbort?: boolean;
+}
+/**
+ * Assert that a `CompactionStrategy` satisfies the core adapter contract:
+ * `compact()` returns a `CompactionResult` with a non-empty summary, known
+ * secrets are redacted from the summary and any returned entries, and (when
+ * requested) an already-aborted signal is observed. Throws on the first
+ * violation; returns the result when the strategy conforms.
+ */
+export declare function assertCompactionStrategyConforms(strategy: CompactionStrategy, options?: CompactionConformanceOptions): Promise<{
+    summary: string;
+}>;

package/dist/testing/compaction-conformance.js

@@ -0,0 +1,61 @@
+// ponytail: dependency-free conformance helper for the CompactionStrategy
+// adapter contract. The core default strategy and the first-party LLM
+// compaction package both implement CompactionStrategy; adapter authors call
+// this once to assert the summary-result shape, secret redaction, and
+// abort-observation invariants that compaction.test.ts and the LLM
+// compaction package's strategy tests already check. Throws plain Error; no
+// test runner, no network, no real credentials.
+import { createSessionEntry } from "../session-stores.js";
+/**
+ * Assert that a `CompactionStrategy` satisfies the core adapter contract:
+ * `compact()` returns a `CompactionResult` with a non-empty summary, known
+ * secrets are redacted from the summary and any returned entries, and (when
+ * requested) an already-aborted signal is observed. Throws on the first
+ * violation; returns the result when the strategy conforms.
+ */
+export async function assertCompactionStrategyConforms(strategy, options = {}) {
+    const secrets = options.secrets ?? [];
+    const entries = [
+        createSessionEntry({ sessionId: "s", kind: "message", message: { role: "user", content: [{ type: "text", text: `old ${secrets[0] ?? "history"}` }] } }),
+        createSessionEntry({ sessionId: "s", kind: "message", message: { role: "assistant", content: [{ type: "text", text: "recent" }] } }),
+    ];
+    const context = {
+        sessionId: "conformance",
+        entries,
+        keepRecentEntries: 1,
+        trigger: "manual",
+        secrets,
+    };
+    const result = await strategy.compact(context);
+    if (!result.summary || typeof result.summary !== "string") {
+        throw new Error("CompactionStrategy must return a non-empty string summary");
+    }
+    for (const secret of secrets) {
+        if (secret && result.summary.includes(secret)) {
+            throw new Error(`CompactionStrategy leaked a secret into the summary: ${secret.slice(0, 8)}...`);
+        }
+    }
+    if (result.entries) {
+        for (const secret of secrets) {
+            if (secret && JSON.stringify(result.entries).includes(secret)) {
+                throw new Error(`CompactionStrategy leaked a secret into returned entries: ${secret.slice(0, 8)}...`);
+            }
+        }
+    }
+    if (options.exerciseAbort) {
+        const controller = new AbortController();
+        controller.abort(new Error("aborted"));
+        let observed = false;
+        try {
+            await strategy.compact({ ...context, signal: controller.signal });
+        }
+        catch {
+            observed = true;
+        }
+        if (!observed) {
+            throw new Error("CompactionStrategy did not observe an already-aborted signal");
+        }
+    }
+    return { summary: result.summary };
+}
+//# sourceMappingURL=compaction-conformance.js.map

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

@@ -0,0 +1,26 @@
+import type { Extension } from "../contracts.js";
+import { createExtensionKernel, type ExtensionKernel } from "../extensions.js";
+export interface ExtensionConformanceOptions {
+    /**
+     * Secret strings that must be redacted from any setup-error event under the
+     * default `errorPolicy: "event"`. When omitted, error redaction is not
+     * asserted. Ignored under `expectThrow`.
+     */
+    readonly secrets?: readonly string[];
+    /**
+     * When true, asserts that a thrown setup error is rethrown to the caller
+     * (the `errorPolicy: "throw"` opt-in). Use this to confirm the host's throw
+     * policy surfaces setup failures instead of isolating them.
+     */
+    readonly expectThrow?: boolean;
+}
+/**
+ * Assert that an `Extension` satisfies the core adapter contract: `setup` runs
+ * on load, registered contributions land in the inert contribution registries,
+ * and (when a `secrets` list is provided) a failing setup emits a redacted
+ * `extension_error` event under the default event policy, or rethrows under
+ * `expectThrow`. Throws on the first violation; returns the loaded kernel so
+ * the caller can inspect registered contributions.
+ */
+export declare function assertExtensionConforms(extension: Extension, options?: ExtensionConformanceOptions): Promise<ExtensionKernel>;
+export { createExtensionKernel };

package/dist/testing/extension-conformance.js

@@ -0,0 +1,55 @@
+// ponytail: dependency-free conformance helper for the Extension adapter
+// contract. Extension authors call this once to assert their Extension's
+// setup runs, contributions land in the inert registries (no side effects
+// until the host selects them), and setup errors are handled per the kernel's
+// error policy: redacted as `extension_error` events under the default
+// `errorPolicy: "event"`, or rethrown under `errorPolicy: "throw"`. Mirrors
+// the assertions in src/__tests__/extensions.test.ts. Throws plain Error; no
+// test runner, no network.
+import { createExtensionKernel } from "../extensions.js";
+/**
+ * Assert that an `Extension` satisfies the core adapter contract: `setup` runs
+ * on load, registered contributions land in the inert contribution registries,
+ * and (when a `secrets` list is provided) a failing setup emits a redacted
+ * `extension_error` event under the default event policy, or rethrows under
+ * `expectThrow`. Throws on the first violation; returns the loaded kernel so
+ * the caller can inspect registered contributions.
+ */
+export async function assertExtensionConforms(extension, options = {}) {
+    const kernel = createExtensionKernel({ secrets: options.secrets, errorPolicy: options.expectThrow ? "throw" : undefined });
+    await kernel.load([extension]);
+    // setup ran: the extension loaded without rejecting. Contribution registries
+    // are inert by construction (the kernel stores envelopes; it never invokes
+    // provider/tool/skill capabilities until host code resolves and calls them).
+    if (options.expectThrow) {
+        // A second extension that throws must rethrow under errorPolicy: "throw".
+        const failing = { name: "conformance-failing", setup: () => { throw new Error("conformance setup failed"); } };
+        let threw = false;
+        try {
+            await kernel.load([failing]);
+        }
+        catch {
+            threw = true;
+        }
+        if (!threw)
+            throw new Error("Failing extension setup did not rethrow under errorPolicy: throw");
+        return kernel;
+    }
+    if (options.secrets && options.secrets.length > 0) {
+        const secret = options.secrets[0];
+        const failing = { name: "conformance-failing", setup: () => { throw new Error(`boom ${secret}`); } };
+        const errors = [];
+        kernel.events.on("extension_error", (event) => { errors.push(event.error ?? {}); });
+        await kernel.load([failing]);
+        if (errors.length === 0)
+            throw new Error("Failing extension setup did not emit an extension_error event");
+        if (errors[0]?.message?.includes(secret)) {
+            throw new Error("Setup error event leaked a secret instead of redacting it");
+        }
+    }
+    return kernel;
+}
+// Re-export the kernel factory so adapter authors can build a fresh kernel
+// without an extra import when composing custom probes.
+export { createExtensionKernel };
+//# sourceMappingURL=extension-conformance.js.map

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

@@ -23,6 +23,12 @@ export interface ToolCallDeltaExpectation {
 export interface SerializedContentCoverageOptions {
     readonly unsupported?: readonly ContentBlock["type"][];
 }
+export interface ProviderHeaderOwnershipConformanceOptions {
+    /** Provider-owned header names mapped to the authoritative values the provider must set. */
+    readonly owned: Readonly<Record<string, string>>;
+    /** Caller-supplied headers, including attempts to override owned names and non-owned additions. */
+    readonly caller: Readonly<Record<string, string>>;
+}
 export interface ProviderSecretLeakConformanceOptions {
     readonly events: readonly ProviderEvent[];
     readonly secrets: readonly string[];
@@ -32,5 +38,6 @@ export declare function assertProviderStreamConforms(options: ProviderStreamConf
 export declare function assertAbortIsObserved(options: ProviderAbortConformanceOptions): Promise<void>;
 export declare function assertToolCallDeltasReconstruct(events: readonly ProviderEvent[], expected: readonly ToolCallDeltaExpectation[]): readonly ToolCallContent[];
 export declare function assertSerializedRequestCoversContent(request: ProviderRequest, body: unknown, options?: SerializedContentCoverageOptions): void;
+export declare function assertProviderOwnedHeadersWin(captured: Headers, options: ProviderHeaderOwnershipConformanceOptions): void;
 export declare function assertNoSecretLeak(events: readonly ProviderEvent[], secrets: readonly string[]): void;
 export declare function assertUsageAccounting(events: readonly ProviderEvent[], expected: Usage): Usage;

package/dist/testing/provider-conformance.js

@@ -1,3 +1,4 @@
+import { reconstructToolCallDeltas } from "../provider-events.js";
 export async function collectProviderEvents(provider, request) {
     const events = [];
     for await (const event of provider.generate(request))
@@ -62,6 +63,23 @@ export function assertSerializedRequestCoversContent(request, body, options = {}
         }
     }
 }
+export function assertProviderOwnedHeadersWin(captured, options) {
+    const ownedLower = {};
+    for (const [name, expected] of Object.entries(options.owned))
+        ownedLower[name.toLowerCase()] = expected;
+    for (const [name, expected] of Object.entries(ownedLower)) {
+        const actual = captured.get(name);
+        if (actual !== expected)
+            throw new Error(`Caller header overrode provider-owned "${name}": expected ${JSON.stringify(expected)}, got ${JSON.stringify(actual)}`);
+    }
+    for (const [name, callerValue] of Object.entries(options.caller)) {
+        if (Object.prototype.hasOwnProperty.call(ownedLower, name.toLowerCase()))
+            continue;
+        const actual = captured.get(name);
+        if (actual !== callerValue)
+            throw new Error(`Provider dropped non-owned caller header "${name}": expected ${JSON.stringify(callerValue)}, got ${JSON.stringify(actual)}`);
+    }
+}
 export function assertNoSecretLeak(events, secrets) {
     const eventText = JSON.stringify(events);
     for (const secret of secrets) {
@@ -82,37 +100,6 @@ export function assertUsageAccounting(events, expected) {
     }
     return actual;
 }
-function reconstructToolCallDeltas(events) {
-    const partials = new Map();
-    for (const event of events) {
-        if (event.type !== "tool_call_delta")
-            continue;
-        const partial = partials.get(event.index) ?? { argumentsText: "" };
-        if (event.id !== undefined)
-            partial.id = event.id;
-        if (event.name !== undefined)
-            partial.name = event.name;
-        if (event.argumentsText !== undefined)
-            partial.argumentsText += event.argumentsText;
-        partials.set(event.index, partial);
-    }
-    return [...partials.entries()].sort(([a], [b]) => a - b).map(([index, partial]) => {
-        if (!partial.id || !partial.name)
-            throw new Error(`Incomplete tool call delta at index ${index}`);
-        return { type: "tool_call", id: partial.id, name: partial.name, arguments: parseArguments(partial.argumentsText, index) };
-    });
-}
-function parseArguments(text, index) {
-    try {
-        const value = text ? JSON.parse(text) : {};
-        if (!value || typeof value !== "object" || Array.isArray(value))
-            throw new Error("not object");
-        return value;
-    }
-    catch (error) {
-        throw new Error(`Invalid tool call arguments at index ${index}: ${error instanceof Error ? error.message : String(error)}`);
-    }
-}
 function contentBlockCanaries(block) {
     switch (block.type) {
         case "text":

package/dist/testing/session-store-conformance.d.ts

@@ -0,0 +1,20 @@
+import type { SessionStore } from "../contracts.js";
+export interface SessionStoreConformanceOptions {
+    /** Stable session id used for the conformance run; defaults to "conformance". */
+    readonly sessionId?: string;
+    /**
+     * When true, also exercises the optional `readBranchPath` branch-reader path
+     * and asserts it returns the ancestor chain in root-to-leaf order. Skipped
+     * when the store does not implement `readBranchPath`.
+     */
+    readonly exerciseReadBranchPath?: boolean;
+}
+/**
+ * Assert that a `SessionStore` implementation satisfies the core adapter
+ * contract: round-trip append/list, duplicate-entry-id rejection,
+ * `expectedParentId` conflict (with nothing appended), `idempotencyKey`
+ * deduplication, branching from any existing entry (not just the tip), and
+ * distinct linear appends sharing a key are not collapsed. Throws on the first
+ * violation; returns silently when the store conforms.
+ */
+export declare function assertSessionStoreConforms(store: SessionStore, options?: SessionStoreConformanceOptions): Promise<void>;