@arnilo/prism 0.0.3 → 0.0.4

package/dist/testing/run-ledger-conformance.js

@@ -0,0 +1,172 @@
+// ponytail: dependency-free conformance helper for the RunLedger adapter contract.
+// Database-backed adapters call this once (or via runRunLedgerConformance factory)
+// to assert durable run/event/tool/usage writes, per-run ordering, tenant
+// isolation, and restart idempotency before shipping dialect-local SQL.
+const NOW = "2026-01-01T00:00:00.000Z";
+/**
+ * Assert that a `RunLedger` implementation satisfies the write contract:
+ * all record kinds round-trip via optional read callbacks, per-run event order
+ * is preserved, and tenant-scoped rows store `tenant_id` when
+ * `exerciseTenantIsolation` is enabled.
+ */
+export async function assertRunLedgerConforms(fixture, options = {}) {
+    const sessionId = options.sessionId ?? "ledger-conformance";
+    const runId = options.runId ?? "run-conformance";
+    const tenantId = options.tenantId ?? "tenant-a";
+    const scope = {
+        tenantId,
+        accountId: options.accountId ?? "account-a",
+        userId: options.userId ?? "user-a",
+    };
+    const runStart = {
+        id: runId,
+        sessionId,
+        status: "running",
+        startedAt: NOW,
+        provider: "mock",
+        model: { provider: "mock", model: "demo" },
+        idempotencyKey: "run-key-1",
+        ...scope,
+    };
+    const runFinish = {
+        ...runStart,
+        status: "succeeded",
+        finishedAt: "2026-01-01T00:00:01.000Z",
+    };
+    const eventA = {
+        id: "event-a",
+        sessionId,
+        runId,
+        type: "agent_started",
+        timestamp: NOW,
+        event: { type: "agent_started", sessionId, runId },
+        redacted: false,
+        ...scope,
+    };
+    const eventB = {
+        id: "event-b",
+        sessionId,
+        runId,
+        type: "turn_started",
+        timestamp: "2026-01-01T00:00:00.500Z",
+        event: { type: "turn_started", sessionId, runId, turn: 1 },
+        redacted: false,
+        ...scope,
+    };
+    const tool = {
+        id: "tool-row-1",
+        sessionId,
+        runId,
+        toolCallId: "call-1",
+        name: "echo",
+        arguments: { msg: "hi" },
+        status: "finished",
+        result: { toolCallId: "call-1", name: "echo", value: "hi" },
+        startedAt: NOW,
+        finishedAt: "2026-01-01T00:00:00.800Z",
+        redacted: false,
+        ...scope,
+    };
+    const usage = {
+        id: "usage-1",
+        sessionId,
+        runId,
+        usage: { inputTokens: 3, outputTokens: 5, totalTokens: 8 },
+        recordedAt: "2026-01-01T00:00:01.000Z",
+        ...scope,
+    };
+    await fixture.ledger.appendRun(runStart);
+    await fixture.ledger.appendEvent(eventA);
+    await fixture.ledger.appendEvent(eventB);
+    await fixture.ledger.appendToolCall(tool);
+    await fixture.ledger.appendUsage(usage);
+    await fixture.ledger.appendRun(runFinish);
+    if (fixture.readRuns) {
+        const runs = await fixture.readRuns();
+        const snapshots = runs.filter((row) => row.id === runId);
+        if (!snapshots.some((row) => row.status === "succeeded")) {
+            throw new Error("RunLedger must persist the terminal RunRecord");
+        }
+        const succeeded = snapshots.find((row) => row.status === "succeeded");
+        if (succeeded.startedAt !== runStart.startedAt) {
+            throw new Error("RunLedger must preserve startedAt on the terminal RunRecord");
+        }
+        if (snapshots.length > 1 && !snapshots.some((row) => row.status === "running")) {
+            throw new Error("RunLedger must persist the running RunRecord when multiple snapshots are stored");
+        }
+    }
+    if (fixture.readEvents) {
+        const events = await fixture.readEvents();
+        const forRun = events.filter((row) => row.runId === runId);
+        const ids = forRun.map((row) => row.id);
+        const aIndex = ids.indexOf("event-a");
+        const bIndex = ids.indexOf("event-b");
+        if (aIndex < 0 || bIndex < 0)
+            throw new Error("RunLedger dropped appended AgentEventRecord rows");
+        if (aIndex > bIndex)
+            throw new Error("RunLedger must preserve per-run event append order");
+    }
+    if (fixture.readToolCalls) {
+        const toolCalls = await fixture.readToolCalls();
+        if (!toolCalls.some((row) => row.toolCallId === "call-1")) {
+            throw new Error("RunLedger must persist ToolCallRecord rows");
+        }
+    }
+    if (fixture.readUsage) {
+        const usageRows = await fixture.readUsage();
+        if (!usageRows.some((row) => row.id === "usage-1")) {
+            throw new Error("RunLedger must persist UsageRecord rows");
+        }
+    }
+    if (options.exerciseTenantIsolation && fixture.readRuns) {
+        const otherRun = {
+            id: "run-tenant-b",
+            sessionId: `${sessionId}-tenant-b`,
+            status: "running",
+            startedAt: NOW,
+            provider: "mock",
+            tenantId: "tenant-b",
+            accountId: "account-b",
+            userId: "user-b",
+        };
+        await fixture.ledger.appendRun(otherRun);
+        const runs = await fixture.readRuns();
+        const stored = runs.find((row) => row.id === "run-tenant-b");
+        if (!stored || stored.tenantId !== "tenant-b") {
+            throw new Error("RunLedger must persist tenant_id on records for tenant-scoped isolation");
+        }
+        const scoped = runs.filter((row) => row.tenantId === tenantId);
+        if (!scoped.some((row) => row.id === runId)) {
+            throw new Error("RunLedger read path must return tenant-a rows when queried for conformance session");
+        }
+    }
+}
+/**
+ * Factory-based conformance entry point for durable adapters. Invokes
+ * `assertRunLedgerConforms` against a fresh fixture and optionally reopens via
+ * the same factory to assert writes survive process/database reopen.
+ */
+export async function runRunLedgerConformance(factory, options = {}) {
+    const first = await factory();
+    await assertRunLedgerConforms(first, options);
+    if (!options.exerciseReopen)
+        return;
+    const reopened = await factory();
+    if (!reopened.readRuns && !reopened.readEvents) {
+        throw new Error("exerciseReopen requires readRuns or readEvents on the fixture");
+    }
+    if (reopened.readRuns) {
+        const runs = await reopened.readRuns();
+        const runId = options.runId ?? "run-conformance";
+        if (!runs.some((row) => row.id === runId)) {
+            throw new Error("RunLedger rows did not survive adapter reopen");
+        }
+    }
+    if (reopened.readEvents) {
+        const events = await reopened.readEvents();
+        if (!events.some((row) => row.id === "event-a")) {
+            throw new Error("RunLedger events did not survive adapter reopen");
+        }
+    }
+}
+//# sourceMappingURL=run-ledger-conformance.js.map

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

