@arnilo/prism 0.0.3 → 0.0.5

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

@@ -0,0 +1,178 @@
+// 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,
+        scope: "provider_turn",
+        turn: 1,
+        attempt: 2,
+        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();
+        const storedUsage = usageRows.find((row) => row.id === "usage-1");
+        if (!storedUsage)
+            throw new Error("RunLedger must persist UsageRecord rows");
+        if (storedUsage.scope !== "provider_turn" || storedUsage.turn !== 1 || storedUsage.attempt !== 2) {
+            throw new Error("RunLedger must preserve UsageRecord scope, turn, and attempt");
+        }
+    }
+    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/a2a.md

@@ -0,0 +1,73 @@
+# A2A interoperability
+
+## What it does
+
+`@arnilo/prism-supervisor` implements a bounded text-only subset of Agent2Agent (A2A) protocol 1.0: Agent Cards, JSON-RPC `SendMessage`, `SendStreamingMessage`, `GetExtendedAgentCard`, SSE task updates, ES256 JWS card signatures, and an explicit remote client.
+
+## When to use it
+
+Use it to expose one explicitly selected Prism agent at an A2A endpoint or call a known remote A2A agent. Do not use it as endpoint discovery, a generic proxy, credential forwarding, or a replacement for local workflows.
+
+## Inputs / request
+
+| API/field | Meaning |
+| --- | --- |
+| `createA2AAgentCard(card)` | Validates/freeze a JSONRPC protocol-1.0 HTTPS text card. |
+| `signA2AAgentCard(card, { privateKey, keyId, expiresAt })` | Adds detached-payload ES256 JWS signature using WebCrypto. |
+| `verifyA2AAgentCard(card, { publicKey, keyId?, now?, maxAgeMs? })` | Pins ES256/key/expiry and verifies canonical unsigned card. |
+| `createA2AHandler({ card, exposure, authorize })` | Web-standard card/JSON-RPC/SSE `Request` to `Response` handler. |
+| `createA2AClient({ endpoint, allowedOrigins })` | Explicit HTTPS remote client with optional card verifier/auth callback. |
+| `A2ALimits` | Request 64 KiB, response 1 MiB, event 64 KiB, stream 10 MiB/10k events, concurrency 16, timeout 120s, card 64 KiB defaults; finite hard caps apply. |
+
+## Outputs / response / events
+
+The handler serves `GET /.well-known/agent-card.json` and its configured POST endpoint. JSON-RPC returns `{ result: { task } }` or a bounded error. Streaming returns backpressure-driven SSE task envelopes. Client `send()` maps a terminal remote task to `AgentRunResult`; `stream()` yields validated/redacted text artifacts.
+
+## Request/response example
+
+```json
+{"jsonrpc":"2.0","id":1,"method":"SendMessage","params":{"message":{"role":"user","messageId":"m1","parts":[{"text":"Check sources"}]}}}
+```
+
+## Implementation example
+
+```ts
+import { createA2AClient, createA2AHandler, verifyA2AAgentCard } from "@arnilo/prism-supervisor";
+
+const handler = createA2AHandler({
+  card,
+  exposure: { sessionFactory: ({ ownership }) => agent.createSession({ metadata: ownership }) },
+  authorize: ({ request }) => authenticate(request),
+});
+
+const client = createA2AClient({
+  endpoint: "https://agent.example/a2a/v1",
+  allowedOrigins: ["https://agent.example"],
+  authorize: () => ({ authorization: `Bearer ${resolveOwnedToken()}` }),
+  verifyCard: (remoteCard) => verifyA2AAgentCard(remoteCard, { publicKey, keyId: "agent-key" }),
+});
+
+const result = await client.send("Check sources");
+```
+
+## Extension and configuration notes
+
+The package owns no listener or credential store. Mount the handler in a host server and resolve authentication/authorization on every request. Client auth executes only after body/card validation and serialization. Injectable `fetch` supports host transports/tests; redirects are disabled.
+
+Only `text` parts are accepted. File/data parts, push notifications, task persistence/query/cancel, gRPC, HTTP+JSON binding, automatic JWK fetching, and endpoint discovery are intentionally absent.
+
+## Security and performance notes
+
+- Endpoints and card URLs must be HTTPS and exactly origin-allow-listed before fetch; `redirect: "error"` prevents redirect SSRF.
+- Treat every remote card, error, task, status, artifact, and SSE frame as untrusted. Shape/count/byte/time limits apply before mapping.
+- Card verification pins `alg=ES256`, optional key ID, issue/expiry, optional maximum age, and canonical unsigned-card payload. Hosts provision trusted public keys; remote `jku` is never fetched automatically.
+- Card discovery is public; extended-card and invoke methods call host authorization. Use TLS, rate limits, and replay controls at the host edge.
+- Credentials remain in the client auth callback or server authorizer and never enter cards, messages, events, or metrics.
+- Offline conformance is authoritative. Live endpoints are optional operator smoke tests.
+
+## Related APIs
+
+- [Supervisor delegation](supervisors.md): local child boundary.
+- [Web-standard server](server.md): non-A2A Prism routes.
+- [Host security](host-security.md): authentication, SSRF, and untrusted-output policy.
+- [Agent/session runtime](agent-session-runtime.md): mapped local execution/result.

