@arnilo/prism 0.0.1 → 0.0.3

package/dist/testing/session-store-conformance.js

@@ -0,0 +1,92 @@
+// ponytail: dependency-free, runner-agnostic conformance helper for the
+// SessionStore adapter contract. Hosts implementing a DB-backed SessionStore
+// (see examples/external-app-db-backed.ts) call this once to assert the
+// append/idempotency/conflict/branch invariants that the core memory and JSONL
+// stores already satisfy. Mirrors the assertion shape already repeated across
+// src/__tests__/session-stores.test.ts and node-session-store-jsonl.test.ts so
+// adapter authors do not re-derive them. Throws plain Error; no test runner.
+import { isSessionAppendConflict } from "../contracts.js";
+/**
+ * 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 async function assertSessionStoreConforms(store, options = {}) {
+    const sessionId = options.sessionId ?? "conformance";
+    const now = () => "2026-01-01T00:00:00.000Z";
+    const make = (id, parentId) => ({
+        id,
+        parentId,
+        sessionId,
+        timestamp: now(),
+        kind: "label",
+        label: id,
+    });
+    // 1. append + list round-trip.
+    const root = make("root");
+    await store.append(root);
+    const child = make("child", root.id);
+    await store.append(child);
+    assertIds(await store.list(sessionId), ["root", "child"], "append/list round-trip dropped entries");
+    // 2. duplicate entry id is rejected.
+    await reject(() => store.append(make("root")), /Duplicate session entry id: root/, "store must reject a duplicate entry id");
+    // 3. expectedParentId mismatch throws SessionAppendConflictError and writes nothing.
+    const before = (await store.list(sessionId)).length;
+    await reject(() => store.append(make("orphan"), { expectedParentId: "missing" }), (error) => isSessionAppendConflict(error) && error.conflict.expectedParentId === "missing", "store must throw SessionAppendConflictError when expectedParentId does not exist");
+    if ((await store.list(sessionId)).length !== before) {
+        throw new Error("A rejected append (missing parent) wrote entries; append must be atomic");
+    }
+    // 4. idempotencyKey dedup: an exact retry at the same position is rejected as a duplicate.
+    await store.append(make("idem-a"), { idempotencyKey: "k1" });
+    await reject(() => store.append(make("idem-dup"), { idempotencyKey: "k1" }), (error) => isSessionAppendConflict(error) && error.conflict.idempotencyDuplicate === true, "store must deduplicate an exact retry sharing an idempotencyKey");
+    // 5. branching from any existing entry (not just the tip) succeeds.
+    const branch = make("branch", root.id);
+    await store.append(branch, { expectedParentId: root.id });
+    if (!(await store.list(sessionId)).some((entry) => entry.id === "branch")) {
+        throw new Error("Branching from a non-tip existing entry was rejected; expectedParentId is existence-validation, not tip-CAS");
+    }
+    // 6. distinct linear appends sharing a run-level idempotencyKey are NOT collapsed.
+    const linearA = make("linear-a");
+    await store.append(linearA, { idempotencyKey: "run-1" });
+    const linearB = make("linear-b", linearA.id);
+    await store.append(linearB, { idempotencyKey: "run-1", expectedParentId: linearA.id });
+    if (!(await store.list(sessionId)).some((entry) => entry.id === "linear-b")) {
+        throw new Error("Distinct linear appends sharing an idempotencyKey were collapsed; only same-position retries dedup");
+    }
+    if (options.exerciseReadBranchPath && typeof store.readBranchPath === "function") {
+        const chain = await store.readBranchPath({ sessionId, leafId: branch.id });
+        const ids = chain.items.map((entry) => entry.id);
+        if (ids[0] !== "root" || ids[ids.length - 1] !== "branch") {
+            throw new Error(`readBranchPath must return the ancestor chain root→leaf in order; got ${JSON.stringify(ids)}`);
+        }
+    }
+}
+function assertIds(entries, expected, message) {
+    const actual = entries.map((entry) => entry.id);
+    if (actual.length !== expected.length || expected.some((id, i) => actual[i] !== id)) {
+        throw new Error(`${message}; expected ${JSON.stringify(expected)}, got ${JSON.stringify(actual)}`);
+    }
+}
+async function reject(fn, match, message) {
+    let threw = false;
+    try {
+        await fn();
+    }
+    catch (error) {
+        threw = true;
+        if (match instanceof RegExp) {
+            if (!match.test(error.message ?? String(error))) {
+                throw new Error(`${message}; error did not match ${match}: ${String(error)}`);
+            }
+        }
+        else if (!match(error)) {
+            throw new Error(`${message}; error did not satisfy predicate: ${String(error)}`);
+        }
+    }
+    if (!threw)
+        throw new Error(message);
+}
+//# sourceMappingURL=session-store-conformance.js.map

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

@@ -0,0 +1,39 @@
+import type { AgentEvent, JsonObject, ToolCallContent, ToolDefinition, ToolExecutionContext, ToolRegistry, ToolResult } from "../contracts.js";
+import type { PermissionPolicy } from "../security.js";
+import { type ToolFilterInput, type ToolValidator } from "../tools.js";
+export interface ToolDispatchProbeOptions {
+    readonly call: ToolCallContent;
+    readonly registry: ToolRegistry;
+    readonly context?: Partial<ToolExecutionContext>;
+    readonly filter?: ToolFilterInput;
+    readonly permission?: PermissionPolicy;
+    readonly validate?: ToolValidator;
+    readonly secrets?: readonly (string | undefined)[];
+}
+export interface ToolConformanceOptions {
+    /** A tool that will be registered and used as the success-path target. */
+    readonly tool: ToolDefinition;
+    /** Valid arguments object for the success-path probe. */
+    readonly validArgs: JsonObject;
+    /** Optional permission policy to apply (defaults to allow-all). */
+    readonly permission?: PermissionPolicy;
+    /** Optional validator to apply. */
+    readonly validate?: ToolValidator;
+    /** Optional filter applied to every probe (e.g. a deny list under test). */
+    readonly filter?: ToolFilterInput;
+    readonly secrets?: readonly (string | undefined)[];
+}
+/**
+ * Assert the full tool-dispatch contract against a fresh registry containing
+ * `options.tool`: unknown tools, denied tools, non-object arguments,
+ * permission denials, and validator failures all block with the canonical
+ * reason and never emit `tool_execution_started`; a valid call emits
+ * `tool_execution_started` and returns a result without an error. Throws on
+ * the first violation.
+ */
+export declare function assertToolDispatchConforms(registry: ToolRegistry, options: ToolConformanceOptions): Promise<void>;
+export declare function assertToolBlocked(probe: ToolDispatchProbeOptions, expectedReason: string): Promise<void>;
+export declare function dispatchAndCollect(probe: ToolDispatchProbeOptions): Promise<{
+    result: ToolResult;
+    events: AgentEvent[];
+}>;

