agent-accelerator 0.5.2 → 0.5.4

package/src/types/tool.ts

@@ -20,7 +20,7 @@ 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). */
+  /** Forwards live sub-agent deltas (used by the `subagents` tool for realtime tracking). */
   onSubagentEvent?: (event: { trackingId: string; delta?: string; thinkingDelta?: string; partialText?: string; partialThinking?: string }) => void;
   // Q-55 Tool API v2 context additions (all optional, additive).
   /** Stable id for this run (`newRunId`). Mirrors SubAgentRunIds.runId. */
@@ -29,6 +29,20 @@ export interface ToolExecutionContext {
   emit?: ToolEmitFn;
   /** Structured logger for tool implementations (defaults to no-op). */
   logger?: ToolLogger;
+  /**
+   * Writes one line to this call's log file (`tool-logs/<n>-<tool>.ndjson` in the session folder), flushed at once, so
+   * after a crash it shows how far the call got: `ctx.log("uploaded 3 of 5 files", { done: 3 })`. Only written when the
+   * Agent persists to a folder (`persist: { dir }`); otherwise a no-op. For developers, never sent to the model.
+   */
+  log: (message: string, data?: unknown) => void;
+  /**
+   * Ends the whole run from inside a tool, for example when your own permission check says no:
+   * `if (!(await askUser("Pay $50?"))) ctx.stop("user declined the payment")`. It throws, so the code after it never runs
+   * (even if you forget `return`). The reason is saved as this call's result; the other tool calls of the same batch
+   * still run to completion; then the run ends with `finishReason: "stopped"` and NO further model turn, and the agent
+   * waits for the next user message. `timeoutMs` counts the time spent waiting for your check.
+   */
+  stop: (reason: string) => never;
 }
 
 export type ToolExecuteFn<TInput = any, TOutput = any> = (
@@ -92,12 +106,6 @@ export interface ToolDefinition<TInput = any, TOutput = any> {
   redact?: (err: unknown) => string;
   /** Free-form tags for grouping/filtering tools (e.g. `["web", "readonly"]`). */
   tags?: string[];
-  /**
-   * When true, the host must approve this call before execution (human-in-the-
-   * loop). The loop reads via `(toolDef as any).needsApproval`; enforcement
-   * is wired by the host, default open (undefined = no gate).
-   */
-  needsApproval?: boolean;
   /**
    * Optional output schema (Zod or JSON Schema) used to validate/coerce the
    * tool's return value before it reaches model context. Stored as `unknown`
@@ -135,6 +143,10 @@ export interface ToolResultRecord {
   result: unknown;
   isError?: boolean;
   durationMs?: number;
+  /** This call's log file, relative to the session folder (only when the Agent persists to a folder). */
+  logFile?: string;
+  /** The tool ended the run with `ctx.stop(reason)`; `result` is the reason. */
+  stopped?: boolean;
 }
 
 /**

package/src/utils/durable.ts

@@ -0,0 +1,218 @@
+/**
+ * How the SDK writes state to disk safely. One writer for sessions, scheduled
+ * actions and the catalog cache: a crash or a power cut leaves either the old
+ * file or the new one, never a torn mix, and the last good version is kept as
+ * `<file>.bak`. Also the one-process-per-folder lock and the stale temp-file sweep.
+ */
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { ConfigError } from "../types/errors.ts";
+
+/** Flushes a folder's entries (a new or renamed file) to disk; best effort because some platforms cannot open a folder. */
+export function fsyncFolder(dir: string): void {
+  let fd: number | undefined;
+  try {
+    fd = fs.openSync(dir, "r");
+    fs.fsyncSync(fd);
+  } catch {
+    // why: Windows (and some filesystems) refuse to open or fsync a folder; the file itself is already flushed.
+  } finally {
+    if (fd !== undefined) {
+      try {
+        fs.closeSync(fd);
+      } catch {
+        // why: closing a read-only folder handle cannot lose data.
+      }
+    }
+  }
+}
+
+/**
+ * Durable atomic write: temp file (0600) -> fsync -> previous version kept as `<file>.bak` (hard link, no copy)
+ * -> rename -> fsync of the folder. Throws on failure; the temp file is removed. `backup: false` skips the `.bak`.
+ */
+export function writeFileDurable(filePath: string, content: string | Uint8Array, opts: { backup?: boolean } = {}): void {
+  const dir = path.dirname(filePath);
+  try {
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  } catch {
+    // why: a missing folder surfaces as the open() error below, with a clearer path.
+  }
+  const rand = globalThis.crypto?.randomUUID?.().slice(0, 8) ?? Math.random().toString(36).slice(2, 8);
+  const tmp = `${filePath}.tmp-${process.pid}-${rand}`;
+  try {
+    const fd = fs.openSync(tmp, "wx", 0o600);
+    try {
+      fs.writeFileSync(fd, content);
+      fs.fsyncSync(fd);
+    } finally {
+      fs.closeSync(fd);
+    }
+    if (opts.backup !== false) {
+      try {
+        fs.rmSync(`${filePath}.bak`, { force: true });
+        fs.linkSync(filePath, `${filePath}.bak`); // the old inode survives the rename below
+      } catch {
+        // why: no previous version (first write) or no hard links on this filesystem: the write still goes ahead.
+      }
+    }
+    fs.renameSync(tmp, filePath);
+  } catch (err) {
+    try {
+      fs.rmSync(tmp, { force: true });
+    } catch {
+      // why: the original error is the one worth reporting.
+    }
+    throw err;
+  }
+  fsyncFolder(dir);
+}
+
+/**
+ * Reads `file`; when `isValid` rejects it, falls back to `<file>.bak`. `undefined` when the file is missing (a deleted
+ * file is never resurrected from its backup). When both are invalid the primary text comes back, `fromBackup: false`.
+ */
+export function readWithBackup(file: string, isValid: (text: string) => boolean): { text: string; fromBackup: boolean } | undefined {
+  let text: string;
+  try {
+    text = fs.readFileSync(file, "utf8");
+  } catch {
+    return undefined;
+  }
+  if (isValid(text)) return { text, fromBackup: false };
+  try {
+    const backup = fs.readFileSync(`${file}.bak`, "utf8");
+    if (isValid(backup)) return { text: backup, fromBackup: true };
+  } catch {
+    // why: no backup to fall back to.
+  }
+  return { text, fromBackup: false };
+}
+
+// ---------------------------------------------------------------------------
+// One process per folder
+// ---------------------------------------------------------------------------
+
+/** Folders this process already holds (the lock is re-entrant: many Agents share one home). */
+const heldFolders = new Set<string>();
+let exitHookInstalled = false;
+
+// Blocks the thread for `ms` (a lock file being written by another process is the only reason to wait); in: a short delay, out: nothing.
+function pause(ms: number): void {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+// True while process `pid` exists (EPERM means it exists but belongs to someone else); in: a pid from a lock file, out: lockFolder's stale check.
+function processAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return (err as { code?: string }).code === "EPERM";
+  }
+}
+
+// Removes the locks this process still holds when it exits normally; a killed process leaves its lock for the next start to detect as stale.
+function installExitHook(): void {
+  if (exitHookInstalled) return;
+  exitHookInstalled = true;
+  process.once("exit", () => {
+    for (const dir of heldFolders) {
+      try {
+        fs.rmSync(path.join(dir, ".lock"), { force: true });
+      } catch {
+        // why: nothing can be reported while exiting; a leftover lock is detected as stale.
+      }
+    }
+  });
+}
+
+// Deletes leftover `<file>.tmp-<pid>-<rand>` files of writes that never finished; only safe while holding the folder lock; in: a locked folder, out: nothing.
+function sweepTempFiles(dir: string): void {
+  let entries: fs.Dirent[];
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) sweepTempFiles(full);
+    else if (/\.tmp-\d+-[0-9a-z]+$/.test(entry.name)) {
+      try {
+        fs.rmSync(full, { force: true });
+      } catch {
+        // why: an undeletable leftover is harmless.
+      }
+    }
+  }
+}
+
+/**
+ * Takes the one-process lock of a folder (`<dir>/.lock` = pid, host, start time) and sweeps the temp files of writes
+ * that never finished. Re-entrant inside one process. Throws `ConfigError` at once when another live process holds it;
+ * a lock left by a dead process (same host, pid gone) or an unreadable one is taken over. Local disks only.
+ */
+export function lockFolder(folder: string): void {
+  const dir = path.resolve(folder);
+  if (heldFolders.has(dir)) return;
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const lockFile = path.join(dir, ".lock");
+  const mine = JSON.stringify({ pid: process.pid, host: os.hostname(), startedAt: new Date().toISOString() });
+  let unreadable = 0;
+  for (;;) {
+    try {
+      const fd = fs.openSync(lockFile, "wx", 0o600);
+      try {
+        fs.writeFileSync(fd, mine);
+      } finally {
+        fs.closeSync(fd);
+      }
+      heldFolders.add(dir);
+      installExitHook();
+      sweepTempFiles(dir);
+      return;
+    } catch (err) {
+      if ((err as { code?: string }).code !== "EEXIST") throw err;
+    }
+    let text = "";
+    try {
+      text = fs.readFileSync(lockFile, "utf8");
+    } catch {
+      continue; // released between the open and the read: try again
+    }
+    let owner: { pid?: unknown; host?: unknown; startedAt?: unknown } | undefined;
+    try {
+      owner = JSON.parse(text);
+    } catch {
+      owner = undefined;
+    }
+    if (typeof owner?.pid !== "number") {
+      // Empty or garbage: another process may be mid-write. Give it a moment, then treat it as stale.
+      if (++unreadable <= 5) {
+        pause(40);
+        continue;
+      }
+    } else if (owner.pid !== process.pid) {
+      if (owner.host !== os.hostname()) {
+        throw new ConfigError(
+          `[Agent Accelerator] Folder "${dir}" is locked by host "${String(owner.host)}" (process ${owner.pid}). Only local disks are supported: use a folder on this machine.`
+        );
+      }
+      if (processAlive(owner.pid)) {
+        throw new ConfigError(
+          `[Agent Accelerator] Folder "${dir}" is already in use by process ${owner.pid} (started ${String(owner.startedAt)}). ` +
+            `Only one process may use it at a time: stop that process or use another folder (Agent \`home\`, setHome(), AGENT_ACCEL_HOME). ` +
+            `If that process is gone, delete "${lockFile}".`
+        );
+      }
+    }
+    // Stale (dead owner, our own pid from an earlier life, or unreadable): take it over, but only if nobody replaced it meanwhile.
+    try {
+      if (fs.readFileSync(lockFile, "utf8") === text) fs.rmSync(lockFile, { force: true });
+    } catch {
+      // why: it vanished: the next loop turn creates it.
+    }
+  }
+}

