agent-accelerator 0.5.6 → 0.5.8

package/src/scheduler/store.ts

@@ -1,18 +1,21 @@
 /**
  * Disk layer for scheduled actions. Everything lives under one home folder:
  *
- *   <home>/scheduled_actions/tasks.json         every action, one file
- *   <home>/scheduled_actions/deliveries.json    saved results waiting for their delivery time
- *   <home>/scheduled_actions/<id>/<date>.md     one file per run
+ *   <home>/scheduled/<id>/task.json             the action (`{ version: 2, task }`)
+ *   <home>/scheduled/<id>/delivery.json         its saved results waiting for their delivery time (`{ version: 2, pending }`)
+ *   <home>/scheduled/<id>/<date>.md             one file per run
+ *   <home>/scheduled/<id>/.mutex                short lock held while this action's files change
+ *   <home>/scheduled/<id>/.heartbeat            written while a process is running the action (pid, host; its mtime is refreshed)
  *
- * The files are the source of truth: every write re-reads first (never writes
- * from a stale copy) and goes through `writeFileDurable` (temp file, fsync, `.bak`, rename).
- * Sync `fs`, like the session store.
+ * One folder per action, so processes working on different actions never touch the same file. The files are the
+ * source of truth: every change takes the action's mutex, re-reads first (never writes from a stale copy) and goes
+ * through `writeFileDurable` (temp file, fsync, `.bak`, rename). Sync `fs`, like the session store.
  */
 import * as fs from "node:fs";
+import * as os from "node:os";
 import * as path from "node:path";
 import { z } from "zod";
-import { readWithBackup, writeFileDurable } from "../utils/durable.ts";
+import { readWithBackup, withFileMutex, writeFileDurable } from "../utils/durable.ts";
 import { telemetryBus } from "../telemetry.ts";
 import { resolveHome } from "../utils/home.ts";
 export { resolveHome };
@@ -26,10 +29,10 @@ export const TASK_ID_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
 /** 48-char slug + `-` + 6 random chars. */
 export const MAX_TASK_ID_LENGTH = 55;
 