package/dist/testing/tool-conformance.js

@@ -0,0 +1,79 @@
+// ponytail: dependency-free conformance helper for the tool-dispatch contract.
+// Hosts configuring a ToolRegistry with allow/deny filters, permission policies,
+// and validators call this once to assert the blocked-reason matrix
+// (unknown_tool / tool_denied / invalid_arguments / permission_denied /
+// validation_failed) and the success path. Mirrors the assertions in
+// src/__tests__/tools.test.ts so hosts do not re-derive them. Throws plain
+// Error; no test runner, no network. Execution is observed via the
+// tool_execution_started / tool_execution_blocked events the runtime emits,
+// not by mutating the caller's tool.
+import { dispatchToolCall } from "../tools.js";
+const denyAllPermission = { check: () => ({ allowed: false, reason: "denied" }) };
+const alwaysInvalidValidator = () => "invalid";
+/**
+ * Assert the full tool-dispatch contract against a fresh registry containing
+ * `options.tool`: unknown tools, denied tools, non-object arguments,
+ * permission denials, and validator failures all block with the canonical
+ * reason and never emit `tool_execution_started`; a valid call emits
+ * `tool_execution_started` and returns a result without an error. Throws on
+ * the first violation.
+ */
+export async function assertToolDispatchConforms(registry, options) {
+    registry.register(options.tool);
+    const baseContext = { sessionId: "conformance", runId: "r", toolCallId: "call" };
+    const call = (name, args) => ({ type: "tool_call", id: "call", name, arguments: args });
+    const shared = { registry, secrets: options.secrets };
+    // 1. unknown tool → blocked "unknown_tool".
+    await assertToolBlocked({ call: call("does-not-exist", {}), context: baseContext, ...shared, ...pickPolicy(options) }, "unknown_tool");
+    // 2. denied tool (filter) → blocked "tool_denied".
+    await assertToolBlocked({ call: call(options.tool.name, options.validArgs), context: baseContext, ...shared, ...pickPolicy(options), filter: { deny: [options.tool.name] } }, "tool_denied");
+    // 3. invalid (non-object) arguments → blocked "invalid_arguments".
+    await assertToolBlocked({ call: call(options.tool.name, "not-an-object"), context: baseContext, ...shared, ...pickPolicy(options) }, "invalid_arguments");
+    // 4. permission denial → blocked "permission_denied".
+    await assertToolBlocked({ call: call(options.tool.name, options.validArgs), context: baseContext, ...shared, ...pickPolicy(options), permission: denyAllPermission }, "permission_denied");
+    // 5. validator failure → blocked "validation_failed".
+    await assertToolBlocked({ call: call(options.tool.name, options.validArgs), context: baseContext, ...shared, ...pickPolicy(options), validate: alwaysInvalidValidator }, "validation_failed");
+    // 6. valid call → executes (tool_execution_started), no error, no blocked event.
+    const probe = await dispatchAndCollect({ call: call(options.tool.name, options.validArgs), context: baseContext, ...shared, ...pickPolicy(options) });
+    if (probe.result.error)
+        throw new Error(`Valid tool call was not executed: ${probe.result.error.message}`);
+    if (!probe.events.some((event) => event.type === "tool_execution_started")) {
+        throw new Error("Valid tool call did not emit tool_execution_started");
+    }
+    if (probe.events.some((event) => event.type === "tool_execution_blocked")) {
+        throw new Error("Valid tool call emitted a tool_execution_blocked event");
+    }
+}
+export async function assertToolBlocked(probe, expectedReason) {
+    const captured = await dispatchAndCollect(probe);
+    const blockedEvent = captured.events.find((event) => event.type === "tool_execution_blocked");
+    if (!blockedEvent)
+        throw new Error(`Expected tool_execution_blocked for "${expectedReason}", but no blocked event was emitted`);
+    if (blockedEvent.type === "tool_execution_blocked" && blockedEvent.reason !== expectedReason) {
+        throw new Error(`Blocked reason mismatch: expected ${expectedReason}, got ${blockedEvent.reason}`);
+    }
+    if (!captured.result.error)
+        throw new Error(`Blocked call for "${expectedReason}" carried no error in the result`);
+    if (captured.events.some((event) => event.type === "tool_execution_started")) {
+        throw new Error(`Tool emitted tool_execution_started despite being blocked for "${expectedReason}"; blocked calls must not execute`);
+    }
+}
+export async function dispatchAndCollect(probe) {
+    const events = [];
+    const context = { sessionId: "conformance", runId: "r", toolCallId: probe.call.id, ...probe.context };
+    const result = await dispatchToolCall({
+        call: probe.call,
+        registry: probe.registry,
+        context,
+        filter: probe.filter,
+        permission: probe.permission,
+        validate: probe.validate,
+        secrets: probe.secrets,
+        emit: (event) => { events.push(event); },
+    });
+    return { result, events };
+}
+function pickPolicy(options) {
+    return { permission: options.permission, validate: options.validate, filter: options.filter };
+}
+//# sourceMappingURL=tool-conformance.js.map

