agent-accelerator 0.5.3 → 0.5.4

package/src/agent/loop.ts

@@ -71,6 +71,8 @@ export interface AgentLoopConfig {
   enforceBudget?: (usage?: TokenUsage) => void;
   /** Called after every turn for durable persistence checkpoints (never fails a turn). */
   onProgress?: () => void;
+  /** Called once per model call this agent made itself (never for its workers), with the provider's usage and the catalog spec: the source of `usageReport()`. */
+  onTurnUsage?: (usage: TokenUsage, spec: ModelSpec | undefined) => void;
   /** Called the moment each tool call finishes, before the rest of its batch (the crash-proof record of finished work). */
   onToolResult?: (result: ToolResultRecord) => void;
   /** Opens the log file of one tool call (see `ToolLogs`); unset when the Agent does not persist to a folder. */
@@ -411,16 +413,14 @@ async function generateWithTimeout<T>(task: () => Promise<T>, timeoutMs: number)
   }
 }
 
-/** Compat wrapper around the one cost model (`priceUsage` in session/store.ts, Q-36).
- * Prefers provider-reported totals, else catalog pricing with integer
- * micro-USD accumulation. Returns undefined when unknown (never a 0 object). */
-export function computeCostFromPricing(usage: TokenUsage, spec?: ModelSpec): TokenUsage["cost"] {
+/** Prices one usage snapshot with the one cost model (`priceUsage`): provider-reported total first, else catalog pricing scaled by `serviceTier`; undefined when unknown. In: loop turns and `accumulateUsage`, out: `usage.cost`. */
+export function computeCostFromPricing(usage: TokenUsage, spec?: ModelSpec, serviceTier?: string): TokenUsage["cost"] {
   try {
     if (usage.cost && usage.cost.totalCost !== undefined && usage.cost.totalCost > 0) {
       return usage.cost;
     }
     if (!spec) return usage.cost;
-    const priced = priceUsage(usage, spec);
+    const priced = priceUsage(usage, spec, serviceTier ? { serviceTier } : undefined);
     return priced
       ? {
           inputCost: priced.inputCost,
@@ -448,7 +448,7 @@ export function computeCostFromPricing(usage: TokenUsage, spec?: ModelSpec): Tok
 // This function never mutates `source` (Q-35): the priced cost is cloned
 // into a local before folding into the target.
 // ---------------------------------------------------------------------------
-export function accumulateUsage(target: TokenUsage, source: TokenUsage, spec?: ModelSpec): void {
+export function accumulateUsage(target: TokenUsage, source: TokenUsage, spec?: ModelSpec, serviceTier?: string): void {
   target.inputTokens += source.inputTokens || 0;
   target.outputTokens += source.outputTokens || 0;
   target.totalTokens += source.totalTokens || 0;
@@ -475,7 +475,7 @@ export function accumulateUsage(target: TokenUsage, source: TokenUsage, spec?: M
     });
   }
 
-  const priced = computeCostFromPricing(source, spec);
+  const priced = computeCostFromPricing(source, spec, serviceTier);
   // Q-35: pure — read `source` only; never assign back to `source.cost`.
   // Clone the priced cost so later target folds cannot alias source state.
   const sourceCost = priced ? { ...priced } : undefined;
@@ -799,8 +799,9 @@ export async function runAgentLoop(config: AgentLoopConfig): Promise<AgentRespon
       }
     }
 
-    accumulateUsage(accumulatedUsage, genResult.usage, spec);
-    config.enforceBudget?.({ ...genResult.usage, cost: computeCostFromPricing(genResult.usage, spec) });
+    accumulateUsage(accumulatedUsage, genResult.usage, spec, options?.serviceTier);
+    try { config.onTurnUsage?.(genResult.usage, spec); } catch {}
+    config.enforceBudget?.({ ...genResult.usage, cost: computeCostFromPricing(genResult.usage, spec, options?.serviceTier) });
     checkTokenLimit(accumulatedUsage, limits.maxTotalTokens);
 
     // Record assistant turn in context
@@ -1252,8 +1253,9 @@ export function streamAgentLoop(config: AgentLoopConfig): AssistantMessageEventS
           }
         }
 
