@arnilo/prism 0.0.1

package/dist/skills.js

@@ -0,0 +1,34 @@
+export function createSkillRegistry(skills = []) {
+    const byName = new Map();
+    const registry = {
+        register(skill) {
+            byName.set(skill.name, skill);
+        },
+        get(name) {
+            return byName.get(name);
+        },
+        resolve(name) {
+            const skill = byName.get(name);
+            if (!skill)
+                throw new Error(`Unknown skill: ${name}`);
+            return skill;
+        },
+        list() {
+            return [...byName.values()];
+        },
+    };
+    for (const skill of skills)
+        registry.register(skill);
+    return registry;
+}
+export function resolveActiveSkills(options) {
+    const toolNames = new Set((options.tools ?? []).map((tool) => tool.name));
+    return (options.names ?? []).map((name) => {
+        const skill = options.registry.resolve(name);
+        const missingTool = skill.toolNames?.find((toolName) => !toolNames.has(toolName));
+        if (missingTool)
+            throw new Error(`Skill ${skill.name} requires inactive tool: ${missingTool}`);
+        return skill;
+    });
+}
+//# sourceMappingURL=skills.js.map

package/dist/system-prompts.d.ts

@@ -0,0 +1,6 @@
+import type { SystemPromptConfig } from "./contracts.js";
+export interface ComposeSystemPromptOptions {
+    readonly base?: string | readonly string[];
+}
+export declare function composeSystemPrompt(contributions?: SystemPromptConfig, options?: ComposeSystemPromptOptions): string | undefined;
+export declare function mergeSystemPromptConfig(config: SystemPromptConfig | undefined, override: SystemPromptConfig | undefined): SystemPromptConfig;

package/dist/system-prompts.js

@@ -0,0 +1,47 @@
+const sourceRank = new Map([["package", 0], ["app", 1], ["user", 2], ["run", 3]]);
+export function composeSystemPrompt(contributions = [], options = {}) {
+    const parts = baseParts(options.base);
+    if (contributions === false)
+        return joinPrompt(parts);
+    const layers = [...asContributions(contributions)]
+        .map((layer, index) => ({ layer, index }))
+        .sort((a, b) => rank(a.layer) - rank(b.layer) || a.index - b.index);
+    for (const { layer } of layers) {
+        if (layer.mode === "disable") {
+            parts.length = 0;
+            continue;
+        }
+        if (!layer.text)
+            continue;
+        if (layer.mode === "replace")
+            parts.splice(0, parts.length, layer.text);
+        else if (layer.mode === "prepend")
+            parts.unshift(layer.text);
+        else
+            parts.push(layer.text);
+    }
+    return joinPrompt(parts);
+}
+export function mergeSystemPromptConfig(config, override) {
+    if (override === false)
+        return config ? [] : [];
+    return [...asContributions(config), ...asContributions(override)];
+}
+function asContributions(value) {
+    if (value === undefined || value === false)
+        return [];
+    return isContributionArray(value) ? value : [value];
+}
+function isContributionArray(value) {
+    return Array.isArray(value);
+}
+function baseParts(base) {
+    return (typeof base === "string" ? [base] : base ?? []).filter((text) => text.length > 0);
+}
+function rank(layer) {
+    return sourceRank.get(layer.source ?? "") ?? 10;
+}
+function joinPrompt(parts) {
+    return parts.length ? parts.join("\n\n") : undefined;
+}
+//# sourceMappingURL=system-prompts.js.map

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

