agent-accelerator 0.6.0 → 0.6.6

package/src/agent/architecture.md

@@ -2,26 +2,32 @@
 
 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            |
+| `run-control.ts`    | `RunControl`: the active run, the waiting queue and the machinery behind `steer`/`queue`/`interrupt` (`pumpQueue`, `finishCurrentRun`, urgent queueing). `Agent` keeps the public methods and calls it.                                 | `Agent`                                |
+| `options.ts`        | `buildProviderOptions` (agent config + per-run options in one place), `resolveAgentLimits`, `normalizeThinking`, `resolveEffectiveThinking`, `normalizeToolChoiceOption`.                                                               | `Agent`, barrel                        |
+| `named-sessions.ts` | `NamedSessions`: the in-memory contexts of `run(..., { sessionId })` (LRU 100, 1 h idle TTL).                                                                                                                                           | `Agent`                                |
+| `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
 
-- `runAgentLoop` and `streamAgentLoop` duplicate their turn logic: every loop change goes into both.
+- `runAgentLoop` and `streamAgentLoop` still duplicate the shape of a turn, but the repeated parts live once in helpers at the top of `loop.ts` (`buildTurnOptions`, `promoteThinkingIfAllowed`, `recordModelTurn`, `emitThinkingTrace`, `rollUpToolResults`, `partialProgress`, `newTurnUsage`): change those there, and any change to the turn order itself goes into both loops.
 - An `Agent` runs one thing at a time; delegation forks a copy per call so parallel calls never queue.
 - A worker is a plain `Agent` with a parent link and presets. Never duplicate logic between Agent and worker.
 - 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 } : {}),
+  };
+}

package/src/agent/delegation.ts

@@ -15,6 +15,7 @@ import { nowMs } from "../utils/session.ts";
 import { newRunId } from "../utils/session.ts";
 import { newTurnId } from "../utils/session.ts";
 import { sanitizeToolName, createLiveWorker } from "./worker.ts";
+import type { UsageLimit } from "./usage-limit.ts";
 
 /** Builds a random child session id that fits the 64-char provider limit, embedding a hash of the parent when it must be cut; in: a parent id + tag from scheduled runs, out: the worker's session id. */
 export function createChildSessionId(parentId: string, tag: string): string {
@@ -631,7 +632,7 @@ export interface AgentAsToolTarget {
  *
  * @example `const researchTool = researcher.asTool("research");`
  */
-export function agentToTool(input: Agent | AgentAsToolTarget): ToolDefinition {
+export function agentToTool(input: Agent | AgentAsToolTarget, opts?: { chat?: UsageLimit }): ToolDefinition {
   const agentInstance = "agent" in input ? input.agent : input;
   const rawName =
     ("name" in input && (input as any).name) ||
@@ -679,6 +680,7 @@ export function agentToTool(input: Agent | AgentAsToolTarget): ToolDefinition {
           typeof (agentInstance as Agent).fork === "function"
             ? agentInstance.fork(subSessionId, parentSessionId)
             : agentInstance;
+        if (worker !== agentInstance && opts?.chat) worker.chat = opts.chat; // this call counts into the parent chat's cap
         const workerStream = worker.stream(task, {
           signal: ctx?.signal,
           sessionId: subSessionId,
@@ -729,12 +731,15 @@ export function agentToTool(input: Agent | AgentAsToolTarget): ToolDefinition {
  *
  * @example `const tools = buildAgentTools([researcher, reviewer]);`
  */
-export function buildAgentTools(agents?: (Agent | AgentAsToolTarget)[]): Record<string, ToolDefinition> {
+export function buildAgentTools(
+  agents?: (Agent | AgentAsToolTarget)[],
+  opts?: { chat?: UsageLimit }
+): Record<string, ToolDefinition> {
   if (!agents || agents.length === 0) return {};
 
   const tools: Record<string, ToolDefinition> = {};
   for (const item of agents) {
-    const t = agentToTool(item);
+    const t = agentToTool(item, opts);
     if (t.name) {
       let finalName = t.name;
       let n = 1;