agent-accelerator 0.2.0 → 0.3.0

package/src/tools/executor.ts

@@ -13,6 +13,8 @@ export interface ExecuteToolsOptions {
   parallel?: boolean;
   signal?: AbortSignal;
   sessionId?: string;
+  /** Forwards live sub-agent deltas (realtime worker thinking/text) to the caller. */
+  onSubagentEvent?: (event: { trackingId: string; delta?: string; thinkingDelta?: string; partialText?: string; partialThinking?: string }) => void;
 }
 
 const DEFAULT_TOOL_CONCURRENCY = 8;
@@ -233,7 +235,7 @@ async function executeAttempt(
 export async function executeToolCalls(
   options: ExecuteToolsOptions
 ): Promise<ToolResultRecord[]> {
-  const { tools, toolCalls, agentName, parallel = true, signal, sessionId } = options;
+  const { tools, toolCalls, agentName, parallel = true, signal, sessionId, onSubagentEvent } = options;
   const globalSemaphore = new Semaphore(DEFAULT_TOOL_CONCURRENCY);
   const perToolSemaphores = new Map<string, Semaphore>();
 
@@ -282,6 +284,7 @@ export async function executeToolCalls(
         agentName,
         signal,
         sessionId,
+        onSubagentEvent,
       };
 
       // Validate input if Zod schema is provided

package/src/types/agent.ts

@@ -45,12 +45,20 @@ export interface AgentConfig {
   sessionId?: string;
   /** Headers merged into every provider request. */
   headers?: Record<string, string>;
-  /** Maximum model/tool turns per run. Defaults to 10. */
+  /** Maximum model/tool turns per run. `0` or omitted means infinite. */
   maxTurns?: number;
   /** Fixed worker agents exposed as delegation tools. */
   subagents?: (Agent | { name: string; description: string; agent: Agent })[];
   /** Clears conversation state before and after every run. */
   stateless?: boolean;
+  /**
+   * Durable session persistence: when set, the session file is rewritten
+   * after every step (user turn, assistant turn, tool batch, sub-agent
+   * step) so a crash loses at most the in-flight step. Pass `{ dir }` for
+   * `sessions/<sessionId>/session.json` layout or `{ file }` for a single
+   * pretty `.session.json` file. Writes are atomic and never fail a turn.
+   */
+  persist?: { dir?: string; file?: string };
 }
 
 /** Developer-configured policy for LLM-spawned dynamic sub-agents. */
@@ -91,4 +99,20 @@ export interface AgentRunOptions {
   onEvent?: (event: import("./response.ts").StreamEvent) => void;
   /** When true, wraps reasoning stream as <think>\n...\n</think>\n\n — no manual isThinking needed. */
   wrapThinking?: boolean;
+  /** Called after every model/tool turn with a turn summary (also drives sub-agent step logs + durable persistence). */
+  onTurn?: (turn: AgentTurnEvent) => void;
+}
+
+/** Turn summary emitted to `AgentRunOptions.onTurn` after each loop turn. */
+export interface AgentTurnEvent {
+  /** 1-based turn count within this run. */
+  turns: number;
+  /** Assistant text produced this turn, if any. */
+  text?: string;
+  /** Reasoning produced this turn, if any. */
+  thinking?: string;
+  /** Tool calls requested this turn, if any. */
+  toolCalls?: Array<{ id: string; name: string }>;
+  /** Tool results executed this turn, if any. */
+  toolResults?: Array<{ id: string; name: string; isError?: boolean }>;
 }

package/src/types/core.ts

@@ -9,7 +9,8 @@ export type ThinkingLevel =
   | "low"
   | "medium"
   | "high"
-  | "xhigh";
+  | "xhigh"
+  | "max";
 
 // Internal normalized config (SDK-internal, not exposed as Agent flag)
 /** Internal normalized reasoning configuration passed to providers. */

package/src/types/response.ts

@@ -2,6 +2,19 @@ import type { TokenUsage } from "./core.ts";
 import type { ToolCallRecord, ToolResultRecord } from "./tool.ts";
 import type { ProviderRawData, ProviderId } from "./model.ts";
 
+/** One logged step inside a sub-agent worker run (surfaced via `agent.track(id)`). */
+export interface SubAgentStep {
+  turn: number;
+  type: "assistant" | "tool_call" | "tool_result";
+  name?: string;
+  text?: string;
+  thinking?: string;
+  isError?: boolean;
+  timestamp: number;
+  /** True while the worker is still streaming this step; finalized on turn end. */
+  partial?: boolean;
+}
+
 /** Per-worker result and usage metadata attached to an AgentResponse. */
 export interface SubAgentExecutionMetadata {
   name: string;
@@ -20,6 +33,14 @@ export interface SubAgentExecutionMetadata {
   raw?: ProviderRawData;
   isError?: boolean;
   error?: string;
+  /** Stable display id: `SUBAGENT-NAME-{TrackingID}` (32-char hex, see `createTrackingId`). */
+  trackingId?: string;
+  /** Provider session id used by this worker (≤64 chars, affinity-safe). */
+  sessionId?: string;
+  /** Parent session this worker was spawned from. */
+  parentSessionId?: string;
+  /** Ordered step log for this worker (also persisted in the session file). */
+  steps?: SubAgentStep[];
 }
 
 /** JSON representation returned by AgentResponse.toJSON(). */
@@ -136,6 +157,7 @@ export type StreamEventType =
   | "tool_call_complete"
   | "tool_result"
   | "subagent_complete"
+  | "subagent_delta"
   | "usage"
   | "done"
   | "error";
@@ -148,6 +170,8 @@ export interface StreamEvent {
   toolCall?: ToolCallRecord;
   toolResult?: ToolResultRecord;
   subagent?: SubAgentExecutionMetadata;
+  /** Tracking id of the worker emitting a `subagent_delta` event. */
+  subagentTrackingId?: string;
   usage?: TokenUsage;
   responseId?: string;
   finishReason?: string;

package/src/types/tool.ts

@@ -9,6 +9,8 @@ export interface ToolExecutionContext {
   signal?: AbortSignal;
   /** Session identifier associated with this invocation. */
   sessionId?: string;
+  /** Forwards live sub-agent deltas (used by `spawn_subagents` for realtime tracking). */
+  onSubagentEvent?: (event: { trackingId: string; delta?: string; thinkingDelta?: string; partialText?: string; partialThinking?: string }) => void;
 }
 
 export type ToolExecuteFn<TInput = any, TOutput = any> = (

package/src/utils/session.ts

@@ -24,3 +24,39 @@ export function createSessionId(prefix = "accel"): string {
   }
   return clampCacheKey(id) || id;
 }
+
+/**
+ * Short stable hash (FNV-1a, 8 hex chars) for embedding parent lineage
+ * into truncated child session IDs without extra dependencies.
+ */
+export function hashSessionPart(value: string): string {
+  let h = 0x811c9dc5;
+  for (let i = 0; i < value.length; i++) {
+    h ^= value.charCodeAt(i);
+    h = Math.imul(h, 0x01000193);
+  }
+  return (h >>> 0).toString(16).padStart(8, "0");
+}
+
+/**
+ * System-generated 32-char TrackingID for one sub-agent (lowercase hex, no
+ * dashes). Surfaced as the suffix in `SUBAGENT-NAME-{TrackingID}` display ids
+ * so `agent.track(id)` can address one worker among many concurrent ones.
+ */
+export function createTrackingId(): string {
+  try {
+    const c = (globalThis as any)?.crypto;
+    if (c && typeof c.randomUUID === "function") {
+      return String(c.randomUUID()).replace(/-/g, "").slice(0, 32);
+    }
+  } catch {}
+  try {
+    const nodeCrypto: any = (globalThis as any)?.process?.getBuiltinModule?.("node:crypto") ?? null;
+    if (nodeCrypto?.randomUUID) {
+      return String(nodeCrypto.randomUUID()).replace(/-/g, "").slice(0, 32);
+    }
+  } catch {}
+  let out = "";
+  while (out.length < 32) out += Math.random().toString(16).slice(2);
+  return out.slice(0, 32);
+}