@@ -0,0 +1,36 @@
+import type { AIProvider, ContentBlock, JsonObject, ProviderEvent, ProviderRequest, ToolCallContent, Usage } from "../contracts.js";
+export interface ProviderStreamConformanceOptions {
+    readonly provider: AIProvider;
+    readonly request: ProviderRequest;
+    readonly expect?: {
+        readonly text?: string;
+        readonly usage?: Usage;
+    };
+}
+export interface ProviderAbortConformanceOptions {
+    readonly provider: AIProvider;
+    readonly request: Omit<ProviderRequest, "signal"> & {
+        readonly signal?: AbortSignal;
+    };
+    readonly reason?: unknown;
+}
+export interface ToolCallDeltaExpectation {
+    readonly index: number;
+    readonly id?: string;
+    readonly name?: string;
+    readonly arguments?: JsonObject;
+}
+export interface SerializedContentCoverageOptions {
+    readonly unsupported?: readonly ContentBlock["type"][];
+}
+export interface ProviderSecretLeakConformanceOptions {
+    readonly events: readonly ProviderEvent[];
+    readonly secrets: readonly string[];
+}
+export declare function collectProviderEvents(provider: AIProvider, request: ProviderRequest): Promise<readonly ProviderEvent[]>;
+export declare function assertProviderStreamConforms(options: ProviderStreamConformanceOptions): Promise<readonly ProviderEvent[]>;
+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 assertNoSecretLeak(events: readonly ProviderEvent[], secrets: readonly string[]): void;
+export declare function assertUsageAccounting(events: readonly ProviderEvent[], expected: Usage): Usage;

package/dist/testing/provider-conformance.js

@@ -0,0 +1,164 @@
+export async function collectProviderEvents(provider, request) {
+    const events = [];
+    for await (const event of provider.generate(request))
+        events.push(event);
+    return events;
+}
+export async function assertProviderStreamConforms(options) {
+    const events = await collectProviderEvents(options.provider, options.request);
+    const terminal = events.at(-1);
+    if (!terminal || (terminal.type !== "done" && terminal.type !== "error"))
+        throw new Error("Provider stream must end with done or error");
+    if (events.slice(0, -1).some((event) => event.type === "done" || event.type === "error"))
+        throw new Error("Provider stream terminal event must be last");
+    if (options.expect?.text !== undefined && textFrom(events) !== options.expect.text)
+        throw new Error(`Provider text mismatch: expected ${JSON.stringify(options.expect.text)}`);
+    if (options.expect?.usage)
+        assertUsageAccounting(events, options.expect.usage);
+    return events;
+}
+export async function assertAbortIsObserved(options) {
+    const controller = new AbortController();
+    controller.abort(options.reason ?? new Error("aborted"));
+    let rejected = false;
+    try {
+        await collectProviderEvents(options.provider, { ...options.request, signal: controller.signal });
+    }
+    catch {
+        rejected = true;
+    }
+    if (!rejected)
+        throw new Error("Provider did not observe an already-aborted signal");
+}
+export function assertToolCallDeltasReconstruct(events, expected) {
+    const calls = reconstructToolCallDeltas(events);
+    for (const item of expected) {
+        const call = calls[item.index];
+        if (!call)
+            throw new Error(`Missing tool call at index ${item.index}`);
+        if (item.id !== undefined && call.id !== item.id)
+            throw new Error(`Tool call id mismatch at index ${item.index}`);
+        if (item.name !== undefined && call.name !== item.name)
+            throw new Error(`Tool call name mismatch at index ${item.index}`);
+        if (item.arguments !== undefined && JSON.stringify(call.arguments) !== JSON.stringify(item.arguments))
+            throw new Error(`Tool call arguments mismatch at index ${item.index}`);
+    }
+    return calls;
+}
+export function assertSerializedRequestCoversContent(request, body, options = {}) {
+    const unsupported = new Set(options.unsupported ?? []);
+    const bodyText = JSON.stringify(body);
+    for (const message of request.messages) {
+        for (const block of message.content) {
+            if (unsupported.has(block.type))
+                continue;
+            const canaries = contentBlockCanaries(block);
+            if (canaries.length === 0)
+                continue;
+            const missing = canaries.filter((canary) => !bodyText.includes(canary));
+            if (missing.length > 0) {
+                throw new Error(`Serialized request dropped ${block.type} content; missing canaries: ${JSON.stringify(missing)}`);
+            }
+        }
+    }
+}
+export function assertNoSecretLeak(events, secrets) {
+    const eventText = JSON.stringify(events);
+    for (const secret of secrets) {
+        if (!secret)
+            continue;
+        if (eventText.includes(secret))
+            throw new Error(`Secret leaked into provider events: ${secret.slice(0, 8)}...`);
+    }
+}
+export function assertUsageAccounting(events, expected) {
+    const usage = [...events].reverse().find((event) => event.type === "done" && event.usage || event.type === "usage");
+    const actual = usage?.type === "usage" ? usage.usage : usage?.usage;
+    if (!actual)
+        throw new Error("Provider stream did not include usage");
+    for (const key of ["inputTokens", "outputTokens", "totalTokens", "cacheReadTokens", "cacheWriteTokens"]) {
+        if (expected[key] !== undefined && actual[key] !== expected[key])
+            throw new Error(`Usage ${key} mismatch: expected ${expected[key]}, got ${actual[key]}`);
+    }
+    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":
+            return block.text ? [block.text] : [];
+        case "thinking":
+            return block.text ? [block.text] : [];
+        case "image":
+            return [block.url, block.data, block.mimeType].filter((value) => typeof value === "string" && value.length > 0);
+        case "tool_call":
+            return [block.id, block.name, ...jsonPrimitives(block.arguments)];
+        case "tool_result": {
+            const values = [block.toolCallId, block.name, ...jsonPrimitives(block.result), ...jsonPrimitives(block.error)];
+            return values.filter((value) => typeof value === "string" && value.length > 0);
+        }
+        default:
+            return [];
+    }
+}
+function jsonPrimitives(value) {
+    const primitives = [];
+    const seen = new Set();
+    function walk(current) {
+        if (seen.has(current))
+            return;
+        if (current && typeof current === "object") {
+            seen.add(current);
+            if (Array.isArray(current)) {
+                for (const item of current)
+                    walk(item);
+            }
+            else {
+                for (const item of Object.values(current))
+                    walk(item);
+            }
+        }
+        else if (typeof current === "string" && current.length > 0) {
+            primitives.push(current);
+        }
+        else if (typeof current === "number" || typeof current === "boolean") {
+            primitives.push(String(current));
+        }
+    }
+    walk(value);
+    return primitives;
+}
+function textFrom(events) {
+    return events.map((event) => event.type === "content_delta" && event.content.type === "text" ? event.content.text : "").join("");
+}
+//# sourceMappingURL=provider-conformance.js.map

