@arnilo/prism 0.0.1 → 0.0.3

package/docs/agent-events.md

@@ -0,0 +1,199 @@
+# Agent events
+
+## What it does
+
+`AgentEvent` is the single observable stream every `AgentSession` run emits. Subscribers receive normalized, redacted, in-order events covering agent lifecycle, assistant message streaming, tool execution, queue updates, subscriber overflow, compaction, retry, artifact validation/refinement, and terminal errors. The stream is in-memory, live-only, and bounded per subscriber by `SubscribeOptions`; there is no durable queue, no background work, and no extra dependency.
+
+Events are emitted by the runtime and by loops through `LoopContext.emit`, both of which route through `redactAgentEvent(event, activeRedactor)` so every payload is secret-redacted before subscribers observe it.
+
+## 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.
+
+Do not use `AgentEvent` for durable replay (use a `SessionStore`) or for cross-session coordination (the broadcaster is per-session and live-only).
+
+## Durable event ledger
+
+When `AgentConfig.runLedger` or `RunOptions.runLedger` is configured, every emitted `AgentEvent` is also persisted as an `AgentEventRecord` through the host adapter. The runtime calls `redactAgentEvent(event, activeRedactor)` before creating the record, sets `AgentEventRecord.redacted` to `true` when a redactor is active, and writes the record with the same `sessionId`, `runId`, and `timestamp`.
+
+Event records preserve emission order within a run because the runtime drains pending event appends before writing the final `RunRecord`. Subscribers still see the live, in-memory stream; the ledger is the durable copy.
+
+## Inputs / request
+
+```ts
+import type { AgentEvent } from "@arnilo/prism";
+
+const subscription = session.subscribe({ maxQueuedEvents: 256, overflow: "close" });
+for await (const event of subscription) {
+  switch (event.type) {
+    case "message_delta": // append event.content
+    case "tool_execution_started": // …
+    case "artifact_failed": // budget exhausted
+      break;
+  }
+}
+```
+
+The `AgentEvent` union (grouped by concern):
+
+| Group | Variants |
+| --- | --- |
+| Agent lifecycle | `agent_started`, `agent_finished` |
+| Turns | `turn_started`, `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` |
+| Compaction | `compaction_started`, `compaction_finished` |
+| Retry | `retry_scheduled` |
+| Artifacts | `artifact_validation_started`, `artifact_validation_finished`, `artifact_revision_started`, `artifact_finished`, `artifact_failed` |
+| Errors | `error` |
+
+## Outputs / response / events
+
+`AgentEvent` is a discriminated union on `type`. Common fields are `sessionId` and `runId` (both required on streaming/turn/artifact/tool events; `sessionId` is absent on pre-session `error`, `runId` is optional on compaction events).
+
+Agent / turn / message events:
+
+| Variant | Fields |
+| --- | --- |
+| `agent_started` | `sessionId`, `runId` |
+| `agent_finished` | `sessionId`, `runId`, `usage?: Usage` |
+| `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) |
+
+`message_delta.content.type === "tool_call_delta"` carries `{ index, id?, name?, argumentsText? }`. Treat it as a streaming fragment. The runtime reconstructs and persists a final `tool_call` before executing tools.
+
+Tool execution events:
+
+| Variant | Fields |
+| --- | --- |
+| `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` |
+
+Queue / subscriber / compaction / retry events:
+
+| Variant | Fields |
+| --- | --- |
+| `queue_updated` | `sessionId`, `runId`, `size: number` |
+| `event_subscriber_overflow` | `sessionId`, `droppedEvents: number`, `maxQueuedEvents: number`, `overflow: "close" \| "drop_oldest" \| "drop_newest"` |
+| `compaction_started` | `sessionId`, `runId?` |
+| `compaction_finished` | `sessionId`, `runId?`, `summary: string` |
+| `retry_scheduled` | `sessionId`, `runId`, `attempt: number`, `delayMs: number`, `error: ErrorInfo` |
+
+Artifact validation/refinement events (emitted only by `generateValidateReviseLoop`; `singleShotLoop` emits zero artifact events):
+
+| Variant | Fields |
+| --- | --- |
+| `artifact_validation_started` | `sessionId`, `runId`, `turn: number`, `attempt: number` |
+| `artifact_validation_finished` | `sessionId`, `runId`, `turn`, `attempt`, `result: ArtifactValidation` |
+| `artifact_revision_started` | `sessionId`, `runId`, `turn`, `attempt`, `failure: ArtifactValidation` |
+| `artifact_finished` | `sessionId`, `runId`, `turn`, `attempt`, `result: ArtifactValidation` (loop ended successfully) |
+| `artifact_failed` | `sessionId`, `runId`, `turn`, `attempt`, `result: ArtifactValidation` (budget exhausted) |
+
+### Artifact event ordering
+
+A `generateValidateReviseLoop` run emits normal turn/message events for every provider turn, then a strictly ordered artifact sequence, correlated by `runId` / `turn` / `attempt`:
+
+```
+turn_started
+  → message_started
+    → message_delta*
+      → message_finished
+        → turn_finished
+          → artifact_validation_started
+            → artifact_validation_finished
+              → artifact_revision_started   # when a revision will run next
+               | artifact_finished          # loop ended successfully
+               | artifact_failed            # budget exhausted (maxRevisions+1 attempts)
+```
+
+- `attempt` is 1-indexed per validation attempt and equals the provider `turn` within `generateValidateReviseLoop`; it mirrors `retry_scheduled.attempt` and the `tool_execution_*` block/finish pairing.
+- Single-shot runs emit zero artifact events.
+- **Validation failure triggering a revision is recoverable and never an `error`.** Only terminal budget exhaustion emits `artifact_failed`. The `error` channel is reserved for real failures (provider failures not caught by retry, aborts, etc.), matching the existing convention used by `tool_execution_blocked`.
+
+## Request/response example
+
+```json
+{
+  "type": "event_subscriber_overflow",
+  "sessionId": "sess_01J...",
+  "droppedEvents": 257,
+  "maxQueuedEvents": 256,
+  "overflow": "close"
+}
+```
+
+```json
+{
+  "type": "artifact_revision_started",
+  "sessionId": "sess_01J...",
+  "runId": "run_01J...",
+  "turn": 1,
+  "attempt": 1,
+  "failure": {
+    "ok": false,
+    "errors": [{ "path": "title", "message": "missing field" }]
+  }
+}
+```
+
+```json
+{
+  "type": "artifact_failed",
+  "sessionId": "sess_01J...",
+  "runId": "run_01J...",
+  "turn": 4,
+  "attempt": 4,
+  "result": { "ok": false, "errors": [{ "message": "still invalid" }] }
+}
+```
+
+## Implementation example
+
+```ts
+import { createAgent, createMockProvider, providerTextDelta, providerDone, type AgentEvent, type ArtifactValidator } from "@arnilo/prism";
+
+const validator: ArtifactValidator<unknown> = (v) =>
+  typeof v === "string" && v.length > 0 ? { ok: true } : { ok: false, errors: [{ message: "empty" }] };
+
+const session = createAgent({
+  model: { provider: "mock", model: "demo" },
+  provider: createMockProvider([providerTextDelta("ok"), providerDone()]),
+}).createSession();
+
+for await (const event of session.subscribe()) {
+  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
+
+- All events flow through `redactAgentEvent(event, activeRedactor)` before subscribers observe them. Configure `AgentConfig.redactor` / `RunOptions.redactor` via `createSecretRedactor([...knownSecretStrings])` so secret values are redacted in `message` content, `errors[].message`, `metadata`, and artifact `result`/`failure` payloads.
+- The artifact variants are emitted only by `generateValidateReviseLoop`. `singleShotLoop` (the default when no `AgentConfig.loop` / `RunOptions.loop` is set) emits zero artifact events. See [Agent loops](agent-loops.md).
+- Subscribers are in-process; the broadcaster is in-memory and live-only. Multiple `subscribe()` calls receive the same stream.
+- `session.subscribe(options)` accepts `maxQueuedEvents` (default `1024`, minimum `1`) and `overflow` (default `"close"`). The `close` policy clears queued payload events, queues one `event_subscriber_overflow` notice for that subscriber, then closes it. `drop_oldest` keeps the newest queued events; `drop_newest` ignores new events while full.
+- The union is additive: new variants are appended without renumbering; subscribers should handle unknown `event.type` gracefully.
+
+## Security and performance notes
+
+- The broadcaster is in-memory and live-only. No dependency, no timer, no filesystem/network discovery, no worker, no durable queue.
+- Slow consumers are bounded by `SubscribeOptions`. Use `RunLedger` or host storage for durable replay; do not rely on a live subscriber as a queue.
+- Redaction is exact-string-match only and opt-in via `createSecretRedactor`; values not passed as known secrets are not redacted.
+- `ArtifactValidation.errors[].message` and `metadata` may echo model text; `redactAgentEvent` walks arbitrary nesting and replaces cyclic references with `"[Circular]"` (WeakSet cycle guard), so secret values in `result`/`failure` are redacted without crashing.
+- `artifact_*` events are bounded by `maxRevisions + 1` validation attempts; an always-failing validator cannot loop forever and emits exactly one terminal `artifact_failed`.
+- 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 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.
+- [Tools](tools.md): `tool_execution_*` variants.
+- [Compaction and retry policies](compaction-and-retry.md): `compaction_*` and `retry_scheduled` variants.

package/docs/agent-loops.md

@@ -0,0 +1,217 @@
+# Agent loops
+
+## What it does
+
+Agent loops make the agent's per-run turn-control flow a replaceable strategy without forking the runtime. The runtime owns provider calls, retry, abort, store appends, redaction, and event emission; a loop only orchestrates those shared primitives through a `LoopContext`. The default `singleShotLoop` is the former inline turn loop extracted verbatim — assemble → generate → append assistant message → optional tool dispatch → next turn. `generateValidateReviseLoop` is the first alternative loop: generate → parse → validate → revise up to a budget.
+
+Loops are opt-in. When no `loop` is configured, the runtime runs `singleShotLoop` and behavior is bit-for-bit with the pre-loop runtime.
+
+- `singleShotLoop` — default; one-or-more provider turns with bounded tool rounds.
+- `generateValidateReviseLoop(opts)` — factory returning a generate→validate→revise loop parameterized by host callbacks (`validator`, optional `parser`/`repairer`, `maxRevisions`).
+- `resolveLoop(options, config)` — resolves `RunOptions.loop` (wins) over `AgentConfig.loop`, mapping `AgentLoopOptions` to a built-in strategy and passing through a custom `AgentLoopStrategy` instance.
+
+The `Artifact*` contracts (`ArtifactValidation`, `ArtifactContext`, `ArtifactParseResult<T>`, `ArtifactParser<T>`, `ArtifactValidator<T>`, `ArtifactRepairer<T>`) are generic over a host-defined type `T`. Prism threads `T` through parser→validator→repairer; it never instantiates `T`. No domain control-flow vocabulary (`workflow`/`node`/`step`) appears in these contracts — the seam stays generic.
+
+## When to use it
+
+Use the default `singleShotLoop` implicitly whenever you call `session.run()` — no configuration needed. Opt into `generateValidateReviseLoop` when a run should produce an artifact that must satisfy a host-supplied schema before it is considered complete (e.g. structured output, a validated JSON document, a generated file passing lint) and the host wants Prism to drive the revision turns.
+
+Do not use a loop to re-implement provider calls, retry, abort, store, or event emission — those stay runtime-owned and are exposed to the loop only through `LoopContext`. A loop that needs tools in revision turns is out of scope for `generateValidateReviseLoop`; use `singleShotLoop` or supply a custom `AgentLoopStrategy`.
+
+## Inputs / request
+
+```ts
+import {
+  createAgent,
+  generateValidateReviseLoop,
+  singleShotLoop,
+  resolveLoop,
+  type AgentLoopStrategy,
+  type AgentLoopOptions,
+  type LoopContext,
+  type ArtifactValidator,
+  type ArtifactParser,
+  type ArtifactRepairer,
+  type ArtifactValidation,
+  type ArtifactContext,
+  type ArtifactParseResult,
+} from "@arnilo/prism";
+```
+
+Per-run and per-agent loop selection (RunOptions wins):
+
+```ts
+// AgentConfig.loop pins a loop for the agent/session.
+const agent = createAgent({
+  model,
+  provider,
+  // optional default loop for this agent:
+  loop: { strategy: "single-shot" },
+});
+
+// RunOptions.loop overrides per request.
+await session.run(input, {
+  loop: {
+    strategy: "generate-validate-revise",
+    validator: hostValidator,
+    parser: hostParser,       // optional; default treats assistant text as the value
+    repairer: hostRepairer,  // optional; default stringifies validation.errors[].message
+    maxRevisions: 3,         // optional; default 3
+  },
+});
+
+// Custom loop escape hatch (a host-provided AgentLoopStrategy instance):
+await session.run(input, { loop: myCustomLoop });
+```
+
+`AgentLoopOptions` is the discriminated union:
+
+```ts
+type AgentLoopOptions =
+  | { readonly strategy: "single-shot" }
+  | {
+      readonly strategy: "generate-validate-revise";
+      readonly validator: ArtifactValidator<unknown>;
+      readonly parser?: ArtifactParser<unknown>;
+      readonly repairer?: ArtifactRepairer<unknown>;
+      readonly maxRevisions?: number;
+    };
+```
+
+Host callback contracts (all generic over host `T`):
+
+| Contract | Shape |
+| --- | --- |
+| `ArtifactParser<T>` | `(text: string, ctx: ArtifactContext) => ArtifactParseResult<T> \| Promise<...>` — parse assistant text to a typed value. |
+| `ArtifactValidator<T>` | `(value: T, ctx: ArtifactContext) => ArtifactValidation \| Promise<...>` — return `{ ok: true }` or `{ ok: false, errors }`. |
+| `ArtifactRepairer<T>` | `(value: T \| undefined, failure: ArtifactValidation, ctx: ArtifactContext) => AgentInput \| Promise<...>` — build the revision follow-up input. |
+| `ArtifactValidation` | `{ ok: boolean; errors?: readonly { path?: string; message: string }[]; metadata?: ... }`. |
+| `ArtifactContext` | `{ sessionId, runId, turn, signal, metadata }` — passed to every callback. |
+| `ArtifactParseResult<T>` | `{ ok: boolean; value?: T; error?: string }`. |
+
+`LoopContext` (what the runtime builds for the loop each run):
+
+| Field | Purpose |
+| --- | --- |
+| `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). |
+| `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. |
+| `appendMessage(message)` | Appends to the store under the run (redacted). |
+| `emit(event)` | Emits a redacted `AgentEvent`. |
+
+## 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.
+
+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.
+
+Validation-failure-triggering-a-revision is **not** an `error` event — it is recoverable, like `tool_execution_blocked`. `generateValidateReviseLoop` emits normal turn/message events around each provider turn, then the artifact event sequence `artifact_validation_started` → `artifact_validation_finished` → (`artifact_revision_started`)* → `artifact_finished` (success) | `artifact_failed` (budget exhausted), correlated by `runId`/`turn`/`attempt`; see [Agent events § Artifact event ordering](agent-events.md#artifact-event-ordering). `singleShotLoop` emits zero artifact events. Real failures stay on the `error` channel.
+
+A loop has no path to credentials, provider objects, or unredacted secrets. `LoopContext.generate` receives the already-policy-applied, middleware-run, redacted request; `LoopContext.emit` runs through `redactAgentEvent` with the active `SecretRedactor`.
+
+## Request/response example
+
+```ts
+// Default single-shot run (no loop configured).
+await session.run("Summarize the schema.");
+```
+
+```ts
+// Generate-validate-revise with a host schema validator.
+import { createAgent, type ArtifactValidator } from "@arnilo/prism";
+
+const validator: ArtifactValidator<unknown> = (value, _ctx) =>
+  typeof value === "string" && value.length > 0
+    ? { ok: true }
+    : { ok: false, errors: [{ message: "empty artifact" }] };
+
+await session.run("Write a one-line release note.", {
+  loop: { strategy: "generate-validate-revise", validator, maxRevisions: 3 },
+});
+```
+
+## Implementation example
+
+```ts
+import { createAgent, createMockProvider, providerTextDelta, providerDone, type ArtifactValidator, type ArtifactParser, type ArtifactRepairer } from "@arnilo/prism";
+
+// Host owns the schema shape T. Prism never instantiates it.
+interface JsonDoc { readonly title: string; readonly body: string }
+
+const parser: ArtifactParser<JsonDoc> = (text) => {
+  try {
+    const value = JSON.parse(text) as JsonDoc;
+    return { ok: true, value };
+  } catch (error) {
+    return { ok: false, error: error instanceof Error ? error.message : "parse failed" };
+  }
+};
+
+const validator: ArtifactValidator<JsonDoc> = (value) =>
+  value.title && value.body
+    ? { ok: true }
+    : { ok: false, errors: [{ path: value.title ? "body" : "title", message: "missing field" }] };
+
+const repairer: ArtifactRepairer<JsonDoc> = (_value, failure) => ({
+  role: "user",
+  content: [{ type: "text", text: `Fix these: ${failure.errors?.map((e) => e.message).join("; ")}` }],
+});
+
+const agent = createAgent({
+  model: { provider: "mock", model: "demo" },
+  provider: createMockProvider([
+    providerTextDelta(JSON.stringify({ title: "ok", body: "rev1" })),
+    providerDone(),
+  ]),
+});
+
+await agent.createSession().run("Produce the JSON doc.", {
+  loop: { strategy: "generate-validate-revise", validator, parser, repairer, maxRevisions: 3 },
+});
+```
+
+A custom loop is a plain object; pass it directly as `AgentLoopStrategy`:
+
+```ts
+import { type AgentLoopStrategy } from "@arnilo/prism";
+
+const twoShotLoop: AgentLoopStrategy = {
+  name: "two-shot",
+  async run(ctx) {
+    await ctx.generate(await ctx.assemble(ctx.input));
+    // ...orchestrate further turns via ctx primitives only...
+    return undefined;
+  },
+};
+await session.run(input, { loop: twoShotLoop });
+```
+
+## Extension and configuration notes
+
+- `RunOptions.loop` wins over `AgentConfig.loop`; when neither is set the runtime uses `singleShotLoop`. This mirrors the other `RunOptions` overrides (`redactor`, `validate`, `activeSkills`).
+- `{ 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.
+- 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
+
+- 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.
+- 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/`.
+
+## Related APIs
+- [Agent/session runtime](agent-session-runtime.md): `RuntimeAgentSession.run()` builds the `LoopContext` and delegates to the resolved loop.
+- [Agent events](agent-events.md): the `artifact_*` event variants and ordering emitted by `generateValidateReviseLoop`.
+- [Structured output](structured-output.md): the `ArtifactParser<T>`/`ArtifactValidator<T>`/`ArtifactRepairer<T>` seam (host-defined `T`, Prism never instantiates it) and a Synapta-style schema→`ArtifactValidation` mapping example.
+- [Public contracts](public-contracts.md): `AgentLoopStrategy`, `AgentLoopOptions`, `LoopContext`, `ProviderTurnResult`, and the `Artifact*` contracts.
+- [Input and prompt assembly](input-and-prompt-assembly.md): `assembleProviderInput()`, the primitive behind `LoopContext.assemble`.
+- [Tools](tools.md): `dispatchToolCall()`, the primitive behind `LoopContext.dispatchToolCall`.
+- [Compaction and retry policies](compaction-and-retry.md): `generateWithRetry()` and retry/compaction primitives the loop never re-implements.
+- [Context and skills](context-and-skills.md): per-run skill/tool resolution feeding `LoopContext.assemble`.

package/docs/agent-session-runtime.md

@@ -10,7 +10,7 @@ The agent/session runtime adds the minimal shared SDK surface for running provid
 - `session.run(input, options)`
 - `session.prompt(input, options)`
 - `session.compact(options?)`
-- `session.subscribe()`
+- `session.subscribe(options?)`
 - `session.abort()`
 - `session.entries()`
 - `session.checkout(leafId?)`
@@ -32,7 +32,7 @@ createAgent(config: AgentConfig): Agent
 createAgentSession(config: AgentSessionConfig & { agent: Agent }): AgentSession
 ```
 
-`AgentConfig.provider` must contain the host-selected provider. Prism does not resolve providers from hidden globals.
+`AgentConfig.provider` must contain the host-selected provider. Prism does not resolve providers from hidden globals. Alternatively, set `AgentConfig.providerSource: ProviderResolver` (or override per run with `RunOptions.providerSource`, which wins) to resolve the provider from `model.provider` each run; when `AgentConfig.provider` is set it takes first precedence and the resolver is bypassed. See [Provider layer § Provider resolver](provider-layer.md#provider-resolver).
 
 `session.run(input, options)` accepts the existing Prism input shape:
 
@@ -42,11 +42,11 @@ string | Message | readonly Message[]
 
 `AgentSessionConfig.store` overrides `AgentConfig.store`; otherwise the session gets a private memory store. `AgentSessionConfig.leafId` selects the branch leaf to resume from.
 
-`RunOptions.model` can override the request model for a run. Model overrides append a `model_change` entry. `AgentConfig.providerOptions`/`RunOptions.providerOptions` supply generic provider request options. `AgentConfig.providerRequestPolicies`/`RunOptions.providerRequestPolicies` run before `AIProvider.generate()` and before `provider_request` middleware. `AgentConfig.systemPrompt` and `RunOptions.systemPrompt` add explicit layered system prompt contributions; `RunOptions.systemPrompt: false` disables configured prompt layers for that run while keeping `AgentConfig.instructions` as the base path. `RunOptions.compaction` can enable auto-compaction for that run or use `false` to disable configured auto-compaction. `RunOptions.retry` can enable provider-turn retry for that run or use `false` to disable configured retry. `RunOptions.metadata` is merged with agent/session metadata for assembly, provider requests, and tool contexts. `RunOptions.maxToolRounds` bounds repeated tool turns and defaults to `1`. `RunOptions.signal` is bridged into the per-run abort signal passed to assembly, providers, tools, auto-compaction, and retry backoff.
+`RunOptions.model` can override the request model for a run. Model overrides append a `model_change` entry. `AgentConfig.inputLayout` selects the default input assembly layout (`"legacy"` by default, or opt-in `"cache_aware"`); `RunOptions.inputLayout` wins for one run. `AgentConfig.providerOptions`/`RunOptions.providerOptions` supply generic provider request options; `timeoutMs`, `maxRetries`, and `maxRetryDelayMs` are deprecated inert provider-level hints in first-party providers. Use `RunOptions.signal`/host abort controllers for timeouts and `AgentConfig.retry`/`RunOptions.retry` for retry. `AgentConfig.providerRequestPolicies`/`RunOptions.providerRequestPolicies` run before `AIProvider.generate()` and before `provider_request` middleware. `AgentConfig.systemPrompt` and `RunOptions.systemPrompt` add explicit layered system prompt contributions; `RunOptions.systemPrompt: false` disables configured prompt layers for that run while keeping `AgentConfig.instructions` as the base path. `RunOptions.compaction` can enable auto-compaction for that run or use `false` to disable configured auto-compaction. `RunOptions.retry` can enable provider-turn retry for that run or use `false` to disable configured retry. `RunOptions.metadata` is merged with agent/session metadata for assembly, provider requests, and tool contexts. `RunOptions.maxToolRounds` bounds repeated tool turns and defaults to `1`. `RunOptions.signal` is bridged into the per-run abort signal passed to assembly, providers, tools, auto-compaction, and retry backoff.
 
 ## Outputs / response / events
 
-`session.subscribe()` returns a live `AsyncIterable<AgentEvent>`. Subscribe before `run()` to observe that run's events.
+`session.subscribe(options?)` returns a live `AsyncIterable<AgentEvent>`. Subscribe before `run()` to observe that run's events. The consumer loop and `session.run()` must run concurrently (e.g. start the `for await` consumer, then `await Promise.all([consumer, session.run("Hi")])`): events are only emitted during a live run, so awaiting the subscribe loop before calling `run()` deadlocks. `SubscribeOptions.maxQueuedEvents` defaults to `1024` (minimum `1`) and caps events queued while the consumer is not awaiting `next()`. `SubscribeOptions.overflow` defaults to `"close"`; it clears queued payload events, delivers one `event_subscriber_overflow` notice to that subscriber, then closes it. `"drop_oldest"` keeps newest events; `"drop_newest"` ignores new events while full.
 
 For a text-only provider turn, the runtime emits:
 
@@ -58,7 +58,9 @@ For a text-only provider turn, the runtime emits:
 6. `turn_finished`
 7. `agent_finished`
 
-For complete tool calls, the runtime emits the assistant `tool_call` as `message_delta`, dispatches sequentially through `dispatchToolCall()`, emits tool execution events, appends a tool-result session entry, adds returned `ToolResult` values to the next provider turn, and stops when the provider returns no tool calls or `maxToolRounds` is reached. The next provider turn therefore receives the assistant `tool_call` followed by the matching role `tool` `tool_result` before any final assistant content.
+For tool calls, the runtime streams provider `tool_call_delta` fragments as `message_delta` events for UI consumers, reconstructs the final `tool_call` with the same rules as provider conformance helpers, dispatches each complete call sequentially through `dispatchToolCall()`, emits tool execution events, appends an assistant tool-call session entry and a tool-result session entry, adds returned `ToolResult` values to the next provider turn, and stops when the provider returns no tool calls or `maxToolRounds` is reached. Deltas are live events only; persisted transcripts contain final `tool_call` blocks. The next provider turn therefore receives the assistant `tool_call` followed by the matching role `tool` `tool_result` before any final assistant content.
+
+Provider `thinking`/`reasoning` content emitted during a turn is preserved as `thinking` content blocks on the assistant message in session history. On the next turn, provider packages decide how to carry prior reasoning forward. For example, the NeuralWatt provider serializes prior `thinking` blocks under a `reasoning_content` field for reasoning-capable models (gated on `capabilities.reasoning` / `compat.preserve_thinking`, droppable via `compat.clear_thinking`); see [NeuralWatt provider](providers/neuralwatt.md). Non-reasoning providers/models receive no reasoning field, so prior thinking does not leak into providers that do not support it.
 
 `session.compact(options?)` runs the selected compaction strategy, appends one `kind: "compaction"` entry under the current leaf, updates the leaf, emits `compaction_started` and `compaction_finished`, and returns the appended `CompactionResult`. If `AgentConfig.compaction` or `RunOptions.compaction` includes `thresholdEntries`, auto-compaction checks once after input/model-change entries are appended and before provider input assembly; `RunOptions.compaction: false` skips that run's auto-compaction.
 
@@ -113,7 +115,15 @@ await reader;
 
 ## Extension and configuration notes
 
-The runtime calls `assembleProviderInput()` on every turn and uses only values supplied on `AgentConfig`: `instructions`, `systemPrompt`, `inputBuilder`, `promptBuilder`, `context`, selected `skills`, active `tools`, `middleware`, `resourceLoader`, metadata, `compaction`, `retry`, and `RunOptions.model`/`systemPrompt`/`compaction`/`retry`. Contributions remain inert until a host passes selected values into the agent config.
+The runtime calls `assembleProviderInput()` on every turn and uses only runtime-consumed values supplied on `AgentConfig`: `instructions`, `systemPrompt`, `inputBuilder`, `promptBuilder`, `inputLayout`, `context`, selected `skills`, active `tools`, `middleware`, `resourceLoader`, metadata, `compaction`, `retry`, and `RunOptions.model`/`systemPrompt`/`inputLayout`/`compaction`/`retry`. Contributions remain inert until a host passes selected values into the agent config.
+
+`AgentConfig` fields that are host-owned metadata, not runtime work:
+
+| Field | Runtime behavior |
+| --- | --- |
+| `extensions` | Preserved on `agent.config` only. `createAgent()` / `session.run()` do not call `setup()`, load packages, or auto-register contributions. Load extensions with `createExtensionKernel()` before building config. |
+| `settings` | Preserved on `agent.config` only. The runtime does not call `settings.get()`; hosts or provider packages read settings before passing concrete runtime options. |
+| `credentials` | Preserved on `agent.config` only. The runtime does not call `credentials.resolve()`; provider adapters/request policies resolve credentials at the provider edge and pass exact secret values to redaction when needed. |
 
 The runtime calls `middleware.run("compaction", { context, result })` after a compaction strategy returns and before appending the standard compaction entry. Middleware can adjust the result summary/data, but the runtime still owns store append ordering and branch parent ids.
 
@@ -121,7 +131,7 @@ Provider request policy application is one ordered in-memory pass per provider t
 
 The runtime calls `middleware.run("retry", { context, decision })` after the retry policy decision and before emitting `retry_scheduled`. Middleware can stop retrying or adjust the delay. Retry wraps only the current provider turn, reuses the same assembled request, and never retries after assistant output has been emitted.
 
-`createAgent()` is a thin wrapper over explicit config. It does not load `AgentConfig.extensions`, scan packages, resolve credentials, read settings, or consult hidden registries. External `AgentDefinition` implementations can call it from their own `create()` method:
+`createAgent()` is a thin wrapper over explicit config. It does not load `AgentConfig.extensions`, scan packages, resolve credentials, read settings, call `Extension.setup()`, or consult hidden registries. External `AgentDefinition` implementations can call it from their own `create()` method:
 
 ```ts
 import { createAgent, createContributionRegistries } from "@arnilo/prism";
@@ -150,7 +160,7 @@ await agent.createSession().run("Hi", { model: overrideModel });
 - Compaction context contains branch entries and explicit compaction options only; it does not include provider objects, provider requests, credential resolvers, resolved credentials, settings, or hidden metadata.
 - Store entries contain explicit session data only; Prism does not store provider objects, credential resolvers, resolved credentials, full provider requests, settings, or hidden metadata.
 - Runtime events contain messages/content only; do not put secrets in prompts, metadata, provider events, session entries, or docs examples.
-- The event broadcaster is in-memory and live-only. It adds no dependency, timer, filesystem/network discovery, worker, or durable queue.
+- The event broadcaster is in-memory, live-only, and bounded per subscriber by `SubscribeOptions`. It adds no dependency, timer, filesystem/network discovery, worker, or durable queue.
 
 ## Related APIs
 
@@ -164,4 +174,6 @@ await agent.createSession().run("Hi", { model: overrideModel });
 - [Middleware hooks](middleware-hooks.md): hooks that configured assembly/runtime can run.
 - [CLI/RPC](cli-rpc.md): terminal and JSONL adapters over this runtime.
 
+`AgentConfig.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.
+
 `AgentConfig.redactor` and `RunOptions.redactor` redact exact known secret strings from provider requests, emitted events, and stored session entries. Redaction is opt-in and exact-match only.

package/docs/cli-rpc.md

@@ -35,6 +35,16 @@ CLI flags:
 | `--context <text>` | Context text reserved for host adapters. |
 | `--compact <entries>` | Auto-compaction threshold for the run. |
 | `--max-tool-rounds <n>` | Maximum runtime tool rounds. |
+| `--discover` | Opt-in workspace contribution discovery (`SKILL.md`/`manifest.json`). Never auto-activates or imports. |
+| `--discover-kinds <csv>` | Kinds to scan; defaults to `skill`. Accepts `skill,tool,context,instructions`. |
+| `--no-discovery` | Hard-disable discovery even if `--discover` is set. |
+| `--agents-config <path>` | App config root holding `agents/<name>/AGENT.md` bundles (opt-in). Envelopes only; the host resolves them via `resolveAgentBundle`. The CLI never defaults to the user's home directory. |
+| `--instruction <name>` | Select a registered/discovered instruction injector (repeatable). `--instruction false` disables injectors for the run. Names resolve fail-closed. |
+| `--injector-file <path>` | Load a markdown file as a static `every_turn` injector (repeatable). |
+| `--no-agents-md` | Skip auto-loading `<workspaceRoot>/AGENTS.md` (Phase 31). |
+| `--no-system-md` | Skip auto-loading the global `SYSTEM.md` layer (Phase 31). The CLI does not default to the user's home directory; pass `globalRoot` from a host adapter or use `--system-md-file` to opt in. |
+| `--agents-md-file <path>` | Read AGENTS.md from `<path>` instead — still `source: "app"`, still trust-gated (Phase 31). |
+| `--system-md-file <path>` | Read SYSTEM.md from `<path>` instead — user-owned, `source: "user"` (Phase 31). |
 | `--help` | Print usage. |
 
 RPC request envelope:
@@ -43,7 +53,9 @@ RPC request envelope:
 { id: string | number; command: string; params?: Record<string, unknown> }
 ```
 
-Supported command names: `prompt`, `steer`, `followUp`, `abort`, `state`, `messages`, `setModel`, `compact`, `switchSession`, `forkSession`, `cloneSession`, and `command`.
+Supported command names: `prompt`, `steer`, `followUp`, `abort`, `state`, `messages`, `setModel`, `compact`, `switchSession`, `forkSession`, `cloneSession`, `checkout`, and `command`.
+
+The `prompt` and `followUp` params accept an optional `instructionInjectors?: readonly string[]` field (Phase 30). Names resolve against the `instructionInjectors` registry passed to `runRpcServer({ instructionInjectors })`; an unknown name fails closed (error response correlated to the request `id`, no provider call).
 
 ## Outputs / response / events
 
@@ -63,6 +75,19 @@ RPC writes responses and async events:
 { type: "event"; id: string | number; sessionId?: string; runId?: string; event: AgentEvent }
 ```
 
+Branch-aware session commands return live handle details:
+
+```ts
+{
+  sessionId: string;
+  leafId?: string;
+  handleId: string;
+  handles?: readonly { handleId: string; sessionId: string; leafId?: string }[]; // state only
+}
+```
+
+`sessionId` identifies the durable session. `leafId` is the selected branch tip. `handleId` is the RPC map key used by `switchSession`; forks that share the same `sessionId` get stable ids like `session-1#2` so the parent handle is not overwritten.
+
 Invalid CLI flags return exit code `2`. Invalid JSON, missing ids, unknown RPC commands, unsupported `steer`, unknown command contributions, and runtime failures return `ok: false` response envelopes without executing unknown tools or commands.
 
 ## Request/response example
@@ -71,6 +96,10 @@ Invalid CLI flags return exit code `2`. Invalid JSON, missing ids, unknown RPC c
 {"id":"1","command":"prompt","params":{"input":"Hi"}}
 {"type":"event","id":"1","sessionId":"s1","runId":"run_1","event":{"type":"message_delta"}}
 {"id":"1","ok":true,"result":{"sessionId":"s1"}}
+{"id":"2","command":"forkSession","params":{"leafId":"entry_1"}}
+{"id":"2","ok":true,"result":{"sessionId":"s1","leafId":"entry_1","handleId":"s1#2"}}
+{"id":"3","command":"checkout","params":{"leafId":"entry_5"}}
+{"id":"3","ok":true,"result":{"sessionId":"s1","leafId":"entry_5","handleId":"s1#2"}}
 ```
 
 ## Active run behavior
@@ -78,7 +107,7 @@ Invalid CLI flags return exit code `2`. Invalid JSON, missing ids, unknown RPC c
 `prompt` and `followUp` start an asynchronous run and write their final response only when the run finishes. While a run is active, the RPC loop continues to read and respond to other requests:
 
 - `abort` cancels the active run for the current session and responds immediately.
-- `state`, `messages`, `setModel`, `switchSession`, `forkSession`, `cloneSession`, and registered `command` requests are processed immediately.
+- `state`, `messages`, `setModel`, `switchSession`, `forkSession`, `cloneSession`, `checkout`, and registered `command` requests are processed immediately.
 - `compact` is fail-closed: if the current session has an active run, it returns `ok: false` because the session rejects compaction during a run.
 - A second `prompt` or `followUp` for the same session while it already has an active run returns `ok: false` immediately instead of blocking the input loop.
 
@@ -116,7 +145,9 @@ await agent.createSession({ id: "s1" }).run("Hi");
 
 CLI/RPC are adapters over `AgentSession`. They do not scan packages, import extensions, read config files, fetch resources, resolve credentials, or register tools unless a host adapter explicitly wires those primitives in.
 
-RPC `command` executes only explicitly registered `CommandDefinition` values. `setModel` stores a model override for later prompt/follow-up calls. `compact`, `switchSession`, `forkSession`, and `cloneSession` call the existing session APIs.
+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.
+
+`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
 
@@ -125,6 +156,7 @@ RPC `command` executes only explicitly registered `CommandDefinition` values. `s
 - No full TUI or sandbox is provided or implied.
 - JSONL is processed line by line with Node stdlib; no parser dependency, worker, watcher, or queue is added.
 - Unknown or malformed CLI/RPC input fails closed.
+- Branch handles (`handleId`, `sessionId`, `leafId`) are identifiers only; do not encode credentials, tokens, provider objects, or secrets into them.
 - Do not put resolved credential values, tokens, headers, or secrets in prompts, CLI flags, config, events, or docs examples.
 
 ## Related APIs
@@ -132,9 +164,12 @@ RPC `command` executes only explicitly registered `CommandDefinition` values. `s
 - [Agent/session runtime](agent-session-runtime.md): runtime API used by CLI/RPC.
 - [Contribution registries](contribution-registries.md): command contributions are inert until explicitly wired.
 - [Configuration and manifests](configuration-and-manifests.md): config data stays separate from CLI/RPC execution.
+- [Contribution discovery (workspace)](contribution-discovery.md): the `--discover` / `--discover-kinds` / `--no-discovery` flags fill host registries; no `import()`, no auto-activate.
 - [Node filesystem config loader](node-filesystem-config.md): optional explicit config file loading for Node hosts.
 - [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.
 
-The CLI records flags but does not auto-load project-local resources, extensions, tools, or config. Hosts must make explicit trust and permission decisions before wiring any future local loading.
+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.
+
+For app-controlled agent bundles under `<configRoot>/agents/<name>/AGENT.md` (including the three-layer `SYSTEM.md` → `AGENT.md` body → repo `AGENTS.md` prompt append and the union skill/tool scopes), see [Agent definitions](agent-definitions.md).