Skip to content

armgit / alook

Public Imported from GitHub
0

Multi-Agent Collaboration for Team and Friends

feat(daemon): add opt-in raw runtime trace

Gusced2d4437e7f
diff --git a/src/daemon/src/daemon/createDaemon.test.ts b/src/daemon/src/daemon/createDaemon.test.ts
index 5ebeb10e3..8039e1b99 100644
--- a/src/daemon/src/daemon/createDaemon.test.ts
+++ b/src/daemon/src/daemon/createDaemon.test.ts
@@ -1,6 +1,15 @@
import { describe, it, expect, vi, afterEach } from "vitest";
import { EventEmitter } from "events";
-import { createDaemon, deriveAuditLogSubcommand, emitImplicitTypingStopOnSend } from "./createDaemon";
+import { existsSync, mkdtempSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+ createDaemon,
+ createRuntimeRawLineTap,
+ deriveAuditLogSubcommand,
+ emitImplicitTypingStopOnSend,
+ parseRuntimeRawTraceAgentIds,
+} from "./createDaemon";
import type { Driver } from "../types";
import type { Logger } from "../logger";
@@ -154,6 +163,111 @@ describe("createDaemon", () => {
});
});
+describe("createDaemon — opt-in raw runtime trace (P0-1)", () => {
+ const dirs: string[] = [];
+ afterEach(() => {
+ for (const dir of dirs.splice(0)) rmSync(dir, { recursive: true, force: true });
+ });
+
+ it("parses only explicit comma-separated agent ids and rejects the all-agents wildcard", () => {
+ expect([...parseRuntimeRawTraceAgentIds(" agent_a,agent_b,agent_a,*, ")]).toEqual([
+ "agent_a",
+ "agent_b",
+ ]);
+ expect(parseRuntimeRawTraceAgentIds(undefined).size).toBe(0);
+ });
+
+ it("stays disabled without both a trace directory and an explicit agent", () => {
+ const logger = stubLogger();
+ expect(createRuntimeRawLineTap({ traceDir: "/tmp/no-create", enabledAgentIds: new Set(), logger })).toBeUndefined();
+ expect(createRuntimeRawLineTap({ enabledAgentIds: new Set(["a1"]), logger })).toBeUndefined();
+ });
+
+ it("writes only selected agents, preserves raw lines, and encodes the agent filename", () => {
+ const dir = mkdtempSync(join(tmpdir(), "runtime-raw-trace-"));
+ dirs.push(dir);
+ const selectedAgent = "../agent_a";
+ const tap = createRuntimeRawLineTap({
+ traceDir: dir,
+ enabledAgentIds: new Set([selectedAgent]),
+ logger: stubLogger(),
+ });
+ expect(tap).toBeDefined();
+
+ tap?.("agent_b", '{"ignored":true}');
+ tap?.(selectedAgent, '{"jsonrpc":"2.0","vendor":"kept"}');
+
+ const path = join(dir, "runtime-raw-events-%2E%2E%2Fagent_a.jsonl");
+ expect(readFileSync(path, "utf8")).toBe('{"jsonrpc":"2.0","vendor":"kept"}\n');
+ expect(statSync(path).mode & 0o777).toBe(0o600);
+ expect(existsSync(join(dir, "runtime-raw-events-agent_b.jsonl"))).toBe(false);
+ });
+
+ it("rotates each selected agent independently and keeps both generations at 0600", () => {
+ const dir = mkdtempSync(join(tmpdir(), "runtime-raw-trace-"));
+ dirs.push(dir);
+ const tap = createRuntimeRawLineTap({
+ traceDir: dir,
+ enabledAgentIds: new Set(["a1", "a2"]),
+ logger: stubLogger(),
+ maxBytes: 20,
+ });
+ tap?.("a1", "x".repeat(19));
+ tap?.("a1", "latest-a1");
+ tap?.("a2", "only-a2");
+
+ const a1 = join(dir, "runtime-raw-events-a1.jsonl");
+ const a2 = join(dir, "runtime-raw-events-a2.jsonl");
+ expect(readFileSync(a1, "utf8")).toBe("latest-a1\n");
+ expect(existsSync(`${a1}.1`)).toBe(true);
+ expect(readFileSync(a2, "utf8")).toBe("only-a2\n");
+ for (const path of [a1, `${a1}.1`, a2]) {
+ expect(statSync(path).mode & 0o777).toBe(0o600);
+ expect(statSync(path).size).toBeLessThanOrEqual(20);
+ }
+ });
+
+ it("drops an oversized multibyte line, warns once, and keeps the file hard-capped", () => {
+ const dir = mkdtempSync(join(tmpdir(), "runtime-raw-trace-"));
+ dirs.push(dir);
+ const logger = stubLogger();
+ const tap = createRuntimeRawLineTap({
+ traceDir: dir,
+ enabledAgentIds: new Set(["a1"]),
+ logger,
+ maxBytes: 6,
+ });
+
+ tap?.("a1", "ééé");
+ tap?.("a1", "ééé");
+ tap?.("a1", "ok");
+
+ const path = join(dir, "runtime-raw-events-a1.jsonl");
+ expect(readFileSync(path, "utf8")).toBe("ok\n");
+ expect(statSync(path).size).toBeLessThanOrEqual(6);
+ expect(logger.calls.warn.filter(([, message]) => message === "runtime raw trace sink failed")).toHaveLength(1);
+ });
+
+ it("warns once per agent when the sink is unwritable and never throws", () => {
+ const dir = mkdtempSync(join(tmpdir(), "runtime-raw-trace-"));
+ dirs.push(dir);
+ const blocker = join(dir, "not-a-directory");
+ writeFileSync(blocker, "x");
+ const logger = stubLogger();
+ const tap = createRuntimeRawLineTap({
+ traceDir: blocker,
+ enabledAgentIds: new Set(["a1"]),
+ logger,
+ });
+
+ expect(() => {
+ tap?.("a1", "one");
+ tap?.("a1", "two");
+ }).not.toThrow();
+ expect(logger.calls.warn.filter(([, message]) => message === "runtime raw trace sink failed")).toHaveLength(1);
+ });
+});
+
describe("createDaemon — logging", () => {
const originalFetch = global.fetch;
afterEach(() => {
diff --git a/src/daemon/src/daemon/createDaemon.ts b/src/daemon/src/daemon/createDaemon.ts
index eea018676..3880f1cc4 100644
--- a/src/daemon/src/daemon/createDaemon.ts
+++ b/src/daemon/src/daemon/createDaemon.ts
@@ -58,9 +58,74 @@ const WARMUP_CEILING_MS = 30_000;
* unsampled (full-fidelity deep dives).
*/
const FSM_TRACE_MAX_BYTES = 8 * 1024 * 1024;
+const RUNTIME_RAW_TRACE_MAX_BYTES = 8 * 1024 * 1024;
+export const RUNTIME_RAW_TRACE_AGENT_IDS_ENV = "ALOOK_RUNTIME_RAW_TRACE_AGENT_IDS";
/** How often the daemon rewrites the `daemon status` snapshot file (batch E2). */
const STATUS_WRITE_INTERVAL_MS = 5_000;
+export function parseRuntimeRawTraceAgentIds(value: string | undefined): ReadonlySet<string> {
+ return new Set(
+ (value ?? "")
+ .split(",")
+ .map((agentId) => agentId.trim())
+ .filter((agentId) => agentId.length > 0 && agentId !== "*"),
+ );
+}
+
+export function createRuntimeRawLineTap(args: {
+ traceDir?: string;
+ enabledAgentIds: ReadonlySet<string>;
+ logger: Pick<Logger, "warn">;
+ maxBytes?: number;
+}): ((agentId: string, line: string) => void) | undefined {
+ if (!args.traceDir || args.enabledAgentIds.size === 0) return undefined;
+ const traceDir = args.traceDir;
+ const maxBytes = args.maxBytes ?? RUNTIME_RAW_TRACE_MAX_BYTES;
+ const sinks = new Map<string, ReturnType<typeof createRotatingFileSink>>();
+ const warned = new Set<string>();
+ const warnOnce = (agentId: string, path: string, operation: string, error: unknown): void => {
+ if (warned.has(agentId)) return;
+ warned.add(agentId);
+ args.logger.warn("runtime raw trace sink failed", {
+ agentId,
+ path,
+ operation,
+ error: error instanceof Error ? error.message : String(error),
+ });
+ };
+
+ return (agentId, line) => {
+ if (!args.enabledAgentIds.has(agentId)) return;
+ const encodedAgentId = encodeURIComponent(agentId).replace(/\./g, "%2E");
+ const path = `${traceDir}/runtime-raw-events-${encodedAgentId}.jsonl`;
+ const serializedBytes = Buffer.byteLength(line, "utf8") + 1;
+ if (serializedBytes > maxBytes) {
+ warnOnce(
+ agentId,
+ path,
+ "oversize",
+ new Error(`raw line is ${serializedBytes} bytes; max is ${maxBytes}`),
+ );
+ return;
+ }
+ let sink = sinks.get(agentId);
+ if (!sink) {
+ try {
+ mkdirSync(traceDir, { recursive: true });
+ } catch (error) {
+ warnOnce(agentId, path, "mkdir", error);
+ }
+ sink = createRotatingFileSink(path, maxBytes, {
+ mode: 0o600,
+ hardMaxBytes: true,
+ onError: ({ operation, error }) => warnOnce(agentId, path, operation, error),
+ });
+ sinks.set(agentId, sink);
+ }
+ sink.write(line);
+ };
+}
+
/**
* Derive the audit-log `cli_invocation` subcommand from a proxy request
* pathname. The credential proxy rewrites the CLI's bare `/api/*` calls onto
@@ -217,6 +282,11 @@ export async function createDaemon(opts: CreateDaemonOptions): Promise<RunningDa
// Self-healing: resolve CLI path with fallback if primary is missing
const resolvedCliPath = resolveAlookCliPathWithFallback(opts.agentCliPath);
+ const onRuntimeRawLine = createRuntimeRawLineTap({
+ traceDir: opts.fsmTraceDir,
+ enabledAgentIds: parseRuntimeRawTraceAgentIds(process.env[RUNTIME_RAW_TRACE_AGENT_IDS_ENV]),
+ logger: log,
+ });
const timeline = createTimelineRecorder({
timelineDirFor: (agentId) => `${workdirFor(agentId)}/.context_timeline`,
@@ -618,6 +688,7 @@ export async function createDaemon(opts: CreateDaemonOptions): Promise<RunningDa
// `ready` frame's `runningAgents` reflects what's actually live and the
// server's reconciler safety net can flip stale pills to idle.
onAgentLocallyStopped: (info) => router?.markLocallyStopped(info.agentId),
+ onRuntimeRawLine,
// FSM transition trace → file. One JSON line per reduce so a wedge that
// logs nothing else is reconstructable from its FSM history (the "no log
// when it breaks" fix, plans/daemon-fsm-desync.md). Two modes:
diff --git a/src/daemon/src/manager/managerRuntime.test.ts b/src/daemon/src/manager/managerRuntime.test.ts
index d453699d6..081b5f88d 100644
--- a/src/daemon/src/manager/managerRuntime.test.ts
+++ b/src/daemon/src/manager/managerRuntime.test.ts
@@ -1,4 +1,7 @@
import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { EventEmitter } from "events";
+import type { ChildProcess } from "child_process";
+import { PassThrough } from "stream";
import {
AgentProcessManager,
truncateThinking,
@@ -49,6 +52,27 @@ function fakeDriver(id: string): Driver {
} as unknown as Driver;
}
+function controllableChildDriver(id: string): { driver: Driver; stdout: PassThrough; parseLine: ReturnType<typeof vi.fn> } {
+ const stdout = new PassThrough();
+ const proc = Object.assign(new EventEmitter(), {
+ stdout,
+ stderr: new PassThrough(),
+ stdin: new PassThrough(),
+ pid: undefined,
+ exitCode: null,
+ signalCode: null,
+ kill: () => true,
+ }) as unknown as ChildProcess;
+ const parseLine = vi.fn(() => []);
+ const driver = {
+ ...fakeDriver(id),
+ lifecycle: { kind: "persistent", start: "immediate", exit: "natural", inFlightWake: "queue" },
+ spawn: async () => ({ process: proc }),
+ parseLine,
+ } as unknown as Driver;
+ return { driver, stdout, parseLine };
+}
+
// Fake session with manual EE that we can emit into from tests.
interface FakeSession extends ManagedSession {
fire(evt: string, ...args: unknown[]): void;
@@ -167,6 +191,55 @@ describe("AgentProcessManager — runtime health callbacks", () => {
});
});
+describe("AgentProcessManager — raw runtime line tap (P0-1)", () => {
+ it("adds agent identity before the default child-process session parses the line", async () => {
+ const { driver, stdout, parseLine } = controllableChildDriver("codex");
+ const onRuntimeRawLine = vi.fn();
+ const mgr = new AgentProcessManager({
+ driverFor: () => driver,
+ baseContextFor: () => ({
+ workingDirectory: "/tmp",
+ agentId: "agent_a",
+ standingPrompt: "",
+ config: {} as LaunchContext["config"],
+ credentialProxy: {} as LaunchContext["credentialProxy"],
+ }),
+ onRuntimeRawLine,
+ });
+ mgr.register("agent_a");
+ mgr.deliver("agent_a", { seq: 1, text: "hello" });
+ await new Promise((resolve) => setTimeout(resolve, 0));
+
+ stdout.write('{"vendor":"field"}\n');
+
+ expect(onRuntimeRawLine).toHaveBeenCalledWith("agent_a", '{"vendor":"field"}');
+ expect(parseLine).toHaveBeenCalledWith('{"vendor":"field"}');
+ });
+
+ it("does not attach the child stdout tap to a custom session factory", () => {
+ const session = fakeSession();
+ const sessionFactory = vi.fn(() => session);
+ const onRuntimeRawLine = vi.fn();
+ const mgr = new AgentProcessManager({
+ driverFor: () => fakeDriver("custom"),
+ baseContextFor: () => ({
+ workingDirectory: "/tmp",
+ agentId: "agent_a",
+ standingPrompt: "",
+ config: {} as LaunchContext["config"],
+ credentialProxy: {} as LaunchContext["credentialProxy"],
+ }),
+ sessionFactory,
+ onRuntimeRawLine,
+ });
+ mgr.register("agent_a");
+ mgr.deliver("agent_a", { seq: 1, text: "hello" });
+
+ expect(sessionFactory).toHaveBeenCalledTimes(1);
+ expect(onRuntimeRawLine).not.toHaveBeenCalled();
+ });
+});
+
describe("AgentProcessManager — logging", () => {
it("logs info on spawn start with agentId + runtime", () => {
const logger = stubLogger();
@@ -918,6 +991,7 @@ describe("AgentProcessManager — in-process SDK driver dispatch (Driver.createS
it("dispatches through SdkManagedSession (not a child process) when sdkDriverDepsFor is configured, and streams runtime_events normally", async () => {
const { driver, createSession } = fakeSdkDriver("pi");
const onRuntimeSessionEstablished = vi.fn();
+ const onRuntimeRawLine = vi.fn();
const sdkDeps: SdkDriverDeps = {
buildSpawnEnv: vi.fn().mockResolvedValue({}),
createAgentSession: vi.fn(),
@@ -932,6 +1006,7 @@ describe("AgentProcessManager — in-process SDK driver dispatch (Driver.createS
}),
sdkDriverDepsFor: () => sdkDeps,
onRuntimeSessionEstablished,
+ onRuntimeRawLine,
});
mgr.register("a1");
mgr.deliver("a1", { seq: 1, text: "hello" });
@@ -940,6 +1015,7 @@ describe("AgentProcessManager — in-process SDK driver dispatch (Driver.createS
expect(createSession).toHaveBeenCalledTimes(1);
expect(onRuntimeSessionEstablished).toHaveBeenCalledWith("pi");
+ expect(onRuntimeRawLine).not.toHaveBeenCalled();
});
it("does NOT require a credentialProxy for an in-process SDK driver (that guard is child-process-only)", () => {
diff --git a/src/daemon/src/manager/managerRuntime.ts b/src/daemon/src/manager/managerRuntime.ts
index ae3b6598f..32db35a81 100644
--- a/src/daemon/src/manager/managerRuntime.ts
+++ b/src/daemon/src/manager/managerRuntime.ts
@@ -157,6 +157,12 @@ export interface ManagerRuntimeOpts {
* so `ready.runningAgents` stays aligned with what's actually live.
*/
onAgentLocallyStopped?: (info: { agentId: string; reason: "stop" | "terminate_stalled" }) => void;
+ /**
+ * Observability-only tap for complete child-process stdout lines. The host
+ * owns persistence; the manager only adds agent identity before the shared
+ * runtime session parses the line. SDK sessions do not emit through it.
+ */
+ onRuntimeRawLine?: (agentId: string, line: string) => void;
/**
* Pure-observability FSM transition trace. Called once per `dispatch` reduce
* (for events carrying an agentId) with the post-reduce key fields + the
@@ -680,6 +686,7 @@ export class AgentProcessManager {
| "onAgentActivity"
| "onBotAuditEvent"
| "onAgentLocallyStopped"
+ | "onRuntimeRawLine"
| "onFsmTransition"
| "timeline"
| "wakePromptFooter"
@@ -698,6 +705,7 @@ export class AgentProcessManager {
| "onAgentActivity"
| "onBotAuditEvent"
| "onAgentLocallyStopped"
+ | "onRuntimeRawLine"
| "onFsmTransition"
| "timeline"
| "wakePromptFooter"
@@ -1408,6 +1416,7 @@ export class AgentProcessManager {
);
}
+ const rawLineSink = this.opts.onRuntimeRawLine;
const session: ManagedSession = this.opts.sessionFactory
? this.opts.sessionFactory({ agentId, driver, ctx })
: driver.createSession
@@ -1416,7 +1425,11 @@ export class AgentProcessManager {
ctx,
this.opts.sdkDriverDepsFor!(ctx),
)
- : (createChildProcessRuntimeSession(driver, ctx) as ChildProcessRuntimeSession);
+ : (createChildProcessRuntimeSession(
+ driver,
+ ctx,
+ rawLineSink ? { onRawStdoutLine: (line) => rawLineSink(agentId, line) } : undefined,
+ ) as ChildProcessRuntimeSession);
this.sessions.set(agentId, session);
diff --git a/src/daemon/src/runtime/runtimeSession.test.ts b/src/daemon/src/runtime/runtimeSession.test.ts
index 87dabc82b..975882d67 100644
--- a/src/daemon/src/runtime/runtimeSession.test.ts
+++ b/src/daemon/src/runtime/runtimeSession.test.ts
@@ -1,5 +1,7 @@
-import { describe, it, expect, afterEach } from "vitest";
+import { describe, it, expect, afterEach, vi } from "vitest";
+import { EventEmitter } from "events";
import { spawn, type ChildProcess } from "child_process";
+import { PassThrough } from "stream";
import { ChildProcessRuntimeSession } from "./runtimeSession.js";
import type { Driver, LaunchContext } from "../types.js";
@@ -46,6 +48,30 @@ function minimalCtx(): LaunchContext {
} as LaunchContext;
}
+function controllableDriver(parseLine: Driver["parseLine"]): {
+ driver: Driver;
+ stdout: PassThrough;
+} {
+ const stdout = new PassThrough();
+ const stderr = new PassThrough();
+ const stdin = new PassThrough();
+ const proc = Object.assign(new EventEmitter(), {
+ stdout,
+ stderr,
+ stdin,
+ pid: undefined,
+ exitCode: null,
+ signalCode: null,
+ kill: () => true,
+ }) as unknown as ChildProcess;
+ const driver = {
+ ...realSpawnDriver(),
+ spawn: async () => ({ process: proc }),
+ parseLine,
+ } as Driver;
+ return { driver, stdout };
+}
+
afterEach(() => {
for (const p of spawned.splice(0)) {
try { p.kill("SIGKILL"); } catch { /* already dead */ }
@@ -98,3 +124,45 @@ describe("ChildProcessRuntimeSession — real subprocess exit fills the physical
expect(exitInfo.signal).toBeNull();
});
});
+
+describe("ChildProcessRuntimeSession — raw stdout tap (P0-1)", () => {
+ it("taps each complete non-empty line before parseLine and preserves the original text", async () => {
+ const order: string[] = [];
+ const parseLine = vi.fn((line: string) => {
+ order.push(`parse:${line}`);
+ return [];
+ });
+ const { driver, stdout } = controllableDriver(parseLine);
+ const session = new ChildProcessRuntimeSession(driver, minimalCtx(), {
+ onRawStdoutLine: (line) => order.push(`raw:${line}`),
+ });
+ await session.start({ text: "go" });
+
+ stdout.write(" {\"jsonrpc\":\"2.0\"}");
+ stdout.write(" \n\npartial");
+
+ expect(order).toEqual([
+ 'raw: {"jsonrpc":"2.0"} ',
+ 'parse: {"jsonrpc":"2.0"} ',
+ ]);
+ expect(parseLine).toHaveBeenCalledTimes(1);
+ });
+
+ it("continues through parseLine and runtime_event when the tap throws", async () => {
+ const parsedEvent = { kind: "text", text: "ok" } as const;
+ const parseLine = vi.fn(() => [parsedEvent]);
+ const { driver, stdout } = controllableDriver(parseLine);
+ const session = new ChildProcessRuntimeSession(driver, minimalCtx(), {
+ onRawStdoutLine: () => {
+ throw new Error("sink failed");
+ },
+ });
+ const events: unknown[] = [];
+ session.on("runtime_event", (event) => events.push(event));
+ await session.start({ text: "go" });
+
+ expect(() => stdout.write('{"type":"message"}\n')).not.toThrow();
+ expect(parseLine).toHaveBeenCalledWith('{"type":"message"}');
+ expect(events).toEqual([parsedEvent]);
+ });
+});
diff --git a/src/daemon/src/runtime/runtimeSession.ts b/src/daemon/src/runtime/runtimeSession.ts
index 6e179980c..fcb7b312f 100644
--- a/src/daemon/src/runtime/runtimeSession.ts
+++ b/src/daemon/src/runtime/runtimeSession.ts
@@ -71,6 +71,11 @@ export interface SendInput {
mode?: StdinMode;
}
+export interface ChildProcessRuntimeSessionOptions {
+ /** Observability-only tap for each complete non-empty stdout line, before parsing. */
+ onRawStdoutLine?: (line: string) => void;
+}
+
export class ChildProcessRuntimeSession {
readonly descriptor: RuntimeSessionDescriptor;
private readonly events = new EventEmitter();
@@ -82,6 +87,7 @@ export class ChildProcessRuntimeSession {
constructor(
private readonly driver: Driver,
private readonly ctx: LaunchContext,
+ private readonly opts: ChildProcessRuntimeSessionOptions = {},
) {
this.descriptor = descriptorFromDriver(driver);
}
@@ -155,6 +161,11 @@ export class ChildProcessRuntimeSession {
this.stdoutBuffer = lines.pop() || "";
for (const line of lines) {
if (!line.trim()) continue;
+ try {
+ this.opts.onRawStdoutLine?.(line);
+ } catch {
+ /* an observability tap cannot alter runtime parsing */
+ }
for (const event of this.driver.parseLine(line)) {
this.events.emit("runtime_event", event);
}
@@ -174,6 +185,10 @@ export class ChildProcessRuntimeSession {
}
}
-export function createChildProcessRuntimeSession(driver: Driver, ctx: LaunchContext): ChildProcessRuntimeSession {
- return new ChildProcessRuntimeSession(driver, ctx);
+export function createChildProcessRuntimeSession(
+ driver: Driver,
+ ctx: LaunchContext,
+ opts?: ChildProcessRuntimeSessionOptions,
+): ChildProcessRuntimeSession {
+ return new ChildProcessRuntimeSession(driver, ctx, opts);
}
diff --git a/src/daemon/src/util/rotatingFileSink.test.ts b/src/daemon/src/util/rotatingFileSink.test.ts
index 75671b854..0383f112d 100644
--- a/src/daemon/src/util/rotatingFileSink.test.ts
+++ b/src/daemon/src/util/rotatingFileSink.test.ts
@@ -1,9 +1,14 @@
-import { describe, it, expect, beforeEach, afterEach } from "vitest";
-import { mkdtempSync, rmSync, existsSync, statSync, readFileSync } from "node:fs";
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import { chmodSync, mkdtempSync, mkdirSync, rmSync, existsSync, statSync, readFileSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { createRotatingFileSink } from "./rotatingFileSink";
+vi.mock("node:fs", async (importOriginal) => {
+ const actual = await importOriginal<typeof import("node:fs")>();
+ return { ...actual, chmodSync: vi.fn(actual.chmodSync) };
+});
+
describe("createRotatingFileSink (batch E1 — bounded default trace backing)", () => {
let dir: string;
beforeEach(() => {
@@ -51,4 +56,86 @@ describe("createRotatingFileSink (batch E1 — bounded default trace backing)",
const sink = createRotatingFileSink(join(dir, "nope", "trace.jsonl"), 1000);
expect(() => sink.write("line")).not.toThrow();
});
+
+ it("keeps secure mode on both active and rotated generations", () => {
+ const path = join(dir, "runtime-raw-events-a1.jsonl");
+ const sink = createRotatingFileSink(path, 20, { mode: 0o600 });
+ sink.write("a".repeat(20));
+ sink.write("latest");
+
+ expect(statSync(path).mode & 0o777).toBe(0o600);
+ expect(statSync(`${path}.1`).mode & 0o777).toBe(0o600);
+ });
+
+ it("secures a pre-existing broad active file before appending", () => {
+ const path = join(dir, "runtime-raw-events-a1.jsonl");
+ writeFileSync(path, "old\n");
+ chmodSync(path, 0o644);
+ const sink = createRotatingFileSink(path, 100, { mode: 0o600 });
+
+ sink.write("new");
+
+ expect(statSync(path).mode & 0o777).toBe(0o600);
+ expect(readFileSync(path, "utf8")).toBe("old\nnew\n");
+ });
+
+ it("drops a secure-mode write when chmod fails", () => {
+ const path = join(dir, "runtime-raw-events-a1.jsonl");
+ writeFileSync(path, "old\n");
+ const failures: Array<{ operation: string; error: unknown }> = [];
+ vi.mocked(chmodSync).mockImplementationOnce(() => {
+ throw new Error("chmod failed");
+ });
+ const sink = createRotatingFileSink(path, 100, {
+ mode: 0o600,
+ onError: (info) => failures.push(info),
+ });
+
+ sink.write("secret");
+
+ expect(readFileSync(path, "utf8")).toBe("old\n");
+ expect(failures.map(({ operation }) => operation)).toEqual(["chmod"]);
+ });
+
+ it("reports a write failure without throwing", () => {
+ const failures: Array<{ operation: string; error: unknown }> = [];
+ const sink = createRotatingFileSink(join(dir, "nope", "trace.jsonl"), 1000, {
+ mode: 0o600,
+ onError: (info) => failures.push(info),
+ });
+
+ expect(() => sink.write("line")).not.toThrow();
+ expect(failures).toHaveLength(1);
+ expect(failures[0]?.operation).toBe("append");
+ });
+
+ it("reports a rotation failure and continues writing", () => {
+ const failures: Array<{ operation: string; error: unknown }> = [];
+ const path = join(dir, "trace.jsonl");
+ const sink = createRotatingFileSink(path, 20, {
+ onError: (info) => failures.push(info),
+ });
+ sink.write("a".repeat(20));
+ mkdirSync(`${path}.1`);
+
+ expect(() => sink.write("latest")).not.toThrow();
+ expect(failures.some(({ operation }) => operation === "rotate")).toBe(true);
+ expect(readFileSync(path, "utf8")).toContain("latest\n");
+ });
+
+ it("drops a hard-capped write when its required rotation fails", () => {
+ const failures: Array<{ operation: string; error: unknown }> = [];
+ const path = join(dir, "runtime-raw-events-a1.jsonl");
+ const sink = createRotatingFileSink(path, 20, {
+ hardMaxBytes: true,
+ onError: (info) => failures.push(info),
+ });
+ sink.write("a".repeat(19));
+ mkdirSync(`${path}.1`);
+
+ expect(() => sink.write("secret")).not.toThrow();
+ expect(failures.map(({ operation }) => operation)).toEqual(["rotate"]);
+ expect(readFileSync(path, "utf8")).toBe(`${"a".repeat(19)}\n`);
+ expect(statSync(path).size).toBeLessThanOrEqual(20);
+ });
});
diff --git a/src/daemon/src/util/rotatingFileSink.ts b/src/daemon/src/util/rotatingFileSink.ts
index e16aef29f..a1cd8fd99 100644
--- a/src/daemon/src/util/rotatingFileSink.ts
+++ b/src/daemon/src/util/rotatingFileSink.ts
@@ -24,47 +24,90 @@
* onFsmTransition callback, after the reduce), and keeping it sync avoids
* interleaving/ordering hazards a per-line async write would add.
*/
-import { appendFileSync, statSync, renameSync, existsSync } from "node:fs";
+import { appendFileSync, chmodSync, statSync, renameSync, existsSync } from "node:fs";
export interface RotatingFileSink {
/** Append one already-serialized line (a trailing newline is added). */
write(line: string): void;
}
+export interface RotatingFileSinkOptions {
+ /** Enforced before appending to an existing active generation. */
+ mode?: number;
+ /** Rotate before a write that would make the active generation exceed maxBytes. */
+ hardMaxBytes?: boolean;
+ /** Best-effort observability for callers that need to surface sink failure. */
+ onError?: (info: { operation: "stat" | "rotate" | "append" | "chmod"; error: unknown }) => void;
+}
+
/**
* @param path active file path; rotated file is `${path}.1`.
* @param maxBytes rotate once the active file reaches/exceeds this. Total
* on-disk ≈ 2×maxBytes. Must be > 0; non-positive disables
* rotation (unbounded) — callers that want a cap must pass > 0.
+ * hardMaxBytes callers must reject a serialized line larger
+ * than maxBytes before calling write.
*/
-export function createRotatingFileSink(path: string, maxBytes: number): RotatingFileSink {
- const rotate = (): void => {
+export function createRotatingFileSink(
+ path: string,
+ maxBytes: number,
+ opts: RotatingFileSinkOptions = {},
+): RotatingFileSink {
+ const report = (operation: "stat" | "rotate" | "append" | "chmod", error: unknown): void => {
+ try {
+ opts.onError?.({ operation, error });
+ } catch {
+ /* a diagnostic callback cannot break the sink */
+ }
+ };
+
+ const secureActive = (): boolean => {
+ if (opts.mode === undefined || !existsSync(path)) return true;
+ try {
+ chmodSync(path, opts.mode);
+ return true;
+ } catch (error) {
+ report("chmod", error);
+ return false;
+ }
+ };
+
+ const rotate = (): boolean => {
try {
// Overwrite any prior `.1` — we only keep one generation back.
renameSync(path, `${path}.1`);
- } catch {
+ return true;
+ } catch (error) {
+ report("rotate", error);
/* rename can fail (path gone, races) — swallow; next write recreates. */
+ return false;
}
};
- const currentSize = (): number => {
+ const currentSize = (): number | null => {
try {
return existsSync(path) ? statSync(path).size : 0;
- } catch {
- return 0;
+ } catch (error) {
+ report("stat", error);
+ return null;
}
};
return {
write(line: string): void {
try {
- // Rotate BEFORE the write that would breach the cap, so the active file
- // never grows unbounded between checks. (A single line can still exceed
- // maxBytes; that's fine — it lands in a freshly-rotated active file and
- // the next write rotates again. Bound holds within one line's slack.)
- if (maxBytes > 0 && currentSize() >= maxBytes) rotate();
- appendFileSync(path, line + "\n");
- } catch {
+ if (!secureActive()) return;
+ const serialized = line + "\n";
+ const measuredBytes = currentSize();
+ if (measuredBytes === null && opts.hardMaxBytes) return;
+ const currentBytes = measuredBytes ?? 0;
+ const shouldRotate = maxBytes > 0 && (opts.hardMaxBytes
+ ? currentBytes > 0 && currentBytes + Buffer.byteLength(serialized, "utf8") > maxBytes
+ : currentBytes >= maxBytes);
+ if (shouldRotate && !rotate() && opts.hardMaxBytes) return;
+ appendFileSync(path, serialized, opts.mode === undefined ? undefined : { mode: opts.mode });
+ } catch (error) {
+ report("append", error);
/* never let tracing break the daemon */
}
},