agent-accelerator 0.1.0 → 0.3.0

package/README.md

@@ -1,13 +1,14 @@
 # Agent Accelerator
 
+[![npm version](https://img.shields.io/npm/v/agent-accelerator.svg?color=cb3837&logo=npm)](https://www.npmjs.com/package/agent-accelerator)
 [![GitHub](https://img.shields.io/badge/GitHub-sashvat--bharat%2Fagent--accelerator-blue?logo=github)](https://github.com/sashvat-bharat/agent-accelerator)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-A thin, typed transport SDK for calling LLMs through a single `Agent` interface.
+> **Stability notice:** Agent Accelerator is pre-1.0 and under active development. Public APIs, provider transports, and configuration options may still change in breaking ways between releases. For production use, please pin your dependency to an exact version.
 
-GitHub: [https://github.com/sashvat-bharat/agent-accelerator](https://github.com/sashvat-bharat/agent-accelerator)
+A thin, typed transport SDK for calling LLMs through a single `Agent` interface.
 
-Agent Accelerator supports `google`, `opencode`, `openrouter`, `openai`, and any OpenAI-compatible endpoint using `{PREFIX}_API_KEY` and `{PREFIX}_BASE_URL`.
+Agent Accelerator supports `google`, `openrouter`, `openai`, and any OpenAI-compatible endpoint using `{PREFIX}_API_KEY` and `{PREFIX}_BASE_URL`.
 
 
 ```ts
@@ -45,7 +46,7 @@ yarn add agent-accelerator
 
 Requires `bun` or `node 22+`.
 
-Core dependencies are `zod`, `ai`, and selected `@ai-sdk/*` provider packages used as the backend transport.
+Core dependencies are `zod` only. Document conversion additionally uses the optional `@firecrawl/anydoc` peer. All provider transports are native REST (`fetch`, no SDK).
 
 ---
 
@@ -53,7 +54,6 @@ Core dependencies are `zod`, `ai`, and selected `@ai-sdk/*` provider packages us
 
 ```bash
 GEMINI_API_KEY=...
-OPENCODE_API_KEY=...
 OPENROUTER_API_KEY=...
 OPENAI_API_KEY=...
 # or OPENAI_BASE_API_KEY=...
@@ -126,15 +126,17 @@ An `Agent` holds :
 | `subagents`       | `SubAgent[] \| Agent[]`                              | Pre-defined workers. Each worker becomes a callable tool. Useful for fixed roles such as researcher or critic.                                             |
 | `subagentModel`   | `string \| ModelSpec \| ModelProviderInstance`       | Developer-only model for dynamically spawned workers. Never choosable by the Main Agent. Overridden by `dynamicSubagents.model`. Falls back to `SUB_AGENT_MODEL`. |
 | `dynamicSubagents` | `DynamicSubagentsConfig`                            | Enables and constrains LLM-spawned stateless workers: `{ enabled, model?, maxSpawn?, thinkingLevel?, tools?, timeout? }`. See [Dynamic delegation](#dynamic-delegation). |
-| `thinkingLevel`   | `ThinkingLevel`                                      | `none \| dynamic \| minimal \| low \| medium \| high \| xhigh`. Validated against the model catalog before a request.                                      |
+| `thinkingLevel`   | `ThinkingLevel`                                      | `none \| dynamic \| minimal \| low \| medium \| high \| xhigh \| max`. Validated against the model catalog before a request.                                      |
 | `cache`           | `CacheConfig`                                        | `{ retention, sessionId, cachedContentId, ttlSeconds }`. Controls cache reuse.                                                                             |
 | `serviceTier`     | `"flex" \| "priority"`                               | Cost / priority routing where supported. Omit for standard routing.                                                                                        |
-| `maxTurns`        | `number`                                             | Maximum model → tool → model loops per `run`. Defaults to `10`.                                                                                            |
+| `bypassInputFileModality` | `boolean`                                      | When `true`, `file` parts are converted client-side to Markdown for models lacking native support. Capable models still receive files natively. Defaults to `false`. |
+| `maxTurns`        | `number`                                             | Maximum model → tool → model loops per `run`. Infinite by default (`0` or omitted = no limit). Hitting a finite limit with pending tool calls warns and sets `finishReason: "max_turns"`. |
 | `sessionId`       | `string`                                             | Stable identifier used for cache affinity. Auto-generated when omitted.                                                                                    |
 | `headers`         | `Record<string,string>`                              | Additional headers merged into every request.                                                                                                              |
 | `apiKey`          | `string`                                             | Overrides environment-based API-key lookup for this agent.                                                                                                 |
 | `baseUrl`         | `string`                                             | Overrides the default endpoint for this agent.                                                                                                             |
 | `stateless`       | `boolean`                                            | When `true`, history is cleared before and after each `run`. Useful for one-shot evaluators. Defaults to `false`.                                          |
+| `persist`         | `{ dir?: string; file?: string }`                    | Durable sessions: rewrites the session file after every step (user/assistant/tool/sub-agent). `{ dir }` uses `sessions/<sessionId>/session.json`, `{ file }` a single `.session.json`. Writes are atomic and never fail a turn. |
 
 When `dynamicSubagents.enabled` is set without a resolvable worker model, construction throws `SubAgentModelError`.
 
@@ -145,6 +147,12 @@ await agent.run(prompt, opts?) // non-streaming, or streaming when opts.stream i
 agent.ask(prompt, optsOrBool?) // string deltas when streaming, otherwise same as run
 agent.stream(prompt, opts?) // AssistantMessageEventStream
 agent.reset() // clears messages + signatures, keeps config
+agent.exportSession(telemetry?) // storable snapshot for saveSessionFile
+agent.importSession(saved) // restores messages + config from loadSessionFile
+agent.track(trackingId) // live snapshot of one sub-agent worker (`NAME-{TrackingID}`)
+agent.listTrackedSubAgents() // TrackingIDs of known workers
+agent.subscribeToSubAgent(id, fn) // live worker updates, returns unsubscribe fn
+agent.persistNow() // rewrites the persist target now (no-op unless persist is set)
 ```
 
 `prompt` accepts `string | ContentPart[]`.
@@ -158,8 +166,9 @@ Use `ContentPart[]` when sending images, audio, or video alongside text.
 | `stream`                        | When `true`, returns a stream instead of a regular response promise.                                                                            |
 | `onDelta(delta, event)`         | Called for each text chunk. Use to render answers live.                                                                                         |
 | `onThinkingDelta(delta, event)` | Called for each reasoning chunk. Use to render reasoning separately.                                                                            |
-| `onEvent(event)`                | Called for every event: `text_delta`, `thinking_delta`, `tool_call_complete`, `tool_result`, `subagent_complete`, `usage`, `done`, and `error`. |
+| `onEvent(event)`                | Called for every event: `text_delta`, `thinking_delta`, `tool_call_complete`, `tool_result`, `subagent_complete`, `subagent_delta`, `usage`, `done`, and `error`. |
 | `wrapThinking`                  | Wraps reasoning as `<think>\n...\n</think>\n\n`, allowing UIs to render it without maintaining separate state.                                  |
+| `onTurn(turn)`                  | Called after every model/tool turn with `{ turns, text?, thinking?, toolCalls?, toolResults? }`. Drives sub-agent step logs and persistence.   |
 | `additionalContext`             | Added only to the current user turn. Keeps the system prompt stable for better caching.                                                         |
 | `sessionId`                     | Per-run session override.                                                                                                                       |
 | `headers`                       | Per-run header merge.                                                                                                                           |
@@ -289,6 +298,8 @@ A `spawn_subagents` tool is injected with the following task shape:
 - `tools` — developer-owned pool. Workers get zero tools unless the Main Agent grants a per-task `tools` subset by name (unknown names are ignored), keeping worker context small.
 - `timeout` (ms) — `0` = no limit, `-1` = the Main Agent sets a per-task `timeoutMs`, `>0` = fixed limit for every worker. Timed-out workers report an error entry; the rest of the batch still completes.
 - Workers are stateless: one task in, one result out, then shut down. No history, no recursion. The Main Agent cannot choose worker models or reasoning levels.
+- Worker names use UPPER-KEBAB (`HBM-PRICING-ANALYST`). Each worker gets a system-generated 32-char TrackingID, displayed as `NAME-{TrackingID}` (e.g. `HBM-PRICING-ANALYST-9f2c…`).
+- Workers stream internally: thinking/text deltas update the worker trace live (`agent.track(id)`, `subscribeToSubAgent`) and surface on the parent stream as `subagent_delta` events.
 
 ```ts
 const res = await agent.run("Audit auth pipeline and write a threat model");
@@ -327,11 +338,12 @@ const agent = new Agent({
 
 ### Tool Helpers
 
-* `tool({ name?, description, input?, parameters?, strict?, timeoutMs?, maxTries?, maxConcurrency?, execute })` — creates a `ToolDefinition`. Provide either a Zod `input` schema or raw JSON `parameters`. `execute(input, ctx)` may return arbitrary values; results are converted safely for model context. `timeoutMs` defaults to `0` (no time limit) and is a best-effort event-loop deadline; `ctx.signal` enables cooperative cancellation. `maxTries` accepts a number or numeric string; a positive value is the total attempt limit, while `0`/omitted means no configured limit for transient retries. `maxConcurrency` limits simultaneous calls for that tool (default pool: 8).
+* `tool({ name?, description, input?, parameters?, strict?, timeoutMs?, maxTries?, maxConcurrency?, execute })` — creates a `ToolDefinition`. Provide either a Zod `input` schema or raw JSON `parameters`. `execute(input, ctx)` may return arbitrary values; results are converted safely for model context. `timeoutMs` defaults to `0` (no time limit) and is a best-effort event-loop deadline; `ctx.signal` enables cooperative cancellation. `maxTries` accepts a number or numeric string; a positive value is the total attempt limit, while `0`/omitted falls back to 3 attempts. `maxConcurrency` limits simultaneous calls for that tool (default pool: 8).
 * `toStandardToolDeclarations(record | array)` — converts tools to `{ name, description, parameters }` for providers.
 * `zodToJsonSchema(schema)` — converts Zod schemas using native conversion with a fallback extractor.
 * `cleanJsonSchema(schema)` — removes `$schema`, `$defs`, and `definitions`, resolves `$ref`, and preserves explicit `additionalProperties`.
 * `executeToolCalls({ tools, toolCalls, agentName?, parallel?, signal?, sessionId? })` — executes tool calls. Calls validate Zod input, use bounded parallelism, enforce per-tool timeouts, retry transient failures, recover namespace/camel-case tool-name aliases, and return `ToolResultRecord[]`. Missing tools and aborts are represented as error results rather than thrown.
+* `convert_document_to_markdown` — built-in tool that converts document files (PDF/Word/PowerPoint/Excel/OpenDocument/RTF/EPUB/CSV, local path or URL) to Markdown for models without native document parsing. Requires the optional `@firecrawl/anydoc` peer.
 
 The agent loop also blocks an identical tool name and argument set when the model requests it in the immediately following turn. The synthetic error is returned to the model so it can reuse the prior result or change its arguments.
 
@@ -386,7 +398,8 @@ for (const result of response.toolResults) {
   name,
   arguments,
   rawArguments?,
-  thoughtSignature?
+  thoughtSignature?,
+  callId?,
 }
 ```
 
@@ -408,7 +421,6 @@ for (const result of response.toolResults) {
 First-class provider IDs are:
 
 * `google`
-* `opencode`
 * `openrouter`
 * `openai`
 
@@ -417,9 +429,6 @@ Any other provider prefix is treated as an OpenAI-compatible custom provider.
 ### Model Strings
 
 * `"google/<id>"` → Google AI Studio at `generativelanguage.googleapis.com`.
-* `"opencode/<id>"` → OpenCode Zen at `opencode.ai/zen/v1`.
-* `"opencode-go/<id>"` → OpenCode Go endpoint.
-* OpenCode automatically selects Chat vs Responses API. Claude models and models using `api=openai-responses` use Responses.
 * `"openrouter/<scope>/<model>"` or `"scope/model:variant"` → OpenRouter.
 * `"openai/<id>"` → OpenAI.
 * `"groq/<id>"`, `"ollama/<id>"`, etc. → custom providers using `{PREFIX}_API_KEY` and `{PREFIX}_BASE_URL`. The API key is optional for local endpoints.
@@ -437,7 +446,7 @@ An unknown prefix with no catalog match still routes to a custom provider, allow
 * `getProvider("groq")` → returns a cached provider and automatically creates a custom provider for unknown prefixes.
 * `ensureCustomProvider(prefix, { baseUrl?, apiKey?, name? })` → gets or creates a custom provider. Useful for multiple endpoints in one process.
 * `normalizeProviderPrefix(s)` → lowercases and trims a provider prefix.
-* `ModelProvider.GoogleGenAI(model, apiKey?, { thinkingLevel?, baseUrl? })` — same shape is available for `.OpenCode`, `.OpenRouter`, `.OpenAI`, `.Custom`, `.OpenAICompatible`, and `.Generic`.
+* `ModelProvider.GoogleGenAI(model, apiKey?, { thinkingLevel?, baseUrl? })` — same shape is available for `.OpenRouter`, `.OpenAI`, `.Custom`, `.OpenAICompatible`, and `.Generic`.
 
 Each returns a `ModelProviderInstance`:
 
@@ -472,93 +481,82 @@ new Agent({
 });
 ```
 
-`BaseProvider` is the abstract provider base containing `id`, `name`, `models`, `getModel`, `generate`, `stream`, and `countTokens`.
+`Provider` is the provider contract containing `id`, `name`, `models`, `getModel`, `generate`, and `stream`.
 
-Its catalog-first `getModel` behavior includes a hardcoded fallback.
+Its catalog-first `getModel` behavior includes a permissive fallback (`createGenericModelSpec`) so private model IDs never fail preflight.
 
-Extend `BaseProvider` when implementing a fully custom transport.
+Implement the `Provider` interface when adding a fully custom transport.
 
 `ProviderRequestOptions { apiKey?, baseUrl?, headers?, thinking?, cache?, serviceTier?, tools?, toolChoice?, signal?, sessionId?, env? }` is the per-call options object passed to `generate`/`stream`. Agent builds it automatically.
 
 ### Google
 
-`GoogleAIStudioProvider` and `GOOGLE_MODELS` provide Google AI Studio support.
+`GoogleInteractionsProvider` (aliased as `GoogleAIStudioProvider`) and `GOOGLE_MODELS` provide Google support over the Interactions API (`POST {baseUrl}/interactions`, streaming via `?alt=sse`).
 
-The catalog is filtered with fallback support for lite and flash models.
+Turns chain statefully through `previous_interaction_id` per session, falling back to stateless full-history sends when the session switches providers or models.
 
-Google models matching `gemini-1.x` or `gemini-2.x` are rejected.
-
-Thinking levels map to:
+Thinking levels map to `thinking_level`, with `thinking_summaries` enabled whenever thinking is active:
 
 ```text
-OFF | MINIMAL | LOW | MEDIUM | HIGH
+minimal | low | medium | high   (xhigh/max clamp to high; none is unsupported and omitted; dynamic omits)
 ```
 
 Google-specific handling includes:
 
 * Isolating `thoughtSignature` per part for prefix stability.
 * Converting JSON Schema to OpenAPI 3.0 through `stripSchemaForGoogle`.
-* Supporting explicit `cachedContents` when `retention != implicit` and the prompt is large.
+* Implicit/automatic caching only — explicit retention and `cachedContentId` are warned about and dropped (the Interactions API defines no explicit cache primitives).
 
 Helpers:
 
 * `createExplicitCache({ model, systemInstruction?, contents?, tools?, displayName?, ttlSeconds?, expireTime?, apiKey?, baseUrl? })`
 * `isValidThoughtSignature(sig)`
 * `retainThoughtSignature(existing, incoming)`
+* `extractGoogleThoughtSignature(obj)`
 * `stripSchemaForGoogle(schema)`
+* `clearInteractionChains(sessionId?)`
 
 ### OpenAI
 
-`OpenAIProvider` and `OPENAI_MODELS` provide OpenAI support.
+`OpenAIResponsesProvider` (aliased as `OpenAIProvider`) and `OPENAI_MODELS` provide OpenAI support over the Responses API (`POST {baseUrl}/responses`).
 
-`OpenAIProvider` is also the base class for OpenAI-wire transports.
+Every turn is stateless: the full history is sent explicitly with `store: false`, so no `previous_response_id`, `background`, or conversation chaining is ever used.
 
-Thinking levels map to:
+Thinking levels map to `reasoning.effort` verbatim:
 
 ```text
-reasoning_effort: low | medium | high
+none | minimal | low | medium | high | xhigh | max   (dynamic omits — server default)
 ```
 
 It also:
 
-* passes `service_tier`;
-* derives `max_completion_tokens` from the configured budget;
-* preserves Google thought signatures through `extra_content.google.thought_signature`;
-* exposes `extractGoogleThoughtSignature(obj)`.
-
-### OpenCode
-
-`OpenCodeProvider` and `OPENCODE_MODELS` provide OpenCode support.
-
-Requests include:
-
-* `session_id`
-* `prompt_cache_key`
-* headers used for sticky routing
-
-The provider handles both Chat and Responses payloads.
-
-Transient `500`, `502`, `503`, and `529` errors are retried with thinking disabled, followed by an attempt using the alternate endpoint.
+* passes `service_tier` (`flex` | `priority`);
+* pins cache affinity with `prompt_cache_key` (clamped to 64 chars);
+* rejects `video` parts up front with a one-line error (the Responses wire carries text/image/file only);
+* never sends `temperature`, token caps, or background/conversation fields.
 
 ### OpenRouter
 
-`OpenRouterProvider` and `OPENROUTER_MODELS` provide OpenRouter support.
+`OpenRouterChatCompletionsProvider` (aliased as `OpenRouterProvider` / `OpenRouter`) and `OPENROUTER_MODELS` provide OpenRouter support over Chat Completions (`POST {baseUrl}/chat/completions`).
 
-Requests include:
+Every turn is stateless: the full `messages[]` array is sent explicitly — no chaining primitives exist on this endpoint.
 
-* `session_id`
-* `prompt_cache_key`
+Session affinity is a top-level body `session_id` plus the `x-session-id` header fallback (body takes precedence per OpenRouter docs).
 
-Thinking is mapped to:
+Thinking levels map to `reasoning.effort` verbatim:
 
 ```text
-reasoning { effort | enabled }
-include_reasoning
+none | minimal | low | medium | high | xhigh | max   (dynamic omits — server default)
 ```
 
-based on catalog capabilities.
+It also:
+
+* passes `service_tier` (`flex` | `priority`);
+* enables the `file-parser` plugin when file parts are present (remote file URLs are additionally surfaced in text);
+* maps `tool_choice` (`auto` omitted; `none`, `required`, and function pins supported);
+* reports `cached_tokens` / `cache_write_tokens` / reasoning tokens, preferring provider-reported `cost` when present.
 
-`serviceTier` is mapped to provider routing.
+`serviceTier` values other than `flex` / `priority` are omitted (standard routing).
 
 ### Custom
 
@@ -588,7 +586,6 @@ Examples include:
 
 * `OpenAIChatCompletionRequest`
 * `GoogleGenerateContentRequest`
-* `OpenCodeChatRequest`
 * `OpenRouterChatRequest`
 
 ---
@@ -604,14 +601,15 @@ ThinkingLevel =
   | "low"
   | "medium"
   | "high"
-  | "xhigh";
+  | "xhigh"
+  | "max";
 ```
 
 ### Thinking Levels
 
 * `none` — disables thinking where supported.
 * `dynamic` — allows the model to decide.
-* `minimal`, `low`, `medium`, `high`, `xhigh` — request increasing levels of reasoning where supported.
+* `minimal`, `low`, `medium`, `high`, `xhigh`, `max` — request increasing levels of reasoning where supported.
 
 Thinking can be configured on the `Agent` or through `ModelProvider.*(..., { thinkingLevel })`.
 
@@ -632,6 +630,7 @@ ThinkingConfig {
 
 * `getModelThinkingInfo(provider, modelId)` → `{ supportsThinking, reasoningOptions?, allowedLevels, supportsDisable, description }`. Useful for building UI selectors.
 * `validateModelThinking(provider, modelId, level)` → throws `ThinkingLevelError { provider, modelId, requestedLevel, allowedLevels, supportsThinking }` with a fix hint. Automatically called by `run` and `stream`. Catch it and use `err.allowedLevels` to offer valid options.
+* `resolveEffectiveThinking(base, override?)` → resolves a per-run `thinkingLevel` override into a `ThinkingConfig` without mutating agent config.
 * `getModelsForProvider("google")` → returns known model specifications.
 
 Unknown models allow all thinking levels.
@@ -660,40 +659,40 @@ CacheRetention =
 
 ### Retention
 
-* `implicit` — automatic prefix reuse without an explicit cache object or storage fee.
-* `short` — approximately 5 minutes.
-* `medium` — approximately 1 hour.
-* `long` — approximately 12 hours for Google explicit caches and approximately 24 hours for prompt caching where supported.
+* `implicit` — automatic prefix reuse without an explicit cache object or storage fee. This is the only retention the native adapters act on (by doing nothing special — stable prompts plus session affinity do the work).
+* `short` / `medium` / `long` — TTL hints (`5m` / `1h` / `12h`) consumed only by the opt-in `createExplicitCache` helper. Provider adapters warn about and drop any non-`implicit` retention: none of the native transports expose retention control.
 
 ### Session Affinity
 
 `sessionId` pins provider affinity using mechanisms such as:
 
-* `x-session-id`
-* `x-opencode-session`
-* `prompt_cache_key` (openai/openrouter/opencode only — strict endpoints such as groq reject it, so custom providers get headers only)
+* `x-session-id` (+ `x-client-request-id`) headers — all providers, best effort
+* top-level body `session_id` — OpenRouter (takes precedence over the header)
+* `prompt_cache_key` — OpenAI only (custom endpoints get headers only; strict ones reject unknown body fields)
 
 Reuse the same session ID across turns when cache affinity is desired.
 
-In browser runtimes only CORS-safe attribution headers are sent; affinity
-still flows via `promptCacheKey` provider options, never via headers.
+In browser runtimes custom `x-*` headers are stripped to avoid CORS preflights: OpenAI keeps affinity through its body key, while custom endpoints lose affinity entirely on browsers.
 
 ### Explicit Caches
 
-`cachedContentId` reuses a previously created Google `cachedContents/...` resource.
+`createExplicitCache` mints a Google `cachedContents/...` resource directly (TTL via `retention`/`ttlSeconds`).
+
+`cachedContentId` is accepted and carried in context, but no native adapter currently sends it — explicit references are warned about and dropped, so stable prompts plus session affinity remain the cache-reuse path.
 
 `ttlSeconds` overrides the retention mapping.
 
 ### Provider Cache Mechanisms
 
-* **Google** keeps system prompts and tools stable and isolates signatures.
-* **OpenCode / OpenRouter** use sticky session keys.
+* **Google** keeps system prompts and tools stable and isolates signatures (implicit caching only).
+* **OpenAI** pins affinity with `prompt_cache_key`.
+* **OpenRouter** pins affinity with body `session_id` plus headers (sticky routing from the first request).
+* **Custom endpoints** get headers-only affinity; anything else cache-related is warned about and dropped.
 
 The following cache helpers are exported:
 
-* `applyAnthropicCacheControl`
-* `getCacheControlForRetention`
 * `getPromptCacheRetention`
+* `retentionToTtlSeconds`
 * `clampCacheKey`
 
 For the best cache reuse, keep `instructions` and the tool set stable. Put changing data in user messages or `additionalContext`.
@@ -741,6 +740,7 @@ StreamEvent {
   toolCall?,
   toolResult?,
   subagent?,
+  subagentTrackingId?,
   usage?,
   responseId?,
   finishReason?,
@@ -766,12 +766,13 @@ tool_call_delta
 tool_call_complete
 tool_result
 subagent_complete
+subagent_delta
 usage
 done
 error
 ```
 
-Emitted in practice: `start`, `text_delta`, `thinking_delta`, `tool_call_complete`, `tool_result`, `subagent_complete`, `usage`, `done`, `error`. The rest exist in the type for forward compatibility.
+Emitted in practice: `start`, `text_delta`, `thinking_delta`, `tool_call_complete`, `tool_result`, `subagent_complete`, `subagent_delta`, `usage`, `done`, `error`. The rest exist in the type for forward compatibility.
 
 Use:
 
@@ -779,6 +780,7 @@ Use:
 * `thinking_delta` for reasoning output.
 * `tool_call_complete` / `tool_result` for tool progress.
 * `subagent_complete` for each completed worker during streaming multi-agent runs.
+* `subagent_delta` for live worker thinking/text (`subagentTrackingId` + `delta`/`thinkingDelta` + partials). Render per-worker; never merge into the parent answer.
 * `usage` for interim usage counts.
 * `done` for final usage and completion information.
 
@@ -808,8 +810,6 @@ AgentResponse {
   text,
   thinking?,
   thoughtSignature?,
-  thinkingSignature?,
-  textSignature?,
   toolCalls,
   toolResults,
   subagents,
@@ -850,10 +850,33 @@ SubAgentExecutionMetadata {
   toolCalls?,
   raw?,
   isError?,
-  error?
+  error?,
+  trackingId?,
+  sessionId?,
+  parentSessionId?,
+  steps?
+}
+```
+
+`finishReason` is `"max_turns"` when a finite `maxTurns` limit stopped the run with tool calls still pending (plus a console warning naming the dropped tools).
+
+### SubAgentStep
+
+```ts
+SubAgentStep {
+  turn,
+  type, // "assistant" | "tool_call" | "tool_result"
+  name?,
+  text?,
+  thinking?,
+  isError?,
+  timestamp,
+  partial? // true while the worker is still streaming this step
 }
 ```
 
+`agent.track(id)` returns these live; `partial` entries finalize when the worker's turn completes.
+
 ### TokenUsage
 
 ```ts
@@ -930,8 +953,8 @@ const res = await agent.run([...]).catch(fail);
 
 Agent Accelerator features an adaptive, dynamically synchronized model catalog powered by [models.dev](https://models.dev). To avoid shipping a bloated 4.4 MB static JSON file with production builds, the SDK employs a high-performance **12-hour TTL local caching architecture**:
 
-- **Automated 12-Hour Cache Validation**: When `.run()`, `.ask()`, or `.stream()` executes, the runtime checks `src/data/models-cache.json`. If the cache timestamp is within 12 hours, it reads from disk with zero network delay. When the TTL expires, it transparently synchronizes with `https://models.dev/api.json`.
-- **Git & Package Safety**: The dynamic cache file (`src/data/models-cache.json`) is gitignored and excluded from production packages.
+- **Automated 12-Hour Cache Validation**: When `.run()`, `.ask()`, or `.stream()` executes, the runtime checks `src/data/models.dev.json`. If the cache timestamp is within 12 hours, it reads from disk with zero network delay. When the TTL expires, it transparently synchronizes with `https://models.dev/api.json`.
+- **Git & Package Safety**: The dynamic cache file (`src/data/models.dev.json`) is gitignored and excluded from production packages.
 
 ### Developer Catalog Controls
 
@@ -958,9 +981,9 @@ console.log(status.modelCount, status.providerCount, status.isExpired);
 ### CLI Refresh
 
 ```bash
-bun run update-models                 # Refresh model catalog (force or expired)
-bun scripts/update-models.ts --force  # Force re-download
-bun scripts/update-models.ts --ttl=24h # Refresh with custom TTL
+bun run update-models              # Refresh model catalog (force or expired)
+bun src/update-models.ts --force  # Force re-download
+bun src/update-models.ts --ttl=24h # Refresh with custom TTL
 ```
 
 Upstream data lags on some inputs (e.g. `gpt-4o` accepts audio). Record
@@ -1025,15 +1048,8 @@ ModelCapabilities {
 }
 ```
 
-When estimated input exceeds the available context budget, `Agent` trims the oldest middle history using:
-
-```text
-context * 0.9 - maxOutput
-```
-
-The beginning of the conversation and the most recent tail are preserved.
-
 ---
+
 ## Messages and Media
 
 ### Message
@@ -1092,7 +1108,7 @@ Supported content parts include:
 
 `inferMimeType(path)` infers the MIME type from a file extension.
 
-Media normalization is handled automatically by providers (mapped to Vercel V4 `file` parts). Thinking traces are echoed in follow-up turns only where accepted — strict endpoints receive tool calls without `reasoning_content`.
+Media normalization is handled automatically by providers (mapped to provider-native media shapes). Thinking traces are echoed in follow-up turns only where accepted — strict endpoints receive tool calls without `reasoning_content`.
 
 Provider matrix: text + image + wav/mp3 audio + PDF work on all supported
 providers. Video works on Gemini only.
@@ -1106,40 +1122,31 @@ its verdict surfaces as a concise error (see [Errors](#errors)). Verified
 catalog corrections live in `MODALITY_OVERRIDES` (`src/models/catalog.ts`),
 never in the gitignored snapshot.
 
----
-## Tokens
-
-Token counting is heuristic only.
-
-Actual billing information comes from `res.usage`.
-
-Available helpers:
-
-* `countTokens(string | Message[] | ProviderContext)` — useful for preflight sizing and history trimming.
-* `estimateTokensFromText(text)`
-* `estimateTokensFromMessage(msg)`
-* `estimateTokensFromPart(part)`
-
 ---
 ## Utils
 
 * `createSessionId(prefix="accel")` — creates a UUID-based session ID clamped to 64 characters for affinity.
+* `createTrackingId()` — system-generated 32-char TrackingID for one sub-agent worker (`NAME-{TrackingID}`).
+* `createChildSessionId(parentId, tag)` / `createFixedChildSessionId(parentId, name)` / `isSessionDescendant(child, parent)` — provider-safe (≤64 chars) child session IDs with parent-hash lineage.
 * `getEnv(key, fallback?)` — resolves an environment variable.
 * `getApiKey(provider, explicit?, env?)` — resolves API keys using the configured environment lookup order.
 * `buildSessionHeaders(provider, cache?, custom?, sessionId?)` — builds provider-specific affinity headers. Normally handled automatically.
+* `withRetries(fn, { maxRetries?, maxRetryDelayMs?, signal?, label? })` / `isTransientError(err)` — bounded retries for transient provider failures (defaults: 2 retries, 5s cap, aborts never retried).
+* `convertDocumentToMarkdown(input, { filename?, format?, mimeType?, maxChars? })` — converts PDF/Word/PowerPoint/Excel/OpenDocument/RTF/EPUB/CSV to Markdown via the optional `@firecrawl/anydoc` peer. Throws `DocumentConversionError` on failure.
+* `convert_document_to_markdown` — built-in model-callable version of the above (returns a `<Document>` envelope); auto-registered with `bypassInputFileModality: true`.
 * `z` — re-exported from Zod so tools do not require a separate Zod import.
 
 ---
 ## Examples
 
 ```bash
-bun run examples/06-chat.ts
+bun run examples/05-chat.ts
 # persistent CLI, /model "..." /level <lvl> /help /exit
 
-bun run examples/05-sub-agents.ts
+bun run examples/04-sub-agents.ts
 # fixed researcher + critic pipeline
 
-bun run examples/04-multi_agent.ts
+bun run examples/03-multi_agent.ts
 # dynamic spawn_subagents demo
 
 bun run examples/01-metadata.ts
@@ -1148,17 +1155,23 @@ bun run examples/01-metadata.ts
 bun run examples/02-function_calling.ts
 # single tool call
 
-bun run examples/03-multimodal_image.ts [./photo.png]
+bun run examples/06-multimodal_image.ts [./photo.png]
 # image input (remote URL default, local path optional)
 
 bun run examples/07-multimodal_audio.ts
 # audio input
 
-bun run examples/08-multimodal_document.ts
+bun run examples/09-multimodal_document.ts
 # PDF/file input
 
-bun run examples/09-multimodal_video.ts
+bun run examples/08-multimodal_video.ts
 # video input (video-capable model required)
+
+bun run examples/10-document_markdown.ts
+# document → Markdown preprocessing (any model, optional @firecrawl/anydoc peer)
+
+bun run examples/11-session-identity.ts
+# sub-agent TrackingIDs, live worker boxes, lineage, track(), durable sessions
 ```
 
 Every example ends its `run()` with `.catch(fail)` (`examples/_shared.ts`),
@@ -1167,17 +1180,54 @@ so failures print one line and exit `1` — no stack dumps.
 The chat example persists conversations to:
 
 ```text
-.session.jsonl
+sessions/<sessionId>/session.json  (+ media/ for images, audio, video, files)
 ```
 
-It resumes from that file on next launch.
+It resumes the most recent session on next launch (legacy `.session.json`/`.session.jsonl` files still load) and prints a resume banner:
+
+```text
+↺ Previous session loaded • accel-1a2b… (.session.json) • 12 messages • google/gemini-3.5-flash-lite • total-CH82.4% • $0.013 total
+```
 
-It also displays per-turn:
+It also displays per-turn and session totals on one line:
 
 ```text
-input / output / cached / cost / context %
+↑turn ↓turn CRturn turn-CH% | ↑total ↓total CRtotal total-CH% $total(+turn) ctx%/window
+```
+
+### Session persistence
+
+```ts
+import {
+  Agent,
+  loadSessionFile,
+  saveSessionFile,
+  SessionTelemetry,
+  formatSessionBanner,
+} from "agent-accelerator";
+
+const saved = loadSessionFile(".session.json");
+const telemetry = SessionTelemetry.fromSaved(saved);
+
+const agent = new Agent({
+  model: saved?.model ?? process.env.MODEL,
+  sessionId: saved?.sessionId,
+});
+
+if (saved) agent.importSession(saved);
+
+const res = await agent.run("Hello");
+telemetry.add(res.usage, agent.modelStringOrSpec as string);
+saveSessionFile(".session.json", agent, telemetry);
 ```
 
+* `agent.exportSession(telemetry)` / `agent.importSession(saved)` round-trip messages, system prompt, model, thinking level, instructions, cache, worker model, and sub-agent traces without touching `AgentContext` internals.
+* `SessionTelemetry` accumulates `input / output / cacheRead / cacheWrite / reasoning / cost`, with clamped `turnHitRate()` / `totalHitRate()`, a dual `formatBar(res)`, and `formatSessionBanner(saved, telemetry, path)` for startup.
+* Files are pretty-printed JSON (2-space indent), written atomically (temp + rename). Cost prefers provider-reported totals and falls back to catalog pricing.
+* Binary media (bytes, data URLs, base64) is extracted to `media/` on save via `saveSessionDir("sessions", agent, telemetry)` → `sessions/<sessionId>/{session.json, media/*}`; remote URLs and local paths stay references. `loadSessionDir(dir)` resolves `media/…` refs back to absolute paths, and `findLatestSessionDir("sessions")` resumes the most recent session.
+* Sub-agent traces persist in a dedicated `subagents` section keyed by TrackingID (`{ trackingId, name, sessionId, parentSessionId, status, task, turns, usage, steps, text }`). Files stay lean: redundant `rawArguments` and repeated step text are dropped on save (rebuilt/kept live in memory).
+* With `persist: { dir }` or `{ file }`, the session file is rewritten after every step, so a crash loses at most the in-flight step.
+
 ---
 ## Scripts and Structure
 
@@ -1193,20 +1243,21 @@ bun run update-models # refresh model catalog cache (supports --force, --ttl=24h
 ```text
 src/
 ├── agent/      # Agent, context, loop, delegation, subagent
-├── ai-sdk/     # Provider backend: provider factories, converters, executor, registry
+├── session/    # Session persistence + telemetry (snapshots, hit rates, .session.json store)
+├── providers/  # native REST adapters (google/openai/openrouter/openai-compat) + registry + canonical contract
 ├── models/     # Dynamic catalog cache, parser, verified overrides
 ├── data/       # Dynamic model catalog cache (gitignored, excluded from bundle)
 ├── tools/      # tool(), schema, executor
 ├── streaming/  # event stream, SSE parser
-├── tokens/     # estimator
 ├── types/      # agent, core, message, model, response, tool
-└── utils/      # base64, cache, env, headers, media, serialization, session
+└── utils/      # base64, cache, env, headers, media, serialization, session, thought-signature, documents, retry, errors
 examples/
-├── 01-metadata.ts  02-function_calling.ts  03-multimodal_image.ts
-├── 04-multi_agent.ts  05-sub-agents.ts  06-chat.ts
-├── 07-multimodal_audio.ts  08-multimodal_document.ts
-├── 09-multimodal_video.ts  _shared.ts
-test/            # 105 tests mirroring the above
+├── 01-metadata.ts  02-function_calling.ts  03-multi_agent.ts
+├── 04-sub-agents.ts  05-chat.ts  06-multimodal_image.ts
+├── 07-multimodal_audio.ts  08-multimodal_video.ts
+├── 09-multimodal_document.ts  10-document_markdown.ts
+├── files/  prompts/  research-agent.ts  _shared.ts
+test/            # unit + mocked-provider tests mirroring src/
 ```
 
 ---

package/{SYSTEM_PROMPT_AGENT.md → examples/prompts/SYSTEM_PROMPT_AGENT.md}

@@ -5,7 +5,7 @@ You are an Agent — you evaluate user objectives and decide whether to solve th
    - Single-focus, factual, code-generation, or conversational prompts → Answer directly, concisely, and completely.
    - Do NOT spawn sub-agents for trivial, single-step tasks.
 2. **Delegate**:
-   - Complex research, multi-angle analysis, deep technical trade-offs, or parallel explorations → Invoke `spawn_subagents` with 2 to 5 focused sub-agents in a single batched call.
+    - Complex research, multi-angle analysis, deep technical trade-offs, or parallel explorations → Invoke `spawn_subagents` with 2 to 4 focused sub-agents in a single batched call.
    - For each sub-agent define:
      - `name`: `UPPER_SNAKE_CASE` identifier describing domain focus (e.g., `MARKET_ANALYST`, `SYSTEMS_ARCHITECT`).
      - `role`: Distinct specialized persona.