package/docs/agent-events.md

@@ -8,7 +8,7 @@ Events are emitted by the runtime and by loops through `LoopContext.emit`, both
 
 ## When to use it
 
-Subscribe via `session.subscribe()` whenever a host needs to observe run progress: render streamed assistant text in a UI, react to tool execution, drive observability/telemetry, or audit artifact validation outcomes. Do not parse provider stream events directly for these — `AgentEvent` is the stable, normalized surface across providers and loops.
+Subscribe via `session.stream()` for a single owned run, or `session.subscribe()` when a host needs a long-lived observer across runs: render streamed assistant text in a UI, react to tool execution, drive observability/telemetry, or audit artifact validation outcomes. Do not parse provider stream events directly for these — `AgentEvent` is the stable, normalized surface across providers and loops.
 
 Do not use `AgentEvent` for durable replay (use a `SessionStore`) or for cross-session coordination (the broadcaster is per-session and live-only).
 
@@ -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` |
@@ -57,7 +58,7 @@ Agent / turn / message events:
 | Variant | Fields |
 | --- | --- |
 | `agent_started` | `sessionId`, `runId` |
-| `agent_finished` | `sessionId`, `runId`, `usage?: Usage` |
+| `agent_finished` | `sessionId`, `runId`, `usage?: Usage` (aggregate of all usage-bearing provider turns) |
 | `turn_started` / `turn_finished` | `sessionId`, `runId`, `turn: number` |
 | `message_started` / `message_finished` | `sessionId`, `runId`, `message: Message` |
 | `message_delta` | `sessionId`, `runId`, `content: ContentBlock` (`tool_call_delta` fragments may appear here for live UI streaming; stored messages use final `tool_call` blocks) |
@@ -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 |
@@ -165,12 +173,10 @@ const session = createAgent({
   provider: createMockProvider([providerTextDelta("ok"), providerDone()]),
 }).createSession();
 
-for await (const event of session.subscribe()) {
+for await (const event of session.stream("draft", { loop: { strategy: "generate-validate-revise", validator, maxRevisions: 3 } })) {
   if (event.type === "artifact_finished") console.log("artifact ok", event.attempt);
   if (event.type === "artifact_failed") console.log("artifact exhausted", event.attempt, event.result.errors);
 }
-
-await session.run("draft", { loop: { strategy: "generate-validate-revise", validator, maxRevisions: 3 } });
 ```
 
 ## Extension and configuration notes
@@ -191,9 +197,10 @@ await session.run("draft", { loop: { strategy: "generate-validate-revise", valid
 - Runtime events contain messages/content only; do not put secrets in prompts, metadata, provider events, session entries, tool results, or artifact validation payloads.
 
 ## Related APIs
-- [Agent/session runtime](agent-session-runtime.md): `session.subscribe()` and the live event broadcaster.
+- [Agent/session runtime](agent-session-runtime.md): `session.stream()`, `session.subscribe()`, and the live event broadcaster.
 - [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. |
@@ -104,7 +108,7 @@ Host callback contracts (all generic over host `T`):
 
 ## Outputs / response / events
 
-`AgentLoopStrategy.run(ctx)` returns `Promise<Usage | undefined>` — the last provider usage, handed back to the runtime which emits `agent_finished` with it.
+`AgentLoopStrategy.run(ctx)` returns `Promise<Usage | undefined>` as a fallback for custom loops. Core runtime independently accumulates every usage-bearing provider turn in O(turns), persists scoped turn/run rows, and emits `agent_finished` with the aggregate.
 
 Events during a loop run are the existing `AgentEvent`s (`turn_started`, `message_started`, `message_delta`, `message_finished`, `turn_finished`, tool-execution events when the loop dispatches tools, `error` on real failures). Both built-in loops emit `turn_started` before each provider turn, `message_finished` for every assistant draft, and `turn_finished` after the assistant draft is appended. First-turn input is appended to live history once, matching the already-persisted user message.
 
@@ -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/`.