@arnilo/prism 0.0.1 → 0.0.2

package/docs/structured-output.md

@@ -0,0 +1,247 @@
+# Structured output
+
+## What it does
+
+Structured output in Prism is the `Artifact*` contract seam: a host-defined type `T` threaded through host-supplied `parser` → `validator` → `repairer` callbacks inside the `generateValidateReviseLoop` agent loop. Prism never instantiates `T`. The only way to get typed output from a loop is `ArtifactParser<T>`; Prism has no `WorkflowStep`/`NodeSchema`/`synapta*` types and no domain control-flow vocabulary — the seam is generic over an opaque host `T`.
+
+An artifact loop generates provider text, parses it to `T`, validates `T` against a host schema, and on validation failure runs a repairer to build a follow-up input that asks the model to fix the artifact — repeating up to `maxRevisions` times. The result of every validation and the terminal `artifact_finished`/`artifact_failed` outcomes are observable through `AgentEvent` artifact variants.
+
+## When to use it
+
+Use `generateValidateReviseLoop` (with host `parser`/`validator`/`repairer`) when a run should produce an artifact that must satisfy a host-owned schema before it is considered complete: structured JSON output, a generated file passing lint, a typed response conforming to a Synapta-defined model. Wrap your existing schema/validation library behind the `Artifact*` callbacks.
+
+Do not use it to re-implement provider calls, retry, abort, store, or event emission — those stay runtime-owned and are exposed to the loop only through `LoopContext`. Do not use it for runs that need tool calls during revision turns — use `singleShotLoop` or a custom `AgentLoopStrategy` instead. Do not put Synapta domain types into Prism; map them to `ArtifactValidation` in your callbacks.
+
+## Inputs / request
+
+```ts
+import {
+  createAgent,
+  type ArtifactParser,
+  type ArtifactValidator,
+  type ArtifactRepairer,
+  type ArtifactValidation,
+  type ArtifactContext,
+  type ArtifactParseResult,
+} from "@arnilo/prism";
+```
+
+Host callback contracts (all generic over host `T`; Prism never instantiates `T`):
+
+| Contract | Shape |
+| --- | --- |
+| `ArtifactParser<T>` | `(text: string, ctx: ArtifactContext) => ArtifactParseResult<T> \| Promise<...>` — parse assistant text to a typed value. |
+| `ArtifactValidator<T>` | `(value: T, ctx: ArtifactContext) => ArtifactValidation \| Promise<...>` — return `{ ok: true }` or `{ ok: false, errors }`. |
+| `ArtifactRepairer<T>` | `(value: T \| undefined, failure: ArtifactValidation, ctx: ArtifactContext) => AgentInput \| Promise<...>` — build the revision follow-up input. |
+| `ArtifactValidation` | `{ ok: boolean; errors?: readonly { path?: string; message: string }[]; metadata?: Readonly<Record<string, unknown>> }`. |
+| `ArtifactContext` | `{ sessionId, runId, turn, signal, metadata }` — passed to every callback. |
+| `ArtifactParseResult<T>` | `{ ok: boolean; value?: T; error?: string }`. |
+
+Loop selection (RunOptions wins over AgentConfig):
+
+```ts
+await session.run(input, {
+  loop: {
+    strategy: "generate-validate-revise",
+    validator,         // required
+    parser,            // optional; default treats assistant text as the value
+    repairer,          // optional; default stringifies validation.errors[].message
+    maxRevisions: 3,   // optional; default 3
+  },
+});
+```
+
+## Outputs / response / events
+
+`generateValidateReviseLoop.run(ctx)` returns `Promise<Usage | undefined>`. Observable behavior is emitted through `AgentEvent` artifact variants (zero emitted by `singleShotLoop`):
+
+```
+artifact_validation_started
+  → artifact_validation_finished
+    → (artifact_revision_started)*
+      → artifact_finished | artifact_failed
+```
+
+See [Agent events § Artifact event ordering](agent-events.md#artifact-event-ordering). Validation-failure-triggering-a-revision is recoverable and never an `error`; only terminal budget exhaustion emits `artifact_failed`; real failures stay on `error`.
+
+`ArtifactValidation.errors[].message` may echo model text — every `artifact_*` payload is redacted through `redactAgentEvent` / the active `SecretRedactor` before subscribers observe it.
+
+## Request/response example
+
+```json
+{
+  "ok": false,
+  "errors": [{ "path": "title", "message": "missing required field" }],
+  "metadata": { "schema": "release-note/v1" }
+}
+```
+
+## Implementation example
+
+A Synapta-style host maps its own schema to `ArtifactValidation` via the callbacks — no Synapta type is imported by Prism:
+
+```ts
+import {
+  createAgent,
+  createMockProvider,
+  providerTextDelta,
+  providerDone,
+  createSecretRedactor,
+  type ArtifactParser,
+  type ArtifactValidator,
+  type ArtifactRepairer,
+} from "@arnilo/prism";
+
+// Host owns this schema (Synapta's own type). Prism never imports it.
+interface ReleaseNote { readonly title: string; readonly body: string }
+
+const parser: ArtifactParser<ReleaseNote> = (text) => {
+  try {
+    const value = JSON.parse(text) as ReleaseNote;
+    return { ok: true, value };
+  } catch (error) {
+    return { ok: false, error: error instanceof Error ? error.message : "parse failed" };
+  }
+};
+
+const validator: ArtifactValidator<ReleaseNote> = (value) =>
+  value.title && value.body
+    ? { ok: true }
+    : { ok: false, errors: [{ path: value.title ? "body" : "title", message: "missing field" }] };
+
+const repairer: ArtifactRepairer<ReleaseNote> = (_value, failure) => ({
+  role: "user",
+  content: [{ type: "text", text: `Fix these: ${failure.errors?.map((e) => e.path ? `${e.path}: ${e.message}` : e.message).join("; ")}` }],
+});
+
+const agent = createAgent({
+  model: { provider: "mock", model: "demo" },
+  provider: createMockProvider([
+    providerTextDelta(JSON.stringify({ title: "ok", body: "v1" })),
+    providerDone(),
+  ]),
+  // Redact any leaked secrets from model text echoed in errors[].message/metadata.
+  redactor: createSecretRedactor([process.env.APP_KEY]),
+});
+
+await agent.createSession().run("Produce the JSON release note.", {
+  loop: { strategy: "generate-validate-revise", validator, parser, repairer, maxRevisions: 3 },
+});
+```
+
+## End-to-end third-party integration
+
+A third-party host (for example, Synapta) can mix first-party and own providers, register tools, select skills, load `AGENTS.md`/`SYSTEM.md`, and opt a run into the artifact loop — all without importing any `synapta*` types into Prism and without any `workflow`/`node`/`step` vocabulary in the core contracts.
+
+```ts
+import {
+  createAgent,
+  createProviderResolver,
+  createToolRegistry,
+  createSkillRegistry,
+  createSecretRedactor,
+  type ArtifactParser,
+  type ArtifactValidator,
+  type ArtifactRepairer,
+  type ToolDefinition,
+  type Skill,
+} from "@arnilo/prism";
+import { loadSystemPromptFiles } from "@arnilo/prism/node/system-prompts";
+
+// Host-owned schema (Synapta's own type). Prism never imports it.
+interface ReleaseNote { readonly title: string; readonly body: string }
+
+// Map the host schema to ArtifactValidation. The callbacks are generic at the
+// loop boundary; cast to the host schema inside the callback body.
+const validator: ArtifactValidator<unknown> = (value) => {
+  const note = value as ReleaseNote;
+  const errors: { readonly path?: string; readonly message: string }[] = [];
+  if (!note.title) errors.push({ path: "title", message: "missing title" });
+  if (!note.body) errors.push({ path: "body", message: "missing body" });
+  return errors.length === 0 ? { ok: true } : { ok: false, errors };
+};
+
+const parser: ArtifactParser<unknown> = (text) => {
+  try { return { ok: true, value: JSON.parse(text) as ReleaseNote }; }
+  catch (error) { return { ok: false, error: error instanceof Error ? error.message : "parse failed" }; }
+};
+
+const repairer: ArtifactRepairer<unknown> = (_value, failure) => ({
+  role: "user",
+  content: [{
+    type: "text",
+    text: `Fix these issues: ${failure.errors?.map((e) => e.path ? `${e.path}: ${e.message}` : e.message).join("; ")}`,
+  }],
+});
+
+// Mix a first-party provider with a host-owned one.
+const resolver = createProviderResolver([
+  firstPartyMockProvider, // e.g. from a Prism provider package
+  createOwnMockProvider(), // host-implemented AIProvider
+]);
+
+const tools = createToolRegistry([
+  firstPartyEchoTool,
+  { name: "acme/fetch-schema", /* ...host tool definition... */ } as ToolDefinition,
+]);
+
+const skills = createSkillRegistry([
+  {
+    name: "schema-skill",
+    instructions: "Use the release-note schema and the acme/fetch-schema tool when needed.",
+    toolNames: ["acme/fetch-schema"],
+    // context: [schemaContextProvider],
+  } as Skill,
+]);
+
+const agent = createAgent({
+  model: { provider: "acme", model: "artifact-v1" },
+  providerSource: resolver,
+  tools,
+  skills,
+  instructions: "You are a release-note writer.",
+  systemPrompt: await loadSystemPromptFiles({ workspaceRoot, globalRoot }),
+  redactor: createSecretRedactor([process.env.ACME_API_KEY ?? ""]),
+});
+
+await agent.createSession().run("Write the release note.", {
+  activeSkills: ["schema-skill"],
+  loop: { strategy: "generate-validate-revise", validator, parser, repairer, maxRevisions: 3 },
+});
+```
+
+Key cross-seam points:
+
+- `providerSource` is a resolver, so the host can supply its own `AIProvider` alongside first-party ones. See [Provider packages](provider-packages.md) and [Provider layer](provider-layer.md).
+- `tools` and `skills` are host-owned registries; a skill's `toolNames` and `context` are selected only when the skill is active. See [Tools](tools.md) and [Context and skills](context-and-skills.md).
+- `systemPrompt` is loaded from `AGENTS.md`/`SYSTEM.md` via the Node loader; the runtime itself is file-name agnostic. See [System prompts](system-prompts.md).
+- The `validator`/`parser`/`repairer` callbacks are typed as `Artifact*<unknown>` at the loop boundary; the host's `ReleaseNote` type is cast inside the callback body. Prism threads an opaque value and never instantiates it.
+- Every `artifact_*` event payload is redacted through the active `SecretRedactor`, so secrets echoed in `errors[].message` or `metadata` are scrubbed before subscribers see them. See [Credentials and redaction](credentials-and-redaction.md).
+- For a runnable, network-free version that also demonstrates tool dispatch and redaction, see [`examples/synapta-style-artifact-loop.ts`](../examples/synapta-style-artifact-loop.ts).
+
+## Extension and configuration notes
+
+- `generate-validate-revise` is selected via `AgentConfig.loop` / `RunOptions.loop` (`RunOptions.loop` wins). See [Agent loops](agent-loops.md). `resolveLoop()` maps the options form to the factory; an unknown `strategy` throws before the first turn; a custom `AgentLoopStrategy` instance bypasses the options form.
+- The default parser treats assistant text as the value (`{ ok: true, value: text }`); supply a host parser whenever `T` is not `string`.
+- The default repairer builds a user message from `validation.errors[].message`; supply a host repairer for schema-specific guidance.
+- `maxRevisions` (default 3) bounds revision turns; budget exhaustion ends the loop and emits `artifact_failed` (it does not throw).
+- Tools are not dispatched in revision turns. Hosts needing tools in artifact turns use `singleShotLoop` or a custom loop.
+
+## Security and performance notes
+
+- Prism never instantiates `T`; it only threads the host-supplied value through parser→validator→repairer. No Synapta type is imported by `src/`.
+- Boundary lock: `src/` imports no `synapta*` package, and the `Artifact*` / `AgentLoop*` / `LoopContext` contract field names contain no `workflow`/`node`/`step` domain vocabulary. Hosts map their own schema names to `ArtifactValidation.errors[].path`.
+- `ArtifactValidation.errors[].message` and `metadata` may echo model text; every `artifact_*` event payload is redacted through `redactAgentEvent` / the active `SecretRedactor`. The generic walker handles nested objects/arrays and replaces cyclic references with `"[Circular]"` without throwing.
+- A run makes at most `maxRevisions + 1` provider turns; it cannot loop forever on an always-failing validator. Each revision costs one provider turn plus one store append.
+- No new dependency is required to use structured output — host callbacks wrap whatever schema/validation library the host already uses.
+
+## Related APIs
+- [Agent loops](agent-loops.md): `generateValidateReviseLoop` factory and `LoopContext`.
+- [Agent events](agent-events.md): `artifact_validation_started` / `artifact_validation_finished` / `artifact_revision_started` / `artifact_finished` / `artifact_failed` variants.
+- [Public contracts](public-contracts.md): `ArtifactValidation`, `ArtifactContext`, `ArtifactParseResult<T>`, `ArtifactParser<T>`, `ArtifactValidator<T>`, `ArtifactRepairer<T>`.
+- [Credentials and redaction](credentials-and-redaction.md): `createSecretRedactor` and `redactAgentEvent`.
+- [Agent/session runtime](agent-session-runtime.md): `session.run(input, options)` and `RunOptions.loop`.
+- [Tools](tools.md): host-owned tool registries and dispatch.
+- [Context and skills](context-and-skills.md): skill selection, `toolNames`, and context providers.
+- [System prompts](system-prompts.md): composing layers and loading `AGENTS.md`/`SYSTEM.md`.
+- [Provider packages](provider-packages.md) and [Provider layer](provider-layer.md): mixing first-party and host-owned providers.

package/docs/system-prompts.md

@@ -28,7 +28,9 @@ composeSystemPrompt([
 ], { base: "Base instruction." });
 ```
 
-`source` order is deterministic for known sources: `package`, `app`, `user`, then `run`. Unknown sources keep input order after known sources.
+Known `source` order is deterministic: `user`, `package`, `app`, then `run`. Unknown custom sources sort between `package` and `app`. Multiple unknown sources keep their relative input order. Unknown sources intentionally rank below host/app and run layers, so a custom `replace` or `disable` cannot override `RunOptions.systemPrompt` by sorting after it.
+
+> **Behavior change (Phase 31):** `source: "user"` is now the global base layer (rank 0), not a high-priority caller override. Without unknown custom sources, the file/host layering arrow remains `SYSTEM.md` (user) → package → `AGENTS.md` (app) → host `AgentConfig.systemPrompt` → `RunOptions.systemPrompt` (run). With unknown custom sources, the full layering arrow is `SYSTEM.md` (user) → package → unknown custom sources → `AGENTS.md` (app) → host `AgentConfig.systemPrompt` → `RunOptions.systemPrompt` (run). Earlier phases ranked `user` above `package`/`app`; Phase 37 moved unknown custom sources below app/run after discovering they could otherwise sort after `run` and override run-level prompt policy. `RunOptions.systemPrompt: false` still disables every configured layer for the run and keeps `AgentConfig.instructions` as the base prompt.
 
 `mode` behavior:
 
@@ -99,18 +101,118 @@ export default definePrismManifest({
 
 The manifest entry does not load or apply the prompt. The host must still select it and pass the `SystemPromptContribution` to the runtime.
 
-No `SYSTEM.md`, `APPEND_SYSTEM.md`, prompt template, settings, or manifest discovery happens in core.
+No `APPEND_SYSTEM.md`, prompt template, settings, or manifest discovery happens in core. `SYSTEM.md` / `AGENTS.md` walk-up loading is a Node/CLI concern — see [AGENTS.md and SYSTEM.md files](#agentsmd-and-systemmd-files) below.
 
 ## Security and performance notes
 
 - Composition is a single in-memory pass plus deterministic ordering; no dependency, watcher, filesystem read, provider call, or tokenizer is added.
 - Prompt text is caller-supplied content. Do not put secrets in prompts, settings, manifests, session entries, package metadata, or docs examples.
+- Unknown custom sources rank before app/run layers; prefer `source: "package"` for package defaults and `source: "run"` only for host-selected run overrides.
 - `replace`/`disable` make prompt policy explicit; they are not permission or sandbox controls.
 
+## AGENTS.md and SYSTEM.md files
+
+### What it does
+
+The Node loader `loadSystemPromptFiles` reads two standard prompt files and returns them as `SystemPromptContribution` layers that feed `composeSystemPrompt` — the same pipeline as explicit `AgentConfig.systemPrompt` layers. There is no parallel mechanism and no hidden global: the loader is a sibling of `src/node/instruction-injectors.ts`, opt-in by passing roots.
+
+- `SYSTEM.md` at `<globalRoot>/.prism/agent/SYSTEM.md` — the user-owned global prompt, tagged `source: "user"` (the Phase 31 base layer). No trust gate; its presence is the user's explicit choice.
+- `AGENTS.md` at `<workspaceRoot>/AGENTS.md` — the project prompt, tagged `source: "app"`. Trust-gated via `createPathTrustPolicy`; an untrusted workspace contributes nothing (fail-closed, silent skip).
+
+The `prism` CLI auto-loads both in print/json modes (see [CLI/RPC](cli-rpc.md)); RPC mode does **not** auto-read them (the host owns the session factory).
+
+### When to use it
+
+Use `loadSystemPromptFiles` when a Node host or the CLI wants to honor the standard `AGENTS.md` / `SYSTEM.md` layout without wiring prompt text by hand. Hosts pass `workspaceRoot` (defaults to `process.cwd()` on the CLI) and `globalRoot` (host-controlled; the CLI no longer defaults it to the user's home directory — pass it explicitly from a host adapter or use `--system-md-file`).
+
+Do not use it to load arbitrary prompt templates, settings, or manifests — it reads exactly two filenames and nothing else. Do not use it from the SDK entrypoint (`@arnilo/prism`) — it lives in the Node subpath `@arnilo/prism/node/system-prompts` and performs real filesystem I/O.
+
+### Inputs / request
+
+`loadSystemPromptFiles(options)`:
+
+| Field | Meaning |
+| --- | --- |
+| `workspaceRoot?` | Reads `<workspaceRoot>/AGENTS.md` (trust-gated, `source: "app"`). |
+| `globalRoot?` | Reads `<globalRoot>/.prism/agent/SYSTEM.md` (user-owned, `source: "user"`). |
+| `agentsMdPath?` | Override the AGENTS.md path (still `source: "app"`, still trust-gated). |
+| `systemMdPath?` | Override the SYSTEM.md path (still `source: "user"`, no trust gate). |
+| `trust?` | `TrustPolicy` (e.g. `createPathTrustPolicy`) fail-closed against the workspace. |
+| `permission?` | `PermissionPolicy` asserting each read (`assertPermission`). |
+
+Passing no roots returns `[]` and performs no filesystem I/O — the SDK escape hatch. `AgentConfig.instructions` / `AgentConfig.systemPrompt` keep working unchanged.
+
+CLI flags:
+
+| Flag | Meaning |
+| --- | --- |
+| `--no-agents-md` | Skip auto-loading `<workspaceRoot>/AGENTS.md`. |
+| `--no-system-md` | Skip auto-loading the global `SYSTEM.md` layer. The CLI does not default to the user's home directory; pass `globalRoot` from a host adapter or use `--system-md-file` to opt in. |
+| `--agents-md-file <path>` | Read AGENTS.md from `<path>` instead (trust-gated, `source: "app"`). |
+| `--system-md-file <path>` | Read SYSTEM.md from `<path>` instead (user-owned, `source: "user"`). |
+
+`--system <text>` stays as `AgentConfig.instructions` (the base prompt) and is composed below the file layers. `RunOptions.systemPrompt` is not surfaced as a CLI flag (the `--system` base + the two file layers cover the CLI surface).
+
+### Outputs / response / events
+
+`loadSystemPromptFiles()` returns `readonly SystemPromptContribution[]` — `SYSTEM.md` first (`source: "user"`), then `AGENTS.md` (`source: "app"`). Input order here only matters for the stable tie-break when sources collide; rank order (`user` → `package` → `app` → `run`) is enforced inside `composeSystemPrompt`. The CLI passes a non-empty result as `AgentConfig.systemPrompt`; the runtime composes it with `instructions` (base) and emits no separate event.
+
+### Request/response example
+
+```json
+{
+  "base": "You are helpful.",
+  "layers": [
+    { "id": "system-md", "source": "user", "mode": "append", "text": "Global system policy." },
+    { "id": "agents-md", "source": "app", "mode": "append", "text": "Project rule." }
+  ],
+  "composed": "You are helpful.\n\nGlobal system policy.\n\nProject rule."
+}
+```
+
+### Implementation example
+
+```ts
+import { composeSystemPrompt } from "@arnilo/prism";
+import { loadSystemPromptFiles } from "@arnilo/prism/node/system-prompts";
+import { createPathTrustPolicy } from "@arnilo/prism/node/trust";
+
+// Trust gate mirrors discoverContributions — untrusted AGENTS.md is skipped silently.
+const trust = createPathTrustPolicy({ trustedRoots: [workspaceRoot] });
+const layers = await loadSystemPromptFiles({ workspaceRoot, globalRoot, trust });
+const composed = composeSystemPrompt(layers, { base: "You are helpful." });
+```
+
+A complete runnable example lives at `examples/system-project-prompts.ts`.
+
+### Agent bundle prompt layers (Phase 34)
+
+`resolveAgentBundle()` (from `@arnilo/prism/node/agent-definitions`) appends up to three prompt sources for a discovered agent bundle, in this fixed order, all reusing `composeSystemPrompt`'s `source` rank (`user` → `package` → `app` → `run`):
+
+1. `<configRoot>/agents/SYSTEM.md` — app-global prompt, `source: "user"`.
+2. `<configRoot>/agents/<agentName>/AGENT.md` — the per-agent bundle's markdown body (below the front fence), `source: "package"`.
+3. `<workspaceRoot>/AGENTS.md` — the repo-level project prompt, `source: "app"`.
+
+Each layer is independently toggled via `ResolveAgentBundleOptions.include` (`systemPrompt`, `agentPrompt`, `repoPrompt`); all default to `true`. The app-config root and workspace root are trust-gated **independently** — an untrusted root contributes nothing (fail-closed, no throw). `RunOptions.systemPrompt` (`source: "run"`) still wins and is appended last at run time. Missing files are skipped silently.
+
+### Extension and configuration notes
+
+The loader reads text only with two `readFile` calls max — no `readdir`, no scan, no `import()`. It does not fit `discoverContributions`' named-subdir scanner (these are root-level single files), so it is a sibling adapter over the shared `readOptionalFile` helper rather than another scanner kind. Override paths (`agentsMdPath` / `systemMdPath`) reuse the same trust gate, so a `--agents-md-file` opt-in still fails closed outside trusted roots.
+
+### Security and performance notes
+
+- **Trust gating**: `AGENTS.md` (and `--agents-md-file`) pass through `createPathTrustPolicy` + `isPathInsideReal`, which resolve symlinks and fail closed. Untrusted workspaces contribute nothing — the run still works with base instructions. `SYSTEM.md` (whether from a host-supplied `globalRoot` or an explicit `--system-md-file`) is user-owned and is not trust-gated.
+- **No code execution**: the loader never `import()`s or `eval()`s a discovered file — it reads prompt text only.
+- **Redaction**: loaded prompt text is caller/host-supplied content subject to `redactProviderRequest` like any system instruction. Do not put secrets in `AGENTS.md` / `SYSTEM.md`, settings, manifests, or docs examples.
+- **Performance**: two `readFile` calls per CLI print/json run; missing files are ENOENT-skipped. Default SDK use (no roots) performs no I/O. RPC mode does not auto-read these files.
+
 ## Related APIs
 
 - [Input and prompt assembly](input-and-prompt-assembly.md): default input builder receives the composed system instruction string.
 - [Agent/session runtime](agent-session-runtime.md): runtime fields `AgentConfig.systemPrompt` and `RunOptions.systemPrompt`.
+- [Contribution discovery (workspace)](contribution-discovery.md): the scanner for `.agents/<kind>/<name>/` contributions; `AGENTS.md`/`SYSTEM.md` loading is a sibling loader, not a scanner kind.
 - [Contribution registries](contribution-registries.md): inert system prompt contribution registry.
 - [Extensions](extensions.md): `registerSystemPromptContribution()`.
+- [CLI/RPC](cli-rpc.md): the `--no-agents-md` / `--no-system-md` / `--agents-md-file` / `--system-md-file` flags, and the `--agents-config <path>` app-config bundle flag.
+- [Agent definitions](agent-definitions.md): `resolveAgentBundle` appends `SYSTEM.md` → `AGENT.md` body → repo `AGENTS.md` as a three-layer prompt model on top of this loader.
 - [Public contracts](public-contracts.md): exported prompt contribution contracts.

package/docs/tool-conformance.md

@@ -0,0 +1,87 @@
+# Tool conformance
+
+## What it does
+
+Tool conformance helpers are dependency-free assertions for tool-dispatch configuration tests. They exercise the blocked-reason matrix and the success path of `dispatchToolCall` without network or credentials.
+
+Exported from `@arnilo/prism/testing/tool-conformance`:
+
+- `assertToolDispatchConforms(registry, options)`
+- `assertToolBlocked(probe, expectedReason)`
+- `dispatchAndCollect(probe)`
+- `ToolConformanceOptions`, `ToolDispatchProbeOptions`
+
+## When to use it
+
+Use this helper when configuring a `ToolRegistry` with allow/deny filters, permission policies, and validators. It asserts the canonical blocked reasons and that blocked calls never execute:
+
+- unknown tool → `tool_execution_blocked` with reason `unknown_tool`
+- denied tool (filter) → `tool_denied`
+- non-object arguments → `invalid_arguments`
+- permission denial → `permission_denied`
+- validator failure → `validation_failed`
+- a valid call emits `tool_execution_started` and returns a result with no error
+
+## Inputs / request
+
+```ts
+import { assertToolDispatchConforms } from "@arnilo/prism/testing/tool-conformance";
+import { createToolRegistry } from "@arnilo/prism";
+
+await assertToolDispatchConforms(createToolRegistry(), {
+  tool: { name: "echo", execute: (args, ctx) => ({ toolCallId: ctx.toolCallId, name: "echo", value: args }) },
+  validArgs: { msg: "hi" },
+  permission: myPermissionPolicy,
+});
+```
+
+`ToolConformanceOptions`:
+- `tool: ToolDefinition` — registered as the success-path target
+- `validArgs: JsonObject` — arguments for the success probe
+- `permission?: PermissionPolicy` — applied to every probe (default allow-all)
+- `validate?: ToolValidator`, `filter?: ToolFilterInput`, `secrets?: readonly (string | undefined)[]`
+
+## Outputs / response / events
+
+`assertToolDispatchConforms` returns `Promise<void>` and throws on the first violation. `dispatchAndCollect` returns `{ result, events }` capturing the emitted `AgentEvent`s for custom assertions.
+
+## Request/response example
+
+```ts
+import { assertToolBlocked } from "@arnilo/prism/testing/tool-conformance";
+
+await assertToolBlocked(
+  { call: { type: "tool_call", id: "c", name: "missing", arguments: {} }, registry: createToolRegistry() },
+  "unknown_tool",
+);
+```
+
+## Implementation example
+
+```ts
+import { assertToolDispatchConforms } from "@arnilo/prism/testing/tool-conformance";
+import { createToolRegistry } from "@arnilo/prism";
+
+await assertToolDispatchConforms(createToolRegistry(), {
+  tool: { name: "echo", execute: (args, ctx) => ({ toolCallId: ctx.toolCallId, name: "echo", value: args }) },
+  validArgs: {},
+});
+```
+
+## Extension and configuration notes
+
+- The helper registers `options.tool` into the supplied registry; pass a fresh registry to avoid duplicate-name errors.
+- Execution is observed via the `tool_execution_started`/`tool_execution_blocked` events the runtime emits — the helper does not mutate the caller's tool.
+- Use `dispatchAndCollect` directly for custom probes (e.g. middleware ordering) beyond the standard matrix.
+
+## Security and performance notes
+
+- No credentials, no network required.
+- The helper uses an allow-all permission policy by default; supply `permission` to validate your fail-closed policy.
+- Blocked calls are proven not to execute by the absence of `tool_execution_started`.
+
+## Related APIs
+
+- [Tools](tools.md)
+- [Settings, auth, trust, security](settings-auth-trust-security.md)
+- [Provider conformance](provider-conformance.md)

package/docs/tools.md

@@ -20,7 +20,7 @@ Do not use the harness as a sandbox, package loader, app-tool pack, permission p
 ## Inputs / request
 
 ```ts
-createToolRegistry(tools?: readonly ToolDefinition[]): ToolRegistry
+createToolRegistry(tools?: readonly ToolDefinition[], options?: { duplicate?: "replace" | "error" }): ToolRegistry
 filterTools(tools: readonly ToolDefinition[], filter?: ToolFilter | readonly ToolFilter[]): readonly ToolDefinition[]
 dispatchToolCall(options: DispatchToolCallOptions): Promise<ToolResult>
 ```
@@ -29,7 +29,7 @@ dispatchToolCall(options: DispatchToolCallOptions): Promise<ToolResult>
 
 | Method | Input | Result |
 | --- | --- | --- |
-| `register(tool)` | `ToolDefinition` | Stores or replaces by `tool.name`. |
+| `register(tool)` | `ToolDefinition` | Stores/replaces by `tool.name`; throws `Duplicate tool: <name>` when `duplicate: "error"`. |
 | `get(name)` | tool name | Returns the tool or `undefined`. |
 | `resolve(name)` | tool name | Returns the tool or throws `Unknown tool: <name>`. |
 | `list()` | none | Returns tools in insertion order. |
@@ -52,13 +52,16 @@ When multiple filters are provided, each non-empty allow list must include the t
 | `context` | `ToolExecutionContext` with session/run/tool call ids, signal, metadata, and optional progress callback. |
 | `filter` | Optional exact allow/deny filter or ordered filters. |
 | `middleware` | Optional `MiddlewareRegistry`; `tool_call` runs before validation/execution and `tool_result` runs after execution. |
-| `validate` | Optional host validator returning `void`, a message string, or `ErrorInfo`. |
+| `validate` | Optional host validator returning `void`, a message string, or `ErrorInfo`. A non-`void` return blocks dispatch with reason `validation_failed` (redacted). Runs after the permission assertion and before `tool.execute()`. |
 | `emit` | Optional `AgentEvent` callback for lifecycle events. |
 | `secrets` | Known secret values to redact from thrown tool errors. |
+| `redactor` | Optional `SecretRedactor` used to redact tool-call ledger records. |
+| `ledger` | Optional `RunLedger` adapter; when set, `dispatchToolCall` appends `ToolCallRecord` rows. |
+| `ownership` | Optional `OwnershipScope` copied into each `ToolCallRecord`. |
 
 ## Outputs / response / events
 
-Registry calls return plain `ToolDefinition` objects. `resolve()` fails closed for unknown names before any tool can execute. Filtering returns only tools already present in the input list; it never creates or enables new tools.
+Registry calls return plain `ToolDefinition` objects. `resolve()` fails closed for unknown names before any tool can execute. Duplicate registrations replace deterministically by default for compatibility; `createToolRegistry([], { duplicate: "error" })` rejects silent shadowing with `Duplicate tool: <name>`. Filtering returns only tools already present in the input list; it never creates or enables new tools.
 
 `dispatchToolCall()` returns a `ToolResult`. Unknown tools, denied tools, invalid arguments, validator failures, and thrown tool errors return a result with `error` and do not throw by default.
 
@@ -72,6 +75,20 @@ Dispatch can emit these `AgentEvent` types:
 | `tool_execution_finished` | After successful execution and `tool_result` middleware. |
 | `tool_execution_error` | When `tool.execute()` throws. |
 
+### Tool-call ledger rows
+
+When `options.ledger` is set, `dispatchToolCall()` also appends a `ToolCallRecord` for each lifecycle transition. The runtime passes each record through `redactRunLedgerRecord(record, options.redactor)` before handing it to the adapter. Rows are written for:
+
+| Status | When | Extra fields |
+| --- | --- | --- |
+| `started` | After `tool_execution_started` | `startedAt`, `arguments` |
+| `started` (progress snapshot) | On each `context.progress()` call | `progress`, `progressMetadata`, `progressAt` |
+| `finished` | After `tool_execution_finished` | `finishedAt`, `result` |
+| `error` | After `tool_execution_error` | `finishedAt`, `result` with `error` |
+| `blocked` | On any blocked path | `finishedAt`, `reason`, `result` with `error` |
+
+Blocked reasons are `unknown_tool`, `tool_denied`, `invalid_arguments`, `permission_denied`, and `validation_failed`. Progress snapshots reuse status `started` because the tool call is still in flight.
+
 ## Request/response example
 
 ```json
@@ -124,13 +141,52 @@ const activeTools = createToolRegistry([contributions.tools.resolve("echo")]);
 
 Middleware can transform `tool_call` and `tool_result` payloads, but dispatch re-checks active registry lookup, filters, and object arguments after `tool_call` middleware. Middleware cannot grant permission by changing a tool name.
 
-Configuration can carry allow/deny names, but Prism does not define a policy class or hidden global active tool set. Skills may reference `toolNames`, but `resolveActiveSkills()` only checks those names against the host-active tool list; it does not register, allow, or execute tools.
+Configuration can carry allow/deny names, but Prism does not define a policy class or hidden global active tool set. Skills may reference `toolNames`, but `resolveActiveSkills()` only checks those names against the host-active tool list; it does not register, allow, permit, or execute tools. A missing `toolNames` dependency fails before the provider turn and writes no tool result.
+
+### Per-run tool scoping
+
+`session.run()` intentionally has no `RunOptions.tools` or `RunOptions.toolFilter`. Scope tools by building the active `ToolRegistry` for the agent/session, by resolving declarative `AgentDefinition.tools`, or by using `PermissionPolicy` / `ToolValidator` to fail closed at dispatch time. Skills do not grant tool access; `toolNames` only validates that host-active tools exist.
+
+```ts
+const activeTools = createToolRegistry([searchTool]);
+const agent = createAgent({ model, provider, tools: activeTools, permission, validator });
+```
+
+Need different tools for one request? Build a short-lived agent/session with a narrower registry, or block extra calls with `PermissionPolicy` / `RunOptions.validate`. No extra per-run tool API exists yet; add one only when host apps need it.
+
+### Runtime-supplied validators
+
+`AgentConfig.validator?` and `RunOptions.validate?` expose the same `ToolValidator` seam that `DispatchToolCallOptions.validate` already uses. The runtime threads `validate: RunOptions.validate ?? AgentConfig.validator` into every `dispatchToolCall` it issues during the tool loop, so an app can supply argument validation without taking ownership of dispatch itself. `RunOptions.validate` overrides `AgentConfig.validator` on a per-run basis (RunOptions wins). When neither is set, dispatch runs unmodified.
+
+The validator runs after the permission assertion and before `tool.execute()`. A `void` return lets the tool run. A non-`void` return (a string message or `ErrorInfo`) blocks the call: `dispatchToolCall` emits `tool_execution_blocked` with reason `validation_failed` and a redacted error, and the tool is not executed. This is the same redaction path as thrown tool errors, so a validator that echoes a secret is scrubbed through the active `SecretRedactor`. Composition of multiple validators is deferred (YAGNI); wrap or call both in a host-supplied function if needed.
+
+```ts
+import { createAgent, createSecretRedactor, type ToolValidator } from "@arnilo/prism";
+
+const validator: ToolValidator = (_tool, args) =>
+  typeof args.query === "string" && args.query.length <= 1000
+    ? undefined
+    : "query too long";
+
+const agent = createAgent({
+  model,
+  provider,
+  tools,
+  // applied to every run of this agent
+  validator,
+  // redacts validator output (and tool errors) the same way as secrets
+  redactor: createSecretRedactor([process.env.APP_KEY!]),
+});
+
+// override per run only
+await session.run(input, { validate: (_t, args) => args.dry ? "dry-run blocked" : undefined });
+```
 
 ## Security and performance notes
 
-- Tool lookup uses a `Map` for O(1) name lookup.
+- Tool lookup uses a `Map` for O(1) name lookup. Strict duplicate mode adds one O(1) `Map.has()` check during registration only.
 - Filtering is exact-name matching over the provided tools and rules.
-- Unknown, denied, malformed, and validator-blocked calls fail closed.
+- Unknown, denied, malformed, duplicate-in-strict-mode, and validator-blocked calls fail closed.
 - Tool arguments must be JSON object-shaped before validation or execution.
 - `parameters` is pass-through metadata; hosts own schema interpretation and validation.
 - Prism does not sandbox host tools and does not include built-in app tools.
@@ -148,4 +204,4 @@ Configuration can carry allow/deny names, but Prism does not define a policy cla
 - [Credentials and redaction](credentials-and-redaction.md): redaction helpers used for tool execution errors.
 - [Observational memory compaction package](compaction-observational-memory.md): optional exact-id recall tool factory.
 
-`DispatchToolCallOptions.permission` can provide a `PermissionPolicy`; denial emits `tool_execution_blocked` before validation or `execute()`. Middleware cannot bypass this guard. Prism does not sandbox tools. See [Security/auth/trust](settings-auth-trust-security.md).
+`DispatchToolCallOptions.permission` can provide a `PermissionPolicy`; denial emits `tool_execution_blocked` before validation or `execute()`. Middleware cannot bypass this guard. `AgentConfig.validator`/`RunOptions.validate` run after this guard; their output is redacted through the active `SecretRedactor`. Prism does not sandbox tools. See [Security/auth/trust](settings-auth-trust-security.md).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arnilo/prism",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "description": "Agent harness for AI providers, agents, sessions, and tools.",
   "type": "module",
   "main": "./dist/index.js",
@@ -18,6 +18,22 @@
       "types": "./dist/testing/provider-conformance.d.ts",
       "default": "./dist/testing/provider-conformance.js"
     },
