@ai-devkit/agent-manager 0.40.0 → 0.42.0

package/src/__tests__/harnesses/muse/MuseSessionParser.test.ts

@@ -0,0 +1,279 @@
+/**
+ * Tests for harnesses/muse/MuseSessionParser.ts — framed transcript parsing.
+ *
+ * Muse session.jsonl lines are frames: either a direct inner record, a
+ * `record_json` string, or a `retained_frame` wrapper whose children carry
+ * `record_json` strings. Inner records dispatch on `payload_type`.
+ */
+
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+import { AgentStatus } from "../../../adapters/AgentAdapter.js";
+import { MuseSessionParser } from "../../../harnesses/muse/MuseSessionParser.js";
+
+const SID = "01a12618-d918-7b63-91c8-4e896326eb1a";
+
+function frame(inner: unknown): string {
+  return JSON.stringify(inner);
+}
+
+function wrapped(inner: unknown): string {
+  return JSON.stringify({ record_json: JSON.stringify(inner) });
+}
+
+function retained(inner: unknown): string {
+  return JSON.stringify({
+    retained_frame: "session_permission_transaction",
+    frame_schema_version: 1,
+    children: [{ child_index: 0, record_json: JSON.stringify(inner) }],
+  });
+}
+
+function intent(text: string, sequence: number, recordedAtUs: number): unknown {
+  return {
+    schema_version: 1,
+    stream: { kind: "session", id: SID },
+    sequence,
+    recorded_at: recordedAtUs,
+    record_type: "event",
+    payload_type: "runtime.user_intent.accepted",
+    payload: {
+      intent_id: `intent-${sequence}`,
+      refill_blocks: [{ kind: "text", text }],
+    },
+  };
+}
+
+function assistantMessage(text: string, sequence: number, recordedAtUs: number): unknown {
+  return {
+    schema_version: 1,
+    stream: { kind: "session", id: SID },
+    sequence,
+    recorded_at: recordedAtUs,
+    record_type: "event",
+    payload_type: "runtime.session",
+    payload: {
+      kind: "run",
+      run_id: "run-1",
+      event: { kind: "assistant_message_committed", text },
+    },
+  };
+}
+
+function metadata(recordedAtUs: number): unknown {
+  return {
+    schema_version: 1,
+    stream: { kind: "session", id: SID },
+    sequence: 1,
+    recorded_at: recordedAtUs,
+    record_type: "event",
+    payload_type: "runtime.session.metadata",
+    payload: {
+      kind: "metadata",
+      record: { workspace_root: "/Users/tester/proj", model_id: "muse-spark-1.3" },
+    },
+  };
+}
+
+function nameChanged(name: string, sequence: number, recordedAtUs: number): unknown {
+  return {
+    schema_version: 1,
+    stream: { kind: "session", id: SID },
+    sequence,
+    recorded_at: recordedAtUs,
+    record_type: "event",
+    payload_type: "session.name.changed",
+    payload: { session_id: SID, previous_name: null, new_name: name },
+  };
+}
+
+describe("MuseSessionParser", () => {
+  let parser: MuseSessionParser;
+  const tempDirs: string[] = [];
+
+  beforeEach(() => {
+    parser = new MuseSessionParser();
+  });
+
+  afterEach(() => {
+    for (const dir of tempDirs) {
+      try {
+        fs.rmSync(dir, { recursive: true, force: true });
+      } catch {
+        /* best effort */
+      }
+    }
+    tempDirs.length = 0;
+  });
+
+  function writeTranscript(lines: string[]): string {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "muse-parser-test-"));
+    tempDirs.push(dir);
+    const filePath = path.join(dir, "session.jsonl");
+    fs.writeFileSync(filePath, lines.join("\n"));
+    return filePath;
+  }
+
+  it("returns null for missing or empty files", () => {
+    expect(parser.readSession("/nonexistent/session.jsonl", "/proj")).toBeNull();
+    expect(parser.readSession(writeTranscript([]), "/proj")).toBeNull();
+  });
+
+  it("skips unparseable lines and wrapper frames without records", () => {
+    const filePath = writeTranscript([
+      "not json at all",
+      JSON.stringify({ retained_frame: "x", children: [] }),
+      frame(intent("hello", 2, 1791640525332173)),
+    ]);
+    const session = parser.readSession(filePath, "/proj");
+    expect(session?.lastUserMessage).toBe("hello");
+  });
+
+  it("unwraps record_json strings and retained children", () => {
+    const filePath = writeTranscript([
+      wrapped(intent("first", 2, 1791640525332173)),
+      retained(intent("second", 3, 1791640525332174)),
+    ]);
+    const session = parser.readSession(filePath, "/proj");
+    expect(session?.firstUserMessage).toBe("first");
+    expect(session?.lastUserMessage).toBe("second");
+  });
+
+  it("reads workspace root, model, and display name", () => {
+    const filePath = writeTranscript([
+      frame(metadata(1791640525332173)),
+      frame(intent("hi", 2, 1791640525332174)),
+      frame(nameChanged("flowing-monoceros", 3, 1791640525332175)),
+    ]);
+    // Empty project path lets the recorded workspace root win (archive sessions).
+    const session = parser.readSession(filePath, "");
+    expect(session?.projectPath).toBe("/Users/tester/proj");
+    expect(session?.modelId).toBe("muse-spark-1.3");
+    expect(session?.displayName).toBe("flowing-monoceros");
+    // First user message is found even when it is not on the first line.
+    expect(session?.firstUserMessage).toBe("hi");
+  });
+
+  it("normalizes microsecond timestamps to millisecond dates", () => {
+    const filePath = writeTranscript([frame(intent("hi", 2, 1791640525332173))]);
+    const session = parser.readSession(filePath, "/proj");
+    expect(session?.lastActive).toEqual(new Date(1791640525332));
+  });
+
+  it("maps last user intent to RUNNING and committed reply to WAITING", () => {
+    const running = parser.readSession(
+      writeTranscript([
+        frame(intent("q", 2, 1791640525332173)),
+        frame(assistantMessage("a", 3, 1791640525332174)),
+        frame(intent("q2", 4, 1791640525332175)),
+      ]),
+      "/proj",
+    );
+    expect(parser.determineStatus(running!)).toBe(AgentStatus.RUNNING);
+
+    const waiting = parser.readSession(
+      writeTranscript([
+        frame(intent("q", 2, 1791640525332173)),
+        frame(assistantMessage("a", 3, 1791640525332174)),
+      ]),
+      "/proj",
+    );
+    expect(parser.determineStatus(waiting!)).toBe(AgentStatus.WAITING);
+  });
+
+  it("maps approval waits and terminal runs to WAITING and IDLE", () => {
+    const waiting = parser.readSession(
+      writeTranscript([
+        frame({
+          schema_version: 1,
+          stream: { kind: "session", id: SID },
+          sequence: 2,
+          recorded_at: 1791640525332173,
+          record_type: "event",
+          payload_type: "runtime.session",
+          payload: {
+            kind: "run",
+            run_id: "run-1",
+            event: { kind: "approval_wait.effect.started", tool_name: "edit" },
+          },
+        }),
+      ]),
+      "/proj",
+    );
+    expect(parser.determineStatus(waiting!)).toBe(AgentStatus.WAITING);
+
+    const idle = parser.readSession(
+      writeTranscript([
+        frame({
+          schema_version: 1,
+          stream: { kind: "session", id: SID },
+          sequence: 2,
+          recorded_at: 1791640525332173,
+          record_type: "event",
+          payload_type: "runtime.session",
+          payload: { kind: "run", run_id: "run-1", event: { kind: "terminal" } },
+        }),
+      ]),
+      "/proj",
+    );
+    expect(parser.determineStatus(idle!)).toBe(AgentStatus.IDLE);
+  });
+
+  it("returns UNKNOWN when no conversation signal exists", () => {
+    const session = parser.readSession(
+      writeTranscript([frame(metadata(1791640525332173))]),
+      "/proj",
+    );
+    expect(parser.determineStatus(session!)).toBe(AgentStatus.UNKNOWN);
+  });
+
+  it("getConversation returns ordered messages and honors tail", () => {
+    const filePath = writeTranscript([
+      frame(metadata(1791640525332173)),
+      frame(intent("first question", 2, 1791640525332174)),
+      frame(assistantMessage("first answer", 3, 1791640525332175)),
+      frame(intent("second question", 4, 1791640525332176)),
+    ]);
+    const full = parser.getConversation(filePath);
+    expect(full.map((m) => [m.role, m.content])).toEqual([
+      ["user", "first question"],
+      ["assistant", "first answer"],
+      ["user", "second question"],
+    ]);
+    const tail = parser.getConversation(filePath, { tail: 1 });
+    expect(tail).toEqual([
+      { role: "user", content: "second question", timestamp: expect.anything() },
+    ]);
+  });
+
+  it("returns [] for a missing transcript and tool calls in verbose mode", () => {
+    expect(parser.getConversation("/nonexistent/session.jsonl")).toEqual([]);
+    const filePath = writeTranscript([
+      frame({
+        schema_version: 1,
+        stream: { kind: "session", id: SID },
+        sequence: 2,
+        recorded_at: 1791640525332173,
+        record_type: "event",
+        payload_type: "runtime.session",
+        payload: {
+          kind: "run",
+          run_id: "run-1",
+          event: {
+            kind: "assistant_tool_calls_committed",
+            tool_calls: [{ tool_name: "read_file" }, { tool_name: "search" }],
+          },
+        },
+      }),
+    ]);
+    expect(parser.getConversation(filePath)).toEqual([]);
+    expect(parser.getConversation(filePath, { verbose: true })).toEqual([
+      {
+        role: "assistant",
+        content: "tool calls: read_file, search",
+        timestamp: expect.anything(),
+      },
+    ]);
+  });
+});

