agent-accelerator 0.5.7 → 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/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.8";
 }
 
 // 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

@@ -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;

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.