package/dist/tools.d.ts

@@ -1,6 +1,7 @@
-import type { AgentEvent, ErrorInfo, JsonObject, ToolCallContent, ToolDefinition, ToolExecutionContext, ToolRegistry, ToolResult } from "./contracts.js";
+import type { AgentEvent, ErrorInfo, JsonObject, OwnershipScope, RunLedger, ToolCallContent, ToolDefinition, ToolExecutionContext, ToolRegistry, ToolResult } from "./contracts.js";
 import type { MiddlewareRegistry } from "./middleware.js";
 import { type SecretRedactor } from "./redaction.js";
+import { type DuplicateRegistrationOptions } from "./registry-options.js";
 import { type PermissionPolicy } from "./security.js";
 export interface ToolFilter {
     readonly allow?: readonly string[];
@@ -19,7 +20,11 @@ export interface DispatchToolCallOptions {
     readonly secrets?: readonly (string | undefined)[];
     readonly permission?: PermissionPolicy;
     readonly redactor?: SecretRedactor;
+    readonly ledger?: RunLedger;
+    readonly ownership?: OwnershipScope;
 }
-export declare function createToolRegistry(tools?: readonly ToolDefinition[]): ToolRegistry;
+export interface ToolRegistryOptions extends DuplicateRegistrationOptions {
+}
+export declare function createToolRegistry(tools?: readonly ToolDefinition[], options?: ToolRegistryOptions): ToolRegistry;
 export declare function filterTools(tools: readonly ToolDefinition[], filter?: ToolFilterInput): readonly ToolDefinition[];
 export declare function dispatchToolCall(options: DispatchToolCallOptions): Promise<ToolResult>;

package/dist/tools.js

@@ -1,10 +1,12 @@
 import { isJsonObject } from "./config.js";
-import { errorToErrorInfo, redactSecrets } from "./redaction.js";
+import { errorToErrorInfo, redactRunLedgerRecord, redactSecrets } from "./redaction.js";
+import { assertCanRegister } from "./registry-options.js";
 import { assertPermission } from "./security.js";
-export function createToolRegistry(tools = []) {
+export function createToolRegistry(tools = [], options = {}) {
     const byName = new Map();
     const registry = {
         register(tool) {
+            assertCanRegister(byName, tool.name, "tool", tool.name, options.duplicate);
             byName.set(tool.name, tool);
         },
         get(name) {
@@ -32,12 +34,13 @@ export function filterTools(tools, filter) {
 }
 export async function dispatchToolCall(options) {
     const secrets = options.secrets ?? [];
-    const precheck = await checkCall(options.call, options);
+    const startedAt = new Date().toISOString();
+    const precheck = await checkCall(options.call, options, startedAt);
     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);
+    const postcheck = await checkCall(mediatedCall, options, startedAt);
     if (postcheck)
         return postcheck;
     const context = {
@@ -54,45 +57,55 @@ export async function dispatchToolCall(options) {
                 progress,
                 metadata,
             });
+            await appendToolCallRecord(options, "started", mediatedCall, startedAt, {
+                progress,
+                progressMetadata: metadata,
+                progressAt: new Date().toISOString(),
+            });
         },
     };
     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);
+        return blocked(mediatedCall, context, "permission_denied", errorToErrorInfo(error, secrets), options, startedAt);
     }
     const validation = await options.validate?.(tool, mediatedCall.arguments, context);
     if (validation)
-        return blocked(mediatedCall, context, "validation_failed", toErrorInfo(validation, secrets), options.emit);
+        return blocked(mediatedCall, context, "validation_failed", toErrorInfo(validation, secrets), options, startedAt);
     await options.emit?.({ type: "tool_execution_started", sessionId: context.sessionId, runId: context.runId, call: mediatedCall });
+    await appendToolCallRecord(options, "started", mediatedCall, startedAt, {});
     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;
+        const finishedAt = new Date().toISOString();
         await options.emit?.({ type: "tool_execution_finished", sessionId: context.sessionId, runId: context.runId, result });
+        await appendToolCallRecord(options, "finished", mediatedCall, startedAt, { finishedAt, result });
         return result;
     }
     catch (error) {
         const info = errorToErrorInfo(error, secrets);
         const result = { toolCallId: mediatedCall.id, name: mediatedCall.name, error: info };
+        const finishedAt = new Date().toISOString();
         await options.emit?.({ type: "tool_execution_error", sessionId: context.sessionId, runId: context.runId, call: mediatedCall, error: info });
+        await appendToolCallRecord(options, "error", mediatedCall, startedAt, { finishedAt, result });
         return result;
     }
 }
