agent-accelerator 0.5.1 → 0.5.3

package/src/providers/openai-compat.ts

@@ -90,6 +90,7 @@ import {
   mapGenerationParamsToChat,
   normalizeStructuredOutput,
   augmentSystemPromptWithStructuredOutput,
+  warnIgnoredMediaResolution,
 } from "../providers.ts";
 
 // ---------------------------------------------------------------------------
@@ -704,6 +705,7 @@ export class OpenAICompatibleChatProvider implements Provider {
     }
     // Strict endpoints reject unknown body fields: implicit caching only.
     resolveCache(this.prefix, options?.cache, ["implicit"], `${this.prefix}/${modelId}`);
+    warnIgnoredMediaResolution(this.prefix, context.messages, `${this.prefix}/${modelId}`);
 
     // Structured outputs: native `response_format` when supported, else
     // emulated via system prompt (strict endpoints would 400 on json_schema

package/src/providers/openai.ts

@@ -85,6 +85,7 @@ import {
   normalizeStructuredOutput,
   augmentSystemPromptWithStructuredOutput,
   emitProviderWarning,
+  warnIgnoredMediaResolution,
 } from "../providers.ts";
 
 // ---------------------------------------------------------------------------
@@ -524,6 +525,7 @@ export class OpenAIResponsesProvider implements Provider {
     const serviceTier = mapServiceTierToOpenAI(options?.serviceTier);
     // `12h` maps to `prompt_cache_retention: "24h"`; everything else stays on implicit prompt_cache_key affinity.
     const cache = resolveCache("openai", options?.cache, ["implicit", "12h"], `openai/${modelId}`);
+    warnIgnoredMediaResolution("openai", context.messages, `openai/${modelId}`);
 
     // Structured outputs: native `text.format` when supported, else emulated
     // via instructions (catalog `structured_output: false` would 400).

package/src/providers/openrouter.ts

@@ -77,6 +77,7 @@ import {
   normalizeStructuredOutput,
   augmentSystemPromptWithStructuredOutput,
   emitProviderWarning,
+  warnIgnoredMediaResolution,
 } from "../providers.ts";
 
 // ---------------------------------------------------------------------------
@@ -576,6 +577,7 @@ export class OpenRouterChatCompletionsProvider implements Provider {
     const serviceTier = mapServiceTierToOpenRouter(options?.serviceTier);
     // Anthropic models take a top-level `cache_control` TTL; every other route caches implicitly (docs: prompt-caching.md).
     const cache = resolveCache("openrouter", options?.cache, modelId.startsWith("anthropic/") ? ["implicit", "5m", "1h"] : ["implicit"], `openrouter/${modelId}`);
+    warnIgnoredMediaResolution("openrouter", context.messages, `openrouter/${modelId}`);
 
     // Structured outputs: native `response_format` when supported, else
     // emulated via system-prompt instruction + client validation (catalog

package/src/providers.ts

@@ -11,6 +11,7 @@
  */
 import type { CacheOption, ServiceTier, ThinkingLevel } from "./types/core.ts";
 import type { StructuredOutputSpec } from "./types/model.ts";
+import type { Message } from "./types/message.ts";
 import { zodToJsonSchema } from "./tools/schema.ts";
 import { ValidationError } from "./types/errors.ts";
 import { TRUNCATED_ARGS_KEY } from "./types/tool.ts";
@@ -247,6 +248,21 @@ export function resolveCache(
   return undefined;
 }
 
+/** Warns once per provider/model that per-media `resolution` is ignored (no such control on that wire); in: an adapter's request messages, out: telemetry bus only. */
+export function warnIgnoredMediaResolution(provider: string, messages: Message[], modelRef: string): void {
+  const used = messages.some(
+    (m) => Array.isArray(m.content) && m.content.some((p) => (p.type === "image" || p.type === "video") && p.resolution)
+  );
+  if (!used) return;
+  emitProviderWarning({
+    provider,
+    capability: "media resolution",
+    requested: modelRef,
+    reason: "this provider has no per-media detail control (Google only).",
+    fallback: "the provider's default detail",
+  });
+}
+
 /** OpenRouter Chat Completions `tool_choice` wire values. */
 export type OpenRouterChatToolChoice =
   | "auto"

package/src/scheduler/scheduler.ts

@@ -16,6 +16,7 @@ import type { Agent } from "../agent/agent.ts";
 import { createChildSessionId } from "../agent/delegation.ts";
 import { buildDynamicWorkerConfig, grantWorkerTools, normalizeWorkerTimeoutValue } from "../agent/worker.ts";
 import { telemetryBus } from "../telemetry.ts";
+import { lockFolder } from "../utils/durable.ts";
 import { ConfigError, ValidationError } from "../types/errors.ts";
 import type { ToolDefinition } from "../types/tool.ts";
 import type { AgentResponse } from "../types/response.ts";
@@ -649,6 +650,7 @@ const schedulers = new Map<string, Scheduler>();
 export function getScheduler(home: string): Scheduler {
   let s = schedulers.get(home);
   if (!s) {
+    lockFolder(home); // every scheduler function goes through here: one process per home
     migrateLegacyFolder(home);
     schedulers.set(home, (s = new Scheduler(home)));
   }

package/src/scheduler/store.ts

@@ -6,13 +6,13 @@
  *   <home>/scheduled_actions/<id>/<date>.md     one file per run
  *
  * The files are the source of truth: every write re-reads first (never writes
- * from a stale copy) and goes through `writeFileAtomic` (temp file + rename).
+ * 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 path from "node:path";
 import { z } from "zod";
-import { writeFileAtomic } from "../session/store.ts";
+import { readWithBackup, writeFileDurable } from "../utils/durable.ts";
 import { telemetryBus } from "../telemetry.ts";
 import { resolveHome } from "../utils/home.ts";
 export { resolveHome };
@@ -73,36 +73,49 @@ export function migrateLegacyFolder(home: string): void {
 
 type Raw = Record<string, unknown>;
 
-/** Reads a `{ version, <key>: [...] }` file. Missing = empty; corrupt = quarantined (`*.corrupt-<ts>`) + empty. */
-function readList(file: string, key: "tasks" | "pending"): Raw[] {
-  let text: string;
+// 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 {
   try {
-    text = fs.readFileSync(file, "utf8");
+    const list = (JSON.parse(text) as Raw | null)?.[key];
+    if (!Array.isArray(list)) return undefined;
+    return list.filter((x): x is Raw => !!x && typeof x === "object" && !Array.isArray(x));
   } catch {
-    return [];
+    return 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.
+ */
+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;
+  const moved = `${file}.corrupt-${Date.now()}`;
   try {
-    const list = (JSON.parse(text) as Raw | null)?.[key];
-    if (!Array.isArray(list)) throw new Error(`"${key}" is not an array`);
-    return list.filter((x): x is Raw => !!x && typeof x === "object" && !Array.isArray(x));
+    fs.renameSync(file, moved);
   } catch {
-    const moved = `${file}.corrupt-${Date.now()}`;
+    // why: quarantine is best-effort; the file is ignored either way.
+  }
+  if (list) {
     try {
-      fs.renameSync(file, moved);
+      writeFileDurable(file, read.text, { backup: false }); // keep the good .bak where it is
     } catch {
-      // why: quarantine is best-effort; the file is ignored either way.
+      // why: the backup content is still returned for this read.
     }
-    telemetryBus.emitWarning(
-      "scheduled_action.store_corrupt",
-      `[Agent Accelerator] ${path.basename(file)} is not valid; moved to ${path.basename(moved)} and starting empty.`,
-      { file: moved }
-    );
-    return [];
   }
+  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 }
+  );
+  return list ?? [];
 }
 
 function writeList(file: string, key: "tasks" | "pending", list: Raw[]): void {
-  writeFileAtomic(file, JSON.stringify({ version: 1, [key]: list }, null, 2) + "\n");
+  writeFileDurable(file, JSON.stringify({ version: 1, [key]: list }, null, 2) + "\n");
 }
 
 /** Every record as stored. Records may be invalid: check with {@link validateRecord} before acting on one. */
@@ -212,7 +225,7 @@ export function writeRunFile(home: string, id: string, deliverAt: Date, header:
   const base = runFileName(deliverAt);
   let name = `${base}.md`;
   for (let n = 2; fs.existsSync(path.join(dir, name)); n++) name = `${base}-${n}.md`;
-  writeFileAtomic(path.join(dir, name), renderRun(header, body));
+  writeFileDurable(path.join(dir, name), renderRun(header, body), { backup: false }); // written once, never rewritten
   return `${id}/${name}`;
 }
 

package/src/session/journal.ts

@@ -0,0 +1,201 @@
+/**
+ * Append-only step log for a persisted session (dir mode). `session.json` stays the snapshot; every step after it
+ * adds ONE short line to `journal.ndjson` instead of rewriting the whole file, so a long chat costs the same per step
+ * as a short one. When history changes any other way (rollback, repair, reset, import) or the journal grows past a
+ * limit, a fresh snapshot replaces both. The snapshot carries an `epoch` id and the journal header repeats it, so a
+ * journal left over from before a snapshot is ignored on load (see `replayJournal` in `store.ts`).
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { createHash, randomUUID } from "node:crypto";
+import type { Message, ContentPart } from "../types/message.ts";
+import { writeFileDurable } from "../utils/durable.ts";
+import {
+  JOURNAL_FILE,
+  buildSessionData,
+  embeddedMedia,
+  quarantineIfCorrupt,
+  serializeSession,
+  stripRedundantRawArguments,
+  type SessionAgentLike,
+  type SessionPending,
+  type SessionPendingPrompt,
+  type SessionToolRecord,
+} from "./store.ts";
+
+/** A journal past this many lines is folded into a fresh snapshot. */
+const MAX_JOURNAL_LINES = 500;
+/** A journal past this many bytes is folded into a fresh snapshot. */
+const MAX_JOURNAL_BYTES = 4 * 1024 * 1024;
+
+const EMPTY_PENDING = JSON.stringify({ steer: [], queue: [] });
+
+// One `tool` journal line; the result is saved as given (tool results are JSON-safe by the time the executor returns them); in: a finished tool call, out: the journal.
+function toolLine(t: SessionToolRecord): string {
+  return JSON.stringify({ t: "tool", call: t.id, name: t.name, result: t.result, ...(t.isError ? { isError: true } : {}), ...(t.stopped ? { stopped: true } : {}) });
+}
+
+/** Persists one session folder (`sessions/<id>/`) step by step. */
+export class SessionJournal {
+  /** Epoch of the snapshot the journal belongs to; unset until the first snapshot (and after a failed append). */
+  private epoch: string | undefined;
+  /** How many messages are on disk, and the last one (identity check: history only grew since the last sync). */
+  private count = 0;
+  private last: Message | undefined;
+  private lines = 0;
+  private bytes = 0;
+  /** JSON of the last written non-message state (config, system prompt, worker traces). */
+  private meta = "";
+  /** How many run marks are on disk, and the last one. */
+  private runCount = 0;
+  private lastRun: unknown;
+  /** JSON of the last journaled waiting prompts. */
+  private pending = EMPTY_PENDING;
+  /** Run ids whose ending is on disk. */
+  private readonly endsOnDisk = new Set<string>();
+  /** How many of the current run's finished tool results are on disk, and the last one. */
+  private toolCount = 0;
+  private lastTool: unknown;
+  /** Disk form of each message already prepared (media replaced by `media/` files, redundant raw arguments dropped). */
+  private readonly onDisk = new WeakMap<Message, Message>();
+  /** Same for waiting prompts made of content parts. */
+  private readonly promptOnDisk = new WeakMap<ContentPart[], ContentPart[]>();
+
+  constructor(readonly dir: string) {}
+
+  // Brings the folder up to date with the agent: appends new messages and changed state, or writes a fresh snapshot when history changed another way; in: Agent.doPersist after every step, out: files in this.dir.
+  sync(agent: SessionAgentLike): void {
+    const messages = agent.context.messages;
+    const runs = agent.runMarks ?? [];
+    const grew =
+      this.epoch !== undefined &&
+      messages.length >= this.count &&
+      (this.count === 0 || messages[this.count - 1] === this.last) &&
+      runs.length >= this.runCount &&
+      (this.runCount === 0 || runs[this.runCount - 1] === this.lastRun);
+    if (!grew) {
+      this.snapshot(agent);
+      return;
+    }
+    const records: string[] = [];
+    for (let i = this.count; i < messages.length; i++) records.push(JSON.stringify({ t: "msg", i, m: this.toDisk(messages[i]!) }));
+    for (let r = this.runCount; r < runs.length; r++) records.push(JSON.stringify({ t: "run", id: runs[r]!.id, i: runs[r]!.i, at: runs[r]!.at }));
+    for (const mark of runs) {
+      if (mark.end && !this.endsOnDisk.has(mark.id)) records.push(JSON.stringify({ t: "end", id: mark.id, status: mark.end }));
+    }
+    const tools = agent.toolRecords ?? [];
+    const firstNewTool = this.toolCount > 0 && tools[this.toolCount - 1] === this.lastTool ? this.toolCount : 0; // a new run starts the list over
+    for (let k = firstNewTool; k < tools.length; k++) records.push(toolLine(tools[k]!));
+    const meta = this.metaOf(agent);
+    if (meta !== this.meta) records.push(`{"t":"meta","m":${meta}}`);
+    const pending = this.pendingOf(agent);
+    if (pending !== this.pending) records.push(`{"t":"pending","p":${pending}}`);
+    if (records.length === 0) return;
+    const text = records.join("\n") + "\n";
+    try {
+      const fd = fs.openSync(path.join(this.dir, JOURNAL_FILE), "a", 0o600);
+      try {
+        fs.writeFileSync(fd, text);
+        fs.fsyncSync(fd);
+      } finally {
+        fs.closeSync(fd);
+      }
+    } catch (err) {
+      this.epoch = undefined; // a half-written line may be on disk: the next sync starts over with a snapshot
+      throw err;
+    }
+    this.count = messages.length;
+    this.last = messages[messages.length - 1];
+    this.meta = meta;
+    this.runCount = runs.length;
+    this.lastRun = runs[runs.length - 1];
+    this.pending = pending;
+    this.toolCount = tools.length;
+    this.lastTool = tools[tools.length - 1];
+    for (const mark of runs) if (mark.end) this.endsOnDisk.add(mark.id);
+    this.lines += records.length;
+    this.bytes += text.length;
+    if (this.lines >= MAX_JOURNAL_LINES || this.bytes >= MAX_JOURNAL_BYTES) this.snapshot(agent);
+  }
+
+  // Writes `session.json` (new epoch) and then restarts the journal under that epoch; a crash in between leaves a journal with the old epoch, which load ignores; in: sync, out: both files.
+  private snapshot(agent: SessionAgentLike): void {
+    const messages = agent.context.messages;
+    const epoch = randomUUID();
+    const target = path.join(this.dir, "session.json");
+    if (this.epoch === undefined) quarantineIfCorrupt(target);
+    const data = buildSessionData({ ...agent, context: { ...agent.context, messages: messages.map((m) => this.toDisk(m)) } }, null);
+    writeFileDurable(target, serializeSession({ ...data, epoch }) + "\n");
+    const pending = this.pendingOf(agent);
+    const tools = agent.toolRecords ?? [];
+    // Waiting prompts and the current run's finished tool results live only in the journal, so a new journal starts with them.
+    const header =
+      JSON.stringify({ t: "base", e: epoch }) + "\n" + (pending === EMPTY_PENDING ? "" : `{"t":"pending","p":${pending}}\n`) + tools.map((t) => toolLine(t) + "\n").join("");
+    writeFileDurable(path.join(this.dir, JOURNAL_FILE), header, { backup: false });
+    this.epoch = epoch;
+    this.pending = pending;
+    this.runs(agent);
+    this.count = messages.length;
+    this.last = messages[messages.length - 1];
+    this.lines = (pending === EMPTY_PENDING ? 0 : 1) + tools.length;
+    this.toolCount = tools.length;
+    this.lastTool = tools[tools.length - 1];
+    this.endsOnDisk.clear();
+    for (const mark of agent.runMarks ?? []) if (mark.end) this.endsOnDisk.add(mark.id); // the snapshot holds them
+    this.bytes = 0;
+    this.meta = this.metaOf(agent);
+  }
+
+  // Remembers which run marks the snapshot already holds; in: snapshot, out: the next sync's "which marks are new".
+  private runs(agent: SessionAgentLike): void {
+    const runs = agent.runMarks ?? [];
+    this.runCount = runs.length;
+    this.lastRun = runs[runs.length - 1];
+  }
+
+  // JSON of the waiting prompts with media moved to files; in: the agent's steer inbox + follow-up queue, out: change detection + the `pending` record.
+  private pendingOf(agent: SessionAgentLike): string {
+    const waiting = agent.pendingPrompts?.();
+    if (!waiting || waiting.steer.length + waiting.queue.length === 0) return EMPTY_PENDING;
+    const parts = (prompt: ContentPart[]): ContentPart[] => {
+      let disk = this.promptOnDisk.get(prompt);
+      if (!disk) this.promptOnDisk.set(prompt, (disk = this.toDisk({ role: "user", content: prompt }).content as ContentPart[]));
+      return disk;
+    };
+    const slim = (list: SessionPendingPrompt[]): SessionPendingPrompt[] =>
+      list.map((w) => ({ ...w, prompt: typeof w.prompt === "string" ? w.prompt : parts(w.prompt) }));
+    return JSON.stringify({ steer: slim(waiting.steer), queue: slim(waiting.queue) } satisfies SessionPending);
+  }
+
+  // JSON of everything in the snapshot that is not a message, identity or totals; in: the live agent, out: change detection + the `meta` record.
+  private metaOf(agent: SessionAgentLike): string {
+    const { version: _v, sessionId: _s, messages: _m, totals: _t, runs: _r, ...rest } = buildSessionData(
+      { ...agent, context: { ...agent.context, messages: [] } },
+      null
+    );
+    return JSON.stringify(rest);
+  }
+
+  // The form of a message that goes to disk: embedded media written once as `media/<kind>-h<hash>.<ext>` (content-addressed, never deleted or renumbered), redundant raw arguments dropped; in: a live message, out: journal lines and snapshots.
+  private toDisk(message: Message): Message {
+    const known = this.onDisk.get(message);
+    if (known) return known;
+    const slim = stripRedundantRawArguments([message])[0]!;
+    let out = slim;
+    if (Array.isArray(slim.content)) {
+      let changed = false;
+      const content = (slim.content as ContentPart[]).map((part) => {
+        const found = embeddedMedia(part);
+        if (!found) return part;
+        const file = `${found.key}-h${createHash("sha256").update(found.bytes).digest("hex").slice(0, 16)}.${found.ext}`;
+        const dest = path.join(this.dir, "media", file);
+        if (!fs.existsSync(dest)) writeFileDurable(dest, found.bytes, { backup: false });
+        changed = true;
+        return { ...(part as unknown as Record<string, unknown>), [found.key]: `media/${file}`, ...(found.mimeType ? { mimeType: found.mimeType } : {}) } as unknown as ContentPart;
+      });
+      if (changed) out = { ...slim, content };
+    }
+    this.onDisk.set(message, out);
+    return out;
+  }
+}