package/dist/tools.d.ts

@@ -0,0 +1,25 @@
+import type { AgentEvent, ErrorInfo, JsonObject, ToolCallContent, ToolDefinition, ToolExecutionContext, ToolRegistry, ToolResult } from "./contracts.js";
+import type { MiddlewareRegistry } from "./middleware.js";
+import { type SecretRedactor } from "./redaction.js";
+import { type PermissionPolicy } from "./security.js";
+export interface ToolFilter {
+    readonly allow?: readonly string[];
+    readonly deny?: readonly string[];
+}
+export type ToolFilterInput = ToolFilter | readonly ToolFilter[];
+export type ToolValidator = (tool: ToolDefinition, args: JsonObject, context: ToolExecutionContext) => void | string | ErrorInfo | Promise<void | string | ErrorInfo>;
+export interface DispatchToolCallOptions {
+    readonly call: ToolCallContent;
+    readonly registry: ToolRegistry;
+    readonly context: ToolExecutionContext;
+    readonly filter?: ToolFilterInput;
+    readonly middleware?: MiddlewareRegistry;
+    readonly validate?: ToolValidator;
+    readonly emit?: (event: AgentEvent) => void | Promise<void>;
+    readonly secrets?: readonly (string | undefined)[];
+    readonly permission?: PermissionPolicy;
+    readonly redactor?: SecretRedactor;
+}
+export declare function createToolRegistry(tools?: readonly ToolDefinition[]): ToolRegistry;
+export declare function filterTools(tools: readonly ToolDefinition[], filter?: ToolFilterInput): readonly ToolDefinition[];
+export declare function dispatchToolCall(options: DispatchToolCallOptions): Promise<ToolResult>;

package/dist/tools.js

