agent-accelerator 0.5.6 → 0.5.8

package/src/utils/durable.ts

@@ -91,7 +91,7 @@ export function readWithBackup(file: string, isValid: (text: string) => boolean)
 }
 
 // ---------------------------------------------------------------------------
-// One process per folder
+// One process per folder (used for session folders)
 // ---------------------------------------------------------------------------
 
 /** Folders this process already holds (the lock is re-entrant: many Agents share one home). */
@@ -103,8 +103,8 @@ 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 {
+/** True while process `pid` exists (EPERM means it exists but belongs to someone else); in: a pid from a lock or heartbeat file, out: the stale checks. */
+export function processAlive(pid: number): boolean {
   try {
     process.kill(pid, 0);
     return true;
@@ -216,3 +216,78 @@ export function lockFolder(folder: string): void {
     }
   }
 }
+
+/** Longest a short mutex may be held before it counts as stale even though its owner process is alive (a hung holder). */
+const MUTEX_MAX_AGE_MS = 30_000;
+/** Longest a caller waits for a short mutex before getting a ConfigError. */
+const MUTEX_WAIT_MS = 10_000;
+/** Mutex files this process holds right now; a second `withFileMutex` on the same file inside `fn` would deadlock, so it throws. */
+const heldMutexes = new Set<string>();
+
+/**
+ * Runs `fn` while holding a short mutex file (`lockFile`, created with O_EXCL, content = pid, host, time), so several
+ * processes can change one shared file without losing updates. Hold it for milliseconds only: `fn` must be synchronous and
+ * quick. A waiter retries every few ms; a holder whose pid is gone (same host) or whose lock is older than 30 s is taken
+ * over. Not re-entrant (a nested call on the same file throws). The folder of `lockFile` must exist: if it is removed meanwhile
+ * (its owner deleted it) the call throws the plain `ENOENT` error, and the caller decides what that means. Throws
+ * `ConfigError` after 10 s of waiting. Local disks only.
+ */
+export function withFileMutex<T>(lockFile: string, fn: () => T): T {
+  const file = path.resolve(lockFile);
+  if (heldMutexes.has(file)) throw new ConfigError(`[Agent Accelerator] Mutex "${file}" is already held by this process (nested use).`);
+  const mine = JSON.stringify({ pid: process.pid, host: os.hostname(), at: Date.now() });
+  const deadline = Date.now() + MUTEX_WAIT_MS;
+  let unreadable = 0;
+  for (;;) {
+    try {
+      const fd = fs.openSync(file, "wx", 0o600);
+      try {
+        fs.writeFileSync(fd, mine);
+      } finally {
+        fs.closeSync(fd);
+      }
+      break;
+    } catch (err) {
+      if ((err as { code?: string }).code !== "EEXIST") throw err;
+    }
+    let text = "";
+    let mtime = 0;
+    try {
+      text = fs.readFileSync(file, "utf8");
+      mtime = fs.statSync(file).mtimeMs;
+    } catch {
+      continue; // released between the open and the read: try again
+    }
+    let owner: { pid?: unknown; host?: unknown } | undefined;
+    try {
+      owner = JSON.parse(text);
+    } catch {
+      owner = undefined;
+    }
+    let stale = false;
+    if (typeof owner?.pid !== "number") stale = ++unreadable > 5; // empty or garbage: another process may be mid-write
+    else if (owner.host === os.hostname() && !processAlive(owner.pid)) stale = true;
+    else if (Date.now() - mtime > MUTEX_MAX_AGE_MS) stale = true;
+    if (stale) {
+      try {
+        if (fs.readFileSync(file, "utf8") === text) fs.rmSync(file, { force: true });
+      } catch {
+        // why: it vanished: the next loop turn creates it.
+      }
+      continue;
+    }
+    if (Date.now() > deadline) throw new ConfigError(`[Agent Accelerator] Timed out after ${MUTEX_WAIT_MS} ms waiting for the lock "${file}" (held by process ${String(owner?.pid)}).`);
+    pause(typeof owner?.pid === "number" ? 2 : 40);
+  }
+  heldMutexes.add(file);
+  try {
+    return fn();
+  } finally {
+    heldMutexes.delete(file);
+    try {
+      fs.rmSync(file, { force: true });
+    } catch {
+      // why: a leftover mutex is detected as stale by the next caller.
+    }
+  }
+}

package/src/utils/env.ts

@@ -3,7 +3,7 @@
  */
 /**
  * Reads an environment value. Process env only. No globalThis fallback:
- * DOM-clobberable in browsers (Q-05).
+ * DOM-clobberable in browsers.
  *
  * @example `const apiKey = getEnv("OPENAI_API_KEY");`
  */

package/src/utils/errors.ts

@@ -3,6 +3,7 @@ import { getModelFromCatalog } from "../models/catalog.ts";
 
 const CONCISE = "__agentAccelConcise";
 
+// HTTP status from the shapes provider errors carry, else undefined; in: toConciseProviderError, out: a status.
 function readStatus(error: any): number | undefined {
   const s =
     error?.statusCode ??
@@ -14,6 +15,7 @@ function readStatus(error: any): number | undefined {
   return Number.isFinite(n) && n > 0 ? n : undefined;
 }
 
+// The request URL of an error without its query string; in: toConciseProviderError, out: a string.
 function readUrl(error: any): string {
   const raw =
     (typeof error?.url === "string" && error.url) ||
@@ -22,6 +24,7 @@ function readUrl(error: any): string {
   return raw.split("?")[0];
 }
 
+// The provider's own message from the error's data, body or message; in: toConciseProviderError, out: one trimmed line.
 function readProviderMessage(error: any): string {
   const data = error?.data;
   if (typeof data?.error?.message === "string" && data.error.message.trim()) return data.error.message.trim();
@@ -39,6 +42,7 @@ function readProviderMessage(error: any): string {
   return String(error?.message ?? error).slice(0, 300);
 }
 
+// `provider/model` without doubling an existing prefix; in: the error messages, out: a label.
 function displayModel(providerId: string, modelId: string): string {
   if (modelId.toLowerCase().startsWith(`${providerId.toLowerCase()}/`)) return modelId;
   return `${providerId}/${modelId}`;

package/src/utils/headers.ts

@@ -1,6 +1,7 @@
 import type { ProviderId } from "../types/model.ts";
 import { clampCacheKey } from "./cache.ts";
 
+/** True in a browser, worker or React Native scope, where custom headers cause CORS preflights; in: header building, out: a boolean. */
 export function isBrowserRuntime(): boolean {
   try {
     const g = globalThis as any;
@@ -23,9 +24,10 @@ 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.6";
+  return "0.5.8";
 }
 
+// User-Agent string with version and platform; in: AGENT_ACCEL_USER_AGENT, out: a string.
 function getAgentAccelUserAgent(): string {
   const version = getPackageVersion();
   try {
@@ -41,7 +43,7 @@ function getAgentAccelUserAgent(): string {
 export const AGENT_ACCEL_USER_AGENT = getAgentAccelUserAgent;
 
 // ---------------------------------------------------------------------------
-// Attribution (Q-17): configurable, default none except OpenRouter legacy.
+// Attribution: configurable, default none except OpenRouter legacy.
 // ---------------------------------------------------------------------------
 
 /** Configurable attribution headers (OpenRouter `HTTP-Referer` / `X-Title`). */
@@ -102,7 +104,7 @@ export function setHeaderCaseInsensitive(
 }
 
 // ---------------------------------------------------------------------------
-// Thought-signature namespacing (Q-18).
+// Thought-signature namespacing.
 // ---------------------------------------------------------------------------
 
 /**
@@ -125,6 +127,7 @@ const BROWSER_DROPPED = new Set([
   "x-goog-api-client",
 ]);
 
+// Drops the headers a browser may not or should not send; in: buildSessionHeaders, out: the safe headers.
 function stripForBrowser(headers: Record<string, string>): Record<string, string> {
   const out: Record<string, string> = {};
   for (const [k, v] of Object.entries(headers)) {
@@ -137,7 +140,7 @@ function stripForBrowser(headers: Record<string, string>): Record<string, string
 /**
  * Builds provider-specific session, cache-affinity, and attribution headers.
  *
- * Q-17: attribution is configurable via `setAttribution()` (default none; no
+ * Attribution is configurable via `setAttribution()` (default none; no
  * referer/title is ever sent unless you set one). Custom (non-first-class)
  * prefixes receive minimal `x-session-id`/`x-client-request-id` affinity only
  * (no `session_id` alias, no attribution) when a session id is present.

package/src/utils/home.ts

@@ -3,7 +3,7 @@ import { getEnv } from "./env.ts";
 
 /**
  * The Agent Accelerator home: ONE folder that holds everything the SDK stores
- * (`sessions/`, `scheduled_actions/`, `telemetry/`, `catalog/`), so nothing is
+ * (`sessions/`, `scheduled/`, `telemetry/`, `catalog/`), so nothing is
  * scattered across the project or the package.
  */
 let defaultHome: string | undefined;

package/src/utils/media.ts

@@ -38,6 +38,7 @@ export function inferMimeType(input: string, fallback = "application/octet-strea
   return fallback;
 }
 
+// True when the bytes spell `text` at `start`; in: sniffMimeType, out: a boolean.
 const ascii = (bytes: Uint8Array, start: number, text: string): boolean =>
   bytes.length >= start + text.length && [...text].every((ch, i) => bytes[start + i] === ch.charCodeAt(0));
 

package/src/utils/raw-capture.ts

@@ -3,6 +3,7 @@ import type { ProviderRawData } from "../types/model.ts";
 /** How much of the wire exchange `AgentResponse.raw` keeps (see `AgentConfig.captureRaw`). */
 export type CaptureRawMode = false | "redacted" | true;
 
+// Serialized length of a value, 0 if it cannot be serialized; in: the body summaries, out: a number.
 function byteLength(value: unknown): number {
   try {
     return JSON.stringify(value)?.length ?? 0;
@@ -11,6 +12,7 @@ function byteLength(value: unknown): number {
   }
 }
 
+// Tool names from a request body's `tools`, if any; in: summarizeRequestBody, out: names or undefined.
 function toolNames(tools: unknown): string[] | undefined {
   if (!Array.isArray(tools)) return undefined;
   const names = tools
@@ -34,6 +36,7 @@ function summarizeRequestBody(body: unknown): unknown {
   };
 }
 
+// Content-free summary of a response body (size, id, status); in: applyCaptureRaw, out: the summary.
 function summarizeResponseBody(body: unknown): unknown {
   if (body === null || body === undefined) return body;
   const b = (typeof body === "object" ? body : {}) as Record<string, unknown>;

package/src/utils/retry.ts

@@ -6,7 +6,7 @@ export { isAbortError };
 /**
  * Checks whether a provider error is transient and safe to retry.
  * Structured-data only: status / code / transient flag. Never message text,
- * so a 400 mentioning "512 tokens" is not retried (Q-24).
+ * so a 400 mentioning "512 tokens" is not retried.
  */
 export function isTransientError(error: unknown): boolean {
   if (!error) return false;
@@ -43,6 +43,7 @@ export function isRetryableRun(error: unknown): boolean {
   return isTransientError(error);
 }
 
+/** The server's wait hint in ms from `retryAfterMs` or a Retry-After header, capped at 60 s; in: withRetries, out: ms or undefined. */
 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.

package/src/utils/safe-io.ts

@@ -98,6 +98,7 @@ export async function enforceFileAccess(messages: Message[], roots: readonly str
 // Remote fetch guard (SSRF + size cap)
 // ---------------------------------------------------------------------------
 
+// True for the private, loopback, link-local and CGNAT IPv4 ranges; in: isPrivateAddress, out: a boolean.
 function ipv4Private(a: number, b: number): boolean {
   return (
     a === 0 ||
@@ -124,6 +125,7 @@ export function isPrivateAddress(address: string): boolean {
   return false;
 }
 
+// True for localhost, .local/.internal names and private addresses; in: assertRemoteUrlAllowed, out: a boolean.
 function isPrivateHostname(host: string): boolean {
   return (
     host === "localhost" ||
@@ -134,6 +136,7 @@ function isPrivateHostname(host: string): boolean {
   );
 }
 
+// Throws RemoteFetchError for a non-http(s) URL or, unless private hosts are allowed, a private host (also by DNS result); in: fetchRemoteBytes on every hop, out: nothing or a thrown error.
 async function assertRemoteUrlAllowed(url: URL, allowPrivateNetwork: boolean): Promise<void> {
   if (url.protocol !== "http:" && url.protocol !== "https:") {
     throw new RemoteFetchError("blocked", `[Agent Accelerator] Only http(s) URLs are allowed (got ${url.protocol}).`, url.href);
@@ -156,6 +159,7 @@ async function assertRemoteUrlAllowed(url: URL, allowPrivateNetwork: boolean): P
   }
 }
 
+// Reads a response body up to `maxBytes`, throwing too_large as soon as the declared or streamed size passes it; in: fetchRemoteBytes, out: the bytes.
 async function readCapped(res: Response, maxBytes: number, url: string): Promise<Uint8Array> {
   const tooLarge = () =>
     new RemoteFetchError(

package/src/utils/session.ts

@@ -1,7 +1,5 @@
 import { clampCacheKey } from "./cache.ts";
 import type { ThinkingLevel } from "../types/core.ts";
-import type { MidSessionMode } from "../types/agent.ts";
-import type { AgentConfig } from "../types/agent.ts";
 import type { ModelSpec } from "../types/model.ts";
 import type { ModelProviderInstance } from "../providers/registry.ts";
 import type { ContentPart } from "../types/message.ts";
@@ -68,7 +66,7 @@ export function createTrackingId(): string {
 }
 
 /**
- * Monotonic clock for measuring durations (Q-42). Uses `performance.now()`
+ * Monotonic clock for measuring durations. Uses `performance.now()`
  * when available, falling back to `Date.now()`. Differences on the same
  * clock are valid durations; never treat the value as wall-clock epoch.
  *
@@ -83,6 +81,7 @@ export function nowMs(): number {
   return Date.now();
 }
 
+// 32 random lowercase hex characters; in: newRunId/newTurnId, out: a string.
 function random32Hex(): string {
   try {
     const c = (globalThis as any)?.crypto;
@@ -96,7 +95,7 @@ function random32Hex(): string {
 }
 
 /**
- * New stable run id: 32 lowercase hex chars (crypto.randomUUID, no dashes) (Q-42).
+ * New stable run id: 32 lowercase hex chars (crypto.randomUUID, no dashes).
  * Opaque lineage token attached via `(metadata as any).runId`.
  */
 export function newRunId(): string {
@@ -104,21 +103,14 @@ export function newRunId(): string {
 }
 
 /**
- * New stable turn id: 32 lowercase hex chars (crypto.randomUUID, no dashes) (Q-42).
+ * New stable turn id: 32 lowercase hex chars (crypto.randomUUID, no dashes).
  * Opaque lineage token attached via `(metadata as any).turnId`.
  */
 export function newTurnId(): string {
   return random32Hex();
 }
 
-/**
- * Single canonical prompt preview (Q-49): merges the former
- * `previewPrompt` (agent.ts) / `steerPreview` (loop.ts) duplicates.
- * Bounded to 500 chars, display-only. Other modules own their copies;
- * new code should import this one.
- *
- * @example `previewPrompt("hello")`
- */
+/** Bounded (500 chars), display-only preview of a prompt, used in `queued`/`steer_injected` events, turn lists and `interrupted()`. */
 export function previewPrompt(prompt: string | ContentPart[]): string {
   if (typeof prompt === "string") return prompt.slice(0, 500);
   try {
@@ -132,7 +124,7 @@ export function previewPrompt(prompt: string | ContentPart[]): string {
   }
 }
 
-/** Parsed model reference returned by {@link parseModelRef} (Q-48). */
+/** Parsed model reference returned by {@link parseModelRef}. */
 export interface ParsedModelRef {
   provider: string;
   modelId: string;
@@ -141,6 +133,7 @@ export interface ParsedModelRef {
   thinking?: ThinkingLevel;
 }
 
+// Splits `provider/model` on the first slash (bare ids default to openrouter); in: parseModelRef, out: provider and model id.
 function splitModelString(raw: string): { provider: string; modelId: string } {
   const trimmed = raw.trim();
   const slash = trimmed.indexOf("/");
@@ -153,12 +146,14 @@ function splitModelString(raw: string): { provider: string; modelId: string } {
   };
 }
 
+// Type guard for a `{ model: string }` helper result; in: parseModelRef, out: a boolean.
 function isModelProviderInstance(v: unknown): v is ModelProviderInstance {
   if (!v || typeof v !== "object" || Array.isArray(v)) return false;
   const r = v as Record<string, unknown>;
   return typeof r["model"] === "string" && (r["model"] as string).length > 0;
 }
 
+// Type guard for a catalog spec (`provider` and `id` strings); in: parseModelRef, out: a boolean.
 function isModelSpec(v: unknown): v is ModelSpec {
   if (!v || typeof v !== "object" || Array.isArray(v)) return false;
   const r = v as Record<string, unknown>;
@@ -166,7 +161,7 @@ function isModelSpec(v: unknown): v is ModelSpec {
 }
 
 /**
- * Single model-ref parser (Q-48). Table-driven, no env sniffing:
+ * Single model-ref parser. Table-driven, no env sniffing:
  * - string `"provider/model"` → split on first `/`; bare ids default to `openrouter`.
  * - `ModelProviderInstance` (`{ model, apiKey?, baseUrl?, thinkingLevel? }`) → parse `model`, passthrough creds.
  * - `ModelSpec` (`{ provider, id }`) → direct mapping.
@@ -192,154 +187,3 @@ export function parseModelRef(input: string | ModelSpec | ModelProviderInstance)
   }
   throw new ConfigError("parseModelRef: expected string | ModelSpec | ModelProviderInstance.");
 }
-
-/** Validated, readonly agent configuration returned by {@link resolveAgentConfig} (Q-32). */
-export interface ResolvedAgentConfig {
-  readonly model: NonNullable<AgentConfig["model"]>;
-  readonly thinkingLevel?: ThinkingLevel;
-  readonly maxTurns: number;
-  readonly midSession: { readonly mode: MidSessionMode; readonly maxQueued: number };
-  readonly toolNames: readonly string[];
-}
-
-const VALID_THINKING_LEVELS: readonly ThinkingLevel[] = [
-  "none",
-  "dynamic",
-  "minimal",
-  "low",
-  "medium",
-  "high",
-  "xhigh",
-  "max",
-];
-
-const VALID_MIDSESSION_MODES: readonly MidSessionMode[] = ["steer", "queue", "auto"];
-
-/** Local name normalization mirroring `normalizeToolName` (no import cycle, Q-32). */
-function normalizeConfigToolName(name: string): string {
-  return name
-    .trim()
-    .replace(/^(?:functions?|tools?)\./i, "")
-    .replace(/([a-z0-9])([A-Z])/g, "$1_$2")
-    .replace(/[\s-]+/g, "_")
-    .toLowerCase();
-}
-
-/**
- * Single config resolution (Q-32). Validates `model`, `thinkingLevel`,
- * `maxTurns`, `midSession`, and tool-name collisions, collecting EVERY issue
- * and throwing one `ConfigError` listing all of them. Not wired into `Agent`
- * (other owner) — call it from setup paths that want fail-fast validation.
- *
- * @example `const cfg = resolveAgentConfig({ model, maxTurns: 10 });`
- */
-export function resolveAgentConfig(config: AgentConfig): Readonly<ResolvedAgentConfig> {
-  const issues: string[] = [];
-  const cfg = (config ?? {}) as AgentConfig;
-
-  let model: NonNullable<AgentConfig["model"]> | undefined;
-  const rawModel = cfg.model;
-  if (typeof rawModel === "string") {
-    if (rawModel.trim()) model = rawModel;
-    else issues.push("model: must be a non-empty string | ModelSpec | ModelProviderInstance.");
-  } else if (rawModel && typeof rawModel === "object") {
-    model = rawModel as NonNullable<AgentConfig["model"]>;
-  } else {
-    issues.push("model: is required (string | ModelSpec | ModelProviderInstance).");
-  }
-
-  let thinkingLevel: ThinkingLevel | undefined;
-  if (cfg.thinkingLevel !== undefined) {
-    if ((VALID_THINKING_LEVELS as readonly string[]).includes(cfg.thinkingLevel)) {
-      thinkingLevel = cfg.thinkingLevel;
-    } else {
-      issues.push(
-        `thinkingLevel: invalid '${cfg.thinkingLevel}'. Expected one of: ${VALID_THINKING_LEVELS.join(", ")}.`
-      );
-    }
-  }
-
-  let maxTurns = Infinity;
-  if (cfg.maxTurns !== undefined) {
-    const m = cfg.maxTurns;
-    if (m === 0) {
-      maxTurns = Infinity;
-    } else if (m === Infinity) {
-      maxTurns = Infinity;
-    } else if (typeof m === "number" && Number.isFinite(m) && m >= 1) {
-      maxTurns = Math.floor(m);
-    } else {
-      issues.push(`maxTurns: must be finite >= 1 or Infinity (0/omitted means unlimited). Received: ${String(m)}.`);
-    }
-  }
-
-  let mode: MidSessionMode = "auto";
-  if (cfg.midSession?.mode !== undefined) {
-    if ((VALID_MIDSESSION_MODES as readonly string[]).includes(cfg.midSession.mode as string)) {
-      mode = cfg.midSession.mode as MidSessionMode;
-    } else {
-      issues.push(
-        `midSession.mode: invalid '${String(cfg.midSession.mode)}'. Expected one of: ${VALID_MIDSESSION_MODES.join(", ")}.`
-      );
-    }
-  }
-  let maxQueued = 20;
-  if (cfg.midSession?.maxQueued !== undefined) {
-    const q = cfg.midSession.maxQueued;
-    if (typeof q === "number" && Number.isFinite(q) && Math.floor(q) === q && q >= 0) {
-      maxQueued = q;
-    } else {
-      issues.push(`midSession.maxQueued: must be an integer >= 0. Received: ${String(q)}.`);
-    }
-  }
-
-  const toolNames: string[] = [];
-  const tools = cfg.tools;
-  if (tools !== undefined) {
-    const entries: Array<[string, string]> = [];
-    if (Array.isArray(tools)) {
-      for (const def of tools) {
-        const declared = (def as { name?: unknown })?.name;
-        if (typeof declared === "string" && declared.trim()) {
-          toolNames.push(declared);
-          entries.push([declared, declared]);
-        } else {
-          issues.push("tools: array entries must declare a non-empty `name`.");
-        }
-      }
-    } else if (tools && typeof tools === "object") {
-      for (const [key, def] of Object.entries(tools)) {
-        toolNames.push(key);
-        const declared = (def as { name?: unknown })?.name;
-        entries.push([key, typeof declared === "string" && declared ? declared : key]);
-      }
-    } else {
-      issues.push("tools: must be a record or array of ToolDefinitions.");
-    }
-    const seen = new Map<string, string>();
-    for (const [key, declared] of entries) {
-      for (const candidate of new Set([key, declared])) {
-        const normalized = normalizeConfigToolName(String(candidate));
-        const prev = seen.get(normalized);
-        if (prev !== undefined && prev !== key) {
-          issues.push(
-            `tools: name collision: '${prev}' and '${key}' both normalize to '${normalized}'. Rename one tool.`
-          );
-        } else if (prev === undefined) {
-          seen.set(normalized, key);
-        }
-      }
-    }
-  }
-
-  if (issues.length > 0) {
-    throw new ConfigError(`Invalid Agent config (${issues.length} issue${issues.length === 1 ? "" : "s"}): ${issues.join(" ")}`);
-  }
-  return {
-    model: model as NonNullable<AgentConfig["model"]>,
-    ...(thinkingLevel !== undefined ? { thinkingLevel } : {}),
-    maxTurns,
-    midSession: { mode, maxQueued },
-    toolNames,
-  };
-}