-async function checkCall(call, options) {
+async function checkCall(call, options, startedAt) {
     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);
+        return blocked(call, context, "unknown_tool", { message: `Unknown tool: ${call.name}` }, options, startedAt);
     if (filterTools([tool], options.filter).length === 0)
-        return blocked(call, context, "tool_denied", { message: `Tool denied: ${call.name}` }, options.emit);
+        return blocked(call, context, "tool_denied", { message: `Tool denied: ${call.name}` }, options, startedAt);
     if (!isJsonObject(call.arguments))
-        return blocked(call, context, "invalid_arguments", { message: "Tool arguments must be a JSON object" }, options.emit);
+        return blocked(call, context, "invalid_arguments", { message: "Tool arguments must be a JSON object" }, options, startedAt);
     return undefined;
 }
-async function blocked(call, context, reason, error, emit) {
-    await emit?.({
+async function blocked(call, context, reason, error, options, startedAt) {
+    await options.emit?.({
         type: "tool_execution_blocked",
         sessionId: context.sessionId,
         runId: context.runId,
@@ -101,9 +114,33 @@ async function blocked(call, context, reason, error, emit) {
         reason,
         error,
     });
-    return { toolCallId: call.id, name: call.name, error };
+    const finishedAt = new Date().toISOString();
+    const result = { toolCallId: call.id, name: call.name, error };
+    await appendToolCallRecord(options, "blocked", call, startedAt, { reason, finishedAt, result });
+    return result;
 }
 function toErrorInfo(value, secrets) {
     return typeof value === "string" ? errorToErrorInfo(value, secrets) : redactSecrets(value, secrets);
 }
+function randomId(prefix) {
+    return `${prefix}_${globalThis.crypto?.randomUUID?.() ?? Math.random().toString(36).slice(2)}`;
+}
+function appendToolCallRecord(options, status, call, startedAt, fields) {
+    if (!options.ledger)
+        return undefined;
+    const record = {
+        id: randomId("toolcall"),
+        sessionId: options.context.sessionId,
+        runId: options.context.runId,
+        toolCallId: call.id,
+        name: call.name,
+        arguments: call.arguments,
+        status,
+        startedAt,
+        redacted: Boolean(options.redactor),
+        ...options.ownership,
+        ...fields,
+    };
+    return options.ledger.appendToolCall(redactRunLedgerRecord(record, options.redactor));
+}
 //# sourceMappingURL=tools.js.map

package/docs/agent-definitions.md

@@ -0,0 +1,251 @@
+# Agent definitions
+
+## What it does
+
+An agent definition declares what an agent needs — model, tools, skills, context, system prompt, instructions, loop — without owning how those are loaded or executed. Two helpers turn a definition into a runnable `Agent`:
+
+- `resolveAgentDefinition(def, context)` (re-exported from `@arnilo/prism`): resolves a declarative `AgentDefinition` against the registries the host passes in. Missing dependencies fail closed before any provider turn.
+- `resolveAgentBundle(bundle, options)` (Node subpath `@arnilo/prism/node/agent-definitions`): turns a discovered app-config agent bundle envelope into an `Agent` by building union skill/tool registries across three scopes, appending up to three prompt layers, and delegating to `resolveAgentDefinition`.
+
+A third helper, `discoverAgentBundles(options)` (same Node subpath), scans an app-controlled `configRoot` for agent bundle envelopes without parsing or importing any file content; resolution happens later in `resolveAgentBundle`.
+
+`AgentDefinition` is the same shape registered programmatically via `ExtensionAPI.registerAgent()` (see [Extensions](extensions.md)) — a definition is data, registration is inert, activation is run-owned.
+
+## When to use it
+
+Use `resolveAgentDefinition` when an app already holds a `AgentDefinition` (from an extension, a manifest, or hand-written config) and wants to turn it into an `Agent` against its registries — without wiring every field by hand.
+
+Use `discoverAgentBundles` + `resolveAgentBundle` when a host app keeps per-agent bundles on disk under an app-controlled config root (for example `.clay/extensions/prism/agents/<agentName>/AGENT.md`) and wants to honor them as first-class agents. The bundle layout is host-owned: Prism never picks the config root, never touches the user's home directory, and never auto-runs resolution — the host calls `discoverAgentBundles` and then `resolveAgentBundle` explicitly.
+
+Do not use the bundle loader to discover providers — provider/model packages stay config/package-driven (Phase 24; see [Provider packages](provider-packages.md)). Do not use it to auto-activate undeclared tools or skills: omitted `tools` / `skills` means no active capabilities by default; named bundle entries are explicit activation, and runtime skill selection can narrow further with `RunOptions.activeSkills`.
+
+## Inputs / request
+
+### `AgentDefinition` (contract, `@arnilo/prism`)
+
+| Field | Meaning |
+| --- | --- |
+| `name` | Required agent name. |
+| `description?` | Optional description. |
+| `model?` | `ModelConfig` object, or a `"<provider>/<model>"` string resolved through `registries.models`. |
+| `tools?` | Tool names to activate from the active tool registry / `registries.tools`. Omitted means no active tools unless `activateAllCapabilities: true` is passed for migration. |
+| `skills?` | Skill names resolved via `resolveActiveSkills()`; omitted means no active skills unless `activateAllCapabilities: true` is passed for migration. `toolNames` enforcement applies at activation. |
+| `context?` | Context provider names from `registries.contextProviders`. |
+| `systemPrompt?` | `SystemPromptConfig` layer (see [System prompts](system-prompts.md)). |
+| `instructions?` | Base prompt text. |
+| `loop?` | `AgentLoopStrategy` or `AgentLoopOptions` (see [Agent loops](agent-loops.md)). |
+| `metadata?` | Free-form metadata. |
+| `create?(config?)` | Optional escape hatch. When present, overrides declarative resolution: the helper builds a base `AgentConfig` from the declarative fields, calls `create(config)`, then merges `context.overrides`. |
+
+### `AgentDefinitionResolutionContext` (contract, `@arnilo/prism`)
+
+All fields optional — the host controls scope by which registries it passes.
+
+| Field | Meaning |
+| --- | --- |
+| `registries?` | `ContributionRegistries` carrying `models`, `providers`, `tools`, `contextProviders`, ... |
+| `providerSource?` | `ProviderResolver` override. |
+| `tools?` | `ToolRegistry` or `readonly ToolDefinition[]` scope override. |
+| `skillsRegistry?` | `SkillRegistry` override. |
+| `activateAllCapabilities?` | Migration-only `true`: omitted `tools`/`skills` activate every in-scope tool/skill. Default is fail-closed: omitted means none. |
+| `overrides?` | `Partial<AgentConfig>` applied last, after declarative resolution. |
+
+### App-config bundle layout
+
+`resolveAgentBundle` reads a three-scope layout rooted at an app-controlled `configRoot` (plus optional repo contributions from `discoverContributions`):
+
+| Scope | Path | Default include flag |
+| --- | --- | --- |
+| App-global prompt | `<configRoot>/agents/SYSTEM.md` | `include.systemPrompt` (default `true`) |
+| Per-agent definition + body prompt | `<configRoot>/agents/<agentName>/AGENT.md` | `include.agentPrompt` (default `true`) |
+| Repo project prompt | `<workspaceRoot>/AGENTS.md` | `include.repoPrompt` (default `true`) |
+| App-global skills | `<configRoot>/agents/skills/<name>/SKILL.md` | `include.globalSkills` (default `true`) |
+| App-global tools | `<configRoot>/agents/tools/<name>/manifest.json` | `include.globalTools` (default `true`) |
+| Per-agent skills | `<configRoot>/agents/<agentName>/skills/<name>/SKILL.md` | `include.agentSkills` (default `true`) |
+| Per-agent tools | `<configRoot>/agents/<agentName>/tools/<name>/manifest.json` | `include.agentTools` (default `true`) |
+| Repo skills | `<workspaceRoot>/.agents/skills/<name>/SKILL.md` | `include.repoSkills` (default `true`) |
+| Repo tools | `<workspaceRoot>/.agents/tools/<name>/manifest.json` | `include.repoTools` (default `true`) |
+
+`AGENT.md` frontmatter mirrors the declarative `AgentDefinition` fields above that fit YAML: `name`, `description`, `model` (a `"<provider>/<model>"` string), `tools` (list), `skills` (list), `context` (list), and `instructions` (frontmatter value or the markdown body as the per-agent prompt layer). `systemPrompt` and `loop` are intentionally deferred from frontmatter — they carry complex types not easily represented in YAML; pass them through `context.overrides` or a `create()` escape hatch.
+
+### `AgentBundle` / `DiscoverAgentBundlesOptions` (`@arnilo/prism/node/agent-definitions`)
+
+`discoverAgentBundles({ configRoot, trust?, permission?, signal? })` returns one `AgentBundle` per subdirectory of `<configRoot>/agents/` that contains an `AGENT.md`. Each `AgentBundle` carries paths only — `name`, `path` (the `AGENT.md`), `configRoot`, an optional `systemPromptPath`, and the collected `globalSkills`/`globalTools`/`agentSkills`/`agentTools` path lists. No file content is parsed here.
+
+### `ResolveAgentBundleOptions` (`@arnilo/prism/node/agent-definitions`)
+
+| Field | Meaning |
+| --- | --- |
+| `readFile?` | File reader. Defaults to `node:fs/promises.readFile`. |
+| `workspaceRoot?` | Workspace root for the repo prompt and repo contributions. |
+| `repoContributions?` | Repo-level contributions from `discoverContributions` (see [Contribution discovery](contribution-discovery.md)). |
+| `registries?` | Host registries (`models`, `providers`, `contextProviders`, ...). |
+| `providerSource?` / `tools?` / `skillsRegistry?` / `activateAllCapabilities?` | Forwarded to `AgentDefinitionResolutionContext`. `activateAllCapabilities` is migration-only; default omitted `tools`/`skills` activate none. |
+| `overrides?` | `Partial<AgentConfig>` applied after resolution. |
+| `trust?` | `TrustPolicy` gating the app-config root and workspace root **independently**. |
+| `permission?` | `PermissionPolicy` asserting each prompt-file read. |
+| `include?` | `AgentBundleScopeFlags` — every source defaults to `true`; set a flag to `false` to drop that scope's contributions for this resolution. |
+
+## Outputs / response / events
+
+`resolveAgentDefinition()` and `resolveAgentBundle()` return an `Agent` (sync or `Promise<Agent>` when the `create()` escape hatch is async). The helpers never emit events; the returned `Agent`/session emits the normal `AgentEvent` stream when run.
+
+Skill and tool contributions are merged as a **union** across the enabled scopes — there is no override on name collision. A duplicate skill or tool name across two enabled scopes throws `Duplicate skill/tool name across scopes: <name> (found in <scope> and <other>)` so the conflict is surfaced instead of silently masked. Disable a scope via its `include` flag to resolve a collision deliberately.
+
+Prompt layers are appended (never replace) in this fixed order, reusing `composeSystemPrompt`'s `source` rank (`user` → `package` → `app` → `run`):
+
+1. `<configRoot>/agents/SYSTEM.md` — app-global, `source: "user"`.
+2. `<configRoot>/agents/<agentName>/AGENT.md` body — per-agent, `source: "package"`.
+3. `<workspaceRoot>/AGENTS.md` — repo project prompt, `source: "app"`.
+
+The app-config root and the workspace root are trust-gated independently: an untrusted root contributes nothing for that layer (fail-closed, silent skip) while the other layers still load. `RunOptions.systemPrompt` (`source: "run"`) is appended last at run time and still wins. Missing files are skipped silently.
+
+## Request/response example
+
+A discovered bundle at `<configRoot>/agents/coding/AGENT.md`:
+
+```yaml
+---
+name: coding
+model: openai/gpt-4o
+tools: [read, echo]
+skills: [format]
+context: [repo]
+instructions: You are a careful coding agent.
+---
+Prefer minimal diffs. Cite the file you changed.
+```
+
+`discoverAgentBundles({ configRoot })` returns (paths only):
+
+```json
+[
+  {
+    "name": "coding",
+    "path": "/app/agents/coding/AGENT.md",
+    "configRoot": "/app",
+    "systemPromptPath": "/app/agents/SYSTEM.md",
+    "globalSkills": ["/app/agents/skills/format/SKILL.md"],
+    "globalTools": [],
+    "agentSkills": [],
+    "agentTools": []
+  }
+]
+```
+
+## Implementation example
+
+```ts
+import { type AgentBundle } from "@arnilo/prism/node/agent-definitions";
+import { discoverAgentBundles, resolveAgentBundle } from "@arnilo/prism/node/agent-definitions";
+import { discoverContributions } from "@arnilo/prism/node/contribution-discovery";
+import { createPathTrustPolicy } from "@arnilo/prism/node/trust";
+import { createContributionRegistries } from "@arnilo/prism";
+
+// 1. App owns configRoot; never auto-discovered, never the user's home dir.
+const configRoot = "/app/cfg";
+const workspaceRoot = "/repo";
+const trust = createPathTrustPolicy({ trustedRoots: [configRoot, workspaceRoot] });
+
+// 2. Discover bundle envelopes (paths only — no parse, no import).
+const [bundle] = await discoverAgentBundles({ configRoot, trust });
+if (!bundle) throw new Error("no agent bundle found");
+
+// 3. Repo .agents/ contributions are a separate scan (opt-in discovery).
+const registries = createContributionRegistries();
+const repoContributions = await discoverContributions({
+  kinds: ["skill", "tool"],
+  workspaceRoot,
+  trust,
+});
+
+// 4. Resolve the bundle into an Agent. Skills/tools union across scopes;
+//    duplicate names across scopes throw. Prompt layers append: SYSTEM.md →
+//    AGENT.md body → AGENTS.md. Drop the repo AGENTS.md layer here via flags.
+const agent = await resolveAgentBundle(bundle as AgentBundle, {
+  workspaceRoot,
+  repoContributions,
+  registries,
+  trust,
+  include: { repoPrompt: false },
+});
+
+// 5. The host still owns activation.
+await agent.createSession().run("Hi", { activeSkills: ["format"] });
+```
+
+For a hand-held `AgentDefinition` without a bundle, `resolveAgentDefinition` is the lighter path. Capability lists are explicit: omit `tools`/`skills` to activate none.
+
+```ts
+import { resolveAgentDefinition } from "@arnilo/prism";
+
+const agent = resolveAgentDefinition(
+  { name: "doc", model: "openai/gpt-4o", tools: ["echo"], skills: ["brief"], instructions: "Be concise." },
+  { registries, providerSource, tools: myToolRegistry, skillsRegistry },
+);
+
+// Migration-only old behavior: omitted tools/skills means all in-scope tools/skills.
+const legacy = resolveAgentDefinition(
+  { name: "legacy", model: "openai/gpt-4o" },
+  { registries, tools: myToolRegistry, skillsRegistry, activateAllCapabilities: true },
+);
+```
+
+## Migration: explicit capability activation
+
+Old Phase 37 behavior could treat an omitted `tools` list as “every scoped tool”; some hosts also expected all scoped skills to be available. Phase 38 changes the safe default: omitted `tools` and omitted `skills` mean no active capabilities.
+
+Preferred migration:
+
+```ts
+// Before: omitted tools could receive every scoped tool.
+resolveAgentDefinition({ name: "doc", model: "openai/gpt-4o" }, context);
+
+// After: list the capabilities this agent may use.
+resolveAgentDefinition(
+  { name: "doc", model: "openai/gpt-4o", tools: ["read"], skills: ["brief"] },
+  context,
+);
+```
+
+Temporary compatibility shim:
+
+```ts
+resolveAgentDefinition(
+  { name: "legacy", model: "openai/gpt-4o" },
+  { ...context, activateAllCapabilities: true },
+);
+```
+
+Use `activateAllCapabilities: true` only while migrating old configs. It intentionally scans/list-activates every in-scope tool/skill. New configs should list names and use strict contribution registries (`createContributionRegistries({ duplicate: "error" })`) so a third-party package cannot silently shadow a capability name.
+
+## Extension and configuration notes
+
+- `ExtensionAPI.registerAgent(agent)` contributes an inert `AgentDefinition` programmatically; its `create()` (if present) is only invoked when the host runs it through `resolveAgentDefinition`. See [Extensions](extensions.md).
+- Bundle resolution is config over code: every seam lives on `AgentDefinition`, `AgentDefinitionResolutionContext`, or `ResolveAgentBundleOptions`. `systemPrompt` and `loop` are passed via `context.overrides` / `create()` rather than frontmatter.
+- Migration note: before Phase 38, a definition that omitted `tools` but had a tool scope could receive every scoped tool. Now omitted `tools`/`skills` activates none. Add explicit names to `tools` / `skills`; use `activateAllCapabilities: true` only while migrating old configs.
+- `parseAgentFile(text, path)` (re-exported from `@arnilo/prism`) is the stdlib-only frontmatter parser for `AGENT.md`. `parseContextFile` and `parseToolFile` parse colocated `CONTEXT.md` / tool descriptors inside the Node subpath.
+- Repo contributions (`<workspaceRoot>/.agents/{skills,tools}/`) are scanned by `discoverContributions` and passed via `repoContributions`. Repo `.agents/` is preserved as a shared contribution surface across every agent that operates on the same repository; multiple agents from different apps can work the same repo, and all share its repo-level skills.
+
+## Security and performance notes
+
+- **App owns `configRoot`**: Prism never picks the config root, never defaults to the user's home directory, and never auto-runs discovery or resolution. The host calls `discoverAgentBundles` / `resolveAgentBundle` explicitly. `--agents-config <path>` on the `prism` CLI is the explicit opt-in.
+- **All layers optional**: every prompt and contribution scope is independently togglable via `AgentBundleScopeFlags` (all default `true`); region can be enabled per agent or globally by the host.
+- **Explicit capability activation**: omitted `AgentDefinition.tools` / `skills` activates no tools or skills by default, even when registries are in scope. Named dependencies resolve fail-closed; `activateAllCapabilities: true` is the only legacy all-capabilities opt-in.
+- **Duplicate names error, not override**: skills/tools union across scopes throw on collision so a name shadow can never silently change behavior.
+- **Independent trust gating**: `resolveAgentBundle` trust-gates the app-config root (`SYSTEM.md`) and the workspace root (`AGENTS.md`) independently via `createPathTrustPolicy` + `isPathInsideReal`; symlink escapes are excluded, untrusted roots contribute nothing (fail-closed). See [Security/auth/trust](settings-auth-trust-security.md).
+- **No execution on discovery**: `discoverAgentBundles` returns paths only; `resolveAgentBundle` reads text only — it never `import()`s, `require()`s, or `eval()`s any contribution file. Tool descriptors parsed from `manifest.json` are descriptor-only `ToolDefinition` objects whose `execute()` throws `Discovered tool <name> requires host execution` if invoked. The host lifts them into live tools itself.
+- **Secrets**: loaded prompt/skill text is caller- and host-supplied content subject to `redactProviderRequest` like any system instruction. Do not put secrets in `AGENT.md` / `SYSTEM.md` / `SKILL.md`, settings, manifests, or docs examples.
+- **Performance**: `discoverAgentBundles` is one `readdir` per level; `resolveAgentBundle` reads each prompt file at most once per call. There is no cross-call cache — resolution is one-shot (memoize in the host if the same bundle is resolved repeatedly).
+
+## Related APIs
+
+- [Agent/session runtime](agent-session-runtime.md): `createAgent` / `createAgentSession`, the runtime `resolveAgentDefinition` builds onto.
+- [System prompts](system-prompts.md): `composeSystemPrompt` source ranks and the `AGENT.md` body / `SYSTEM.md` / `AGENTS.md` prompt layering reused by `resolveAgentBundle`.
+- [Contribution discovery (workspace)](contribution-discovery.md): `discoverContributions` for repo `.agents/` contributions passed as `repoContributions`.
+- [Context and skills](context-and-skills.md): `resolveActiveSkills` and `RunOptions.activeSkills` activation that consumes discovered skills.
+- [Tools](tools.md): `ToolDefinition` / `(toolNames)` enforcement and host-owned tool execution.
+- [Agent loops](agent-loops.md): `resolveLoop` and loop strategies passed via `loop` / `context.overrides`.
+- [Extensions](extensions.md): `registerAgent()` programmatic registration of inert `AgentDefinition` values.
+- [CLI/RPC](cli-rpc.md): the `--agents-config <path>` flag.
+- [Security/auth/trust](settings-auth-trust-security.md): `createPathTrustPolicy`, `assertPermission`, and the trust model.