@@ -2,13 +2,23 @@ import type { SessionStore } from "../contracts.js";
 export interface SessionStoreConformanceOptions {
     /** Stable session id used for the conformance run; defaults to "conformance". */
     readonly sessionId?: string;
+    /** Secondary session id for branch-isolation probes; defaults to "conformance-other". */
+    readonly otherSessionId?: string;
     /**
      * When true, also exercises the optional `readBranchPath` branch-reader path
      * and asserts it returns the ancestor chain in root-to-leaf order. Skipped
      * when the store does not implement `readBranchPath`.
      */
     readonly exerciseReadBranchPath?: boolean;
+    /** When true, appends concurrent children of the same parent (fork allowed). */
+    readonly exerciseConcurrentParentAppend?: boolean;
+    /**
+     * When true, the factory is invoked again after writes to assert durable state
+     * survives reopen (database adapters only).
+     */
+    readonly exerciseReopen?: boolean;
 }
+export type SessionStoreConformanceFactory = () => SessionStore | Promise<SessionStore>;
 /**
  * Assert that a `SessionStore` implementation satisfies the core adapter
  * contract: round-trip append/list, duplicate-entry-id rejection,
@@ -18,3 +28,9 @@ export interface SessionStoreConformanceOptions {
  * violation; returns silently when the store conforms.
  */
 export declare function assertSessionStoreConforms(store: SessionStore, options?: SessionStoreConformanceOptions): Promise<void>;
+/**
+ * Factory-based conformance entry point for durable adapters. Calls the factory
+ * to obtain a store, runs the full contract, and optionally reopens through the
+ * same factory to assert idempotency rows and entries survive restart.
+ */
+export declare function runSessionStoreConformance(factory: SessionStoreConformanceFactory, options?: SessionStoreConformanceOptions): Promise<void>;

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

@@ -63,6 +63,79 @@ export async function assertSessionStoreConforms(store, options = {}) {
             throw new Error(`readBranchPath must return the ancestor chain root→leaf in order; got ${JSON.stringify(ids)}`);
         }
     }