package/src/__tests__/harnesses/opencode/OpenCodeSessionParser.test.ts

@@ -143,6 +143,7 @@ function insertPart(
   db: Database.Database,
   input: { messageId: string; sessionId: string; data: unknown; timeCreated: number },
 ): void {
-  db.prepare("INSERT INTO part (message_id, session_id, data, time_created) VALUES (?, ?, ?, ?)")
-    .run(input.messageId, input.sessionId, JSON.stringify(input.data), input.timeCreated);
+  db.prepare(
+    "INSERT INTO part (message_id, session_id, data, time_created) VALUES (?, ?, ?, ?)",
+  ).run(input.messageId, input.sessionId, JSON.stringify(input.data), input.timeCreated);
 }

package/src/__tests__/harnesses/readiness/AgentReadiness.test.ts

@@ -68,6 +68,7 @@ function fixture(overrides: Partial<AgentReadinessOptions> = {}) {
     ".gemini/antigravity-cli",
     ".config/opencode",
     ".config/devin",
+    ".config/muse",
     ".pi",
   ]) {
     files[path.join(homeDir, directory)] = "<dir>";
@@ -128,6 +129,7 @@ describe("agent readiness", () => {
       "copilot",
       "pi",
       "devin",
+      "muse",
     ]);
     for (const [agent, report] of Object.entries(reports) as Array<
       [ReadinessAgentType, (typeof reports)[ReadinessAgentType]]
@@ -166,6 +168,7 @@ describe("agent readiness", () => {
     expect(reports.kiro.integration).toBeUndefined();
     expect(reports.antigravity_cli.integration).toBeUndefined();
     expect(reports.opencode.integration).toBeUndefined();
+    expect(reports.muse.integration).toBeUndefined();
   });
 
   it("resolves agent executables from PATH directories containing spaces", async () => {
@@ -309,6 +312,39 @@ describe("agent readiness", () => {
     });
   });
 
+  it("checks Muse auth from the muse auth.json file", async () => {
+    const authPath = path.join("/home/test", ".config", "muse", "auth.json");
+    const { options, files } = fixture();
+    files[authPath] = JSON.stringify({ meta: { token: "secret" } });
+
+    const report = await getAgentReadinessReport("muse", options);
+
+    expect(report.auth).toMatchObject({ state: "authenticated", status: "pass" });
+    expect(report.globalConfig).toMatchObject({ status: "pass" });
+  });
+
+  it("reports Muse as unauthenticated with an empty auth file", async () => {
+    const authPath = path.join("/home/test", ".config", "muse", "auth.json");
+    const { options, files } = fixture();
+    files[authPath] = JSON.stringify({});
+
+    const report = await getAgentReadinessReport("muse", options);
+
+    expect(report.auth).toMatchObject({
+      state: "unauthenticated",
+      status: "fail",
+      errors: ["Muse credential file has no entries"],
+    });
+  });
+
+  it("reports Muse as unauthenticated without an auth file", async () => {
+    const { options } = fixture();
+
+    const report = await getAgentReadinessReport("muse", options);
+
+    expect(report.auth).toMatchObject({ state: "unauthenticated", status: "fail" });
+  });
+
   it("reports Devin as unauthenticated without a login line", async () => {
     const { options } = fixture({
       runCommand: vi.fn(async (command) => {

package/src/__tests__/harnesses/runtimeProfiles.test.ts

@@ -36,6 +36,19 @@ describe("harness runtime profiles", () => {
     expect(runtimeAgentMatchesHarness("gemini", "gemini_cli")).toBe(true);
     expect(runtimeAgentMatchesHarness("codex", "claude")).toBe(false);
   });
+
+  it("profiles the versioned muse launcher", () => {
+    expect(HARNESS_RUNTIME_PROFILES.muse).toMatchObject({
+      command: "muse",
+      runtimeKind: "muse",
+      discoveryAliases: ["muse"],
+    });
+    expect(
+      HARNESS_RUNTIME_PROFILES.muse.matches("/Users/dev/.local/bin/muse-bin-1.4.4-R5419.1"),
+    ).toBe(true);
+    expect(HARNESS_RUNTIME_PROFILES.muse.matches("/usr/local/bin/muse")).toBe(true);
+    expect(runtimeAgentMatchesHarness("muse", "muse")).toBe(true);
+  });
 });
 
 describe("harness matchers with executables under paths containing spaces", () => {

package/src/__tests__/readiness-fixtures.test.ts

@@ -0,0 +1,79 @@
+/**
+ * Readiness fixture replay: each committed bundle under
+ * `fixtures/readiness/` provides the injectable seams (files,
+ * executables, command outputs, codexAuth) plus `expected` — the
+ * byte-identical reports the readiness probes must produce replaying
+ * the same bundle through their injectable seams.
+ */
+
+import { describe, it, expect } from "vitest";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import {
+  getAgentReadinessReports,
+  type AgentReadinessOptions,
+} from "../harnesses/readiness/AgentReadiness.js";
+
+interface ReadinessBundle {
+  options: {
+    homeDir: string;
+    path: string;
+    assetRoot?: string;
+    builtInSkillNames?: string[];
+    skillRoots?: Record<string, string>;
+  };
+  /** Absolute path → contents, or "<dir>" for a directory entry. */
+  files: Record<string, string>;
+  /** Paths that answer X_OK access. */
+  executables: string[];
+  /** `"command arg1 arg2"` → output; `ok: false` rejects like execFile. */
+  commands: Record<string, { stdout: string; stderr?: string; ok?: boolean }>;
+  codexAuth?: boolean | null;
+  expected: Record<string, unknown>;
+}
+
+const READINESS_ROOT = path.resolve(__dirname, "../../../..", "fixtures", "readiness");
+
+const bundlePaths = fs.existsSync(READINESS_ROOT)
+  ? fs
+      .readdirSync(READINESS_ROOT)
+      .filter((f) => f.endsWith(".json") && !f.startsWith("live"))
+      .sort()
+      .map((f) => path.join(READINESS_ROOT, f))
+  : [];
+
+function replay(bundle: ReadinessBundle): Promise<Record<string, unknown>> {
+  const executableSet = new Set(bundle.executables);
+  const options: AgentReadinessOptions = {
+    homeDir: bundle.options.homeDir,
+    path: bundle.options.path,
+    assetRoot: bundle.options.assetRoot,
+    builtInSkillNames: bundle.options.builtInSkillNames ?? [],
+    skillRoots: bundle.options.skillRoots ?? {},
+    readFile: async (target) => {
+      if (!(target in bundle.files)) throw new Error("missing");
+      return bundle.files[target];
+    },
+    access: async (target) => {
+      if (executableSet.has(target) || target in bundle.files) return;
+      throw new Error("missing");
+    },
+    runCommand: async (command, args) => {
+      const key = [command, ...args].join(" ");
+      const stub = bundle.commands[key];
+      if (!stub) throw new Error(`unexpected command ${key}`);
+      if (stub.ok === false) throw new Error(`command failed: ${key}`);
+      return { stdout: stub.stdout, stderr: stub.stderr ?? "" };
+    },
+    codexAuth: async () => bundle.codexAuth ?? null,
+  };
+  return getAgentReadinessReports(options);
+}
+
+describe("readiness fixture replay", () => {
+  it.each(bundlePaths)("%s", async (bundlePath) => {
+    const bundle = JSON.parse(fs.readFileSync(bundlePath, "utf8")) as ReadinessBundle;
+    const reports = await replay(bundle);
+    expect(reports).toEqual(bundle.expected);
+  });
+});

package/src/__tests__/utils/process.test.ts

@@ -18,6 +18,8 @@ import {
   captureProcessSnapshot,
   createProcessSnapshotCapture,
   filterByProcessNames,
+  matchesExecutablePrefix,
+  snapshotOptions,
   executableBasename,
   executablePath,
   type ProcessExec,
@@ -259,6 +261,34 @@ describe("filterByProcessNames", () => {
     expect(filterByProcessNames(processes, ["node"])).toEqual([processes[0], processes[1]]);
     expect(filterByProcessNames(processes, ["node.exe"])).toEqual([processes[0], processes[1]]);
   });
+
+  it("matches versioned launchers by basename prefix without leaking to siblings", () => {
+    const processes: ProcessInfo[] = [
+      { pid: 1, command: "/Users/dev/.local/bin/muse-bin-1.4.4-R5419.1", cwd: "", tty: "" },
+      { pid: 2, command: "/usr/local/bin/muse", cwd: "", tty: "" },
+      { pid: 3, command: "/usr/bin/museums", cwd: "", tty: "" },
+      { pid: 4, command: "/usr/local/bin/claude", cwd: "", tty: "" },
+    ];
+
+    expect(filterByProcessNames(processes, ["muse"], ["muse"])).toEqual([
+      processes[0],
+      processes[1],
+    ]);
+    // Exact names alone never match the versioned launcher.
+    expect(filterByProcessNames(processes, ["muse"])).toEqual([processes[1]]);
+    // No prefixes: previous behavior is unchanged.
+    expect(filterByProcessNames(processes, ["claude"])).toEqual([processes[3]]);
+    expect(matchesExecutablePrefix(processes[0].command, new Set(["muse"]))).toBe(true);
+    expect(matchesExecutablePrefix(processes[2].command, new Set(["muse"]))).toBe(false);
+    expect(matchesExecutablePrefix(processes[0].command, new Set())).toBe(false);
+  });
+
+  it("builds snapshot options with prefixes only when present", () => {
+    const isCandidate = () => true;
+    expect(snapshotOptions([], isCandidate)).toEqual({ isCandidate });
+    const withPrefixes = snapshotOptions(["muse"], isCandidate);
+    expect(withPrefixes).toMatchObject({ namePrefixes: ["muse"], isCandidate });
+  });
 });
 
 describe("executables installed under paths containing spaces", () => {

package/src/adapters/AgentAdapter.ts

@@ -17,6 +17,7 @@ export const AGENT_TYPES = [
   "copilot",
   "pi",
   "devin",
+  "muse",
 ] as const;
 
 /**
@@ -201,6 +202,14 @@ export interface AgentAdapter {
   /** Executable basenames required for shared process discovery. */
   readonly processNames?: readonly string[];
 
+  /**
+   * Basename prefixes for shared process discovery: an argv[0] basename
+   * matches when it equals the prefix or starts with `<prefix>-`.
+   * For versioned launchers such as `muse-bin-1.4.4-R5419.1`.
+   * Recall-oriented like `processNames`; `canHandle` stays the precision gate.
+   */
+  readonly processNamePrefixes?: readonly string[];
+
   /**
    * Detect running agents of this type
    * @returns List of detected agents

package/src/fixtures/bundle.ts

@@ -0,0 +1,130 @@
+/**
+ * Golden-fixture bundles: the parity oracle for the devkit-harness Rust port.
+ * A bundle records everything `detectAgents` consumed and produced so both
+ * the TS adapter and its Rust port can be run against identical inputs.
+ *
+ * Format (committed under fixtures/harness/<type>/<case>.json):
+ * {
+ *   adapter, capturedAt, frozenNow,
+ *   processes: ProcessInfo[],
+ *   home: { "<relpath under $FIXTURE_HOME>": "<content with $FIXTURE_HOME refs>" },
+ *   expected: AgentInfo[] (dates as ISO strings)
+ * }
+ */
+
+import type { AgentInfo, ProcessInfo } from "../adapters/AgentAdapter.js";
+
+export const HOME_PLACEHOLDER = "$FIXTURE_HOME";
+/** Resolves to the instant home files were written (birthtime matching). */
+export const NOW_PLACEHOLDER = "$NOW";
+/** Resolves to the local `YYYY/MM/DD` day dir at replay (Codex sessions). */
+export const TODAY_PLACEHOLDER = "$TODAY";
+
+export interface FixtureBundle {
+  adapter: string;
+  capturedAt: string;
+  /** Epoch ms the clock was frozen at; `"$NOW"` = materialization instant. */
+  frozenNow: number | string;
+  processes: ProcessInfo[];
+  /** Files under the fixture HOME; content may embed HOME_PLACEHOLDER. */
+  home: Record<string, string>;
+  /**
+   * mtime overrides keyed by `home` relpath — epoch ms, or "$NOW" for the
+   * materialization instant. Adapters whose output derives from file mtimes
+   * (Grok's lastActive / latest-session pick) need deterministic mtimes.
+   */
+  mtimes?: Record<string, number | string>;
+  /**
+   * AgentRegistry rows (pid→sessionFilePath etc.) visible at capture time,
+   * restricted to captured process pids — adapters' registry caches read
+   * this state, so replay seeds an isolated registry with it.
+   */
+  registry?: Record<string, unknown>[];
+  /**
+   * SQLite stores adapters consult (OpenCode's opencode.db), keyed by
+   * relpath under $FIXTURE_HOME: SQL statements (DDL + INSERTs) executed
+   * in order to materialize each db. Statements may embed HOME_PLACEHOLDER.
+   */
+  sqlite?: Record<string, string[]>;
+  expected: Record<string, unknown>[];
+}
+
+/**
+ * Rewrite harness dot-dir paths (`<home>/.claude`, `<home>/.codex`, …) to the
+ * placeholder — nothing else. Project cwds share the home prefix
+ * (`<home>/Code/proj`) and MUST stay literal: harnesses encode them into
+ * session-dir names (`-Users-foo-proj`), so rewriting them breaks
+ * cwd↔session matching on replay.
+ */
+export function sanitize<T>(value: T, realHome: string): T {
+  const homeDot = `${realHome}/.`;
+  if (typeof value === "string") {
+    return value.split(homeDot).join(`${HOME_PLACEHOLDER}/.`) as T;
+  }
+  if (Array.isArray(value)) return value.map((v) => sanitize(v, realHome)) as T;
+  if (value && typeof value === "object") {
+    if (value instanceof Date) return value.toISOString() as T;
+    const out: Record<string, unknown> = {};
+    for (const [k, v] of Object.entries(value)) out[k] = sanitize(v, realHome);
+    return out as T;
+  }
+  return value;
+}
+
+/** Inverse of sanitize: expand the placeholder to a concrete dir. */
+export function expand<T>(value: T, fixtureHome: string): T {
+  if (typeof value === "string") {
+    return value.split(HOME_PLACEHOLDER).join(fixtureHome) as T;
+  }
+  if (Array.isArray(value)) return value.map((v) => expand(v, fixtureHome)) as T;
+  if (value && typeof value === "object" && !(value instanceof Date)) {
+    const out: Record<string, unknown> = {};
+    for (const [k, v] of Object.entries(value)) out[k] = expand(v, fixtureHome);
+    return out as T;
+  }
+  return value;
+}
+
+/** Replace NOW_PLACEHOLDER strings with a resolved ISO instant. */
+export function expandNow<T>(value: T, isoInstant: string): T {
+  if (typeof value === "string") {
+    return value.split(NOW_PLACEHOLDER).join(isoInstant) as T;
+  }
+  if (Array.isArray(value)) return value.map((v) => expandNow(v, isoInstant)) as T;
+  if (value && typeof value === "object" && !(value instanceof Date)) {
+    const out: Record<string, unknown> = {};
+    for (const [k, v] of Object.entries(value)) out[k] = expandNow(v, isoInstant);
+    return out as T;
+  }
+  return value;
+}
+
+/** Agents normalized the way the wire carries them (Date → ISO string). */
+export function normalizeAgents(agents: AgentInfo[], realHome: string) {
+  return sanitize(JSON.parse(JSON.stringify(agents)), realHome);
+}
+
+/**
+ * Freeze `Date` at `epochMs` for the duration of `fn`. Adapters stamp
+ * `new Date()` in several places; parity requires a fixed clock.
+ */
+export async function withFrozenClock<T>(epochMs: number, fn: () => Promise<T>): Promise<T> {
+  const RealDate = Date;
+  class FrozenDate extends RealDate {
+    constructor(...args: unknown[]) {
+      if (args.length === 0) super(epochMs);
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      else super(...(args as [any]));
+    }
+    static override now() {
+      return epochMs;
+    }
+  }
+  const g = globalThis as { Date: DateConstructor };
+  g.Date = FrozenDate as DateConstructor;
+  try {
+    return await fn();
+  } finally {
+    g.Date = RealDate;
+  }
+}