-/** A saved run waiting for its delivery time (one entry of `deliveries.json`). */
+/** A saved run waiting for its delivery time (one entry of an action's `delivery.json`). */
 export interface PendingDelivery {
   id: string;
-  /** Run file path, relative to `scheduled_actions/`. */
+  /** Run file path, relative to `scheduled/`. */
   file: string;
   status: ScheduledRunStatus;
   readyAt: string;
@@ -72,31 +75,105 @@ export interface RunHeader {
   error?: string;
 }
 
-const baseDir = (home: string): string => path.join(home, "scheduled_actions");
-const tasksFile = (home: string): string => path.join(baseDir(home), "tasks.json");
-const deliveriesFile = (home: string): string => path.join(baseDir(home), "deliveries.json");
+// The `scheduled` folder of a home; in: the path helpers, out: its path.
+const baseDir = (home: string): string => path.join(home, "scheduled");
 
-/** Absolute path of a run file given its `scheduled_actions/`-relative path. */
-export function runPath(home: string, relativeFile: string): string {
-  return path.resolve(baseDir(home), relativeFile);
+// The folder of one action; refuses anything that is not an action id, so a hand-edited id can never point outside `scheduled/`; in: every per-action helper, out: its path.
+function taskDir(home: string, id: string): string {
+  if (typeof id !== "string" || !TASK_ID_PATTERN.test(id) || id.length > MAX_TASK_ID_LENGTH) {
+    throw new ValidationError(`${JSON.stringify(id)} is not a scheduled action id.`);
+  }
+  return path.join(baseDir(home), id);
+}
+// Path of an action's record; in: the task helpers, out: its path.
+const taskFile = (dir: string): string => path.join(dir, "task.json");
+// Path of an action's saved deliveries; in: the delivery helpers, out: its path.
+const deliveryFile = (dir: string): string => path.join(dir, "delivery.json");
+// Path of the short mutex that serialises every change to one action (record and deliveries); in: updateTask/updateDeliveries/deleteTask, out: its path.
+const mutexFile = (dir: string): string => path.join(dir, ".mutex");
+
+// Path of the file a running action's owner keeps fresh; in: the heartbeat helpers, out: its path.
+const heartbeatFile = (dir: string): string => path.join(dir, ".heartbeat");
+
+/** Who is running an action and how long ago they last said so. */
+export interface Heartbeat {
+  pid: number;
+  host: string;
+  /** Identifies the scheduler instance inside that process. */
+  token: string;
+  ageMs: number;
+}
+
+/** Marks an action as running in this process (pid, host, token); written before the record flips to `cooking`; in: startCook, out: `<id>/.heartbeat`. */
+export function writeHeartbeat(home: string, id: string, token: string): void {
+  fs.writeFileSync(heartbeatFile(taskDir(home, id)), JSON.stringify({ pid: process.pid, host: os.hostname(), token }), { mode: 0o600 });
+}
+
+/** Refreshes the heartbeat's modification time; false when the file is gone; in: the scheduler tick for each run in flight. */
+export function touchHeartbeat(home: string, id: string): boolean {
+  try {
+    const now = new Date();
+    fs.utimesSync(heartbeatFile(taskDir(home, id)), now, now);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** The heartbeat of an action, or undefined when it has none or the file is unreadable; in: the dead-owner checks and `delete`. */
+export function readHeartbeat(home: string, id: string): Heartbeat | undefined {
+  try {
+    const file = heartbeatFile(taskDir(home, id));
+    const raw = JSON.parse(fs.readFileSync(file, "utf8")) as Partial<Heartbeat>;
+    if (typeof raw.pid !== "number" || typeof raw.host !== "string" || typeof raw.token !== "string") return undefined;
+    return { pid: raw.pid, host: raw.host, token: raw.token, ageMs: Date.now() - fs.statSync(file).mtimeMs };
+  } catch {
+    return undefined;
+  }
 }
 
-/** Renames the pre-0.5.0 `scheduled_tasks/` folder to `scheduled_actions/` (once, only when the new one does not exist). */
-export function migrateLegacyFolder(home: string): void {
-  const legacy = path.join(home, "scheduled_tasks");
+/** Removes the heartbeat when a run ends; in: the scheduler after a run, out: nothing. */
+export function clearHeartbeat(home: string, id: string): void {
   try {
-    if (fs.existsSync(legacy) && !fs.existsSync(baseDir(home))) fs.renameSync(legacy, baseDir(home));
+    fs.rmSync(heartbeatFile(taskDir(home, id)), { force: true });
   } catch {
-    // why: best effort; the old folder simply stays where it is.
+    // why: a leftover heartbeat of a finished run is harmless (it is only read for actions that are cooking).
   }
 }
 
+// True for the error of a folder that was removed while we waited for its lock; in: the catch blocks of the mutating helpers, out: a boolean.
+const isMissingFolder = (err: unknown): boolean => (err as { code?: string } | null)?.code === "ENOENT";
+
+// Deletes the leftover temp files of a task.json / delivery.json write that never finished (a killed process); only called while holding the action's mutex, which is what makes it safe (run files are written outside the mutex, so they are never touched); in: the three mutating helpers, out: nothing.
+function sweepShardTemps(dir: string): void {
+  try {
+    for (const name of fs.readdirSync(dir)) if (/^(task|delivery)\.json\.tmp-\d+-[0-9a-z]+$/.test(name)) fs.rmSync(path.join(dir, name), { force: true });
+  } catch {
+    // why: an unreadable folder or an undeletable leftover is harmless.
+  }
+}
+
+/** Absolute path of a run file given its `scheduled/`-relative path. */
+export function runPath(home: string, relativeFile: string): string {
+  return path.resolve(baseDir(home), relativeFile);
+}
+
 type Raw = Record<string, unknown>;
 
-// Parses a `{ version, <key>: [...] }` file into its object entries; undefined when the text is not that shape; in: raw file text, out: readList.
-function parseList(text: string, key: "tasks" | "pending"): Raw[] | undefined {
+// Parses `{ version, task: {...} }` into the record; undefined when the text is not that shape; in: readShard, out: the record.
+function parseTask(text: string): Raw | undefined {
   try {
-    const list = (JSON.parse(text) as Raw | null)?.[key];
+    const task = (JSON.parse(text) as Raw | null)?.["task"];
+    return task && typeof task === "object" && !Array.isArray(task) ? (task as Raw) : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+// Parses `{ version, pending: [...] }` into its object entries; undefined when the text is not that shape; in: readShard, out: the entries.
+function parsePending(text: string): Raw[] | undefined {
+  try {
+    const list = (JSON.parse(text) as Raw | null)?.["pending"];
     if (!Array.isArray(list)) return undefined;
     return list.filter((x): x is Raw => !!x && typeof x === "object" && !Array.isArray(x));
   } catch {
@@ -105,21 +182,21 @@ function parseList(text: string, key: "tasks" | "pending"): Raw[] | undefined {
 }
 
 /**
- * Reads a `{ version, <key>: [...] }` file. Missing = empty. A damaged file is renamed `*.corrupt-<ts>`; if its `.bak`
- * (the last good version) is valid it is restored, else the list starts empty.
+ * Reads one JSON file of an action. Missing = undefined. A damaged file is renamed `*.corrupt-<ts>`; if its `.bak`
+ * (the last good version) is valid it is restored and returned, else undefined (the action is treated as absent).
  */
-function readList(file: string, key: "tasks" | "pending"): Raw[] {
-  const read = readWithBackup(file, (t) => parseList(t, key) !== undefined);
-  if (!read) return [];
-  const list = parseList(read.text, key);
-  if (list && !read.fromBackup) return list;
+function readShard<T>(file: string, parse: (text: string) => T | undefined): T | undefined {
+  const read = readWithBackup(file, (t) => parse(t) !== undefined);
+  if (!read) return undefined;
+  const value = parse(read.text);
+  if (value !== undefined && !read.fromBackup) return value;
   const moved = `${file}.corrupt-${Date.now()}`;
   try {
     fs.renameSync(file, moved);
   } catch {
     // why: quarantine is best-effort; the file is ignored either way.
   }
-  if (list) {
+  if (value !== undefined) {
     try {
       writeFileDurable(file, read.text, { backup: false }); // keep the good .bak where it is
     } catch {
@@ -128,39 +205,181 @@ function readList(file: string, key: "tasks" | "pending"): Raw[] {
   }
   telemetryBus.emitWarning(
     "scheduled_action.store_corrupt",
-    `[Agent Accelerator] ${path.basename(file)} is not valid; moved to ${path.basename(moved)} and ${list ? "restored from its backup" : "starting empty"}.`,
-    { file: moved, restored: !!list }
+    `[Agent Accelerator] ${path.relative(baseDir(path.dirname(path.dirname(file))), file)} is not valid; moved to ${path.basename(moved)} and ${value !== undefined ? "restored from its backup" : "ignored"}.`,
+    { file: moved, restored: value !== undefined }
   );
-  return list ?? [];
+  return value;
 }
 
-function writeList(file: string, key: "tasks" | "pending", list: Raw[]): void {
-  writeFileDurable(file, JSON.stringify({ version: 1, [key]: list }, null, 2) + "\n");
+// Names of the action folders of a home (every folder not starting with a dot), sorted; in: readTasks/readDeliveries, out: folder names.
+function actionFolders(home: string): string[] {
+  try {
+    return fs
+      .readdirSync(baseDir(home), { withFileTypes: true })
+      .filter((e) => e.isDirectory() && !e.name.startsWith("."))
+      .map((e) => e.name)
+      .sort();
+  } catch {
+    return [];
+  }
 }
 
-/** Every record as stored. Records may be invalid: check with {@link validateRecord} before acting on one. */
+/** Folder/id mismatches already reported, so a bad hand edit warns once per process. */
+const reportedMismatch = new Set<string>();
+// True when a record or delivery names the folder it sits in; otherwise warns once and says no; in: readTasks/readDeliveries, out: a boolean.
+function inOwnFolder(file: string, folder: string, id: unknown): boolean {
+  if (id === folder) return true;
+  const key = `${file}:${String(id)}`;
+  if (!reportedMismatch.has(key)) {
+    reportedMismatch.add(key);
+    telemetryBus.emitWarning(
+      "scheduled_action.invalid",
+      `[Agent Accelerator] ${folder}/${path.basename(file)} names the id ${JSON.stringify(id)} but sits in the folder "${folder}" and is skipped.`,
+      { id: String(id), problem: "id: does not match its folder", file: path.basename(file) }
+    );
+  }
+  return false;
+}
+
+// Orders records by creation time, then id, so listings are stable; in: readTasks, out: a comparison number.
+function byCreation(a: ScheduledActionRecord, b: ScheduledActionRecord): number {
+  return (a.createdAt ?? "").localeCompare(b.createdAt ?? "") || a.id.localeCompare(b.id);
+}
+
+/** One action as stored (`task.json`), or undefined when it does not exist or `id` is not an action id. May be invalid: check with {@link validateRecord}. */
+export function readTask(home: string, id: string): ScheduledActionRecord | undefined {
+  let dir: string;
+  try {
+    dir = taskDir(home, id);
+  } catch {
+    return undefined;
+  }
+  const raw = readShard(taskFile(dir), parseTask);
+  return raw && inOwnFolder(taskFile(dir), id, raw["id"]) ? (raw as unknown as ScheduledActionRecord) : undefined;
+}
+
+/** Every record as stored, oldest first. Records may be invalid: check with {@link validateRecord} before acting on one. */
 export function readTasks(home: string): ScheduledActionRecord[] {
-  return readList(tasksFile(home), "tasks") as unknown as ScheduledActionRecord[];
+  const out: ScheduledActionRecord[] = [];
+  for (const folder of actionFolders(home)) {
+    if (!TASK_ID_PATTERN.test(folder) || folder.length > MAX_TASK_ID_LENGTH) continue; // not an action folder
+    const rec = readTask(home, folder);
+    if (rec) out.push(rec);
+  }
+  return out.sort(byCreation);
+}
+
+/**
+ * Changes one action under its own short mutex: re-reads `task.json`, calls `fn` (which may mutate the record in place;
+ * it gets `undefined` when the action does not exist) and writes the record back if it changed. If `fn` throws nothing
+ * is written. Other actions are never locked, so processes working on different actions do not wait for each other.
+ */
+export function updateTask<T>(home: string, id: string, fn: (rec: ScheduledActionRecord | undefined) => T): T {
+  let dir: string;
+  try {
+    dir = taskDir(home, id);
+  } catch {
+    return fn(undefined); // not an action id: nothing to change
+  }
+  if (!fs.existsSync(dir)) return fn(undefined);
+  try {
+    return withFileMutex(mutexFile(dir), () => {
+      sweepShardTemps(dir);
+      const rec = readTask(home, id);
+      const before = rec ? JSON.stringify(rec) : "";
+      const result = fn(rec);
+      if (rec && JSON.stringify(rec) !== before) writeFileDurable(taskFile(dir), JSON.stringify({ version: 2, task: rec }, null, 2) + "\n");
+      return result;
+    });
+  } catch (err) {
+    if (!isMissingFolder(err)) throw err;
+    return fn(undefined); // another process deleted the action while we waited for its lock
+  }
 }
 
-/** Re-reads `tasks.json`, applies `fn` (mutating the array/records in place) and writes it back. */
-export function updateTasks<T>(home: string, fn: (tasks: ScheduledActionRecord[]) => T): T {
-  const tasks = readTasks(home);
-  const result = fn(tasks);
-  writeList(tasksFile(home), "tasks", tasks as unknown as Raw[]);
-  return result;
+/**
+ * Creates an action in a new folder. The folder is made with a create-only `mkdir`, so two processes can never take the
+ * same id; `nextId` is called again until a free one is found, then `build` makes the record for it.
+ */
+export function createTask(home: string, nextId: () => string, build: (id: string) => ScheduledActionRecord): ScheduledActionRecord {
+  fs.mkdirSync(baseDir(home), { recursive: true, mode: 0o700 });
+  for (let attempt = 0; attempt < 100; attempt++) {
+    const id = nextId();
+    const dir = taskDir(home, id);
+    try {
+      fs.mkdirSync(dir, { mode: 0o700 });
+    } catch (err) {
+      if ((err as { code?: string }).code === "EEXIST") continue;
+      throw err;
+    }
+    const rec = build(id);
+    withFileMutex(mutexFile(dir), () => {
+      sweepShardTemps(dir);
+      writeFileDurable(taskFile(dir), JSON.stringify({ version: 2, task: rec }, null, 2) + "\n");
+    });
+    return rec;
+  }
+  throw new ValidationError("Could not find a free scheduled action id.");
 }
 
+/** Removes an action's record and saved deliveries (run files stay); true when there was something to remove. An emptied folder is removed too. */
+export function deleteTask(home: string, id: string): boolean {
+  const dir = taskDir(home, id);
+  if (!fs.existsSync(dir)) return false;
+  let removed: boolean;
+  try {
+    removed = withFileMutex(mutexFile(dir), () => {
+      const had = fs.existsSync(taskFile(dir)) || fs.existsSync(deliveryFile(dir));
+      for (const f of [taskFile(dir), deliveryFile(dir)]) fs.rmSync(f, { force: true }), fs.rmSync(`${f}.bak`, { force: true });
+      fs.rmSync(heartbeatFile(dir), { force: true });
+      return had;
+    });
+  } catch (err) {
+    if (isMissingFolder(err)) return false; // another process deleted it first
+    throw err;
+  }
+  try {
+    fs.rmdirSync(dir); // only succeeds when nothing is left in it
+  } catch {
+    // why: run files (or another process's new action) keep the folder.
+  }
+  return removed;
+}
+
+/** Every saved delivery of every action as stored, soonest first (entries may be invalid: check with validateDelivery). */
 export function readDeliveries(home: string): PendingDelivery[] {
-  return readList(deliveriesFile(home), "pending") as unknown as PendingDelivery[];
+  const out: PendingDelivery[] = [];
+  for (const folder of actionFolders(home)) {
+    if (!TASK_ID_PATTERN.test(folder) || folder.length > MAX_TASK_ID_LENGTH) continue;
+    const file = deliveryFile(taskDir(home, folder));
+    for (const entry of readShard(file, parsePending) ?? []) if (inOwnFolder(file, folder, entry["id"])) out.push(entry as unknown as PendingDelivery);
+  }
+  return out.sort((a, b) => String(a.deliverAt).localeCompare(String(b.deliverAt)));
 }
 
-/** Re-reads `deliveries.json`, applies `fn` (mutating in place) and writes it back. */
-export function updateDeliveries<T>(home: string, fn: (pending: PendingDelivery[]) => T): T {
-  const pending = readDeliveries(home);
-  const result = fn(pending);
-  writeList(deliveriesFile(home), "pending", pending as unknown as Raw[]);
-  return result;
+/** Changes the saved deliveries of ONE action under its short mutex (`fn` mutates the array in place); the file is removed when the list ends up empty. */
+export function updateDeliveries<T>(home: string, id: string, fn: (pending: PendingDelivery[]) => T): T {
+  const dir = taskDir(home, id);
+  for (let attempt = 1; ; attempt++) {
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    try {
+      return withFileMutex(mutexFile(dir), () => {
+        sweepShardTemps(dir);
+        const file = deliveryFile(dir);
+        const pending = (readShard(file, parsePending) ?? []) as unknown as PendingDelivery[];
+        const result = fn(pending);
+        if (pending.length === 0) {
+          fs.rmSync(file, { force: true });
+          fs.rmSync(`${file}.bak`, { force: true });
+        } else {
+          writeFileDurable(file, JSON.stringify({ version: 2, pending }, null, 2) + "\n");
+        }
+        return result;
+      });
+    } catch (err) {
+      if (!isMissingFolder(err) || attempt >= 3) throw err; // the folder was removed between making it and locking it: make it again
+    }
+  }
 }
 
 // ---------------------------------------------------------------------------
@@ -219,7 +438,7 @@ const deliverySchema = z.object({
   late: z.boolean().optional(),
 });
 
-/** `undefined` when a `deliveries.json` entry is usable, else a one-line reason. Never throws. */
+/** `undefined` when a `delivery.json` entry is usable, else a one-line reason. Never throws. */
 export function validateDelivery(raw: unknown): string | undefined {
   const parsed = deliverySchema.safeParse(raw);
   return parsed.success ? undefined : parsed.error.issues.map((i) => `${i.path.join(".") || "entry"}: ${i.message}`).join("; ");
@@ -229,6 +448,7 @@ export function validateDelivery(raw: unknown): string | undefined {
 // Run files
 // ---------------------------------------------------------------------------
 
+// Renders a run file: the `---` header lines, a blank line, the result text; in: writeRunFile, out: the file text.
 function renderRun(header: RunHeader, body: string): string {
   const lines = ["---"];
   for (const [key, value] of Object.entries(header)) {
@@ -240,7 +460,7 @@ function renderRun(header: RunHeader, body: string): string {
 
 /**
  * Writes one run under its final name (`27-october-2026.md`, `-2`, `-3` on a
- * same-day clash) and returns its path relative to `scheduled_actions/`.
+ * same-day clash) and returns its path relative to `scheduled/`.
  */
 export function writeRunFile(home: string, id: string, deliverAt: Date, header: RunHeader, body: string): string {
   const dir = path.join(baseDir(home), id);
@@ -287,7 +507,7 @@ export function findRunFile(home: string, id: string, deliverAt: Date, startedAt
   return undefined;
 }
 
-/** Deletes an action's folder (`purge`). Only ever inside `scheduled_actions/`. */
+/** Deletes an action's folder (`purge`). Only ever inside `scheduled/`. */
 export function removeTaskFolder(home: string, id: string): void {
   const root = baseDir(home);
   const dir = path.resolve(root, id);

package/src/scheduler/time.ts

@@ -15,7 +15,9 @@ const DAYS = ["Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday",
 const DDHHMM = /^(\d{2,}):(\d{2}):(\d{2})$/;
 const LOCAL_ISO = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})$/;
 
+// Two-digit zero padding; in: date formatting here, out: a string.
 const pad2 = (n: number): string => String(n).padStart(2, "0");
+// JSON text of a value for error messages; in: the validators, out: a string.
 const show = (v: unknown): string => JSON.stringify(v) ?? String(v);
 
 /** Parses `DD:HH:MM` (DD >= 2 digits, MM < 60). HH is range-checked by the caller. */

package/src/session/architecture.md

@@ -0,0 +1,19 @@
+# src/session/
+
+Saving a conversation, its spending and its tool logs.
+
+| File | What it is |
+| :-- | :-- |
+| `store.ts` | Snapshot format (`session.json`, one line per field and per turn), load validation, `SessionTelemetry`, media extraction, journal replay (`replayJournal`), and `priceUsage` (the one cost model, integer micro-USD). |
+| `journal.ts` | `SessionJournal`: after each step appends one fsynced line to `journal.ndjson`; writes a fresh snapshot (new `epoch`) when history changed any other way or the journal passed 500 lines / 4 MB. |
+| `usage.ts` | Pure spending accounting: `UsageTotals`, `usageLine`, `buildUsageReport`. No Agent import. |
+| `tool-log.ts` | `ToolLogs`: one fsynced NDJSON file per tool call under `<session>/tool-logs/`. |
+
+## Invariants
+- Layout: `<home>/sessions/<id>/{session.json, journal.ndjson, telemetry.ndjson, media/, tool-logs/, workers/}`. `telemetry.ndjson` is written by `telemetry-file.ts` (opt-in), not by the session code; a folder holding only that file is not a session.
+- A journal whose header epoch differs from the snapshot's is ignored on load.
+- Journal record types: `base`, `msg`, `meta`, `run`, `end`, `tool`, `pending`, `usage`. Replay ignores unknown types, drops a torn last line, and stops at earlier damage with `session.journal_corrupt`.
+- Media is content-addressed (`media/<kind>-h<hash>.<ext>`), written once, never deleted.
+- Valid sessions over the load limits throw `SessionLoadError` and are never quarantined; only corrupt files are renamed `*.corrupt-<ts>`.
+- Pricing: a provider-reported cost wins and is never rescaled; unknown pricing stays unknown, never $0; cache reads and writes are subsets of input.
+- Never call `saveSessionDir` on a folder an Agent persists to.