+    await assertSessionStoreBranchIsolation(store, options);
+    if (options.exerciseConcurrentParentAppend) {
+        await assertConcurrentParentAppendAllowed(store, sessionId, now, make);
+    }
+}
+/**
+ * Factory-based conformance entry point for durable adapters. Calls the factory
+ * to obtain a store, runs the full contract, and optionally reopens through the
+ * same factory to assert idempotency rows and entries survive restart.
+ */
+export async function runSessionStoreConformance(factory, options = {}) {
+    const store = await factory();
+    await assertSessionStoreConforms(store, options);
+    if (!options.exerciseReopen)
+        return;
+    const sessionId = options.sessionId ?? "conformance";
+    const listed = await store.list(sessionId);
+    const parent = listed.at(-1);
+    await store.append({
+        id: "reopen-target",
+        parentId: parent?.id,
+        sessionId,
+        timestamp: "2026-01-01T00:00:01.000Z",
+        kind: "label",
+        label: "reopen",
+    }, { idempotencyKey: "reopen-idem", expectedParentId: parent?.id });
+    const before = (await store.list(sessionId)).map((entry) => entry.id);
+    const reopened = await factory();
+    const after = (await reopened.list(sessionId)).map((entry) => entry.id);
+    if (before.join("\u0000") !== after.join("\u0000")) {
+        throw new Error("Session entries did not survive adapter reopen");
+    }
+    await reject(() => reopened.append({
+        id: "reopen-idem-dup",
+        parentId: parent?.id,
+        sessionId,
+        timestamp: "2026-01-01T00:00:01.000Z",
+        kind: "label",
+        label: "dup",
+    }, { idempotencyKey: "reopen-idem", expectedParentId: parent?.id }), (error) => isSessionAppendConflict(error) && error.conflict.idempotencyDuplicate === true, "Restarted store must still deduplicate an exact idempotency retry");
+}
+async function assertSessionStoreBranchIsolation(store, options) {
+    const sessionId = options.sessionId ?? "conformance";
+    const otherSessionId = options.otherSessionId ?? `${sessionId}-other`;
+    const entry = {
+        id: "isolation-entry",
+        sessionId: otherSessionId,
+        timestamp: "2026-01-01T00:00:00.000Z",
+        kind: "label",
+        label: "isolated",
+    };
+    await store.append(entry);
+    const primary = await store.list(sessionId);
+    if (primary.some((row) => row.id === "isolation-entry")) {
+        throw new Error("SessionStore leaked entries across session ids");
+    }
+}
+async function assertConcurrentParentAppendAllowed(store, sessionId, now, make) {
+    const forkRoot = make("fork-root");
+    await store.append(forkRoot);
+    const childA = make("fork-a", forkRoot.id);
+    const childB = make("fork-b", forkRoot.id);
+    const results = await Promise.allSettled([
+        store.append(childA, { expectedParentId: forkRoot.id }),
+        store.append(childB, { expectedParentId: forkRoot.id }),
+    ]);
+    const succeeded = results.filter((result) => result.status === "fulfilled").length;
+    if (succeeded === 0)
+        throw new Error("Concurrent append to an existing parent rejected both writers; at least one fork child must succeed");
+    const listed = await store.list(sessionId);
+    if (!listed.some((entry) => entry.id === "fork-a") && !listed.some((entry) => entry.id === "fork-b")) {
+        throw new Error("Concurrent parent append wrote no child entries");
+    }
 }
 function assertIds(entries, expected, message) {
     const actual = entries.map((entry) => entry.id);

package/dist/tools.d.ts

@@ -9,6 +9,23 @@ export interface ToolFilter {
 }
 export type ToolFilterInput = ToolFilter | readonly ToolFilter[];
 export type ToolValidator = (tool: ToolDefinition, args: JsonObject, context: ToolExecutionContext) => void | string | ErrorInfo | Promise<void | string | ErrorInfo>;
+export interface ToolArgumentValidationError {
+    readonly path?: string;
+    readonly message: string;
+}
+export interface ToolArgumentValidationResult {
+    readonly ok: boolean;
+    readonly errors?: readonly ToolArgumentValidationError[];
+}
+export interface ToolArgumentValidator {
+    validate(schema: JsonObject, value: unknown): ToolArgumentValidationResult;
+}
+export interface ToolParameterValidatorOptions {
+    /** When a tool omits `parameters`. Default `"allow"` preserves pre-validation behavior. */
+    readonly missingSchema?: "allow" | "reject";
+}
+/** Wrap a schema adapter as the existing `ToolValidator` seam used by dispatch and the agent runtime. */
+export declare function createToolParameterValidator(validator: ToolArgumentValidator, options?: ToolParameterValidatorOptions): ToolValidator;
 export interface DispatchToolCallOptions {
     readonly call: ToolCallContent;
     readonly registry: ToolRegistry;

package/dist/tools.js

@@ -2,6 +2,26 @@ import { isJsonObject } from "./config.js";
 import { errorToErrorInfo, redactRunLedgerRecord, redactSecrets } from "./redaction.js";
 import { assertCanRegister } from "./registry-options.js";
 import { assertPermission } from "./security.js";
+/** Wrap a schema adapter as the existing `ToolValidator` seam used by dispatch and the agent runtime. */
+export function createToolParameterValidator(validator, options = {}) {
+    const missingSchema = options.missingSchema ?? "allow";
+    return (tool, args) => {
+        if (!tool.parameters) {
+            if (missingSchema === "reject")
+                return `Tool ${tool.name} has no parameters schema`;
+            return undefined;
+        }
+        const result = validator.validate(tool.parameters, args);
+        if (result.ok)
+            return undefined;
+        return formatToolArgumentValidationErrors(tool.name, result.errors);
+    };
+}
+function formatToolArgumentValidationErrors(toolName, errors) {
+    if (!errors?.length)
+        return `Tool arguments failed validation: ${toolName}`;
+    return errors.map((error) => (error.path ? `${error.path}: ${error.message}` : error.message)).join("; ");
+}
 export function createToolRegistry(tools = [], options = {}) {
     const byName = new Map();
     const registry = {
@@ -32,6 +52,9 @@ export function filterTools(tools, filter) {
     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)));
 }
+function toolExecutionMetadata(startedAt, status) {
+    return { durationMs: Math.max(0, Date.now() - Date.parse(startedAt)), status };
+}
 export async function dispatchToolCall(options) {
     const secrets = options.secrets ?? [];
     const startedAt = new Date().toISOString();
@@ -80,7 +103,8 @@ export async function dispatchToolCall(options) {
         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 });
+        const metadata = toolExecutionMetadata(startedAt, "finished");
+        await options.emit?.({ type: "tool_execution_finished", sessionId: context.sessionId, runId: context.runId, result, metadata });
         await appendToolCallRecord(options, "finished", mediatedCall, startedAt, { finishedAt, result });
         return result;
     }
