agent-accelerator 0.5.7 → 0.5.9

package/src/utils/cache.ts

@@ -11,7 +11,7 @@ export function clampCacheKey(key?: string): string | undefined {
 }
 
 // ---------------------------------------------------------------------------
-// Central redaction helpers (Q-11, temporary home to avoid owner conflicts).
+// Central redaction helpers (temporary home to avoid owner conflicts).
 // Providers must call these instead of maintaining local deny-lists.
 // ---------------------------------------------------------------------------
 
@@ -45,7 +45,7 @@ function valueLooksSensitive(value: unknown): boolean {
 }
 
 /**
- * Redacts a single value: sensitive strings become "[REDACTED]" (Q-11).
+ * Redacts a single value: sensitive strings become "[REDACTED]".
  */
 export function redactValue(value: unknown): unknown {
   if (typeof value !== "string") return value;
@@ -54,7 +54,7 @@ export function redactValue(value: unknown): unknown {
 }
 
 /**
- * Redacts sensitive header values (Q-11). Returns a shallow copy; input untouched.
+ * Redacts sensitive header values. Returns a shallow copy; input untouched.
  * Deny-list (name contains): *key*, *token*, *secret*, cookie, authorization.
  * Value patterns (redacted regardless of name): sk-, AIza, gsk-, xox-.
  */
@@ -71,7 +71,7 @@ export function redactHeadersCentral(
 }
 
 /**
- * Redacts secret-looking substrings inside free text (Q-11).
+ * Redacts secret-looking substrings inside free text.
  * Replaces `sk-...`, `AIza...`, `gsk-...`, `xox-...` tokens with "[REDACTED]".
  */
 export function redactText(text: string): string {

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

@@ -1,5 +1,32 @@
 import type { ProviderContext } from "../types/message.ts";
 import { getModelFromCatalog } from "../models/catalog.ts";
+import { AgentAccelError, ProviderError, ValidationError, isAbortError } from "../types/errors.ts";
+
+/**
+ * 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.
+ */
+export function isTransientError(error: unknown): boolean {
+  if (!error) return false;
+  if (isAbortError(error)) return false;
+  const err = error as Record<string, unknown>;
+  if (err["transient"] === true) return true;
+  if ((err as { retryable?: unknown }).retryable === true) return true;
+  const status = Number(
+    (err["status"] as number | undefined) ??
+      (err["statusCode"] as number | undefined) ??
+      ((err["response"] as Record<string, unknown> | undefined)?.["status"] as number | undefined) ??
+      ((err["lastError"] as Record<string, unknown> | undefined)?.["status"] as number | undefined) ??
+      NaN
+  );
+  if ([408, 425, 429, 500, 502, 503, 504].includes(status)) return true;
+  const code = String((err["providerCode"] as string | undefined) ?? (err["code"] as string | undefined) ?? "").toUpperCase();
+  if (["ECONNRESET", "ECONNREFUSED", "EAI_AGAIN", "UND_ERR_CONNECT_TIMEOUT", "EPIPE", "ETIMEDOUT"].includes(code)) {
+    return true;
+  }
+  return false;
+}
 
 const CONCISE = "__agentAccelConcise";
 
@@ -49,12 +76,12 @@ function displayModel(providerId: string, modelId: string): string {
 }
 
 /**
- * Collapses a raw provider error (which carries the full request/response
- * dump as enumerable props) into a one-line actionable error. Raw details stay
- * available but non-enumerable, so runtime dumps stay small.
+ * Collapses a raw provider error (which carries the full request/response dump as enumerable props) into a one-line
+ * `ProviderError` with `retryable` set from its status/code; the provider's own error code is `providerCode`. Raw
+ * details stay available but non-enumerable, so runtime dumps stay small. An SDK error (already typed) passes through.
  */
 export function toConciseProviderError(error: unknown, providerId: string, modelId: string): Error {
-  if (error instanceof Error && (error as any)[CONCISE]) return error;
+  if (error instanceof AgentAccelError || (error instanceof Error && (error as any)[CONCISE])) return error;
   const err = error as any;
   const status = readStatus(err);
   const url = readUrl(err);
@@ -70,10 +97,10 @@ export function toConciseProviderError(error: unknown, providerId: string, model
   if (rawMeta && !detail.includes(rawMeta.slice(0, 80))) {
     detail = `${detail}\n${rawMeta.slice(0, 500)}`.slice(0, 800);
   }
-  const concise = new Error(
-    `[${displayModel(providerId, modelId)}] request failed${status ? ` (${status})` : ""}: ${detail}`
+  const concise = new ProviderError(
+    `[${displayModel(providerId, modelId)}] request failed${status ? ` (${status})` : ""}: ${detail}`,
+    { status, provider: providerId, model: modelId, retryable: isTransientError(err) }
   );
-  concise.name = "AgentAccelProviderError";
   Object.defineProperties(concise, {
     [CONCISE]: { value: true, enumerable: false },
     statusCode: { value: status, enumerable: false },
@@ -90,11 +117,10 @@ export function toConciseProviderError(error: unknown, providerId: string, model
     ...(typeof err?.errorType === "string"
       ? { errorType: { value: err.errorType, enumerable: false } }
       : {}),
-    // Forwarded when present (e.g. Google's `not_found` chain-eviction code,
-    // which carries no HTTP status on SSE error frames). Survives re-wraps
-    // so chain-expiry detectors never lose it.
+    // The provider's own error code (e.g. Google's `not_found` chain-eviction code, which carries no HTTP status on
+    // SSE error frames); `code` itself is the SDK kind (`"provider"`). Survives re-wraps so chain detectors never lose it.
     ...((typeof err?.code === "string" || typeof err?.code === "number") && err.code !== ""
-      ? { code: { value: err.code, enumerable: false } }
+      ? { providerCode: { value: err.code, enumerable: false } }
       : {}),
     // Server rate-limit hint in ms (from Retry-After); survives re-wraps so
     // `withRetries` can honor it instead of hammering a 429.
@@ -120,7 +146,7 @@ const PART_TO_MODALITY: Record<string, "image" | "audio" | "video" | "pdf"> = {
  * lacks a requested input modality (image/audio/video/document; files are
  * not checked on OpenRouter, which parses them for any model). Unknown
  * models (custom providers, dynamic routers) are skipped: the provider
- * verdict stands and surfaces via toConciseProviderError instead.
+ * verdict stands and surfaces via toConciseProviderError instead. Throws a `ValidationError`.
  */
 export function assertModalitiesSupported(
   context: ProviderContext,
@@ -147,16 +173,10 @@ export function assertModalitiesSupported(
   if (!supported) return;
   const missing = [...needed].filter((k) => !supported.includes(k));
   if (missing.length === 0) return;
-  const err = new Error(
-    `[${displayModel(providerId, modelId)}] unsupported ${missing.join("+")} input (supports: ${supported.join(", ") || "text"}). Use a capable model or drop the ${missing.join("+")} part.`
+  throw new ValidationError(
+    `[${displayModel(providerId, modelId)}] unsupported ${missing.join("+")} input (supports: ${supported.join(", ") || "text"}). Use a capable model or drop the ${missing.join("+")} part.`,
+    { provider: providerId, model: modelId }
   );
-  err.name = "AgentAccelProviderError";
-  Object.defineProperties(err, {
-    [CONCISE]: { value: true, enumerable: false },
-    provider: { value: providerId, enumerable: false },
-    model: { value: modelId, enumerable: false },
-  });
-  throw err;
 }
 
 /**
@@ -169,7 +189,7 @@ export function assertModalitiesSupported(
  * `openrouter/stealth/space-bunny-alpha` under the old Responses skin despite
  * its catalog `video` flag, which is chat-transport oriented). Fail fast with
  * a clear one-liner instead; video stays Gemini-only, and OpenRouter Chat
- * Completions carries `video_url` natively (no guard there).
+ * Completions carries `video_url` natively (no guard there). Throws a `ValidationError`.
  */
 export function assertNoVideoPartsOnResponses(
   context: ProviderContext,
@@ -197,14 +217,8 @@ export function assertNoVideoPartsOnResponses(
     // contradict the rejection).
     if (known && known.length > 0) supported = known.filter((m) => m !== "video").join(", ") || "text";
   } catch {}
-  const err = new Error(
-    `[${displayModel(providerId, modelId)}] unsupported video input (the Responses API accepts text/image/file only; supports: ${supported}). Use a video-capable model (e.g. google/gemini-*) or drop the video part.`
+  throw new ValidationError(
+    `[${displayModel(providerId, modelId)}] unsupported video input (the Responses API accepts text/image/file only; supports: ${supported}). Use a video-capable model (e.g. google/gemini-*) or drop the video part.`,
+    { provider: providerId, model: modelId }
   );
-  err.name = "AgentAccelProviderError";
-  Object.defineProperties(err, {
-    [CONCISE]: { value: true, enumerable: false },
-    provider: { value: providerId, enumerable: false },
-    model: { value: modelId, enumerable: false },
-  });
-  throw err;
 }

package/src/utils/headers.ts

@@ -24,7 +24,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.7";
+  return "0.5.9";
 }
 
 // User-Agent string with version and platform; in: AGENT_ACCEL_USER_AGENT, out: a string.
@@ -43,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`). */
@@ -104,7 +104,7 @@ export function setHeaderCaseInsensitive(
 }
 
 // ---------------------------------------------------------------------------
-// Thought-signature namespacing (Q-18).
+// Thought-signature namespacing.
 // ---------------------------------------------------------------------------
 
 /**
@@ -140,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/retry.ts

@@ -1,33 +1,7 @@
-import { toConciseProviderError } from "./errors.ts";
+import { toConciseProviderError, isTransientError } from "./errors.ts";
 import { isAbortError } from "../types/errors.ts";
 
-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).
- */
-export function isTransientError(error: unknown): boolean {
-  if (!error) return false;
-  if (isAbortError(error)) return false;
-  const err = error as Record<string, unknown>;
-  if (err["transient"] === true) return true;
-  if ((err as { retryable?: unknown }).retryable === true) return true;
-  const status = Number(
-    (err["status"] as number | undefined) ??
-      (err["statusCode"] as number | undefined) ??
-      ((err["response"] as Record<string, unknown> | undefined)?.["status"] as number | undefined) ??
-      ((err["lastError"] as Record<string, unknown> | undefined)?.["status"] as number | undefined) ??
-      NaN
-  );
-  if ([408, 425, 429, 500, 502, 503, 504].includes(status)) return true;
-  const code = String((err["code"] as string | undefined) ?? "").toUpperCase();
-  if (["ECONNRESET", "ECONNREFUSED", "EAI_AGAIN", "UND_ERR_CONNECT_TIMEOUT", "EPIPE", "ETIMEDOUT"].includes(code)) {
-    return true;
-  }
-  return false;
-}
+export { isAbortError, isTransientError };
 
 /**
  * Whether a FAILED RUN (the provider layer already retried the call) is worth trying again: the failure is transient

package/src/utils/session.ts

@@ -66,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.
  *
@@ -95,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 {
@@ -103,7 +103,7 @@ 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 {
@@ -124,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;
@@ -161,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.