agent-accelerator 0.5.9 → 0.6.5

package/src/agent/subagent.ts

@@ -16,9 +16,7 @@ export interface SubAgentConfig extends AgentConfig {}
  * `Agent.fromEnv()` (attached below without touching `agent.ts`, owned by
  * another audit lane) delegates here.
  */
-export function agentFromEnv(
-  config?: Omit<AgentConfig, "model"> & { model?: AgentConfig["model"] }
-): Agent {
+export function agentFromEnv(config?: Omit<AgentConfig, "model"> & { model?: AgentConfig["model"] }): Agent {
   return new Agent({
     ...config,
     model: config?.model ?? getModel() ?? getSubModel(),

package/src/agent/subagents-tool.ts

@@ -1,9 +1,8 @@
 /**
  * The model-facing `subagents` tool: one flat tool with a `command` field (`spawn | message | close | list`), a thin
- * wrapper over `agent.workers`. The tool manual lives in `subagents.md`, not in code. Results are plain text with one
+ * wrapper over `agent.workers`. The tool manual lives in `src/prompts/subagents-tool.md`, not in code. Results are plain text with one
  * header line naming the worker; the branded envelope under them carries usage and lineage to the loop.
  */
-import { readFileSync } from "node:fs";
 import { z } from "zod";
 import type { Agent } from "./agent.ts";
 import { tool } from "../tools/tool.ts";
@@ -11,18 +10,15 @@ import { makeSubagentResult } from "../tools/subagent-result.ts";
 import { ValidationError } from "../types/errors.ts";
 import type { ToolDefinition } from "../types/tool.ts";
 import type { WorkerReply } from "./workers.ts";
+import { fillPrompt, type Prompts } from "../prompts/prompts.ts";
 
 const COMMANDS = ["spawn", "message", "close", "list"] as const;
 
-let manual: string | undefined;
-/** Read on first use (not at import), so a program that never enables workers never touches the file. */
-function loadManual(): string {
-  return (manual ??= readFileSync(new URL("./subagents.md", import.meta.url), "utf8"));
-}
-
 // One worker reply as the model sees it: a header line naming the worker, then its text; in: a WorkerReply, out: the branded result.
-function asResult(reply: WorkerReply): ReturnType<typeof makeSubagentResult> {
-  const text = reply.error ? `[worker ${reply.id}] failed: ${reply.error}` : `[worker ${reply.id}] replied:\n${reply.text}`;
+function asResult(reply: WorkerReply, prompts: Prompts): ReturnType<typeof makeSubagentResult> {
+  const text = reply.error
+    ? fillPrompt(prompts.workerFailed, { id: reply.id, reason: reply.error })
+    : fillPrompt(prompts.workerReplied, { id: reply.id, text: reply.text });
   return makeSubagentResult(text, [reply.metadata]);
 }
 
@@ -32,9 +28,12 @@ export function createSubagentsTool(agent: Agent): ToolDefinition {
   const max = agent.dynamicSubagents?.maxSpawn ?? Infinity;
   return tool({
     name: "subagents",
-    description: loadManual()
-      .replace("{{LIMIT}}", Number.isFinite(max) ? `You can have at most ${max} open workers. Close the ones you are done with.` : "There is no limit on open workers. Close the ones you are done with: each one keeps its whole conversation.")
-      .replace("{{TOOLS}}", poolNames.length > 0 ? poolNames.join(", ") : "none (omit tools)"),
+    description: fillPrompt(agent.prompts.subagentsTool, {
+      LIMIT: Number.isFinite(max)
+        ? `You can have at most ${max} open workers. Close the ones you are done with.`
+        : "There is no limit on open workers. Close the ones you are done with: each one keeps its whole conversation.",
+      TOOLS: poolNames.length > 0 ? poolNames.join(", ") : "none (omit tools)",
+    }),
     input: z.object({
       command: z.enum(COMMANDS),
       id: z.string().optional().describe("The worker's full id (message, close)."),
@@ -42,15 +41,28 @@ export function createSubagentsTool(agent: Agent): ToolDefinition {
       role: z.string().optional().describe("Short persona for the worker (spawn)."),
       instructions: z.string().optional().describe("The worker's own system prompt (spawn)."),
       task: z.string().optional().describe("The assignment (spawn) or the next message to the worker (message)."),
-      tools: z.array(z.string()).optional().describe(`Worker tools to grant, from: ${poolNames.join(", ") || "none"} (spawn).`),
-      history: z.number().int().min(0).optional().describe("How many of the first finished turns of this conversation to copy into the worker; 0 or omitted = none (spawn)."),
+      tools: z
+        .array(z.string())
+        .optional()
+        .describe(`Worker tools to grant, from: ${poolNames.join(", ") || "none"} (spawn).`),
+      history: z
+        .number()
+        .int()
+        .min(0)
+        .optional()
+        .describe(
+          "How many of the first finished turns of this conversation to copy into the worker; 0 or omitted = none (spawn)."
+        ),
     }),
     execute: async (a, ctx) => {
       const opts = { signal: ctx.signal, callId: ctx.toolCallId, onSubagentEvent: ctx.onSubagentEvent };
       const need = (field: "id" | "name" | "task"): string => {
         const value = a[field];
         if (!value?.trim()) {
-          const example = a.command === "spawn" ? { command: "spawn", name: "researcher", task: "Do the work." } : { command: a.command, id: "researcher-1a2b3c4d", task: "Next question." };
+          const example =
+            a.command === "spawn"
+              ? { command: "spawn", name: "researcher", task: "Do the work." }
+              : { command: a.command, id: "researcher-1a2b3c4d", task: "Next question." };
           throw new ValidationError(`${a.command} needs "${field}". Example: ${JSON.stringify(example)}`);
         }
         return value;
@@ -59,10 +71,21 @@ export function createSubagentsTool(agent: Agent): ToolDefinition {
         switch (a.command) {
           case "spawn":
             return asResult(
-              await agent.workers.spawn({ name: need("name"), role: a.role, instructions: a.instructions, task: need("task"), tools: a.tools, history: a.history }, opts)
+              await agent.workers.spawn(
+                {
+                  name: need("name"),
+                  role: a.role,
+                  instructions: a.instructions,
+                  task: need("task"),
+                  tools: a.tools,
+                  history: a.history,
+                },
+                opts
+              ),
+              agent.prompts
             );
           case "message":
-            return asResult(await agent.workers.message(need("id"), need("task"), opts));
+            return asResult(await agent.workers.message(need("id"), need("task"), opts), agent.prompts);
           case "close":
             return `Worker ${agent.workers.close(need("id")).id} closed.`;
           case "list":
@@ -81,7 +104,15 @@ export function createSubagentsTool(agent: Agent): ToolDefinition {
 function describeWorkers(agent: Agent): string {
   const workers = agent.workers.list();
   const turns = agent.workers.turns();
-  const open = workers.length === 0 ? "none" : workers.map((w) => `- ${w.id} (${w.name}${w.role ? `, ${w.role}` : ""}) tools: ${w.tools.join(", ") || "none"}${w.busy ? " [busy]" : ""}`).join("\n");
+  const open =
+    workers.length === 0
+      ? "none"
+      : workers
+          .map(
+            (w) =>
+              `- ${w.id} (${w.name}${w.role ? `, ${w.role}` : ""}) tools: ${w.tools.join(", ") || "none"}${w.busy ? " [busy]" : ""}`
+          )
+          .join("\n");
   const copyable = turns.length === 0 ? "none yet" : turns.map((t) => `${t.n}. ${t.prompt}`).join("\n");
   return `Open workers:\n${open}\n\nFinished turns of this conversation (history: N copies turns 1 to N):\n${copyable}`;
 }

package/src/agent/turns.ts

@@ -53,7 +53,9 @@ export function historyUpTo(messages: Message[], marks: SessionRunMark[], n: num
     );
   }
   if (n === 0) return [];
-  const first = marks.filter((m) => m.i >= 0 && m.i < messages.length).reduce((lo, m) => Math.min(lo, m.i), messages.length);
+  const first = marks
+    .filter((m) => m.i >= 0 && m.i < messages.length)
+    .reduce((lo, m) => Math.min(lo, m.i), messages.length);
   const kept = [...messages.slice(0, first)];
   for (const turn of turns.slice(0, n)) kept.push(...messages.slice(turn.from, turn.to));
   return deepCloneValue(kept);

package/src/agent/usage-limit.ts

@@ -0,0 +1,92 @@
+/**
+ * The chat-wide spending cap (`AgentConfig.usageLimit`). One `UsageLimit` belongs to the root agent of a chat and is
+ * handed to every agent below it (registry workers at any depth, fixed `subagents` workers), so each model turn of the
+ * whole tree adds to one running total and every turn is checked before it starts. The total survives a restart: the
+ * first run rebuilds the starting point from the saved sessions of the agent and its workers (`usageReport()`), after
+ * which only new turns are added. Scheduled actions are separate and never count.
+ */
+import { BudgetExceededError } from "../types/errors.ts";
+
+/** What the cap is made of; either part may be set, the first one reached stops the chat. */
+export interface UsageLimitConfig {
+  maxCostUsd?: number;
+  maxTotalTokens?: number;
+}
+
+/** A one-line problem with a `usageLimit` value, or undefined when it is valid; in: the Agent constructor, out: its ConfigError. */
+export function checkUsageLimitConfig(raw: unknown): string | undefined {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw))
+    return "expected an object like { maxCostUsd, maxTotalTokens }";
+  const r = raw as Record<string, unknown>;
+  const keys = Object.keys(r).filter((k) => r[k] !== undefined);
+  if (keys.length === 0) return "set maxCostUsd, maxTotalTokens or both";
+  for (const k of keys) {
+    if (k !== "maxCostUsd" && k !== "maxTotalTokens") return `unknown key "${k}" (use maxCostUsd or maxTotalTokens)`;
+    const v = r[k];
+    if (!(typeof v === "number" && Number.isFinite(v) && v > 0)) return `${k} must be a number greater than 0`;
+  }
+  return undefined;
+}
+
+/** The running total of one chat and its limit. */
+export class UsageLimit {
+  private baseTokens = 0;
+  private baseMicroUSD = 0;
+  private addedTokens = 0;
+  private addedMicroUSD = 0;
+  private started = false;
+
+  constructor(readonly limit: UsageLimitConfig) {}
+
+  /** Takes the starting point (what the chat spent before this process) once; later calls do nothing until `restart()`. */
+  begin(startingPoint: () => { tokens: number; microUSD: number }): void {
+    if (this.started) return;
+    this.started = true;
+    const s = startingPoint();
+    this.baseTokens = s.tokens;
+    this.baseMicroUSD = s.microUSD;
+    this.addedTokens = 0;
+    this.addedMicroUSD = 0;
+  }
+
+  /** Forgets the total (a session was imported over this agent): the next `begin` takes a new starting point. */
+  restart(): void {
+    this.started = false;
+  }
+
+  /** Adds one model turn of any agent in the chat. Unpriced turns add tokens only (unknown pricing is never a made-up $0 of cost). */
+  add(tokens: number, microUSD: number): void {
+    this.addedTokens += tokens;
+    this.addedMicroUSD += microUSD;
+  }
+
+  /** What the chat has spent so far. */
+  spent(): { tokens: number; costUsd: number } {
+    return {
+      tokens: this.baseTokens + this.addedTokens,
+      costUsd: (this.baseMicroUSD + this.addedMicroUSD) / 1_000_000,
+    };
+  }
+
+  /** Throws a `BudgetExceededError` ("Usage limit reached") once the chat has spent its whole limit. */
+  check(): void {
+    const { tokens, costUsd } = this.spent();
+    const { maxCostUsd, maxTotalTokens } = this.limit;
+    const byCost = maxCostUsd !== undefined && costUsd >= maxCostUsd;
+    const byTokens = maxTotalTokens !== undefined && tokens >= maxTotalTokens;
+    if (!byCost && !byTokens) return;
+    const parts = [
+      ...(maxCostUsd !== undefined ? [`$${costUsd.toFixed(6)} of $${maxCostUsd}`] : []),
+      ...(maxTotalTokens !== undefined ? [`${tokens} of ${maxTotalTokens} tokens`] : []),
+    ];
+    throw new BudgetExceededError(
+      `[Agent Accelerator] Usage limit reached: ${parts.join(", ")} spent by this chat (the agent and all its workers).`,
+      {
+        context: {
+          limit: "usageLimit",
+          partial: { usage: { inputTokens: 0, outputTokens: 0, totalTokens: tokens }, turns: 0 },
+        },
+      }
+    );
+  }
+}

package/src/agent/worker.ts

@@ -30,14 +30,23 @@ export interface LiveWorkerTrace {
 export function sanitizeXmlTag(raw: string): string {
   let s = raw.toUpperCase().replace(/[^A-Z0-9.-]/g, "-");
   if (!/^[A-Z]/.test(s)) s = `AGENT-${s}`;
-  s = s.replace(/[.]/g, "-").replace(/-{2,}/g, "-").replace(/^-+|-+$/g, "");
+  s = s
+    .replace(/[.]/g, "-")
+    .replace(/-{2,}/g, "-")
+    .replace(/^-+|-+$/g, "");
   return s.slice(0, 64) || "SUBAGENT";
 }
 
 /** Sanitizes a worker name into a tool name (`lower-kebab`, 64 chars). */
 export function sanitizeToolName(raw: string): string {
   const tag = sanitizeXmlTag(raw);
-  return tag.toLowerCase().replace(/[^a-z0-9-]/g, "-").replace(/-{2,}/g, "-").slice(0, 64) || "sub-agent";
+  return (
+    tag
+      .toLowerCase()
+      .replace(/[^a-z0-9-]/g, "-")
+      .replace(/-{2,}/g, "-")
+      .slice(0, 64) || "sub-agent"
+  );
 }
 
 // ---------------------------------------------------------------------------
@@ -91,13 +100,8 @@ export function resolveMainModel(configModel: AgentConfig["model"]): {
  * `dynamicSubagents.model ?? subagentModel ?? SUB_AGENT_MODEL`.
  * Unwraps `ModelProviderInstance` / `ModelSpec` the same way.
  */
-export function resolveDynamicWorkerModel(
-  dynModelRawInput: unknown
-): string | Record<string, unknown> | undefined {
-  const dynModelRaw = dynModelRawInput as
-    | { model?: unknown; id?: unknown; provider?: unknown }
-    | string
-    | undefined;
+export function resolveDynamicWorkerModel(dynModelRawInput: unknown): string | Record<string, unknown> | undefined {
+  const dynModelRaw = dynModelRawInput as { model?: unknown; id?: unknown; provider?: unknown } | string | undefined;
   let dynModel: string | Record<string, unknown> | undefined;
   if (dynModelRaw && typeof dynModelRaw === "object" && "model" in (dynModelRaw as Record<string, unknown>)) {
     dynModel = (dynModelRaw as { model: string }).model as unknown as string | Record<string, unknown>;
@@ -109,7 +113,7 @@ export function resolveDynamicWorkerModel(
   ) {
     dynModel = dynModelRaw as Record<string, unknown>;
   } else {
-    dynModel = (dynModelRaw as string | undefined) || getSubModel() as string | undefined;
+    dynModel = (dynModelRaw as string | undefined) || (getSubModel() as string | undefined);
   }
   return dynModel;
 }
@@ -132,7 +136,10 @@ export function resolveDynamicModelInput(
  * `config.model ?? SUB_AGENT_MODEL ?? MODEL`, throwing with the same message
  * when nothing resolves. Kept here so `Agent` / `SubAgent` share one chain.
  */
-export function resolveSubAgentModel(config: { name?: string; model?: AgentConfig["model"] }): NonNullable<AgentConfig["model"]> {
+export function resolveSubAgentModel(config: {
+  name?: string;
+  model?: AgentConfig["model"];
+}): NonNullable<AgentConfig["model"]> {
   const resolvedModel = config.model ?? getSubModel() ?? getModel();
   if (!resolvedModel) {
     throw new ConfigError(
@@ -191,8 +198,10 @@ export function grantWorkerTools(
     if (declared) poolByNormalized.set(normalizeToolName(declared), def);
   }
   const grantedTools: Record<string, ToolDefinition> = {};
-  for (const toolName of ((requested as string[] | undefined) ?? [])) {
-    const pooled = (toolPool as Record<string, ToolDefinition>)[toolName] ?? poolByNormalized.get(normalizeToolName(String(toolName)));
+  for (const toolName of (requested as string[] | undefined) ?? []) {
+    const pooled =
+      (toolPool as Record<string, ToolDefinition>)[toolName] ??
+      poolByNormalized.get(normalizeToolName(String(toolName)));
     if (pooled) grantedTools[(pooled as ToolDefinition).name || toolName] = pooled;
   }
   return grantedTools;
@@ -205,9 +214,9 @@ function providerOf(modelStr: string | unknown | undefined): string | undefined
     const m =
       typeof modelStr === "string"
         ? modelStr
-        : (modelStr as { model?: unknown; id?: unknown })?.model ??
+        : ((modelStr as { model?: unknown; id?: unknown })?.model ??
           (modelStr as { id?: unknown })?.id ??
-          String(modelStr);
+          String(modelStr));
     return resolveModel(m as string).provider.id;
   } catch {
     return undefined;
@@ -225,9 +234,9 @@ export function resolveWorkerCredentials(
   const chosenModelStrForProvider =
     typeof chosenModel === "string"
       ? chosenModel
-      : (chosenModel as { model?: unknown; id?: unknown })?.model ??
+      : ((chosenModel as { model?: unknown; id?: unknown })?.model ??
         (chosenModel as { id?: unknown })?.id ??
-        String(chosenModel);
+        String(chosenModel));
   const attemptedProvider = providerOf(chosenModelStrForProvider);
   const parentProvider = providerOf(parentAgent.modelStringOrSpec as string);
   const targetProviderFinal = providerOf(chosenModelStrForProvider);
@@ -237,6 +246,14 @@ export function resolveWorkerCredentials(
   return { apiKeyToUse: undefined, baseUrlToUse: undefined, attemptedProvider };
 }
 
+// Configs built by `buildDynamicWorkerConfig`: the Agent constructor checks it so SDK-built workers never take `configure()` or env defaults.
+const workerConfigs = new WeakSet<object>();
+
+/** True for a config made by `buildDynamicWorkerConfig` (a chat worker or a scheduled run), not by the developer. */
+export function isWorkerConfig(config: object): boolean {
+  return workerConfigs.has(config);
+}
+
 /** How many levels of workers may exist below an agent unless `dynamicSubagents.maxDepth` says otherwise: unlimited. */
 export const DEFAULT_MAX_DEPTH = Infinity;
 
@@ -247,7 +264,7 @@ export const DEFAULT_MAX_DEPTH = Infinity;
  * `persistent` makes a multi-turn worker that keeps its history (saved under `persistent.dir` when given, and
  * continued by `resume()` after a crash, never automatically). A persistent worker with levels left below it
  * (`maxDepth` of the parent, minus one for itself) gets its own `subagents` tool; its children can only be granted
- * the tools it was granted. One-shot workers never spawn. `dynamicSubagents.workerBudget` becomes each worker's own
+ * the tools it was granted. One-shot workers never spawn. `dynamicSubagents.workerBudget` becomes each chat worker's own
  * per-run `budget` (and is passed to its children).
  */
 export function buildDynamicWorkerConfig(
@@ -265,7 +282,7 @@ export function buildDynamicWorkerConfig(
   const { apiKeyToUse, baseUrlToUse } = resolveWorkerCredentials(parent, model);
   const dyn = parent.dynamicSubagents;
   const levelsBelow = (dyn?.maxDepth ?? DEFAULT_MAX_DEPTH) - 1;
-  return {
+  const config: AgentConfig = {
     name: worker.name,
     description: worker.role || `Sub-agent ${worker.name}`,
     instructions: worker.instructions,
@@ -275,7 +292,11 @@ export function buildDynamicWorkerConfig(
     thinkingLevel: parent.dynamicSubagents?.thinkingLevel ?? parent.thinkingConfig?.level,
     sessionId: worker.sessionId,
     tools: worker.tools,
-    ...(dyn?.workerBudget ? { budget: { ...dyn.workerBudget } } : {}),
+    // A chat worker (persistent) is capped by `workerBudget`; a one-shot scheduled run only by `scheduledActionBudget`.
+    ...(() => {
+      const cap = worker.persistent ? dyn?.workerBudget : dyn?.scheduledActionBudget;
+      return cap ? { budget: { ...cap } } : {};
+    })(),
     stateless: !worker.persistent,
     ...(worker.persistent?.dir ? { persist: { dir: worker.persistent.dir }, resume: "explicit" as const } : {}),
     ...(worker.persistent && levelsBelow >= 1
@@ -296,6 +317,8 @@ export function buildDynamicWorkerConfig(
     maxTurns: parent.maxTurns,
     ...parent.inheritableConfig(),
   };
+  workerConfigs.add(config);
+  return config;
 }
 
 // ---------------------------------------------------------------------------
@@ -380,10 +403,18 @@ export function createLiveWorker(
         trace.steps.push({ turn: turn.turns, type: "tool_result", name: tr.name, isError: tr.isError, timestamp });
       }
       trace.turns = Math.max(trace.turns, turn.turns);
-      try { hooks.trim?.(trace); } catch {}
-      try { hooks.touch?.(trace.trackingId); } catch {}
-      try { hooks.notify?.(trackingId); } catch {}
-      try { hooks.persist?.(); } catch {}
+      try {
+        hooks.trim?.(trace);
+      } catch {}
+      try {
+        hooks.touch?.(trace.trackingId);
+      } catch {}
+      try {
+        hooks.notify?.(trackingId);
+      } catch {}
+      try {
+        hooks.persist?.();
+      } catch {}
     } catch {}
   };
 
@@ -409,8 +440,12 @@ export function createLiveWorker(
         entry.thinking = partialThinking;
         entry.timestamp = Date.now();
       }
-      try { hooks.trim?.(trace); } catch {}
-      try { hooks.notify?.(trackingId); } catch {}
+      try {
+        hooks.trim?.(trace);
+      } catch {}
+      try {
+        hooks.notify?.(trackingId);
+      } catch {}
       try {
         hooks.emit?.({
           trackingId: displayId,
@@ -429,11 +464,19 @@ export function createLiveWorker(
   }): (() => void) => {
     const textListener = (e: { delta?: string }): void => onWorkerDelta(e.delta, undefined);
     const thinkingListener = (e: { thinkingDelta?: string }): void => onWorkerDelta(undefined, e.thinkingDelta);
-    try { workerStream.on("text_delta", textListener as (e: { delta?: string; thinkingDelta?: string }) => void); } catch {}
-    try { workerStream.on("thinking_delta", thinkingListener as (e: { delta?: string; thinkingDelta?: string }) => void); } catch {}
+    try {
+      workerStream.on("text_delta", textListener as (e: { delta?: string; thinkingDelta?: string }) => void);
+    } catch {}
+    try {
+      workerStream.on("thinking_delta", thinkingListener as (e: { delta?: string; thinkingDelta?: string }) => void);
+    } catch {}
     return () => {
-      try { workerStream.off("text_delta", textListener as (e: { delta?: string; thinkingDelta?: string }) => void); } catch {}
-      try { workerStream.off("thinking_delta", thinkingListener as (e: { delta?: string; thinkingDelta?: string }) => void); } catch {}
+      try {
+        workerStream.off("text_delta", textListener as (e: { delta?: string; thinkingDelta?: string }) => void);
+      } catch {}
+      try {
+        workerStream.off("thinking_delta", thinkingListener as (e: { delta?: string; thinkingDelta?: string }) => void);
+      } catch {}
     };
   };