@@ -88,7 +112,8 @@ export async function dispatchToolCall(options) {
         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 });
+        const metadata = toolExecutionMetadata(startedAt, "error");
+        await options.emit?.({ type: "tool_execution_error", sessionId: context.sessionId, runId: context.runId, call: mediatedCall, error: info, metadata });
         await appendToolCallRecord(options, "error", mediatedCall, startedAt, { finishedAt, result });
         return result;
     }
@@ -105,6 +130,7 @@ async function checkCall(call, options, startedAt) {
     return undefined;
 }
 async function blocked(call, context, reason, error, options, startedAt) {
+    const metadata = toolExecutionMetadata(startedAt, "blocked");
     await options.emit?.({
         type: "tool_execution_blocked",
         sessionId: context.sessionId,
@@ -113,6 +139,7 @@ async function blocked(call, context, reason, error, options, startedAt) {
         name: call.name,
         reason,
         error,
+        metadata,
     });
     const finishedAt = new Date().toISOString();
     const result = { toolCallId: call.id, name: call.name, error };

package/docs/agent-events.md

@@ -40,6 +40,7 @@ The `AgentEvent` union (grouped by concern):
 | --- | --- |
 | Agent lifecycle | `agent_started`, `agent_finished` |
 | Turns | `turn_started`, `turn_finished` |
+| Provider turns | `provider_turn_started`, `provider_turn_finished` |
 | Assistant messages | `message_started`, `message_delta`, `message_finished` |
 | Tool execution | `tool_execution_started`, `tool_execution_progress`, `tool_execution_finished`, `tool_execution_error`, `tool_execution_blocked` |
 | Queue/subscribers | `queue_updated`, `event_subscriber_overflow` |
@@ -70,11 +71,11 @@ Tool execution events:
 | --- | --- |
 | `tool_execution_started` | `sessionId`, `runId`, `call: ToolCallContent` |
 | `tool_execution_progress` | `sessionId`, `runId`, `toolCallId`, `name`, `progress?`, `metadata?` |
-| `tool_execution_finished` | `sessionId`, `runId`, `result: ToolResult` |
-| `tool_execution_error` | `sessionId`, `runId`, `call: ToolCallContent`, `error: ErrorInfo` |
-| `tool_execution_blocked` | `sessionId`, `runId`, `toolCallId`, `name`, `reason: string`, `error: ErrorInfo` |
+| `tool_execution_finished` | `sessionId`, `runId`, `result: ToolResult`, `metadata: ToolExecutionMetadata` |
+| `tool_execution_error` | `sessionId`, `runId`, `call: ToolCallContent`, `error: ErrorInfo`, `metadata: ToolExecutionMetadata` |
+| `tool_execution_blocked` | `sessionId`, `runId`, `toolCallId`, `name`, `reason: string`, `error: ErrorInfo`, `metadata: ToolExecutionMetadata` |
 
-Queue / subscriber / compaction / retry events:
+Queue / subscriber / compaction / retry / provider events:
 
 | Variant | Fields |
 | --- | --- |
@@ -84,6 +85,13 @@ Queue / subscriber / compaction / retry events:
 | `compaction_finished` | `sessionId`, `runId?`, `summary: string` |
 | `retry_scheduled` | `sessionId`, `runId`, `attempt: number`, `delayMs: number`, `error: ErrorInfo` |
 
+Provider turn events (metadata only — see [Observability](observability.md)):
+
+| Variant | Fields |
+| --- | --- |
+| `provider_turn_started` | `sessionId`, `runId`, `turn`, `metadata: ProviderTurnMetadata` |
+| `provider_turn_finished` | `sessionId`, `runId`, `turn`, `metadata` (includes `latencyMs` on finish), `usage?`, `error?` |
+
 Artifact validation/refinement events (emitted only by `generateValidateReviseLoop`; `singleShotLoop` emits zero artifact events):
 
 | Variant | Fields |
@@ -195,5 +203,6 @@ await session.run("draft", { loop: { strategy: "generate-validate-revise", valid
 - [Agent loops](agent-loops.md): `singleShotLoop` and `generateValidateReviseLoop` emit the artifact events.
 - [Structured output](structured-output.md): `ArtifactValidation` shape threaded through parser/validator/repairer.
 - [Public contracts](public-contracts.md): full `AgentEvent` union and `ArtifactValidation` contract.
+- [Observability](observability.md): `ProviderTurnMetadata`, OpenTelemetry adapter package.
 - [Tools](tools.md): `tool_execution_*` variants.
 - [Compaction and retry policies](compaction-and-retry.md): `compaction_*` and `retry_scheduled` variants.

package/docs/agent-loops.md

@@ -46,7 +46,7 @@ const agent = createAgent({
   model,
   provider,
   // optional default loop for this agent:
-  loop: { strategy: "single-shot" },
+  loop: { strategy: "single-shot", toolConcurrency: 4 },
 });
 
 // RunOptions.loop overrides per request.
@@ -68,7 +68,11 @@ await session.run(input, { loop: myCustomLoop });
 
 ```ts
 type AgentLoopOptions =
-  | { readonly strategy: "single-shot" }
+  | {
+      readonly strategy: "single-shot";
+      /** Independent tool calls per turn run concurrently up to this limit. Default `1`. */
+      readonly toolConcurrency?: number;
+    }
   | {
       readonly strategy: "generate-validate-revise";
       readonly validator: ArtifactValidator<unknown>;
@@ -95,7 +99,7 @@ Host callback contracts (all generic over host `T`):
 | --- | --- |
 | `sessionId`, `runId`, `metadata`, `signal` | Run identity and abort. |
 | `history: Message[]` | Live mutable history — the loop pushes assistant and repair messages directly. |
-| `input`, `inputMessages`, `maxToolRounds` | First-turn input, the redacted input messages, and the tool-round budget (single-shot parity hooks). |
+| `input`, `inputMessages`, `maxToolRounds`, `toolConcurrency` | First-turn input, redacted input messages, tool-round budget, and per-turn parallel dispatch limit (`toolConcurrency` default `1`). |
 | `assemble(nextInput, toolResults?)` | Wraps `assembleProviderInput()` with resolved skills/tools/context/system prompt/provider options. |
 | `generate(request)` | Wraps provider request policies + `provider_request` middleware + `generateWithRetry()`; returns `ProviderTurnResult`. |
 | `dispatchToolCall(call)` | Wraps `dispatchToolCall()` with resolved registry/middleware/permission/redactor/validate. |
@@ -195,7 +199,8 @@ await session.run(input, { loop: twoShotLoop });
 - `{ strategy: "single-shot" }` resolves to the exported `singleShotLoop`; `{ strategy: "generate-validate-revise", ... }` is mapped by `resolveLoop()` to `generateValidateReviseLoop(opts)`. An unknown `strategy` throws before the first turn. Passing an `AgentLoopStrategy` instance bypasses the options form entirely (custom-loop escape hatch).
 - The loop is resolved once per run inside `RuntimeAgentSession.run()`, after the usual setup (provider/skills/tools resolution, history rebuild, model-change entry, input append, auto-compaction). The runtime's outer try/catch/finally, run-exclusivity, abort bridging, and subscriber close remain in place around `loop.run(ctx)`.
 - `LoopContext.assemble(nextInput, toolResults?)` accepts an optional tool-result accumulator so `singleShotLoop` can pass its loop-local `toolResults`; `generateValidateReviseLoop` omits it (no tools in revision turns).
-- `maxToolRounds` bounds `singleShotLoop` tool rounds; `maxRevisions` (default 3) bounds `generateValidateReviseLoop` revision turns. Budget exhaustion ends the loop and returns the last usage; it does not throw.
+- `maxToolRounds` bounds `singleShotLoop` tool rounds; `toolConcurrency` (default `1`) bounds how many independent tool calls from one provider turn may execute concurrently. Results and transcript rows are still appended in original call order. If any resolved `ToolDefinition` in a turn has `exclusive: true`, that turn uses concurrency `1`; later non-exclusive turns restore configured concurrency.
+- `maxRevisions` (default 3) bounds `generateValidateReviseLoop` revision turns. Budget exhaustion ends the loop and returns the last usage; it does not throw.
 - A revision cycle appends one assistant draft and one repair user message per revision to the session store, so store entries reflect every attempted draft. The original user input is stored once by the runtime and pushed into loop history once on the first turn.
 
 ## Security and performance notes
@@ -203,6 +208,7 @@ await session.run(input, { loop: twoShotLoop });
 - Loops have no path to credentials, provider objects, or unredacted secrets. `LoopContext.generate` consumes an already-redacted request; `LoopContext.emit` runs through `redactAgentEvent` with the active `SecretRedactor`; `LoopContext.appendMessage` appends a redacted entry.
 - `ArtifactValidation.errors[].message` may echo model text — `artifact_*` event payloads flow through the same `redactAgentEvent` path as other `AgentEvent`s (see [Agent events](agent-events.md)).
 - `generateValidateReviseLoop` 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.
+- Parallel tool dispatch uses a bounded worker pool over the calls in one turn; queue depth is `calls.length`, not unbounded. Exclusive turns use the same sequential path. Each call still runs through `dispatchToolCall` (permission + validation + execute). Tool lifecycle events may complete out of order; history/store appends stay in call order.
 - The loop is a plain object/factory; no class hierarchy, no background work, no extra dependencies. `LoopContext` is a single object literal of bound arrows built once per run.
 - The Synapta-free boundary is guarded by tests: `src/` imports no `synapta*` package, and the `Artifact*`/`AgentLoop*`/`LoopContext` contracts contain no `workflow`/`node`/`step` field names. Hosts supply their own schema; no host domain type is imported by `src/`.
 

package/docs/agent-session-runtime.md

@@ -173,6 +173,7 @@ await agent.createSession().run("Hi", { model: overrideModel });
 - [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.
+- [Workflows](workflows.md): optional DAG orchestration that calls `AgentSession.run()` for agent nodes.
 
 `AgentConfig.loop` and `RunOptions.loop` select a replaceable per-run control loop (`singleShotLoop` default, or `generate-validate-revise` with host callbacks); see [Agent loops](agent-loops.md). `RunOptions.loop` wins over `AgentConfig.loop`. Built-in loops emit the same normal turn/message envelope around provider turns, and both add the first run input to live history once after the first provider turn so later turns see the same transcript shape.
 

package/docs/cli-rpc.md

@@ -147,6 +147,8 @@ CLI/RPC are adapters over `AgentSession`. They do not scan packages, import exte
 
 RPC `command` executes only explicitly registered `CommandDefinition` values. `setModel` stores a model override for later prompt/follow-up calls. `compact`, `switchSession`, `forkSession`, `cloneSession`, and `checkout` call the existing session APIs.
 
+Optional workflow control (from `@arnilo/prism-workflows`) registers `workflow.start`, `workflow.status`, `workflow.list`, `workflow.cancel`, and `workflow.resume` via `createWorkflowCommands({ workflows, checkpoints, runOptions? })`. Pass the returned `CommandDefinition[]` into `runRpcServer({ commands })` the same way as observational-memory commands. Cancel aborts in-process runs through the package active-run registry; orphaned durable checkpoints still marked `running` are fail-closed to `aborted`.
+
 `forkSession` creates another handle for the same `sessionId` and selected `leafId`; it no longer overwrites the parent handle in the RPC map. Keep the returned `handleId` when a UI needs to switch among sibling branches. `switchSession` accepts `handleId` (preferred), `sessionId`, or `id`; with multiple branch handles, use `handleId` to avoid ambiguity. `checkout` requires `params.leafId`, calls `AgentSession.checkout(leafId)`, and keeps the active handle id unchanged while moving that handle to the existing leaf. `messages` returns entries for the active branch path.
 
 ## Security and performance notes
@@ -169,6 +171,7 @@ RPC `command` executes only explicitly registered `CommandDefinition` values. `s
 - [Resource loading](resource-loading.md): explicit resource loading primitives.
 - [Credentials and redaction](credentials-and-redaction.md): secret redaction helpers and credential boundaries.
 - [Observational memory compaction package](compaction-observational-memory.md): optional `om:status` and `om:view` command factories for explicitly wired hosts.
+- [Workflows](workflows.md): optional `createWorkflowCommands()` for start/status/list/cancel/resume over the same RPC `command` seam.
 
 The CLI records flags but does not auto-load project-local resources, extensions, tools, or config. The two system/project prompt files are the exception: in print/json modes the CLI auto-loads `<workspaceRoot>/AGENTS.md` (trust-gated) and an app-supplied `SYSTEM.md` layer as `AgentConfig.systemPrompt` layers composed with `--system` (base); `--no-agents-md` / `--no-system-md` skip them and `--agents-md-file` / `--system-md-file` override the paths. The CLI does not default `globalRoot` to the user's home directory — pass it from a host adapter or use `--agents-config <path>` for the app-config bundle layout. RPC mode does not auto-read these files (the host owns the session factory). Hosts must make explicit trust and permission decisions before wiring any other local loading.
 

package/docs/coding-agent-tools.md

@@ -14,6 +14,8 @@
 | `createReadOnlyTools(cwd, options?)` | Read-only subset: `read` only. |
 | `createAllTools(cwd, options?)` | Every tool the package provides (currently identical to `createCodingTools`). |
 | `detectSupportedImageMimeType(buf)` / `detectSupportedImageMimeTypeFromFile(path)` | Magic-byte image MIME detection (PNG/JPEG/GIF/WebP/BMP) used by `read`. |
+| `DEFAULT_MAX_IMAGE_BYTES` | Default `read` image size ceiling (10 MB). |
+| `TransformImage` / `TransformImageInput` | Types for the optional `read` `transformImage` callback. |
 | `withFileMutationQueue(path, fn)` | Per-path serialization primitive re-exported for hosts. |
 
 Each factory returns a plain `ToolDefinition` (no auto-registration). Register what you need:
@@ -29,7 +31,19 @@ const tools = createToolRegistry(createCodingTools(process.cwd()));
 
 Use this package when a host wants ready-made coding tools for an agent, session, or run, registered explicitly into a `ToolRegistry` and dispatched through the normal Prism tool harness. The tools perform **real** shell and filesystem operations on the host — they are not mocked or sandboxed. Use the individual factories when you need per-tool options or custom operation backends; use the aggregators when you want the default set.
 
-Do not use this package as a sandbox, permission policy, secret store, or provider loop. Prism gates tool dispatch with `PermissionPolicy` / `ToolValidator` / trust policies; the package performs no gating of its own. Do not register these tools for an untrusted provider.
+Do not use this package as a sandbox, permission policy, secret store, or provider loop. Prism gates tool dispatch with `PermissionPolicy` / `ToolValidator` / trust policies; pass an optional `ExecutionPolicy` (for example from `@arnilo/prism-coding-security`) for path/command approval before side effects. Do not register these tools for an untrusted provider.
+
+```ts
+import { createCodingTools } from "@arnilo/prism-coding-agent";
+import { createCodingApprovalPolicy } from "@arnilo/prism-coding-security";
+
+const tools = createCodingTools(workspaceRoot, {
+  executionPolicy: createCodingApprovalPolicy({
+    roots: [workspaceRoot],
+    approve: async ({ action }) => host.confirm(action),
+  }),
+});
+```
 
 ### pi name mapping
 
@@ -40,7 +54,7 @@ Do not use this package as a sandbox, permission policy, secret store, or provid
 | `write` | `write` |
 | `edit` | `edit` |
 
-## Tools
+## Inputs / request
 
 ### `shell`
 
@@ -77,16 +91,36 @@ Read a text or image file.
 | `offset` | `number` | Line to start reading from (1-indexed). |
 | `limit` | `number` | Maximum number of lines to read. |
 
-**Outputs:** text files become a single `TextContent`, truncated to `maxLines`/`maxBytes` (defaults 2000 lines / 50 KB) with a `Use offset=N to continue` footer when more remains. Image files (PNG/JPEG/GIF/WebP/BMP by magic bytes) become `[TextContent note, ImageContent]` with base64 `data` and `mimeType`. Read failures (missing file, offset beyond end, abort) are error results.
+**Outputs:** text files become a single `TextContent`, truncated to `maxLines`/`maxBytes` (defaults 2000 lines / 50 KB) with a `Use offset=N to continue` footer when more remains. Image files (PNG/JPEG/GIF/WebP/BMP by **magic bytes**, not extension) become `[TextContent note, ImageContent]` with base64 `data` and `mimeType`. Oversize images are rejected by `stat` (when available) or `buffer.length` against `maxImageBytes` (default 10 MB) before base64 encoding. An optional `transformImage` callback lets hosts resize or re-encode images without adding image-processing dependencies to the base package. Read failures (missing file, offset beyond end, oversize image, abort) are error results.
+
+`read` tool options (via `createReadTool(cwd, options)` or `ToolsOptions.read`):
+
+| Option | Default | Purpose |
+| --- | --- | --- |
+| `maxImageBytes` | `DEFAULT_MAX_IMAGE_BYTES` (10 MB) | Reject image reads larger than this many bytes. |
+| `transformImage` | — | Host callback `( { buffer, mimeType } ) => Promise<Buffer>` run after read, before base64. |
+| `autoResizeImages` | — | **Deprecated.** Ignored unless `transformImage` is also set (use `transformImage` instead). |
+| `maxLines` / `maxBytes` | 2000 / 50 KB | Text head truncation limits. |
+| `operations` | local fs | Pluggable `ReadOperations` backend. |
+| `executionPolicy` | — | Structured pre-execution policy (see [Coding security](coding-security.md)). |
+
+```ts
+import { createReadTool, DEFAULT_MAX_IMAGE_BYTES } from "@arnilo/prism-coding-agent";
+
+const read = createReadTool(cwd, {
+  maxImageBytes: DEFAULT_MAX_IMAGE_BYTES,
+  transformImage: async ({ buffer, mimeType }) => host.resizeImage(buffer, mimeType),
+});
+```
 
 `read` result `metadata`:
 
 | Field | Present when | Purpose |
 | --- | --- | --- |
 | `truncation` | text reads | `TruncationResult`. |
-| `image` | image reads | `{ mimeType, resized: false }`. |
+| `image` | image reads | `{ mimeType, resized, bytes }`. `resized` is `true` when `transformImage` ran. |
 
-> `autoResizeImages` is accepted but is currently a documented no-op (deferred); images are returned at their original size with `image.resized = false`.
+> `autoResizeImages` is deprecated. It has no effect without `transformImage`; use `transformImage` for host-owned resizing.
 
 ### `write`
 
@@ -187,7 +221,7 @@ const remoteWrite = createWriteTool("/repo", {
 ## Extension and configuration notes
 
 - **Pluggable operation backends.** Every tool accepts an `operations` seam so a host can delegate to a remote system (e.g. SSH) while keeping the tool's matching/serialization behavior: `BashOperations` (`shell`), `ReadOperations` (`read`), `WriteOperations` (`write`), `EditOperations` (`edit`).
-- **Per-tool options.** `ShellToolOptions` (`shellPath`, `commandPrefix`, `maxLines`, `maxBytes`, `tempFilePrefix`, `operations`, `spawnHook`); `ReadToolOptions` (`operations`, `autoResizeImages`, `maxLines`, `maxBytes`); `WriteToolOptions` (`operations`); `EditToolOptions` (`operations`).
+- **Per-tool options.** `ShellToolOptions` (`shellPath`, `commandPrefix`, `maxLines`, `maxBytes`, `tempFilePrefix`, `operations`, `spawnHook`, `executionPolicy`); `ReadToolOptions` (`operations`, `maxImageBytes`, `transformImage`, `maxLines`, `maxBytes`, `executionPolicy`; `autoResizeImages` deprecated); `WriteToolOptions` (`operations`, `executionPolicy`); `EditToolOptions` (`operations`, `executionPolicy`).
 - **Aggregator options.** `ToolsOptions` (`{ shell?, read?, write?, edit? }`) threads each sub-object to the matching tool.
 - **`ToolsOptions`** and the per-tool option types are exported from the package barrel for host configuration.
 - No auto-discovery or manifest registration: import and register explicitly. This package registers no extensions and owns no globals (the mutation queue is a process-wide per-path map — see `ponytail:` note in the source).
@@ -198,7 +232,7 @@ const remoteWrite = createWriteTool("/repo", {
 - **Non-zero exit is not an error.** A failing command is a normal `shell` result (exit code in metadata); only timeout/abort/spawn failures are error results. Do not assume `error == undefined` means the command succeeded.
 - **Bounded output.** `shell`/`read` accumulate output into a rolling tail bounded by `maxLines`/`maxBytes`; oversized output spills to a temp file (`fullOutputPath`), so memory use is bounded regardless of command output size.
 - **Per-path serialization.** Concurrent mutations to the same file serialize; concurrent mutations to different files do not block each other. The queue is a process-wide map — across sessions in one process, same-path writes still serialize (upgrade path: scope per registry if throughput matters).
-- **Single runtime dependency.** `diff` (for `edit` unified patch/diff generation) plus the Node standard library. No native modules; no image-processing native dependency (image auto-resize is deferred, so no `sharp`/WASM dependency).
+- **Bounded image reads.** `read` rejects images over `maxImageBytes` (default 10 MB) by `stat` before read when possible; MIME is detected from magic bytes only. Optional `transformImage` is host-owned — the base package has no image-processing dependency.
 
 ## Related APIs