@@ -0,0 +1,109 @@
+import { isJsonObject } from "./config.js";
+import { errorToErrorInfo, redactSecrets } from "./redaction.js";
+import { assertPermission } from "./security.js";
+export function createToolRegistry(tools = []) {
+    const byName = new Map();
+    const registry = {
+        register(tool) {
+            byName.set(tool.name, tool);
+        },
+        get(name) {
+            return byName.get(name);
+        },
+        resolve(name) {
+            const tool = byName.get(name);
+            if (!tool)
+                throw new Error(`Unknown tool: ${name}`);
+            return tool;
+        },
+        list() {
+            return [...byName.values()];
+        },
+    };
+    for (const tool of tools)
+        registry.register(tool);
+    return registry;
+}
+export function filterTools(tools, filter) {
+    const filters = Array.isArray(filter) ? filter : filter ? [filter] : [];
+    const denied = new Set(filters.flatMap((item) => item.deny ?? []));
+    const allows = filters.map((item) => item.allow?.length ? new Set(item.allow) : undefined).filter((item) => Boolean(item));
+    return tools.filter((tool) => !denied.has(tool.name) && allows.every((allow) => allow.has(tool.name)));
+}
+export async function dispatchToolCall(options) {
+    const secrets = options.secrets ?? [];
+    const precheck = await checkCall(options.call, options);
+    if (precheck)
+        return precheck;
+    const mediatedCall = await (options.middleware?.run("tool_call", options.call) ?? options.call);
+    const tool = options.registry.get(mediatedCall.name);
+    const postcheck = await checkCall(mediatedCall, options);
+    if (postcheck)
+        return postcheck;
+    const context = {
+        ...options.context,
+        toolCallId: mediatedCall.id,
+        progress: async (progress, metadata) => {
+            await options.context.progress?.(progress, metadata);
+            await options.emit?.({
+                type: "tool_execution_progress",
+                sessionId: options.context.sessionId,
+                runId: options.context.runId,
+                toolCallId: mediatedCall.id,
+                name: mediatedCall.name,
+                progress,
+                metadata,
+            });
+        },
+    };
+    try {
+        await assertPermission(options.permission, { kind: "tool", action: "execute", target: mediatedCall.name, metadata: options.context.metadata });
+    }
+    catch (error) {
+        return blocked(mediatedCall, context, "permission_denied", errorToErrorInfo(error, secrets), options.emit);
+    }
+    const validation = await options.validate?.(tool, mediatedCall.arguments, context);
+    if (validation)
+        return blocked(mediatedCall, context, "validation_failed", toErrorInfo(validation, secrets), options.emit);
+    await options.emit?.({ type: "tool_execution_started", sessionId: context.sessionId, runId: context.runId, call: mediatedCall });
+    try {
+        const raw = await tool.execute(mediatedCall.arguments, context);
+        const mediatedResult = await (options.middleware?.run("tool_result", raw) ?? raw);
+        const result = options.redactor?.redact(mediatedResult) ?? mediatedResult;
+        await options.emit?.({ type: "tool_execution_finished", sessionId: context.sessionId, runId: context.runId, result });
+        return result;
+    }
+    catch (error) {
+        const info = errorToErrorInfo(error, secrets);
+        const result = { toolCallId: mediatedCall.id, name: mediatedCall.name, error: info };
+        await options.emit?.({ type: "tool_execution_error", sessionId: context.sessionId, runId: context.runId, call: mediatedCall, error: info });
+        return result;
+    }
+}
+async function checkCall(call, options) {
+    const context = options.context;
+    const tool = options.registry.get(call.name);
+    if (!tool)
+        return blocked(call, context, "unknown_tool", { message: `Unknown tool: ${call.name}` }, options.emit);
+    if (filterTools([tool], options.filter).length === 0)
+        return blocked(call, context, "tool_denied", { message: `Tool denied: ${call.name}` }, options.emit);
+    if (!isJsonObject(call.arguments))
+        return blocked(call, context, "invalid_arguments", { message: "Tool arguments must be a JSON object" }, options.emit);
+    return undefined;
+}
+async function blocked(call, context, reason, error, emit) {
+    await emit?.({
+        type: "tool_execution_blocked",
+        sessionId: context.sessionId,
+        runId: context.runId,
+        toolCallId: call.id,
+        name: call.name,
+        reason,
+        error,
+    });
+    return { toolCallId: call.id, name: call.name, error };
+}
+function toErrorInfo(value, secrets) {
+    return typeof value === "string" ? errorToErrorInfo(value, secrets) : redactSecrets(value, secrets);
+}
+//# sourceMappingURL=tools.js.map