+    "./testing/session-store-conformance": {
+      "types": "./dist/testing/session-store-conformance.d.ts",
+      "default": "./dist/testing/session-store-conformance.js"
+    },
+    "./testing/compaction-conformance": {
+      "types": "./dist/testing/compaction-conformance.d.ts",
+      "default": "./dist/testing/compaction-conformance.js"
+    },
+    "./testing/tool-conformance": {
+      "types": "./dist/testing/tool-conformance.d.ts",
+      "default": "./dist/testing/tool-conformance.js"
+    },
+    "./testing/extension-conformance": {
+      "types": "./dist/testing/extension-conformance.d.ts",
+      "default": "./dist/testing/extension-conformance.js"
+    },
     "./node/config": {
       "types": "./dist/node/config.d.ts",
       "default": "./dist/node/config.js"
@@ -33,6 +49,22 @@
     "./node/session-store-jsonl": {
       "types": "./dist/node/session-store-jsonl.d.ts",
       "default": "./dist/node/session-store-jsonl.js"
+    },
+    "./node/contribution-discovery": {
+      "types": "./dist/node/contribution-discovery.d.ts",
+      "default": "./dist/node/contribution-discovery.js"
+    },
+    "./node/instruction-injectors": {
+      "types": "./dist/node/instruction-injectors.d.ts",
+      "default": "./dist/node/instruction-injectors.js"
+    },
+    "./node/system-prompts": {
+      "types": "./dist/node/system-project-prompts.d.ts",
+      "default": "./dist/node/system-project-prompts.js"
+    },
+    "./node/agent-definitions": {
+      "types": "./dist/node/agent-definitions.d.ts",
+      "default": "./dist/node/agent-definitions.js"
     }
   },
   "bin": {
@@ -58,7 +90,8 @@
     "typecheck": "npm run build:core && npm run typecheck --workspaces --if-present && tsc -p examples --noEmit",
     "test": "npm run build && node --test dist/__tests__/*.test.js && npm run test --workspaces --if-present",
     "pack:dry-run": "npm pack --dry-run && npm run pack:dry-run --workspaces --if-present",
-    "release:dry-run": "npm test && npm run pack:dry-run"
+    "release:dry-run": "npm run sdk:ready",
+    "sdk:ready": "npm run typecheck && npm test && npm run pack:dry-run"
   },
   "devDependencies": {
     "typescript": "^5.7.0",