agent-accelerator 0.6.0 → 0.6.5

package/README.md

@@ -121,12 +121,13 @@ An `Agent` holds:
 | `tools`           | `Record<string, ToolDefinition> \| ToolDefinition[]` | Deterministic functions the model can call. See [Tools](#tools).                                                                                          |
 | `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. Deprecated alias of `dynamicSubagents.model` (which wins). Falls back to `SUB_AGENT_MODEL`. |
-| `dynamicSubagents` | `DynamicSubagentsConfig`                            | Enables and constrains LLM-spawned workers: `{ enabled, model?, maxSpawn?, maxDepth?, workerBudget?, thinkingLevel?, tools?, workerTimeoutMs?, allowScheduledActions? }` (`workerTimeoutMs` is for scheduled actions only). See [Pre-defined vs Dynamic Delegation](#pre-defined-vs-dynamic-delegation) and [Scheduled actions](#scheduled-actions). |
+| `dynamicSubagents` | `DynamicSubagentsConfig`                            | Enables and constrains LLM-spawned workers: `{ enabled, model?, maxSpawn?, maxDepth?, workerBudget?, scheduledActionBudget?, thinkingLevel?, tools?, workerTimeoutMs?, allowScheduledActions? }` (`workerTimeoutMs` is for scheduled actions only). See [Pre-defined vs Dynamic Delegation](#pre-defined-vs-dynamic-delegation) and [Scheduled actions](#scheduled-actions). |
 | `thinking`        | `ThinkingOption`                                     | Canonical reasoning option: `none \| dynamic \| minimal \| low \| medium \| high \| xhigh \| max`, or `{ level, budgetTokens }`. Legacy `thinkingLevel` still works (canonical wins). Validated against the model catalog before a request.                                      |
 | `cache`           | `CacheOption`                                        | `"implicit" \| "5m" \| "30m" \| "1h" \| "12h"`. Prompt-cache lifetime; unsupported values warn and fall back (see [Cache](#cache)).                                                                             |
 | `serviceTier`     | `"flex" \| "priority"`                               | Cost / priority routing where supported. Omit for standard routing.                                                                                        |
 | `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"`. |
 | `limits`          | `AgentRunLimits`                                     | `{ maxTurns?, deadlineMs?, maxToolCallsPerRun?, maxTotalTokens?, requestTimeoutMs?, firstByteTimeoutMs?, streamIdleTimeoutMs? }`. The first four are unlimited by default; hitting `maxTurns` ends the run with `finishReason: "max_turns"`, the other three throw a `BudgetExceededError`. The three network timeouts default to 300 s / 120 s / 300 s so a silent connection fails instead of hanging; set one to `0` or `Infinity` to turn it off. A timeout raises a retryable `TimeoutError`. See [Safety and operations](docs/guides/safety-and-ops.md#network-timeouts). |
+| `usageLimit`      | `{ maxCostUsd?, maxTotalTokens? }`                   | A spending cap for the WHOLE chat, for its whole life: the agent and all its workers added up, kept across restarts. Reaching it throws `BudgetExceededError` ("Usage limit reached"). Scheduled actions never count. Unset = no cap. |
 | `budget`          | `Budget`                                             | `{ maxCostUsd?, maxTotalTokens?, maxDurationMs?, maxTotalSubagents? }`, per run, workers included. Unlimited by default; exceeding it throws `BudgetExceededError` with partial usage. |
 | `sessionId`       | `string`                                             | Stable identifier used for cache affinity. Auto-generated when omitted.                                                                                    |
 | `headers`         | `Record<string,string>`                              | Additional headers merged into every request.                                                                                                              |
@@ -292,7 +293,8 @@ One `subagents` tool is injected. It takes `{ command, id?, name?, role?, instru
 - `tools` is the developer-owned pool. Workers get zero tools unless the Main Agent grants a subset by name; unknown names are rejected with the pool listed.
 - The Main Agent cannot choose worker models, reasoning levels or timeouts. The `subagents` tool has no timeouts (`workerTimeoutMs` and an action's `timeoutMs` apply only to scheduled actions).
 - `maxDepth` caps how many levels of workers may exist below the agent. By default there is no cap (a worker can start workers that start workers, as deep as the model goes); set a whole number >= 1 to limit it: `1` keeps workers flat, `3` allows three levels. A worker with levels left gets its own `subagents` tool, and its children can only be granted the tools **it** was granted. The levels are saved inside each other (`<session>/workers/<id>/workers/<id>/…`).
-- `workerBudget: { maxCostUsd?, maxTotalTokens? }` is each worker's own spending cap, applied as that worker's per-run `budget` (a spawn, a message or a scheduled run is one run; the usage of the worker's own workers counts toward it) and passed down to its workers. Going over fails that call with a budget error (`[worker <id>] failed: Token budget exceeded…`), leaves the worker open and does not affect the parent. Default: unlimited; models with unknown pricing count $0 toward `maxCostUsd`. Values must be numbers above 0.
+- `workerBudget: { maxCostUsd?, maxTotalTokens? }` is each chat worker's own spending cap, applied as that worker's per-run `budget` (a spawn or a message is one run; the usage of the worker's own workers counts toward it) and passed down to its workers. Going over fails that call with a budget error (`[worker <id>] failed: Token budget exceeded…`), leaves the worker open and does not affect the parent. Default: unlimited; models with unknown pricing count $0 toward `maxCostUsd`. Values must be numbers above 0.
+- `scheduledActionBudget: { maxCostUsd?, maxTotalTokens? }` is the same kind of cap for each scheduled-action run (retries included). Scheduled actions are detached from the chat, so only this cap applies to them: not `workerBudget`, the agent's `budget` or `usageLimit`. Default: unlimited.
 - Workers are real agents with their own session: see [Persistent workers](#persistent-workers-agentworkers) below (the same functions in code, saved on disk with `persist`, resumed after a restart). Each reply's usage is metered into the parent's usage and budget.
 - Each run of a worker gets a system-generated 32-char TrackingID, displayed as `NAME-{TrackingID}`. Thinking/text deltas update the worker trace live (`agent.track(id)`, `subscribeToSubAgent`) and surface on the parent stream as `subagent_delta` events.
 
@@ -354,9 +356,9 @@ The Main Agent then gets two tools, fixed by config so the prompt cache stays st
 The same code is available to your program:
 
 ```ts
-import { createScheduledAction, telemetryBus } from "agent-accelerator";
+import { telemetryBus } from "agent-accelerator";
 
-createScheduledAction(agent, {
+agent.scheduled.create({
   instructions: "You write a short, sourced AI research brief.",
   task: "Summarize the most important AI news of the last day in 5 bullets.",
   tools: ["recent_news"], // names from the worker pool
@@ -377,16 +379,16 @@ telemetryBus.onEvent((e) => {
 });
 ```
 
-| Function | What it does |
+| `agent.scheduled` | What it does |
 | --- | --- |
-| `createScheduledAction(agent, input)` | Schedule a new action. Throws one `ValidationError` listing every problem. |
-| `listScheduledActions({ home? })` | Every action with its metadata, state (`waiting`, `cooking`, `missed`, `done`), `lastRun` and a `running` flag. |
-| `updateScheduledAction(id, patch, { home? })` | Change instructions, task, tools, timeout, role or any schedule field. Schedule changes are refused while it is cooking. |
-| `runScheduledAction(id, { home? })` | Run now, outside the schedule (also resolves a missed run). Needs the creating `Agent` alive. |
-| `skipScheduledAction(id, { home? })` | Ignore a missed run and wait for the next scheduled time. |
-| `deleteScheduledAction(id, { force?, purge?, home? })` | Delete for good. While it is cooking nothing changes unless `force: true`; `purge: true` also deletes past run files. |
+| `create(input)` | Schedule a new action under this agent. Throws one `ValidationError` listing every problem, and a `ConfigError` when `allowScheduledActions` is off. |
+| `list()` | Every action in the agent's home with its metadata, state (`waiting`, `cooking`, `missed`, `done`), `lastRun` and a `running` flag. |
+| `update(id, patch)` | Change instructions, task, tools, timeout, role or any schedule field. Schedule changes are refused while it is cooking. |
+| `run(id)` | Run now, outside the schedule (also resolves a missed run). Needs the creating `Agent` alive. |
+| `skip(id)` | Ignore a missed run and wait for the next scheduled time. |
+| `delete(id, { force?, purge? })` | Delete for good. While it is cooking nothing changes unless `force: true`; `purge: true` also deletes past run files. |
 
-Every function except `createScheduledAction` finds the home folder through `setHome()`, `AGENT_ACCEL_HOME`, or `.agent-accel/` in the working directory. If you built the Agent with its own `home`, pass the same `{ home }` to these calls (the model's `scheduled_actions` tool already does).
+Every method works on **the agent's own home** (`home` option, else `setHome()`, `AGENT_ACCEL_HOME`, or `.agent-accel/`), so nothing needs a `{ home }` argument. `list`, `update`, `run`, `skip` and `delete` see every action in that home, like the model's `scheduled_actions` tool does.
 
 **How it behaves**
 
@@ -401,6 +403,21 @@ Every function except `createScheduledAction` finds the home folder through `set
 * **Missed runs.** If the process was down when a run was due, the SDK emits `scheduled_action.missed` once. By default it runs nothing by itself and the action waits as `missed`: pick `run_now` or `skip`. Set `scheduled_action.onMissed` per action to decide in advance: `"skip"` moves on to the next time (a one-shot is `done`; a `skipped` event follows), `"run"` runs it as soon as the program is back (delivered when it finishes, marked `late`). The same applies to a run a crash cut off. An action whose creating Agent is gone stays `missed` whatever `onMissed` says (nothing can run it). A result saved before the process exited is simply delivered (marked `late`) on the first tick after start. `late` means the result was delivered more than two ticks after its time, finished after its delivery second, or replaced a missed run. A `run_now` result is delivered when it finishes: it is `late` only when it replaces a missed run (a `run_now` on a `missed` action, or `onMissed: "run"`), never for an ordinary early run.
 
 ---
+## Prompts
+
+The SDK's own prompts (the reasoning directive, tool refusals, worker reply headers, the manuals of the `subagents` and `scheduled_actions` tools) are plain `.md` files in `src/prompts/`, exported as `DEFAULT_PROMPTS`. `AgentConfig.prompts` replaces single ones for an agent and its workers; the rest keep their defaults. `{{name}}` marks values the SDK fills in.
+
+```ts
+import { Agent, DEFAULT_PROMPTS } from "agent-accelerator";
+
+const agent = new Agent({
+  model: "google/gemini-3.5-flash-lite",
+  prompts: { toolNotFound: "Unknown tool '{{tool}}'.{{suggestion}} Use only the tools you were given." },
+});
+```
+
+**Keeping the original prompt is recommended**: it is what the SDK is tested with, and `DEFAULT_PROMPTS` is the reference for writing your own. Names, placeholders and where each prompt appears: [the prompts guide](docs/guides/prompts.md).
+
 ## Tools
 
 ```ts
@@ -427,6 +444,7 @@ 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. `maxAttempts` is the canonical name for `maxTries` (number or numeric string). A positive value is the total attempt limit; `0`/omitted means 3 attempts for `idempotent` tools and 1 for all others. `maxConcurrency` limits simultaneous calls for that tool (default pool: 8).
+* `toolContent([...])` — a tool's return value of text and media (`return toolContent(["chart.png", { type: "image", image: bytes, mimeType: "image/png" }])`). The text is the result every provider sees; Google (Gemini 3 and later) also gets the media inside the function result, other providers warn once and get the text only. Only a value made by `toolContent` counts, so JSON fetched by a tool can never become media. See the tools guide.
 * `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`.
@@ -717,10 +735,24 @@ It also:
 * passes `service_tier` (`flex` | `priority`);
 * sends audio with its real format (`wav`, `mp3`, `aiff`, `aac`, `ogg`, `flac`, `m4a`) and QuickTime video as `video/mov`;
 * sends file parts as `file.file_data` (a public URL or a base64 data URL) and never adds a plugin: OpenRouter reads the file natively or with its own default parser;
-* maps `tool_choice` (`auto` omitted; `none`, `required`, and function pins supported);
+* maps `tool_choice` (`auto` omitted; `none`, `required`, and function pins supported; `validated` is Google-only and is dropped with one warning);
 * treats an error chunk inside a stream (HTTP 200) like an HTTP error: its status comes from the chunk's `code`, or from its `error_type` (`rate_limit_exceeded` 429, `provider_overloaded` 503, `provider_unavailable` 502, `timeout` 504, `server` 500), so `runRetries` retries the retryable ones;
 * reports `cached_tokens` / `cache_write_tokens` / reasoning tokens, preferring provider-reported `cost` when present (a reported `0`, a free model or a cache hit, stays a known `$0`);
-* accepts `anthropic/...` and `~anthropic/...` model names for the `5m` / `1h` cache setting.
+* accepts `anthropic/...` and `~anthropic/...` model names for the `5m` / `1h` cache setting;
+* sends a turn's `reasoning_details` blocks and parsed-PDF `file` annotations back on the next turns, exactly as OpenRouter returned them;
+* reads provider routing and a few request fields from env vars (see below), never from `AgentConfig`.
+
+**Env vars** (an Agent's own `env: { ... }` wins over `process.env`; nothing is sent for a variable that is not set; a bad value throws a `ConfigError` before any request):
+
+| Variable | Sent as |
+|---|---|
+| `OPENROUTER_ORDER`, `OPENROUTER_ONLY`, `OPENROUTER_IGNORE` | `provider.order` / `only` / `ignore` (comma-separated provider slugs) |
+| `OPENROUTER_ALLOW_FALLBACKS`, `OPENROUTER_REQUIRE_PARAMETERS`, `OPENROUTER_ZDR` | `provider.allow_fallbacks` / `require_parameters` / `zdr` (`true`/`false`/`1`/`0`) |
+| `OPENROUTER_DATA_COLLECTION` | `provider.data_collection` (`allow` or `deny`) |
+| `OPENROUTER_SORT` | `provider.sort` (`price`, `throughput` or `latency`) |
+| `OPENROUTER_PARALLEL_TOOL_CALLS` | `parallel_tool_calls` (only when the request has tools) |
+| `OPENROUTER_REASONING_EXCLUDE` | `reasoning.exclude` (the model reasons but the text is not returned) |
+| `OPENROUTER_USER` | `user` (a stable end-user id) |
 
 `serviceTier` values other than `flex` / `priority` are omitted (standard routing).
 
@@ -1021,6 +1053,8 @@ TokenUsage {
   cacheReadTokens?,
   cacheWriteTokens?,
   thinkingTokens?,
+  inputDetails?: { audioTokens?, videoTokens? },   // media part of inputTokens (OpenRouter), report only
+  outputDetails?: { audioTokens?, imageTokens? }, // media part of outputTokens (OpenRouter), report only
   cost?: {
     inputCost?,
     outputCost?,
@@ -1138,6 +1172,7 @@ The model catalog is synced from [models.dev](https://models.dev) into a local c
 
 - **Automated 12-hour validation**: `.run()`, `.ask()` and `.stream()` check `<home>/catalog/models.dev.json`. Within 12 hours it reads from disk with no network delay. After that the expired catalog is served immediately and refreshed from `https://models.dev/api.json` in the background (8 s timeout). Only a cold start, with nothing loaded yet, waits for the download. A failed refresh pauses automatic refreshes for 10 minutes.
 - **Git & Package Safety**: The cache lives in the single Agent Accelerator home (`<home>/catalog/models.dev.json`, `.agent-accel/` by default and gitignored), never inside the package or scattered in the project.
+- **Spending-cap defaults**: `configure({ usageLimit, scheduledActionBudget })` sets the two caps for every agent you build (one call at startup, like `setHome()`; each call replaces the last, `configure({})` clears it). The env vars `AGENT_ACCEL_USAGE_LIMIT_USD` / `_TOKENS` and `AGENT_ACCEL_SCHEDULED_BUDGET_USD` / `_TOKENS` do the same. Precedence, field by field: the Agent's own config, then `configure()`, then env, then no cap. Workers and scheduled runs built by the SDK never take them.
 - **Environment**: `setHome(dir)` / `AGENT_ACCEL_HOME` move the whole home; `AGENT_CACHE_DIR` moves only the cache (for read-only or serverless filesystems). `AGENT_CATALOG_REFRESH=off` disables automatic refreshes; `bun run update-models` and `refreshModelCatalog()` still work.
 
 ### Developer Catalog Controls
@@ -1275,7 +1310,7 @@ Supported content parts include:
 * `ToolResultPart { type:"tool_result", id, name, result, isError? }`
 * `ImagePart { type:"image", image, mimeType?, resolution? }`
 * `AudioPart { type:"audio", audio, mimeType? }`
-* `VideoPart { type:"video", video, mimeType?, resolution? }`
+* `VideoPart { type:"video", video, mimeType?, resolution?, processing? }`
 * `FilePart { type:"file", file, mimeType?, filename? }` — PDFs/documents.
 
 `image`, `audio`, `video`, and `file` inputs accept:
@@ -1321,6 +1356,16 @@ OpenRouter an image's `resolution` is sent as `image_url.detail` (`low` → `low
 downgrades to `high` where unsupported); a video's `resolution` is ignored. Other
 providers (and OpenRouter videos) ignore it with one `provider_warning`.
 
+`processing` (`VideoProcessing`: `"static" | "agentic"`) sets how Google reads one
+video. `"static"` (the default) puts frames taken at a fixed rate into the
+context. `"agentic"` lets the model explore the timeline and load only the
+transcript and frames the prompt needs, which suits long videos and
+needle-in-a-haystack questions (Google lists Gemini 4 Argon, 3.8 Flash, 3.6 Flash
+and 3.5 Flash Lite as supporting it; for any other model Google returns its own
+error). The model's `processing_call` / `processing_result` steps are kept and
+replayed with the rest of the turn's raw steps. Other providers ignore it with
+one `provider_warning`; an unknown value throws a `ValidationError`.
+
 Before any network call, the executor checks `image` / `audio` / `video` /
 `file`-as-PDF parts against the catalog's `modalities.input` for that
 provider/model and fails fast with a one-line error naming the gap
@@ -1462,7 +1507,8 @@ bun run update-models # refresh model catalog cache (supports --force, --ttl=24h
 ```text
 src/
 ├── agent/      # Agent, context, loop, delegation, subagent
-├── scheduler/  # Scheduled actions: clock, store, tool + its manual (scheduled-actions.md)
+├── scheduler/  # Scheduled actions: clock, store, tool
+├── prompts/    # The SDK's own prompts as .md files, DEFAULT_PROMPTS, AgentConfig.prompts
 ├── 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-accelerator",
-  "version": "0.6.0",
+  "version": "0.6.5",
   "description": "High-performance SDK for AI agents with a unified API across AI providers. Optimized for high cache hit rates, observability, and seamless agent orchestration. Built to power production-grade agentic systems and harnesses for teams at any scale.",
   "license": "MIT",
   "author": "Sashvat Bharat",

package/src/agent/agent.ts

@@ -28,14 +28,23 @@ import { AgentContext } from "./context.ts";
 import { resolveModel } from "../providers/registry.ts";
 import { buildAgentTools } from "./delegation.ts";
 import { createSubagentsTool } from "./subagents-tool.ts";
-import { WorkerRegistry } from "./workers.ts";
-import { DEFAULT_MAX_DEPTH, normalizeToolMap, resolveDynamicModelInput, resolveMainModel } from "./worker.ts";
+import { WorkerRegistry, savedSpend } from "./workers.ts";
+import {
+  DEFAULT_MAX_DEPTH,
+  isWorkerConfig,
+  normalizeToolMap,
+  resolveDynamicModelInput,
+  resolveMainModel,
+} from "./worker.ts";
 import * as path from "node:path";
-import { registerAgent } from "../scheduler/scheduler.ts";
+import { registerAgent, ScheduledActions } from "../scheduler/scheduler.ts";
 import { resolveHome } from "../utils/home.ts";
 import { persistTelemetry, registerSessionFolder, unregisterSessionFolder } from "../telemetry-file.ts";
 import { lockFolder } from "../utils/durable.ts";
 import { createScheduledActionsTool, getDatetimeTool } from "../scheduler/tool.ts";
+import { fillPrompt, resolvePrompts, type Prompts } from "../prompts/prompts.ts";
+import { UsageLimit, checkUsageLimitConfig } from "./usage-limit.ts";
+import { mergeCap } from "./defaults.ts";
 import { applyEditable, assertModelAllowed, modelKey, toEditableConfig } from "./config-blocks.ts";
 import { assertNoToolCollisions } from "../tools/executor.ts";
 import {
@@ -197,6 +206,8 @@ export class Agent {
   readonly description: string;
   /** Stable system instructions. */
   instructions: string;
+  /** The SDK prompts in use: the shipped defaults with `AgentConfig.prompts` applied. */
+  readonly prompts: Prompts;
   /** Original model string or catalog spec used for resolution. */
   readonly modelStringOrSpec: string | any;
   /** Configured dynamic sub-agent model, if enabled. */
@@ -217,6 +228,8 @@ export class Agent {
     maxDepth: number;
     /** Per-run spending cap of each worker (unset = unlimited). */
     workerBudget?: { maxCostUsd?: number; maxTotalTokens?: number };
+    /** Per-run spending cap of each scheduled-action run (unset = unlimited). */
+    scheduledActionBudget?: { maxCostUsd?: number; maxTotalTokens?: number };
   };
   /** Home folder for everything written to disk (`sessions/`, `scheduled/`, `telemetry/`). */
   readonly home: string;
@@ -324,6 +337,11 @@ export class Agent {
   /** The resume in flight, so a second `resume()` returns the same promise. */
   private resuming?: Promise<AgentResponse | undefined>;
   private workerRegistry?: WorkerRegistry;
+  /** The chat-wide spending cap this agent counts into and checks against: its own (`usageLimit`) or the root's, handed down to workers. @internal */
+  chat?: UsageLimit;
+  /** True for the agent that created `chat` from its own `usageLimit` (the root of the chat). */
+  private ownsChat = false;
+  private scheduledActions?: ScheduledActions;
 
   /**
    * Creates an agent and registers its model, tools, cache, and delegation settings.
@@ -349,6 +367,18 @@ export class Agent {
     this.description = config.description || "AI Agent powered by Agent Accelerator";
     // DX1: only instructions (no systemPrompt alias)
     this.instructions = config.instructions || "";
+    this.prompts = resolvePrompts(config.prompts);
+    // Workers and scheduled runs the SDK builds never take developer defaults (`configure()`, env vars).
+    const takesDefaults = !isWorkerConfig(config);
+    if (config.usageLimit !== undefined) {
+      const problem = checkUsageLimitConfig(config.usageLimit);
+      if (problem) throw new ConfigError(`[Agent Accelerator] Invalid usageLimit: ${problem}.`);
+    }
+    const chatCap = mergeCap("usageLimit", config.usageLimit, takesDefaults);
+    if (chatCap) {
+      this.chat = new UsageLimit(chatCap);
+      this.ownsChat = true;
+    }
     // Unified model resolution (shared with SubAgent/workers): supports
     // ModelProviderInstance {model,apiKey,...} and ModelSpec {id,provider}.
     const { modelStringOrSpec, rawModel } = resolveMainModel(config.model);
@@ -374,15 +404,25 @@ export class Agent {
           `[Agent Accelerator] Invalid dynamicSubagents.maxDepth ${JSON.stringify(rawDepth)}: expected a whole number >= 1, or omit it for no limit; set dynamicSubagents.enabled: false to turn workers off.`
         );
       }
-      const rawBudget = (dynRaw as { workerBudget?: { maxCostUsd?: unknown; maxTotalTokens?: unknown } }).workerBudget;
-      for (const key of ["maxCostUsd", "maxTotalTokens"] as const) {
-        const v = rawBudget?.[key];
-        if (v !== undefined && !(typeof v === "number" && Number.isFinite(v) && v > 0)) {
-          throw new ConfigError(
-            `[Agent Accelerator] Invalid dynamicSubagents.workerBudget.${key} ${JSON.stringify(v)}: expected a number greater than 0, or omit it for no limit.`
-          );
+      type RawBudget = { maxCostUsd?: unknown; maxTotalTokens?: unknown } | undefined;
+      const checkBudgetKeys = (name: "workerBudget" | "scheduledActionBudget"): RawBudget => {
+        const raw = (dynRaw as Record<string, RawBudget>)[name];
+        for (const key of ["maxCostUsd", "maxTotalTokens"] as const) {
+          const v = raw?.[key];
+          if (v !== undefined && !(typeof v === "number" && Number.isFinite(v) && v > 0)) {
+            throw new ConfigError(
+              `[Agent Accelerator] Invalid dynamicSubagents.${name}.${key} ${JSON.stringify(v)}: expected a number greater than 0, or omit it for no limit.`
+            );
+          }
         }
-      }
+        return raw;
+      };
+      const rawBudget = checkBudgetKeys("workerBudget");
+      const rawScheduledBudget = mergeCap(
+        "scheduledActionBudget",
+        checkBudgetKeys("scheduledActionBudget") as { maxCostUsd?: number; maxTotalTokens?: number } | undefined,
+        takesDefaults
+      );
       // Open workers are unlimited unless the developer sets a cap (a number >= 1; Infinity also means unlimited).
       const rawMax = (dynRaw as { maxSpawn?: unknown }).maxSpawn;
       if (rawMax !== undefined && (typeof rawMax !== "number" || Number.isNaN(rawMax))) {
@@ -416,6 +456,9 @@ export class Agent {
         allowScheduledActions: dynRaw.allowScheduledActions === true,
         maxDepth: (rawDepth as number | undefined) ?? DEFAULT_MAX_DEPTH,
         ...(rawBudget ? { workerBudget: { ...(rawBudget as { maxCostUsd?: number; maxTotalTokens?: number }) } } : {}),
+        ...(rawScheduledBudget
+          ? { scheduledActionBudget: { ...(rawScheduledBudget as { maxCostUsd?: number; maxTotalTokens?: number }) } }
+          : {}),
       };
     }
     this.apiKey = (rawModel as any)?.apiKey || config.apiKey;
@@ -519,7 +562,7 @@ export class Agent {
     }
 
     if (Array.isArray(config.subagents)) {
-      const subagentTools = buildAgentTools(config.subagents);
+      const subagentTools = buildAgentTools(config.subagents, { chat: this.chat });
       for (const [toolName, toolDef] of Object.entries(subagentTools)) {
         this.tools[toolName] = toolDef;
       }
@@ -559,6 +602,11 @@ export class Agent {
     return (this.workerRegistry ??= new WorkerRegistry(this));
   }
 
+  /** The scheduled actions of this agent's home: `create`, `list`, `update`, `run`, `skip`, `delete` (see `ScheduledActions`). */
+  get scheduled(): ScheduledActions {
+    return (this.scheduledActions ??= new ScheduledActions(this));
+  }
+
   // Takes the one-process lock of the folder this Agent persists to: its own session folder, or the folder of a single `persist.file`; throws ConfigError when another live process holds it; in: the constructor and importSession (a new session id is a new folder), out: a `.lock` file there.
   private lockSessionFolder(): void {
     const cfg = this.persistConfig;
@@ -621,15 +669,14 @@ export class Agent {
   // Puts saved spending totals back after a restart or import (zeros when the file has none); in: a loaded session's `usage`, out: this.usageTotals.
   private restoreUsage(saved: unknown): void {
     Object.assign(this.usageTotals, readUsage(saved));
+    if (this.ownsChat) this.chat!.restart(); // a restored session changes the starting point of the chat total
   }
 
   // Records one model call of THIS agent (priced per turn, with the service tier); in: the loop's onTurnUsage, out: this.usageTotals (saved by the next persist).
   private recordTurnUsage(usage: TokenUsage, spec: Parameters<typeof priceUsage>[1]): void {
-    addTurn(
-      this.usageTotals,
-      usage,
-      priceUsage(usage, spec, this.serviceTier ? { serviceTier: this.serviceTier } : undefined)
-    );
+    const priced = priceUsage(usage, spec, this.serviceTier ? { serviceTier: this.serviceTier } : undefined);
+    addTurn(this.usageTotals, usage, priced);
+    this.chat?.add((usage.inputTokens || 0) + (usage.outputTokens || 0), priced?.breakdown.totalMicroUSD ?? 0);
   }
 
   /** Adds another agent's spending to this one (a fixed worker's per-call copy into its template). @internal */
@@ -738,6 +785,7 @@ export class Agent {
           result: t.result,
           ...(t.isError ? { isError: true } : {}),
           ...(t.stopped ? { stopped: true } : {}),
+          ...(t.parts && t.parts.length > 0 ? { parts: t.parts } : {}),
         } as ToolResultRecord,
       ])
     );
@@ -759,6 +807,7 @@ export class Agent {
       result: isSubagentResult(result.result) ? result.result.xml : result.result,
       ...(result.isError ? { isError: true } : {}),
       ...(result.stopped ? { stopped: true } : {}),
+      ...(result.parts && result.parts.length > 0 ? { parts: result.parts } : {}),
     });
     this.doPersist();
   }
@@ -769,12 +818,8 @@ export class Agent {
     let out = base;
     const isThinkingEnabled =
       this.thinkingConfig?.enabled !== false && this.thinkingConfig?.level && this.thinkingConfig?.level !== "none";
-    if (isThinkingEnabled && !out.includes("[Reasoning Directive]")) {
-      const guidance =
-        "[Reasoning Directive]\n" +
-        "1. Use internal reasoning strictly for private planning and step-by-step thinking.\n" +
-        "2. Never attempt to execute tools or output final user deliverables inside reasoning.\n" +
-        "3. Once your reasoning is complete, output your final response or function calls directly in the standard response output.";
+    const guidance = this.prompts.reasoningDirective;
+    if (isThinkingEnabled && !out.includes(guidance)) {
       out = out ? `${out}\n\n${guidance}` : guidance;
     }
     return out || undefined;
@@ -1299,6 +1344,7 @@ export class Agent {
     const d = this.callDefaults;
     return {
       limits: { ...this.runLimits },
+      ...(this.forkConfig.prompts ? { prompts: { ...this.forkConfig.prompts } } : {}),
       ...(d.retry ? { retry: d.retry } : {}),
       ...(d.env ? { env: d.env } : {}),
       ...(d.fetch ? { fetch: d.fetch } : {}),
@@ -1350,13 +1396,34 @@ export class Agent {
     return new Agent(applyEditable(editable, base));
   }
 
+  // Takes the chat total's starting point (what the saved sessions of this agent and its workers already spent) once, before the first turn of the chat's root agent; in: the run starters, out: this.chat.
+  private beginChat(): void {
+    if (!this.ownsChat) return;
+    this.chat!.begin(() => {
+      // A persisted chat starts from its saved sessions (this agent's and every worker's); a memory-only one from what it holds now.
+      const root = this.persistConfig?.dir;
+      if (root && !this.stateless) {
+        try {
+          const saved = savedSpend(sessionDirFor(root, this.sessionId));
+          return { tokens: saved.inputTokens + saved.outputTokens, microUSD: saved.costMicroUSD.total };
+        } catch {
+          // not a usable session folder name: nothing was saved there
+        }
+      }
+      const total = this.usageReport().total;
+      return { tokens: total.tokens.total, microUSD: Math.round((total.cost.totalUsd ?? 0) * 1_000_000) };
+    });
+  }
+
   /** Budgets are per run: counters restart whenever a new run begins. */
   private resetBudgetState(): void {
+    this.beginChat();
     if (this.budget) this.budgetState = { spawned: 0, totalTokens: 0, totalCostUsd: 0, startedAtMs: nowMs() };
   }
 
   /** Loop hook: charge `usage` (when given) and throw `BudgetExceededError` once any cap is passed. */
   private enforceBudget(usage?: TokenUsage): void {
+    this.chat?.check(); // the chat-wide cap: before every turn and right after each one
     if (!this.budget) return;
     if (usage) chargeBudgetUsage(this as unknown as Parameters<typeof chargeBudgetUsage>[0], usage);
     checkBudget(this.budget, this.budgetState);
@@ -1390,6 +1457,7 @@ export class Agent {
       serviceTier: this.serviceTier,
       sessionId,
       ...(this.outputSpec ? { output: this.outputSpec } : {}),
+      prompts: { structuredOutput: this.prompts.structuredOutput, toolBridge: this.prompts.toolBridge },
       ...(this.googleTier ? { googleTier: this.googleTier } : {}),
       ...(toolChoice !== undefined ? { toolChoice } : {}),
       ...(maxOutputTokens !== undefined ? { maxOutputTokens } : {}),
@@ -1447,7 +1515,7 @@ export class Agent {
         ...(this.fileAccess ? { fileAccess: this.fileAccess } : {}),
         onFailure: this.onFailure,
         ...(this.captureRaw !== undefined ? { captureRaw: this.captureRaw } : {}),
-        ...(this.budget ? { enforceBudget: (u?: TokenUsage) => this.enforceBudget(u) } : {}),
+        ...(this.budget || this.chat ? { enforceBudget: (u?: TokenUsage) => this.enforceBudget(u) } : {}),
         onProgress: () => this.persistNow(),
         onTurnUsage: (u: TokenUsage, spec: Parameters<typeof priceUsage>[1]) => this.recordTurnUsage(u, spec),
         onToolResult: (r: ToolResultRecord) => this.recordTool(r),
@@ -1457,6 +1525,7 @@ export class Agent {
         onSteerInjected: () => this.persistNow(),
         // Loop enforces these (plus local timeout races).
         limits: { ...this.runLimits },
+        prompts: this.prompts,
         ...(this.output !== undefined ? { output: this.output } : {}),
       };
 
@@ -1543,7 +1612,7 @@ export class Agent {
       ...(this.fileAccess ? { fileAccess: this.fileAccess } : {}),
       onFailure: this.onFailure,
       ...(this.captureRaw !== undefined ? { captureRaw: this.captureRaw } : {}),
-      ...(this.budget ? { enforceBudget: (u?: TokenUsage) => this.enforceBudget(u) } : {}),
+      ...(this.budget || this.chat ? { enforceBudget: (u?: TokenUsage) => this.enforceBudget(u) } : {}),
       onProgress: () => this.persistNow(),
       onTurnUsage: (u: TokenUsage, spec: Parameters<typeof priceUsage>[1]) => this.recordTurnUsage(u, spec),
       onToolResult: (r: ToolResultRecord) => this.recordTool(r),
@@ -1552,6 +1621,7 @@ export class Agent {
       onSteerInjected: () => this.persistNow(),
       // Loop enforces these (plus local timeout races).
       limits: { ...this.runLimits },
+      prompts: this.prompts,
       ...(this.output !== undefined ? { output: this.output } : {}),
     };
 
@@ -1898,7 +1968,7 @@ export class Agent {
     if (options?.additionalContext) {
       // Preserve stable instructions as systemPrompt
       ctx.systemPrompt = fullInstructions;
-      const prefix = `[Additional Context]\n${options.additionalContext}\n\n`;
+      const prefix = `${fillPrompt(this.prompts.additionalContext, { context: options.additionalContext })}\n\n`;
       if (typeof prompt === "string") {
         prompt = prefix + prompt;
       } else if (Array.isArray(prompt)) {

package/src/agent/architecture.md

@@ -2,18 +2,20 @@
 
 The agent and everything that runs under it.
 
-| File                                 | What it is                                                                                                                                                                               | Used by                      |
-| :----------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------- |
-| `agent.ts`                           | `Agent`: `run`/`stream`/`ask`, `steer`/`queue`/`interrupt`, persistence hooks, `resume()`/`interrupted()`, `usageReport()`, `fork()`, `toConfig()`/`fromConfig()`, the `workers` getter. | callers, workers, scheduler  |
-| `loop.ts`                            | `runAgentLoop` / `streamAgentLoop`: per turn budget, pairing repair, file access, provider call, tool execution, repeat guard. Also `ensureToolPairing`, `accumulateUsage`.              | `Agent`                      |
-| `context.ts`                         | `AgentContext`: the validated message list with checkpoint/rollback.                                                                                                                     | `Agent`, loops               |
-| `delegation.ts`                      | Fixed workers (`agentToTool`, `buildAgentTools`), the live worker trace store, session-id helpers, budget helpers, `openWorkerTrace`/`workerMetadata`.                                   | `Agent`, `workers.ts`        |
-| `worker.ts`                          | Worker core: model/tool normalization, `buildDynamicWorkerConfig` (shared preset), `createLiveWorker`.                                                                                   | `Agent`, registry, scheduler |
-| `workers.ts`                         | `WorkerRegistry` (`agent.workers`): persistent multi-turn workers.                                                                                                                       | `Agent`, `subagents` tool    |
-| `subagents-tool.ts` + `subagents.md` | The one model-facing `subagents` tool; the `.md` is its description.                                                                                                                     | `Agent` constructor          |
-| `subagent.ts`                        | `SubAgent` class and `agentFromEnv` (thin, kept for compatibility).                                                                                                                      | callers                      |
-| `turns.ts`                           | Pure grouping of messages into finished turns (history cut for workers).                                                                                                                 | `workers.ts`                 |
-| `config-blocks.ts`                   | RSI blocks: only `model`, `instructions`, `tools` are editable; `allowedModels` check.                                                                                                   | `Agent`                      |
+| File                | What it is                                                                                                                                                                                                                              | Used by                                |
+| :------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------- |
+| `agent.ts`          | `Agent`: `run`/`stream`/`ask`, `steer`/`queue`/`interrupt`, persistence hooks, `resume()`/`interrupted()`, `usageReport()`, `fork()`, `toConfig()`/`fromConfig()`, the `workers` getter.                                                | callers, workers, scheduler            |
+| `loop.ts`           | `runAgentLoop` / `streamAgentLoop`: per turn budget, pairing repair, file access, provider call, tool execution, repeat guard. Also `ensureToolPairing`, `accumulateUsage`.                                                             | `Agent`                                |
+| `context.ts`        | `AgentContext`: the validated message list with checkpoint/rollback.                                                                                                                                                                    | `Agent`, loops                         |
+| `delegation.ts`     | Fixed workers (`agentToTool`, `buildAgentTools`), the live worker trace store, session-id helpers, budget helpers, `openWorkerTrace`/`workerMetadata`.                                                                                  | `Agent`, `workers.ts`                  |
+| `worker.ts`         | Worker core: model/tool normalization, `buildDynamicWorkerConfig` (shared preset), `createLiveWorker`.                                                                                                                                  | `Agent`, registry, scheduler           |
+| `workers.ts`        | `WorkerRegistry` (`agent.workers`): persistent multi-turn workers.                                                                                                                                                                      | `Agent`, `subagents` tool              |
+| `subagents-tool.ts` | The one model-facing `subagents` tool; its description is the `subagentsTool` prompt (`../prompts/subagents-tool.md`).                                                                                                                  | `Agent` constructor                    |
+| `subagent.ts`       | `SubAgent` class and `agentFromEnv` (thin, kept for compatibility).                                                                                                                                                                     | callers                                |
+| `turns.ts`          | Pure grouping of messages into finished turns (history cut for workers).                                                                                                                                                                | `workers.ts`                           |
+| `defaults.ts`       | `configure()` and the `AGENT_ACCEL_*` env vars: developer defaults for `usageLimit` and `dynamicSubagents.scheduledActionBudget`, per field (Agent config > `configure()` > env). SDK-built workers never take them (`isWorkerConfig`). | `Agent`, barrel                        |
+| `usage-limit.ts`    | `UsageLimit`: the chat-wide cap (`AgentConfig.usageLimit`). The root agent owns it, registry and fixed workers share it (`agent.chat`); every model turn adds to it and is checked against it.                                          | `Agent`, `workers.ts`, `delegation.ts` |
+| `config-blocks.ts`  | RSI blocks: only `model`, `instructions`, `tools` are editable; `allowedModels` check.                                                                                                                                                  | `Agent`                                |
 
 ## Invariants
 
@@ -23,5 +25,6 @@ The agent and everything that runs under it.
 - A worker is never less constrained than its parent (`inheritableConfig()`); its children draw only from the tools it was granted.
 - Exactly-once worker calls rest on the call key (parent run mark id + tool call id) and `meta.last`.
 - Only results branded by `makeSubagentResult` have their usage metadata trusted.
+- A chat-wide cap (`usageLimit`) counts every model turn of the root and of all workers through one shared `UsageLimit`; its starting point is read once per process from the saved sessions. Scheduled workers never get it.
 - Each Agent records only its own model turns; never sum `AgentResponse.usage` for totals.
 - `reset()` clears the conversation (messages, run marks, the run's saved tool results) but never the spending totals.

package/src/agent/context.ts

@@ -143,6 +143,7 @@ export class AgentContext {
             isError: res.isError,
             ...(res.logFile ? { logFile: res.logFile } : {}),
             ...(res.stopped ? { stopped: true } : {}),
+            ...(res.parts && res.parts.length > 0 ? { parts: res.parts } : {}),
           },
         ],
       });

package/src/agent/defaults.ts

@@ -0,0 +1,88 @@
+/**
+ * Developer defaults for the spending caps, set in code (`configure()`) or through env vars, so one place can cap every
+ * agent of a program. Precedence, per field (`maxCostUsd`, `maxTotalTokens`): the Agent's own config, then `configure()`,
+ * then the env var, then no cap. Only agents YOU construct take defaults: the workers and scheduled runs the SDK builds
+ * itself never do (a chat worker joins its parent's cap; a scheduled run has its own).
+ */
+import { ConfigError } from "../types/errors.ts";
+import { getEnv } from "../utils/env.ts";
+import { checkUsageLimitConfig, type UsageLimitConfig } from "./usage-limit.ts";
+
+/** What `configure()` can set; every key is optional and has the same meaning as the Agent option of the same name. */
+export interface AgentDefaults {
+  /** Default for `AgentConfig.usageLimit` (the chat-wide cap). Env: `AGENT_ACCEL_USAGE_LIMIT_USD`, `AGENT_ACCEL_USAGE_LIMIT_TOKENS`. */
+  usageLimit?: UsageLimitConfig;
+  /** Default for `dynamicSubagents.scheduledActionBudget`. Env: `AGENT_ACCEL_SCHEDULED_BUDGET_USD`, `AGENT_ACCEL_SCHEDULED_BUDGET_TOKENS`. */
+  scheduledActionBudget?: UsageLimitConfig;
+}
+
+type CapName = keyof AgentDefaults;
+
+const ENV: Record<CapName, { maxCostUsd: string; maxTotalTokens: string }> = {
+  usageLimit: { maxCostUsd: "AGENT_ACCEL_USAGE_LIMIT_USD", maxTotalTokens: "AGENT_ACCEL_USAGE_LIMIT_TOKENS" },
+  scheduledActionBudget: {
+    maxCostUsd: "AGENT_ACCEL_SCHEDULED_BUDGET_USD",
+    maxTotalTokens: "AGENT_ACCEL_SCHEDULED_BUDGET_TOKENS",
+  },
+};
+
+let configured: AgentDefaults = {};
+
+/**
+ * Sets developer defaults for the spending caps; call it once at startup, like `setHome()`. It REPLACES what an earlier
+ * call set (`configure({})` clears it). A key an Agent sets itself wins, field by field; env vars are the fallback.
+ * Throws a `ConfigError` for a value that is not a number above 0.
+ *
+ * @example `configure({ usageLimit: { maxCostUsd: 5 }, scheduledActionBudget: { maxCostUsd: 0.5 } });`
+ */
+export function configure(defaults: AgentDefaults = {}): void {
+  if (!defaults || typeof defaults !== "object" || Array.isArray(defaults)) {
+    throw new ConfigError("[Agent Accelerator] configure() expects an object like { usageLimit: { maxCostUsd: 5 } }.");
+  }
+  for (const key of Object.keys(defaults)) {
+    if (!(key in ENV)) {
+      throw new ConfigError(
+        `[Agent Accelerator] configure(): unknown setting "${key}" (known: ${Object.keys(ENV).join(", ")}).`
+      );
+    }
+    const value = (defaults as Record<string, unknown>)[key];
+    if (value === undefined) continue;
+    const problem = checkUsageLimitConfig(value);
+    if (problem) throw new ConfigError(`[Agent Accelerator] configure(): invalid ${key}: ${problem}.`);
+  }
+  configured = Object.fromEntries(
+    Object.entries(defaults)
+      .filter(([, v]) => v !== undefined)
+      .map(([k, v]) => [k, { ...(v as UsageLimitConfig) }])
+  ) as AgentDefaults;
+}
+
+// Reads one cap field from its env var: undefined when unset, a ConfigError naming the variable when it is not a number above 0; in: mergeCap, out: the value.
+function fromEnv(variable: string): number | undefined {
+  const raw = getEnv(variable);
+  if (raw === undefined) return undefined;
+  const n = Number(raw);
+  if (!(Number.isFinite(n) && n > 0)) {
+    throw new ConfigError(
+      `[Agent Accelerator] Invalid ${variable} ${JSON.stringify(raw)}: expected a number greater than 0.`
+    );
+  }
+  return n;
+}
+
+/** The cap an Agent uses: its own value, field by field over `configure()` over the env vars; undefined when nothing sets one. `withDefaults: false` ignores `configure()` and the env (SDK-built workers). */
+export function mergeCap(
+  name: CapName,
+  own: UsageLimitConfig | undefined,
+  withDefaults: boolean
+): UsageLimitConfig | undefined {
+  const base = withDefaults ? configured[name] : undefined;
+  const maxCostUsd = own?.maxCostUsd ?? base?.maxCostUsd ?? (withDefaults ? fromEnv(ENV[name].maxCostUsd) : undefined);
+  const maxTotalTokens =
+    own?.maxTotalTokens ?? base?.maxTotalTokens ?? (withDefaults ? fromEnv(ENV[name].maxTotalTokens) : undefined);
+  if (maxCostUsd === undefined && maxTotalTokens === undefined) return undefined;
+  return {
+    ...(maxCostUsd !== undefined ? { maxCostUsd } : {}),
+    ...(maxTotalTokens !== undefined ? { maxTotalTokens } : {}),
+  };
+}