package/docs/agent-session-runtime.md

@@ -0,0 +1,167 @@
+# Agent/session runtime
+
+## What it does
+
+The agent/session runtime adds the minimal shared SDK surface for running provider turns, dispatching complete host-owned tool calls, and subscribing to session events:
+
+- `createAgent(config)`
+- `createAgentSession(config)`
+- `agent.createSession(config)`
+- `session.run(input, options)`
+- `session.prompt(input, options)`
+- `session.compact(options?)`
+- `session.subscribe()`
+- `session.abort()`
+- `session.entries()`
+- `session.checkout(leafId?)`
+- `session.fork(options?)`
+- `session.clone(options?)`
+
+The runtime streams provider text/tool-call content into `AgentEvent` values. Complete `tool_call` events are dispatched through the active host `ToolRegistry`, then returned as tool-result messages on the next provider turn. When a store is supplied, user, assistant, tool-result, and model-change entries are appended under the current branch leaf. Abort propagation and run exclusivity use native `AbortController`.
+
+## When to use it
+
+Use this runtime when a host already has an explicit `AIProvider` and wants to run a prompt through Prism's default input/prompt assembly, optionally execute selected host tools, and observe normalized session events.
+
+Do not use it as a CLI/RPC adapter, whole-run retry framework, vector memory engine, provider registry, credential resolver, or app-tool pack.
+
+## Inputs / request
+
+```ts
+createAgent(config: AgentConfig): Agent
+createAgentSession(config: AgentSessionConfig & { agent: Agent }): AgentSession
+```
+
+`AgentConfig.provider` must contain the host-selected provider. Prism does not resolve providers from hidden globals.
+
+`session.run(input, options)` accepts the existing Prism input shape:
+
+```ts
+string | Message | readonly Message[]
+```
+
+`AgentSessionConfig.store` overrides `AgentConfig.store`; otherwise the session gets a private memory store. `AgentSessionConfig.leafId` selects the branch leaf to resume from.
+
+`RunOptions.model` can override the request model for a run. Model overrides append a `model_change` entry. `AgentConfig.providerOptions`/`RunOptions.providerOptions` supply generic provider request options. `AgentConfig.providerRequestPolicies`/`RunOptions.providerRequestPolicies` run before `AIProvider.generate()` and before `provider_request` middleware. `AgentConfig.systemPrompt` and `RunOptions.systemPrompt` add explicit layered system prompt contributions; `RunOptions.systemPrompt: false` disables configured prompt layers for that run while keeping `AgentConfig.instructions` as the base path. `RunOptions.compaction` can enable auto-compaction for that run or use `false` to disable configured auto-compaction. `RunOptions.retry` can enable provider-turn retry for that run or use `false` to disable configured retry. `RunOptions.metadata` is merged with agent/session metadata for assembly, provider requests, and tool contexts. `RunOptions.maxToolRounds` bounds repeated tool turns and defaults to `1`. `RunOptions.signal` is bridged into the per-run abort signal passed to assembly, providers, tools, auto-compaction, and retry backoff.
+
+## Outputs / response / events
+
+`session.subscribe()` returns a live `AsyncIterable<AgentEvent>`. Subscribe before `run()` to observe that run's events.
+
+For a text-only provider turn, the runtime emits:
+
+1. `agent_started`
+2. `turn_started`
+3. `message_started`
+4. `message_delta`
+5. `message_finished`
+6. `turn_finished`
+7. `agent_finished`
+
+For complete tool calls, the runtime emits the assistant `tool_call` as `message_delta`, dispatches sequentially through `dispatchToolCall()`, emits tool execution events, appends a tool-result session entry, adds returned `ToolResult` values to the next provider turn, and stops when the provider returns no tool calls or `maxToolRounds` is reached. The next provider turn therefore receives the assistant `tool_call` followed by the matching role `tool` `tool_result` before any final assistant content.
+
+`session.compact(options?)` runs the selected compaction strategy, appends one `kind: "compaction"` entry under the current leaf, updates the leaf, emits `compaction_started` and `compaction_finished`, and returns the appended `CompactionResult`. If `AgentConfig.compaction` or `RunOptions.compaction` includes `thresholdEntries`, auto-compaction checks once after input/model-change entries are appended and before provider input assembly; `RunOptions.compaction: false` skips that run's auto-compaction.
+
+`entries()` returns the current branch entries. `checkout(leafId?)` moves the session to an existing leaf and rebuilds history. `fork()` returns a session on the same store/session id at the selected leaf without copying entries. `clone({ id })` copies the current branch to a new session id with new entry ids.
+
+Missing providers fail closed: `run()` emits `error` and rejects before calling any provider. Provider `error` events emit session `error` and reject unless configured retry handles a transient provider-turn failure before output. Unknown tools fail closed through the tool harness and do not execute. Tool exceptions emit `tool_execution_error`, return an error `ToolResult`, and may still continue to the next provider turn.
+
+Only one `run()` may be active per session. Concurrent `run()` calls emit `error` and reject immediately; Prism does not queue them. Manual `compact()` also rejects while a run is active.
+
+`session.abort(reason)` aborts the active run. The abort signal is passed to input assembly, provider requests, and tool execution; if a tool/provider path aborts after a tool call, Prism does not start another provider turn.
+
+## Request/response example
+
+```json
+{
+  "input": "Hi",
+  "events": ["agent_started", "turn_started", "message_delta", "agent_finished"],
+  "leafId": "entry_2"
+}
+```
+
+## Implementation example
+
+```ts
+import { createAgent, createMemorySessionStore, createMockProvider, providerDone, providerTextDelta, type ToolDefinition } from "@arnilo/prism";
+
+const echo: ToolDefinition = {
+  name: "echo",
+  execute: (args, context) => ({ toolCallId: context.toolCallId, name: "echo", value: args }),
+};
+
+const store = createMemorySessionStore();
+const agent = createAgent({
+  model: { provider: "mock", model: "demo" },
+  provider: createMockProvider([providerTextDelta("Hello"), providerDone()]),
+  tools: [echo],
+  store,
+});
+
+const session = agent.createSession({ id: "s1" });
+const reader = (async () => {
+  for await (const event of session.subscribe()) console.log(event.type);
+})();
+
+await session.run("Hi", { maxToolRounds: 1, compaction: { thresholdEntries: 20, keepRecentEntries: 6 }, retry: { maxAttempts: 3, baseDelayMs: 50 } });
+await session.compact({ keepRecentEntries: 4 });
+const branch = await session.entries();
+await session.checkout(branch.at(-1)?.id);
+const clone = await session.clone({ id: "s2" });
+await reader;
+```
+
+## Extension and configuration notes
+
+The runtime calls `assembleProviderInput()` on every turn and uses only values supplied on `AgentConfig`: `instructions`, `systemPrompt`, `inputBuilder`, `promptBuilder`, `context`, selected `skills`, active `tools`, `middleware`, `resourceLoader`, metadata, `compaction`, `retry`, and `RunOptions.model`/`systemPrompt`/`compaction`/`retry`. Contributions remain inert until a host passes selected values into the agent config.
+
+The runtime calls `middleware.run("compaction", { context, result })` after a compaction strategy returns and before appending the standard compaction entry. Middleware can adjust the result summary/data, but the runtime still owns store append ordering and branch parent ids.
+
+Provider request policy application is one ordered in-memory pass per provider turn. Policies can patch `ProviderRequest.options` and return exact secret values for provider-error redaction. The runtime then calls `middleware.run("provider_request", request)` once before provider generation.
+
+The runtime calls `middleware.run("retry", { context, decision })` after the retry policy decision and before emitting `retry_scheduled`. Middleware can stop retrying or adjust the delay. Retry wraps only the current provider turn, reuses the same assembled request, and never retries after assistant output has been emitted.
+
+`createAgent()` is a thin wrapper over explicit config. It does not load `AgentConfig.extensions`, scan packages, resolve credentials, read settings, or consult hidden registries. External `AgentDefinition` implementations can call it from their own `create()` method:
+
+```ts
+import { createAgent, createContributionRegistries } from "@arnilo/prism";
+
+const contributions = createContributionRegistries();
+contributions.agents.register("demo", {
+  name: "demo",
+  create: () => createAgent({ model, provider, context: [projectContext], tools: [echo] }),
+});
+
+const agent = await contributions.agents.resolve("demo").create();
+await agent.createSession().run("Hi", { model: overrideModel });
+```
+
+## Security and performance notes
+
+- No hidden provider, tool, credential, resource, settings, or extension globals are created.
+- Unknown providers fail before provider streaming.
+- Unknown, denied, or malformed tool calls fail closed through `dispatchToolCall()`.
+- Abort uses native `AbortController`/`AbortSignal` only; no polling, queue, or dependency is added. Retry backoff uses native abort-aware timers only when configured.
+- Concurrent runs fail fast instead of creating a scheduler.
+- System prompt composition uses caller-supplied strings only; Prism does not discover `SYSTEM.md`, settings, manifests, packages, or prompt files.
+- Provider request policies are in-memory only; they add no cache store, tokenizer, filesystem, network, or worker.
+- Cache keys should be safe caller/session identifiers, not prompt text or credential values.
+- Retry context contains session/run ids, attempt, redacted error info, optional metadata, and signal only; it excludes provider request messages/content, provider objects, credentials, credential resolvers, settings, and hidden metadata.
+- Compaction context contains branch entries and explicit compaction options only; it does not include provider objects, provider requests, credential resolvers, resolved credentials, settings, or hidden metadata.
+- Store entries contain explicit session data only; Prism does not store provider objects, credential resolvers, resolved credentials, full provider requests, settings, or hidden metadata.
+- Runtime events contain messages/content only; do not put secrets in prompts, metadata, provider events, session entries, or docs examples.
+- The event broadcaster is in-memory and live-only. It adds no dependency, timer, filesystem/network discovery, worker, or durable queue.
+
+## Related APIs
+
+- [Public contracts](public-contracts.md): `Agent`, `AgentSession`, `RunOptions`, and `AgentEvent` contracts.
+- [Provider layer](provider-layer.md): `AIProvider`, provider events, and `createMockProvider()`.
+- [Input and prompt assembly](input-and-prompt-assembly.md): request assembly used by `session.run()`.
+- [System prompts](system-prompts.md): layered prompt composition used before default input assembly.
+- [Session stores and branching](session-stores-and-branching.md): `SessionStore`, memory store, branch helpers, and context rebuild.
+- [Compaction and retry policies](compaction-and-retry.md): compaction strategy/config APIs used by `session.compact()` and auto-compaction, plus retry policy/config APIs.
+- [Tools](tools.md): host-owned tool harness used by the bounded runtime tool loop.
+- [Middleware hooks](middleware-hooks.md): hooks that configured assembly/runtime can run.
+- [CLI/RPC](cli-rpc.md): terminal and JSONL adapters over this runtime.
+
+`AgentConfig.redactor` and `RunOptions.redactor` redact exact known secret strings from provider requests, emitted events, and stored session entries. Redaction is opt-in and exact-match only.

package/docs/api-page-template.md

@@ -0,0 +1,32 @@
+# <API name>
+
+## What it does
+<Small description of what the API does.>
+
+## When to use it
+<When an app/package/extension should use this API.>
+
+## Inputs / request
+<Field table or typed shape.>
+
+## Outputs / response / events
+<Field table, return type, events, or side effects.>
+
+## Request/response example
+```json
+<minimal example payload or config>
+```
+
+## Implementation example
+```ts
+<minimal working TypeScript example>
+```
+
+## Extension and configuration notes
+<How extensions/plugins/config can replace or contribute behavior.>
+
+## Security and performance notes
+<Secrets, permissions, trust boundaries, resource use, latency, limits.>
+
+## Related APIs
+- `<API or page>`: <relationship>