-        accumulateUsage(accumulatedUsage, turnResponse.usage, spec2);
-        config.enforceBudget?.({ ...turnResponse.usage, cost: computeCostFromPricing(turnResponse.usage, spec2) });
+        accumulateUsage(accumulatedUsage, turnResponse.usage, spec2, options?.serviceTier);
+        try { config.onTurnUsage?.(turnResponse.usage, spec2); } catch {}
+        config.enforceBudget?.({ ...turnResponse.usage, cost: computeCostFromPricing(turnResponse.usage, spec2, options?.serviceTier) });
         checkTokenLimit(accumulatedUsage, streamLimits.maxTotalTokens);
 
         context.addAssistantMessage(

package/src/agent/subagents-tool.ts

@@ -0,0 +1,87 @@
+/**
+ * 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
+ * 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";
+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";
+
+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}`;
+  return makeSubagentResult(text, [reply.metadata]);
+}
+
+/** Builds the `subagents` tool for `agent`; its description is the manual with the worker pool and the open-worker limit filled in. */
+export function createSubagentsTool(agent: Agent): ToolDefinition {
+  const poolNames = Object.keys(agent.dynamicSubagents?.tools ?? {});
+  const max = agent.dynamicSubagents?.maxSpawn ?? 4;
+  return tool({
+    name: "subagents",
+    description: loadManual()
+      .replace(/\{\{MAX\}\}/g, String(max))
+      .replace("{{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)."),
+      name: z.string().optional().describe('Short label for a new worker, e.g. "researcher" (spawn).'),
+      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)."),
+    }),
+    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." };
+          throw new ValidationError(`${a.command} needs "${field}". Example: ${JSON.stringify(example)}`);
+        }
+        return value;
+      };
+      try {
+        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)
+            );
+          case "message":
+            return asResult(await agent.workers.message(need("id"), need("task"), opts));
+          case "close":
+            return `Worker ${agent.workers.close(need("id")).id} closed.`;
+          case "list":
+            return describeWorkers(agent);
+        }
+      } catch (err) {
+        // A bad request is feedback for the model; anything else (budget, configuration) is a real failure.
+        if (err instanceof ValidationError) return `Error: ${err.message}`;
+        throw err;
+      }
+    },
+  });
+}
+
+// The `list` answer: the open workers and the conversation turns `history` can copy; in: the agent's registry, out: plain text for the model.
+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 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/subagents.md