package/src/utils/headers.ts

@@ -23,7 +23,7 @@ export function getPackageVersion(): string {
     const v = (globalThis as any).process?.env?.npm_package_version;
     if (typeof v === "string" && v) return v;
   } catch {}
-  return "0.5.2";
+  return "0.5.4";
 }
 
 function getAgentAccelUserAgent(): string {

package/src/utils/retry.ts

@@ -29,7 +29,21 @@ export function isTransientError(error: unknown): boolean {
   return false;
 }
 
-function readRetryAfterMs(error: unknown): number | undefined {
+/**
+ * Whether a FAILED RUN (the provider layer already retried the call) is worth trying again: the failure is transient
+ * (HTTP 408/425/429/5xx, network codes, `transient`/`retryable` flags, `incomplete_stream`, a request/stream timeout).
+ * Never for aborts, bad configuration or input (401/403/400/404, `ConfigError`, `ValidationError`, `SecurityPolicyError`,
+ * `ThinkingLevelError`) and never for budgets or limits, which a retry would only reset or hit again.
+ */
+export function isRetryableRun(error: unknown): boolean {
+  if (!error || isAbortError(error)) return false;
+  const name = (error as { name?: unknown }).name;
+  if (name === "TimeoutError") return true; // the loop's own request / first-byte / idle timeouts
+  if (["BudgetExceededError", "ConfigError", "ValidationError", "SecurityPolicyError", "SessionLoadError", "ThinkingLevelError", "ToolError"].includes(String(name))) return false;
+  return isTransientError(error);
+}
+
+export function readRetryAfterMs(error: unknown): number | undefined {
   const err = error as Record<string, unknown>;
   // Preferred: milliseconds attached by the adapter from the Retry-After header.
   const direct = err["retryAfterMs"];