@@ -0,0 +1,31 @@
+Starts helpers ("workers") that work on a task for you and can be asked again later. A worker is a separate agent with its own instructions, its own tools and its own memory: it knows only what you give it (plus the earlier conversation you choose to copy). Use workers for parallel research, a second opinion, or a long side task you do not want in your own context.
+
+COMMANDS (one tool, the `command` field)
+- spawn: start a worker. Needs `name` and `task`. Optional: `instructions` (the worker's own system prompt), `role`, `tools`, `history`. It waits for the worker's first reply and gives you the worker's `id`.
+- message: send `task` to the open worker `id`. The worker remembers everything said to it before. It waits for the reply.
+- close: end the worker `id` when you no longer need it. This frees one of your {{MAX}} open slots. A closed worker cannot be messaged again.
+- list: your open workers, plus the numbered turns of this conversation that `history` can copy.
+
+FIELDS
+- name: a short label such as "researcher". The SDK adds a suffix; use the full `id` it returns ("researcher-1a2b3c4d") in message and close.
+- instructions: the worker's own system prompt: its role, rules and the format you want back.
+- task: for spawn, the first assignment; for message, the next message to that worker.
+- tools: names of worker tools to grant. Available: {{TOOLS}}. Grant only what the task needs.
+- history: a number N (default 0 = none). Starts the worker with a copy of the first N finished turns of this conversation, in order. Call list to see the turns and their numbers. The turn you are in right now is never copied: restate what you need in `task`.
+
+RESULTS
+Every spawn and message answers with one header line and the worker's text: `[worker <id>] replied:` or `[worker <id>] failed: <reason>`. A failed worker stays open: fix the problem and message it again, or close it.
+
+EXAMPLES
+Start a researcher:
+{"command":"spawn","name":"researcher","instructions":"You research databases. Answer in 5 bullets with sources.","task":"Compare SQLite and Postgres for a small SaaS."}
+Ask it a follow-up:
+{"command":"message","id":"researcher-1a2b3c4d","task":"Now focus on write-heavy workloads."}
+
+RULES
+- Several workers at once: make several spawn calls in the same turn. They run in parallel.
+- A worker handles one call at a time. Wait for its reply before messaging it again.
+- You can have at most {{MAX}} open workers. Close the ones you are done with.
+- A worker starts blank: put everything it needs in `instructions` and `task`, or copy earlier turns with `history`.
+- Worker answers are written by another model. Check them before you rely on them.
+- Never put secrets in `instructions` or `task`.

package/src/agent/turns.ts

@@ -0,0 +1,60 @@
+/**
+ * Turn grouping: a "turn" is one finished run (the user prompt plus the whole answer to it: text, thinking, tool calls
+ * and results), found through the run marks the Agent keeps. A worker that starts from a copy of its parent's history
+ * gets whole finished turns only, so a prompt never reaches it without its answer. Pure functions, no Agent import.
+ */
+import type { Message, ContentPart } from "../types/message.ts";
+import type { SessionRunMark } from "../session/store.ts";
+import { ValidationError } from "../types/errors.ts";
+import { previewPrompt } from "../utils/session.ts";
+import { deepCloneValue } from "./context.ts";
+
+/** One finished turn: its 1-based number (counting finished turns only), a prompt preview, and its messages `[from, to)`. */
+export interface Turn {
+  n: number;
+  prompt: string;
+  from: number;
+  to: number;
+}
+
+/** Longest prompt preview shown to a model in a turn list. */
+const PREVIEW_CHARS = 200;
+
+// A run counts as finished when it ended with its answer (`done`) or with a tool's `ctx.stop` (`stopped`); in: a run mark, out: finishedTurns.
+function isFinished(mark: SessionRunMark): boolean {
+  return mark.end === "done" || mark.end === "stopped";
+}
+
+/** The finished turns of a conversation, oldest first. The running turn and failed, aborted or abandoned runs are not turns. */
+export function finishedTurns(messages: Message[], marks: SessionRunMark[]): Turn[] {
+  const sorted = marks.filter((m) => m.i >= 0 && m.i < messages.length).sort((a, b) => a.i - b.i);
+  const turns: Turn[] = [];
+  sorted.forEach((mark, k) => {
+    if (!isFinished(mark)) return;
+    turns.push({
+      n: turns.length + 1,
+      prompt: previewPrompt(messages[mark.i]!.content as string | ContentPart[]).slice(0, PREVIEW_CHARS),
+      from: mark.i,
+      to: sorted[k + 1]?.i ?? messages.length,
+    });
+  });
+  return turns;
+}
+
+/**
+ * A deep copy of the first `n` finished turns (plus anything before the first run mark), in order. `0` gives an empty
+ * history. Throws a `ValidationError` naming how many finished turns exist when `n` is not a whole number in range.
+ */
+export function historyUpTo(messages: Message[], marks: SessionRunMark[], n: number): Message[] {
+  const turns = finishedTurns(messages, marks);
+  if (!Number.isInteger(n) || n < 0 || n > turns.length) {
+    throw new ValidationError(
+      `history: ${JSON.stringify(n)} is not valid; use "none" or a whole number from 1 to ${turns.length} (the number of finished turns).`
+    );
+  }
+  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 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/worker.ts

@@ -42,11 +42,6 @@ export function sanitizeToolName(raw: string): string {
   return tag.toLowerCase().replace(/[^a-z0-9-]/g, "-").replace(/-{2,}/g, "-").slice(0, 64) || "sub-agent";
 }
 
-/** Stable worker ids: `{sanitizedName}-{32hex}` display id + raw tracking id. */
-export function makeWorkerIds(sanitizedName: string, trackingId: string): { trackingId: string; displayId: string } {
-  return { trackingId, displayId: `${sanitizedName}-${trackingId}` };
-}
-
 // ---------------------------------------------------------------------------
 // Shared Agent / SubAgent config normalization (behavior-preserving)
 // ---------------------------------------------------------------------------
@@ -203,11 +198,6 @@ export function grantWorkerTools(
   return grantedTools;
 }
 
-/** Resolves a provider id for credential reuse / error metadata (shared). */
-export function providerOfWorkerModel(modelStr: string | unknown | undefined): string | undefined {
-  return providerOf(modelStr);
-}
-
 function providerOf(modelStr: string | unknown | undefined): string | undefined {
   if (!modelStr) return undefined;
   try {
@@ -246,18 +236,34 @@ export function resolveWorkerCredentials(
   return { apiKeyToUse: undefined, baseUrlToUse: undefined, attemptedProvider };
 }
 
+/** How many levels of workers may exist below an agent unless `dynamicSubagents.maxDepth` says otherwise. */
+export const DEFAULT_MAX_DEPTH = 3;
+
 /**
- * Config of a stateless dynamic worker (`spawn_subagents` and scheduled
- * actions): the developer's fixed worker model, level and limits, never the
- * LLM's choice. Credentials carry over only when the providers match, and
- * `inheritableConfig()` keeps the worker no less constrained than its parent.
+ * Config of a dynamic worker (scheduled actions, the worker registry): the developer's fixed worker
+ * model, level and limits, never the LLM's choice. Credentials carry over only when the providers match, and
+ * `inheritableConfig()` keeps the worker no less constrained than its parent. Stateless one-shot by default;
+ * `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
+ * per-run `budget` (and is passed to its children).
  */
 export function buildDynamicWorkerConfig(
   parent: Agent,
-  worker: { name: string; role?: string; instructions: string; sessionId: string; tools: Record<string, ToolDefinition> }
+  worker: {
+    name: string;
+    role?: string;
+    instructions: string;
+    sessionId: string;
+    tools: Record<string, ToolDefinition>;
+    persistent?: { dir?: string };
+  }
 ): AgentConfig {
   const model = parent.subagentModel;
   const { apiKeyToUse, baseUrlToUse } = resolveWorkerCredentials(parent, model);
+  const dyn = parent.dynamicSubagents;
+  const levelsBelow = (dyn?.maxDepth ?? DEFAULT_MAX_DEPTH) - 1;
   return {
     name: worker.name,
     description: worker.role || `Sub-agent ${worker.name}`,
@@ -268,8 +274,22 @@ export function buildDynamicWorkerConfig(
     thinkingLevel: parent.dynamicSubagents?.thinkingLevel ?? parent.thinkingConfig?.level,
     sessionId: worker.sessionId,
     tools: worker.tools,
-    // Stateless by design: one task in, one result out, then shut down. No history, no recursion.
-    stateless: true,
+    ...(dyn?.workerBudget ? { budget: { ...dyn.workerBudget } } : {}),
+    stateless: !worker.persistent,
+    ...(worker.persistent?.dir ? { persist: { dir: worker.persistent.dir }, resume: "explicit" as const } : {}),
+    ...(worker.persistent && levelsBelow >= 1
+      ? {
+          dynamicSubagents: {
+            enabled: true,
+            model,
+            ...(dyn?.maxSpawn !== undefined ? { maxSpawn: dyn.maxSpawn } : {}),
+            ...(dyn?.thinkingLevel ? { thinkingLevel: dyn.thinkingLevel } : {}),
+            tools: worker.tools,
+            ...(dyn?.workerBudget ? { workerBudget: dyn.workerBudget } : {}),
+            maxDepth: levelsBelow,
+          },
+        }
+      : {}),
     serviceTier: parent.serviceTier,
     headers: parent.customHeaders,
     maxTurns: parent.maxTurns,
@@ -277,18 +297,6 @@ export function buildDynamicWorkerConfig(
   };
 }
 
-/** Builds one `<NAME>...text...</NAME>` block inside `<SUB-AGENTS-RESPONSE>`. */
-export function buildWorkerXmlBlock(name: string, text: string): string {
-  const escaped = escapeXml(text);
-  const indentedText = escaped.split("\n").map((line) => `        ${line}`).join("\n");
-  return `    <${name}>\n${indentedText}\n    </${name}>`;
-}
-
-/** Builds the `<SUB-AGENTS-RESPONSE>` envelope for dynamic workers. */
-export function buildSubagentsXml(results: Array<{ name: string; text: string }>): string {
-  return `<SUB-AGENTS-RESPONSE>\n${results.map((r) => buildWorkerXmlBlock(r.name, r.text)).join("\n")}\n</SUB-AGENTS-RESPONSE>`;
-}
-
 // ---------------------------------------------------------------------------
 // Shared live worker state machine (single home for fixed + dynamic workers)
 // ---------------------------------------------------------------------------
@@ -322,7 +330,7 @@ export interface LiveWorkerHooks {
 
 /**
  * Single live worker state machine shared by fixed (`agentToTool`) and
- * dynamic (`spawn_subagents`) workers. Owns `liveTurn` / `partialText` /
+ * registry workers. Owns `liveTurn` / `partialText` /
  * `partialThinking`, finalizes partial streaming entries on `onTurn`, and
  * forwards deltas to the parent stream. The trace object is mutated in place;
  * trimming / touching / notifying / persisting are delegated to hooks so this