Skip to content

armgit / alook

Public Imported from GitHub
0

Multi-Agent Collaboration for Team and Friends

feat(daemon): add structured logging + fix machine status stuck offline

Gus10080b0fe6be
diff --git a/src/daemon/README.md b/src/daemon/README.md
index 5c39121ec..2407fd1e7 100644
--- a/src/daemon/README.md
+++ b/src/daemon/README.md
@@ -110,6 +110,8 @@ concrete message and terminates the process on turn end.
src/
types.ts # Driver interface + ParsedEvent + lifecycle/capability types
index.ts # public entry point
+ logger.ts # tiny structured logger (ALOOK_LOG_LEVEL); wired through
+ # wsControlChannel.ts/agentRouter.ts/managerRuntime.ts too, not just cli/daemonStart.ts
drivers/
index.ts # getDriver(runtimeId) registry ← start here
cliTransport.ts # shared: state dir, token, decoupling cliName wrapper -> targetCommand, env
diff --git a/src/daemon/src/cli/daemonStart.ts b/src/daemon/src/cli/daemonStart.ts
index e173282cb..5617a3c95 100644
--- a/src/daemon/src/cli/daemonStart.ts
+++ b/src/daemon/src/cli/daemonStart.ts
@@ -416,6 +416,7 @@ export async function daemonStart(opts: DaemonStartOpts): Promise<void> {
arch: process.arch,
osRelease: os.release(),
daemonVersion: readDaemonVersion(),
+ logger: log,
onAuthRejected: () => {
log.error("machine key rejected by server — is it correct / has it expired?");
releaseLock(pf);
diff --git a/src/daemon/src/daemon/createDaemon.test.ts b/src/daemon/src/daemon/createDaemon.test.ts
index 02449813d..101cbef8f 100644
--- a/src/daemon/src/daemon/createDaemon.test.ts
+++ b/src/daemon/src/daemon/createDaemon.test.ts
@@ -1,6 +1,30 @@
-import { describe, it, expect, vi } from "vitest";
+import { describe, it, expect, vi, afterEach } from "vitest";
+import { EventEmitter } from "events";
import { createDaemon } from "./createDaemon";
import type { Driver } from "../types";
+import type { Logger } from "../logger";
+
+/** Stub logger — records calls per level, and hands out tagged children that report into the same store. */
+function stubLogger(): Logger & { calls: Record<"debug" | "info" | "warn" | "error", Array<[string, string, unknown[]]>> } {
+ const calls: Record<"debug" | "info" | "warn" | "error", Array<[string, string, unknown[]]>> = {
+ debug: [],
+ info: [],
+ warn: [],
+ error: [],
+ };
+ function make(tag: string): Logger {
+ const logger: Logger & { calls: typeof calls } = {
+ calls,
+ debug: (m: string, ...d: unknown[]) => calls.debug.push([tag, m, d]),
+ info: (m: string, ...d: unknown[]) => calls.info.push([tag, m, d]),
+ warn: (m: string, ...d: unknown[]) => calls.warn.push([tag, m, d]),
+ error: (m: string, ...d: unknown[]) => calls.error.push([tag, m, d]),
+ child: (childTag: string) => make(`${tag}:${childTag}`),
+ };
+ return logger;
+ }
+ return make("root") as ReturnType<typeof stubLogger>;
+}
class FakeSocket {
url: string;
@@ -32,6 +56,27 @@ const fakeDriver: Driver = {
status: vi.fn(),
} as unknown as Driver;
+/** A driver complete enough for `AgentProcessManager.doSpawn` to actually spawn it. */
+function fullFakeDriver(id: string): Driver {
+ return {
+ id,
+ lifecycle: { kind: "per_turn", start: "immediate", exit: "natural", inFlightWake: "spawn_new" } as never,
+ session: { recovery: "resume_or_fresh" } as never,
+ model: { detectedModelsVerifiedAs: "launchable", toLaunchSpec: () => ({ args: [] }) } as never,
+ supportsStdinNotification: false,
+ busyDeliveryMode: "none",
+ probe: () => ({ status: "healthy" as const, version: "test" }),
+ spawn: async () => {
+ const proc = new EventEmitter() as unknown as { kill: () => void };
+ proc.kill = () => {};
+ return { process: proc as never };
+ },
+ parseLine: () => [],
+ encodeStdinMessage: () => null,
+ buildSystemPrompt: () => "",
+ } as unknown as Driver;
+}
+
function factory(sockets: FakeSocket[]) {
return (url: string, headers: Record<string, string>) => {
const s = new FakeSocket(url, headers);
@@ -108,3 +153,131 @@ describe("createDaemon", () => {
await daemon.stop();
});
});
+
+describe("createDaemon — logging", () => {
+ const originalFetch = global.fetch;
+ afterEach(() => {
+ global.fetch = originalFetch;
+ });
+
+ it("threads the shared logger into WsControlChannel/AgentRouter/AgentProcessManager, and logs bot:removed + a successful wake through the manager", async () => {
+ global.fetch = vi.fn(async (url: string | URL) => {
+ const href = String(url);
+ if (href.includes("/enroll-agent")) {
+ return new Response(JSON.stringify({ runnerKey: "rk_1" }), { status: 200 });
+ }
+ // Bots warmup — no bots needed, this test seeds botsById directly via bot:added.
+ return new Response(JSON.stringify({ bots: [] }), { status: 200 });
+ }) as unknown as typeof fetch;
+
+ const sockets: FakeSocket[] = [];
+ const logger = stubLogger();
+ const daemon = await createDaemon({
+ machineKey: "cmk_log",
+ serverUrl: "http://localhost:9999",
+ serverWsUrl: "ws://x",
+ webSocketFactory: factory(sockets) as any,
+ runtimeReport: [{ id: "codex" }],
+ driverFor: () => fullFakeDriver("codex"),
+ capabilities: [],
+ logger,
+ });
+ sockets[0].emit("open");
+ // ws-tagged log proves the channel got `.child("ws")`.
+ expect(logger.calls.info.some(([tag, m]) => tag.includes("ws") && m === "control channel open")).toBe(true);
+
+ sockets[0].emit(
+ "message",
+ JSON.stringify({ type: "bot:added", botId: "bot_1", name: "Bot One" }),
+ );
+ // bot:added is logged directly on the root logger (createDaemon's own tag).
+ expect(logger.calls.debug.some(([, m]) => m === "bot:added")).toBe(true);
+
+ sockets[0].emit(
+ "message",
+ JSON.stringify({
+ type: "agent:wake",
+ agentId: "bot_1",
+ config: { version: 1, runtime: "codex", model: { kind: "default" }, mode: { kind: "default" } },
+ launchId: "l1",
+ unreadNotice: { kind: "unread_notice", channel: "/demo/general", latestSeq: 1 },
+ }),
+ );
+ await new Promise((r) => setTimeout(r, 20));
+
+ // router-tagged log proves AgentRouter got `.child("router")`.
+ expect(logger.calls.info.some(([tag, m]) => tag.includes("router") && m === "agent:wake received")).toBe(true);
+ // manager-tagged log proves AgentProcessManager got `.child("manager")`.
+ expect(logger.calls.info.some(([tag, m]) => tag.includes("manager") && m === "spawning agent")).toBe(true);
+
+ sockets[0].emit("message", JSON.stringify({ type: "bot:removed", botId: "bot_1" }));
+ expect(logger.calls.debug.some(([, m]) => m === "bot:removed")).toBe(true);
+
+ await daemon.stop();
+ });
+
+ it("logs cold-start warmup success with the bot count", async () => {
+ global.fetch = vi.fn(async () => new Response(JSON.stringify({ bots: [{ id: "b1", name: "n" }] }), { status: 200 })) as unknown as typeof fetch;
+
+ const sockets: FakeSocket[] = [];
+ const logger = stubLogger();
+ const daemon = await createDaemon({
+ machineKey: "cmk_warmup_ok",
+ serverUrl: "http://localhost:9999",
+ serverWsUrl: "ws://x",
+ webSocketFactory: factory(sockets) as any,
+ runtimeReport: [],
+ driverFor: () => fakeDriver,
+ capabilities: [],
+ logger,
+ });
+ sockets[0].emit("open");
+ await new Promise((r) => setTimeout(r, 20));
+
+ expect(
+ logger.calls.info.some(([, m, d]) => m === "cold-start bot-cache warmup succeeded" && (d[0] as any).bots === 1),
+ ).toBe(true);
+ await daemon.stop();
+ });
+
+ it("logs enrollAgent's failure branch (bot known, enroll HTTP call fails)", async () => {
+ global.fetch = vi.fn(async (url: string | URL) => {
+ const href = String(url);
+ if (href.includes("/enroll-agent")) {
+ return new Response(JSON.stringify({ error: "server exploded" }), { status: 500 });
+ }
+ return new Response(JSON.stringify({ bots: [] }), { status: 200 });
+ }) as unknown as typeof fetch;
+
+ const sockets: FakeSocket[] = [];
+ const logger = stubLogger();
+ const daemon = await createDaemon({
+ machineKey: "cmk_enroll_fail",
+ serverUrl: "http://localhost:9999",
+ serverWsUrl: "ws://x",
+ webSocketFactory: factory(sockets) as any,
+ runtimeReport: [{ id: "codex" }],
+ driverFor: () => fullFakeDriver("codex"),
+ capabilities: [],
+ logger,
+ });
+ sockets[0].emit("open");
+ sockets[0].emit("message", JSON.stringify({ type: "bot:added", botId: "bot_1", name: "Bot One" }));
+ sockets[0].emit(
+ "message",
+ JSON.stringify({
+ type: "agent:wake",
+ agentId: "bot_1",
+ config: { version: 1, runtime: "codex", model: { kind: "default" }, mode: { kind: "default" } },
+ launchId: "l1",
+ unreadNotice: { kind: "unread_notice", channel: "/demo/general", latestSeq: 1 },
+ }),
+ );
+ await new Promise((r) => setTimeout(r, 20));
+
+ expect(
+ logger.calls.warn.some(([, m, d]) => m === "agent enroll failed" && (d[0] as any).agentId === "bot_1"),
+ ).toBe(true);
+ await daemon.stop();
+ });
+});
diff --git a/src/daemon/src/daemon/createDaemon.ts b/src/daemon/src/daemon/createDaemon.ts
index 36fc39f4e..40a34d677 100644
--- a/src/daemon/src/daemon/createDaemon.ts
+++ b/src/daemon/src/daemon/createDaemon.ts
@@ -28,6 +28,7 @@ import { AgentProcessManager, AgentRouter } from "../manager/index.js";
import { UnknownBotError, BotEnrollFailedError, UnknownRuntimeError } from "../manager/agentRouter.js";
import { createTimelineRecorder } from "../timeline/index.js";
import { resolveAlookCliPathWithFallback } from "../discovery.js";
+import { createLogger, type Logger } from "../logger.js";
import type { Driver, LaunchContext } from "../types.js";
import type { RuntimeConfig } from "../runtimeConfig.js";
import type { UnreadNotice, HostCommand } from "../server/contract.js";
@@ -81,6 +82,15 @@ export interface CreateDaemonOptions {
arch?: string;
osRelease?: string;
daemonVersion?: string;
+ /**
+ * Shared logger for the whole daemon process. Defaults to
+ * `createLogger({ header: "@alook/daemon" })`; `.child("ws")` /
+ * `.child("router")` / `.child("manager")` are passed into the respective
+ * collaborators so every line from one daemon process shares one header
+ * family. `daemonStart.ts` passes its own instance here so the process has
+ * exactly one logger tree instead of two independent ones.
+ */
+ logger?: Logger;
}
export interface RunningDaemon {
@@ -96,6 +106,7 @@ export interface RunningDaemon {
* the agent manager. The full real code path is exercised — no shortcuts.
*/
export async function createDaemon(opts: CreateDaemonOptions): Promise<RunningDaemon> {
+ const log = opts.logger ?? createLogger({ header: "@alook/daemon" });
const fallbackBase = (process.env.ALOOK_PROJECT_ROOT || `${homedir()}/.alook`) + "/daemon";
const workdirFor = (agentId: string) => `${opts.workingDirectoryBase ?? fallbackBase}/${agentId}`;
@@ -152,6 +163,7 @@ export async function createDaemon(opts: CreateDaemonOptions): Promise<RunningDa
for (const b of bots) {
botsById.set(b.id, { name: b.name, description: b.description });
}
+ log.info("cold-start bot-cache warmup succeeded", { bots: bots.length, attempt });
return;
} catch {
const delay = WARMUP_BACKOFF_MS[Math.min(attempt, WARMUP_BACKOFF_MS.length - 1)];
@@ -161,6 +173,7 @@ export async function createDaemon(opts: CreateDaemonOptions): Promise<RunningDa
}
// Ceiling exhausted — resolve empty. A subsequent `agent:wake` frame
// will trigger a deferred retry via enrollAgent.
+ log.warn("cold-start bot-cache warmup exhausted its ceiling", { ceilingMs: WARMUP_CEILING_MS, attempts: attempt });
}
const enrollAgent = async (agentId: string): Promise<string> => {
@@ -190,9 +203,12 @@ export async function createDaemon(opts: CreateDaemonOptions): Promise<RunningDa
return json.runnerKey;
} catch (err) {
if (err instanceof UnknownBotError || err instanceof BotEnrollFailedError) {
+ log.warn("agent enroll failed", { agentId, err: err.message });
throw err;
}
- throw new BotEnrollFailedError(agentId, err);
+ const wrapped = new BotEnrollFailedError(agentId, err);
+ log.warn("agent enroll failed", { agentId, err: wrapped.message });
+ throw wrapped;
}
};
@@ -201,6 +217,7 @@ export async function createDaemon(opts: CreateDaemonOptions): Promise<RunningDa
headers: { Authorization: `Bearer ${opts.machineKey}` },
webSocketFactory: opts.webSocketFactory as never,
onAuthRejected: opts.onAuthRejected,
+ logger: log.child("ws"),
});
// Cache-side handler for bot:* frames. Runs BEFORE AgentRouter sees them,
@@ -209,6 +226,7 @@ export async function createDaemon(opts: CreateDaemonOptions): Promise<RunningDa
switch (cmd.type) {
case "bot:added":
botsById.set(cmd.botId, { name: cmd.name, description: cmd.description });
+ log.debug("bot:added", { botId: cmd.botId, name: cmd.name });
break;
case "bot:updated": {
const prev = botsById.get(cmd.botId);
@@ -218,6 +236,7 @@ export async function createDaemon(opts: CreateDaemonOptions): Promise<RunningDa
// new system prompt. Rename is effective on next spawn, not mid-flight.
const nameChanged = prev && prev.name !== cmd.name;
const descChanged = prev && (prev.description ?? "") !== (cmd.description ?? "");
+ log.debug("bot:updated", { botId: cmd.botId, name: cmd.name });
if (nameChanged || descChanged) {
void manager.stop(cmd.botId);
}
@@ -226,6 +245,7 @@ export async function createDaemon(opts: CreateDaemonOptions): Promise<RunningDa
case "bot:removed":
botsById.delete(cmd.botId);
enrolledKeys.delete(cmd.botId);
+ log.debug("bot:removed", { botId: cmd.botId });
void manager.stop(cmd.botId);
break;
default:
@@ -281,6 +301,7 @@ export async function createDaemon(opts: CreateDaemonOptions): Promise<RunningDa
onAgentSession: (info) => void channel.reportAgentSession(info),
timeline,
wakePromptFooter: "Use `alook inbox pull` to read your messages, then reply with `alook message send`.",
+ logger: log.child("manager"),
});
manager.start();
@@ -293,6 +314,7 @@ export async function createDaemon(opts: CreateDaemonOptions): Promise<RunningDa
arch: opts.arch,
osRelease: opts.osRelease,
daemonVersion: opts.daemonVersion,
+ logger: log.child("router"),
// onBeforeAgent gate — reject unknown bots BEFORE enroll to keep the
// failure code stable (`bot_unknown` vs `bot_enroll_failed`).
onBeforeAgent: async (agentId) => {
diff --git a/src/daemon/src/logger.test.ts b/src/daemon/src/logger.test.ts
index 594e8e205..4242dc74f 100644
--- a/src/daemon/src/logger.test.ts
+++ b/src/daemon/src/logger.test.ts
@@ -1,4 +1,4 @@
-import { describe, it, expect } from "vitest";
+import { describe, it, expect, afterEach } from "vitest";
import { createLogger } from "./logger";
function capture() {
@@ -87,3 +87,40 @@ describe("createLogger", () => {
expect(c.out[0]).toBe("2026-06-25T12:00:00.000Z @alook/daemon INFO plain message");
});
});
+
+describe("createLogger — ALOOK_LOG_LEVEL env fallback", () => {
+ const ORIGINAL = process.env.ALOOK_LOG_LEVEL;
+ afterEach(() => {
+ if (ORIGINAL === undefined) delete process.env.ALOOK_LOG_LEVEL;
+ else process.env.ALOOK_LOG_LEVEL = ORIGINAL;
+ });
+
+ it("ALOOK_LOG_LEVEL=warn suppresses info/debug and still emits warn/error", () => {
+ process.env.ALOOK_LOG_LEVEL = "warn";
+ const c = capture();
+ const log = createLogger({ now: FIXED, ...c.sink });
+ log.debug("d");
+ log.info("i");
+ log.warn("w");
+ log.error("e");
+ expect(c.out).toEqual([]);
+ expect(c.err.map((l) => l.split(" ").pop())).toEqual(["w", "e"]);
+ });
+
+ it("an explicit options.level overrides the env var", () => {
+ process.env.ALOOK_LOG_LEVEL = "warn";
+ const c = capture();
+ const log = createLogger({ now: FIXED, level: "debug", ...c.sink });
+ log.debug("shown");
+ expect(c.out).toEqual(["2026-06-25T12:00:00.000Z @alook/daemon DEBUG shown"]);
+ });
+
+ it("an invalid ALOOK_LOG_LEVEL value falls back to the info default", () => {
+ process.env.ALOOK_LOG_LEVEL = "not-a-level";
+ const c = capture();
+ const log = createLogger({ now: FIXED, ...c.sink });
+ log.debug("hidden");
+ log.info("shown");
+ expect(c.out).toEqual(["2026-06-25T12:00:00.000Z @alook/daemon INFO shown"]);
+ });
+});
diff --git a/src/daemon/src/logger.ts b/src/daemon/src/logger.ts
index 222305ba1..ed0fbbafc 100644
--- a/src/daemon/src/logger.ts
+++ b/src/daemon/src/logger.ts
@@ -10,7 +10,10 @@
* (e.g. a sub-tag like `@alook/daemon:daemon`) so a line still says where it came
* from without each call site hand-prefixing `[daemon]`.
* - Default level is `info`; `debug` lines are suppressed unless the level is
- * lowered. `warn`/`error` go to stderr, `info`/`debug` to stdout.
+ * lowered. `warn`/`error` go to stderr, `info`/`debug` to stdout. When
+ * `options.level` isn't passed, the `ALOOK_LOG_LEVEL` env var is used as a
+ * fallback (same 4 values), so one env var controls verbosity for a whole
+ * daemon process without every call site threading it through explicitly.
* - Variadic data args are auto-formatted as key=value pairs when objects are
* passed, or stringified otherwise. This keeps the injectable-sink design
* (test-friendly) while making complex debug output painless.
@@ -44,6 +47,12 @@ export interface LoggerOptions {
}
const DEFAULT_HEADER = "@alook/daemon";
+const VALID_LEVELS: readonly LogLevel[] = ["debug", "info", "warn", "error"];
+
+function envLevel(): LogLevel | undefined {
+ const raw = process.env.ALOOK_LOG_LEVEL?.toLowerCase();
+ return VALID_LEVELS.includes(raw as LogLevel) ? (raw as LogLevel) : undefined;
+}
function formatData(data: unknown[]): string {
if (data.length === 0) return "";
@@ -65,7 +74,7 @@ function formatData(data: unknown[]): string {
export function createLogger(options: LoggerOptions = {}): Logger {
const header = options.header ?? DEFAULT_HEADER;
- const minRank = LEVEL_RANK[options.level ?? "info"];
+ const minRank = LEVEL_RANK[options.level ?? envLevel() ?? "info"];
const now = options.now ?? (() => new Date().toISOString());
const out = options.out ?? ((line) => process.stdout.write(line + "\n"));
const err = options.err ?? ((line) => process.stderr.write(line + "\n"));
diff --git a/src/daemon/src/manager/agentRouter.test.ts b/src/daemon/src/manager/agentRouter.test.ts
index 25728c753..bfcc08749 100644
--- a/src/daemon/src/manager/agentRouter.test.ts
+++ b/src/daemon/src/manager/agentRouter.test.ts
@@ -2,6 +2,26 @@ import { describe, it, expect } from "vitest";
import { AgentRouter, UnknownRuntimeError } from "./agentRouter";
import type { AgentProcessManager } from "./managerRuntime";
import type { HostControlChannel, HostCommand, SessionErrorFrame } from "../server/contract";
+import type { Logger } from "../logger";
+
+/** Stub logger — records calls per level for assertions. */
+function stubLogger(): Logger & { calls: Record<"debug" | "info" | "warn" | "error", Array<[string, unknown[]]>> } {
+ const calls: Record<"debug" | "info" | "warn" | "error", Array<[string, unknown[]]>> = {
+ debug: [],
+ info: [],
+ warn: [],
+ error: [],
+ };
+ const logger = {
+ calls,
+ debug: (m: string, ...d: unknown[]) => calls.debug.push([m, d]),
+ info: (m: string, ...d: unknown[]) => calls.info.push([m, d]),
+ warn: (m: string, ...d: unknown[]) => calls.warn.push([m, d]),
+ error: (m: string, ...d: unknown[]) => calls.error.push([m, d]),
+ child: () => logger,
+ };
+ return logger;
+}
/** Fake manager recording deliver/register; enough for router behavior tests. */
function fakeManager() {
@@ -316,3 +336,93 @@ describe("AgentRouter — runtime health map", () => {
expect(router.isRuntimeHealthy("codex")).toBe(false);
});
});
+
+describe("AgentRouter — logging", () => {
+ it("logs info when agent:wake is received, and info for the ack (ok status)", async () => {
+ const { mgr } = fakeManager();
+ const { ch, fire } = fakeChannel();
+ const logger = stubLogger();
+ const router = new AgentRouter({ manager: mgr, channel: ch, runtimeReport: [{ id: "mock" }], logger });
+ await router.start();
+
+ await fire({
+ type: "agent:wake",
+ agentId: "a1",
+ config: { version: 1, runtime: "mock", model: { kind: "default" }, mode: { kind: "default" } },
+ launchId: "l1",
+ unreadNotice: { kind: "unread_notice", channel: "/demo/general", latestSeq: 7 },
+ });
+
+ expect(
+ logger.calls.info.some(
+ ([m, d]) => m === "agent:wake received" && (d[0] as any).agentId === "a1" && (d[0] as any).channel === "/demo/general",
+ ),
+ ).toBe(true);
+ expect(logger.calls.info.some(([m, d]) => m === "agent:wake ack" && (d[0] as any).status === "ok")).toBe(true);
+ });
+
+ it("logs info for the ack with error status when the wake fails", async () => {
+ const throwing: UnknownRuntimeError = new UnknownRuntimeError("gemini", ["claude"]);
+ const mgr = {
+ register() {
+ throw throwing;
+ },
+ deliver() {},
+ stop() {},
+ liveSessionReports: () => [],
+ } as unknown as AgentProcessManager;
+ const { ch, fire } = fakeChannel();
+ const logger = stubLogger();
+ const router = new AgentRouter({ manager: mgr, channel: ch, runtimeReport: [{ id: "claude" }], logger });
+ await router.start();
+
+ await fire({
+ type: "agent:wake",
+ agentId: "a1",
+ config: { version: 1, runtime: "gemini", model: { kind: "default" }, mode: { kind: "default" } },
+ launchId: "l1",
+ unreadNotice: { kind: "unread_notice", channel: "/demo/general", latestSeq: 1 },
+ });
+
+ expect(logger.calls.info.some(([m, d]) => m === "agent:wake ack" && (d[0] as any).status === "error")).toBe(
+ true,
+ );
+ });
+
+ it("logs info on agent:stop received + ack", async () => {
+ const { mgr } = fakeManager();
+ const { ch, fire } = fakeChannel();
+ const logger = stubLogger();
+ const router = new AgentRouter({ manager: mgr, channel: ch, runtimeReport: [{ id: "mock" }], logger });
+ await router.start();
+
+ await fire({ type: "agent:stop", agentId: "a1" });
+
+ expect(logger.calls.info.some(([m, d]) => m === "agent:stop received" && (d[0] as any).agentId === "a1")).toBe(
+ true,
+ );
+ expect(logger.calls.info.some(([m, d]) => m === "agent:stop ack" && (d[0] as any).status === "ok")).toBe(true);
+ });
+
+ it("logs warn/info from markRuntimeUnhealthy/markRuntimeHealthy only on actual state changes", () => {
+ const { mgr } = fakeManager();
+ const { ch } = fakeChannel();
+ const logger = stubLogger();
+ const router = new AgentRouter({
+ manager: mgr,
+ channel: ch,
+ runtimeReport: [{ id: "codex" }],
+ logger,
+ scheduleReadyResend: (fn) => fn(),
+ });
+
+ router.markRuntimeUnhealthy("codex", "ENOENT");
+ // Idempotent repeat — no new warn log.
+ router.markRuntimeUnhealthy("codex", "ENOENT");
+ expect(logger.calls.warn.filter(([m]) => m === "runtime marked unhealthy")).toHaveLength(1);
+
+ router.markRuntimeHealthy("codex");
+ router.markRuntimeHealthy("codex"); // idempotent — already healthy
+ expect(logger.calls.info.filter(([m]) => m === "runtime marked healthy again")).toHaveLength(1);
+ });
+});
diff --git a/src/daemon/src/manager/agentRouter.ts b/src/daemon/src/manager/agentRouter.ts
index 956035041..8f1b14ad5 100644
--- a/src/daemon/src/manager/agentRouter.ts
+++ b/src/daemon/src/manager/agentRouter.ts
@@ -20,6 +20,7 @@
*/
import type { HostCommand, HostControlChannel, HostReady, HostReadyRuntime, UnreadNotice, AgentSessionReport, SessionErrorFrame } from "../server/contract.js";
import type { AgentProcessManager } from "./managerRuntime.js";
+import { createLogger, type Logger } from "../logger.js";
/**
* Thrown by a `driverFor` implementation when the server asked for a runtime
@@ -98,6 +99,8 @@ export interface AgentRouterOpts {
* into one wire frame. Tests inject a synchronous scheduler.
*/
scheduleReadyResend?: (fn: () => void) => void;
+ /** Defaults to `createLogger({ header: "@alook/daemon:router" })`. */
+ logger?: Logger;
}
function defaultFormatUnreadNoticeText(notice: UnreadNotice): string {
@@ -120,8 +123,10 @@ export class AgentRouter {
/** Coalescer: one microtask-scheduled `sendReady` per burst of mutations. */
private pendingResend = false;
private readonly scheduleResend: (fn: () => void) => void;
+ private readonly log: Logger;
constructor(private readonly opts: AgentRouterOpts) {
+ this.log = opts.logger ?? createLogger({ header: "@alook/daemon:router" });
this.scheduleResend = opts.scheduleReadyResend ?? queueMicrotask.bind(globalThis);
for (const r of opts.runtimeReport) {
this.runtimes.set(r.id, {
@@ -202,6 +207,7 @@ export class AgentRouter {
lastError: reason,
lastErrorAt: nowIso,
});
+ this.log.warn("runtime marked unhealthy", { runtimeId: id, reason });
this.scheduleReadyFrameResend();
}
@@ -220,6 +226,7 @@ export class AgentRouter {
version: existing.version,
status: "healthy",
});
+ this.log.info("runtime marked healthy again", { runtimeId: id });
this.scheduleReadyFrameResend();
}
@@ -243,6 +250,11 @@ export class AgentRouter {
private async onCommand(cmd: HostCommand): Promise<void> {
switch (cmd.type) {
case "agent:wake":
+ this.log.info("agent:wake received", {
+ agentId: cmd.agentId,
+ channel: cmd.unreadNotice.channel,
+ latestSeq: cmd.unreadNotice.latestSeq,
+ });
try {
await this.opts.onBeforeAgent?.(cmd.agentId);
this.opts.manager.register(cmd.agentId, {
@@ -260,6 +272,7 @@ export class AgentRouter {
launchId: cmd.launchId,
status: "ok",
});
+ this.log.info("agent:wake ack", { agentId: cmd.agentId, status: "ok" });
} catch (err) {
if (err instanceof UnknownRuntimeError) {
// Forward a structured session.error so the server / machine DO
@@ -284,23 +297,33 @@ export class AgentRouter {
message: err.message,
},
});
+ this.log.info("agent:wake ack", {
+ agentId: cmd.agentId,
+ status: "error",
+ "error.code": "bot_runtime_missing",
+ });
return;
}
// Any other throw — including onBeforeAgent throws that used to be
// swallowed silently — surfaces as a structured error ack.
- await this.opts.channel.reportWakeAck?.({
- agentId: cmd.agentId,
- launchId: cmd.launchId,
- status: "error",
- error: {
- code: classifyErrorCode(err),
- message: err instanceof Error ? err.message : String(err),
- },
- });
+ {
+ const code = classifyErrorCode(err);
+ await this.opts.channel.reportWakeAck?.({
+ agentId: cmd.agentId,
+ launchId: cmd.launchId,
+ status: "error",
+ error: {
+ code,
+ message: err instanceof Error ? err.message : String(err),
+ },
+ });
+ this.log.info("agent:wake ack", { agentId: cmd.agentId, status: "error", "error.code": code });
+ }
return;
}
break;
case "agent:stop":
+ this.log.info("agent:stop received", { agentId: cmd.agentId });
try {
this.running.delete(cmd.agentId);
void this.opts.manager.stop(cmd.agentId);
@@ -308,15 +331,18 @@ export class AgentRouter {
agentId: cmd.agentId,
status: "ok",
});
+ this.log.info("agent:stop ack", { agentId: cmd.agentId, status: "ok" });
} catch (err) {
+ const code = classifyErrorCode(err);
await this.opts.channel.reportStoppedAck?.({
agentId: cmd.agentId,
status: "error",
error: {
- code: classifyErrorCode(err),
+ code,
message: err instanceof Error ? err.message : String(err),
},
});
+ this.log.info("agent:stop ack", { agentId: cmd.agentId, status: "error", "error.code": code });
}
break;
// bot:* frames are handled at the daemon layer (createDaemon), NOT here.
diff --git a/src/daemon/src/manager/managerRuntime.test.ts b/src/daemon/src/manager/managerRuntime.test.ts
index d23777257..f5ca7d30c 100644
--- a/src/daemon/src/manager/managerRuntime.test.ts
+++ b/src/daemon/src/manager/managerRuntime.test.ts
@@ -1,6 +1,26 @@
import { describe, it, expect, vi } from "vitest";
import { AgentProcessManager, type ManagedSession, type SessionFactory } from "./managerRuntime.js";
import type { Driver, LaunchContext } from "../types.js";
+import type { Logger } from "../logger.js";
+
+/** Stub logger — records calls per level for assertions. */
+function stubLogger(): Logger & { calls: Record<"debug" | "info" | "warn" | "error", Array<[string, unknown[]]>> } {
+ const calls: Record<"debug" | "info" | "warn" | "error", Array<[string, unknown[]]>> = {
+ debug: [],
+ info: [],
+ warn: [],
+ error: [],
+ };
+ const logger = {
+ calls,
+ debug: (m: string, ...d: unknown[]) => calls.debug.push([m, d]),
+ info: (m: string, ...d: unknown[]) => calls.info.push([m, d]),
+ warn: (m: string, ...d: unknown[]) => calls.warn.push([m, d]),
+ error: (m: string, ...d: unknown[]) => calls.error.push([m, d]),
+ child: () => logger,
+ };
+ return logger;
+}
// Minimal driver — the manager only reads .id and .lifecycle here (via register).
function fakeDriver(id: string): Driver {
@@ -52,7 +72,7 @@ function fakeSession(): FakeSession {
return s;
}
-function makeManager() {
+function makeManager(opts: { logger?: Logger; tickIntervalMs?: number; idleTimeoutMs?: number; staleThresholdMs?: number; now?: () => number } = {}) {
const session = fakeSession();
const factory: SessionFactory = () => session;
const onRuntimeSpawnFailed = vi.fn();
@@ -69,6 +89,7 @@ function makeManager() {
sessionFactory: factory,
onRuntimeSpawnFailed,
onRuntimeSessionEstablished,
+ ...opts,
});
mgr.register("a1");
return { mgr, session, onRuntimeSpawnFailed, onRuntimeSessionEstablished };
@@ -134,3 +155,209 @@ describe("AgentProcessManager — runtime health callbacks", () => {
expect(onRuntimeSessionEstablished).toHaveBeenCalledTimes(3);
});
});
+
+describe("AgentProcessManager — logging", () => {
+ it("logs info on spawn start with agentId + runtime", () => {
+ const logger = stubLogger();
+ const { mgr } = makeManager({ logger });
+ mgr.deliver("a1", { seq: 1, text: "hello" });
+
+ expect(
+ logger.calls.info.some(
+ ([m, d]) => m === "spawning agent" && (d[0] as any).agentId === "a1" && (d[0] as any).runtime === "codex",
+ ),
+ ).toBe(true);
+ });
+
+ it("logs info on session established (session_init) with agentId/sessionId/runtime", () => {
+ const logger = stubLogger();
+ const { mgr, session } = makeManager({ logger });
+ mgr.deliver("a1", { seq: 1, text: "hello" });
+
+ session.fire("runtime_event", { kind: "session_init", sessionId: "s1" });
+
+ expect(
+ logger.calls.info.some(
+ ([m, d]) =>
+ m === "agent session established" &&
+ (d[0] as any).agentId === "a1" &&
+ (d[0] as any).sessionId === "s1" &&
+ (d[0] as any).runtime === "codex",
+ ),
+ ).toBe(true);
+ });
+
+ it("logs warn on a pre-handshake spawn failure (ENOENT)", () => {
+ const logger = stubLogger();
+ const { mgr, session } = makeManager({ logger });
+ mgr.deliver("a1", { seq: 1, text: "hello" });
+
+ session.fire("error", { code: "ENOENT" });
+ session.fire("exit");
+
+ expect(
+ logger.calls.warn.some(
+ ([m, d]) => m === "spawn failed" && (d[0] as any).agentId === "a1" && (d[0] as any).reason === "ENOENT",
+ ),
+ ).toBe(true);
+ });
+
+ it("logs info on session ended with reason=turn_end", () => {
+ const logger = stubLogger();
+ const { mgr, session } = makeManager({ logger });
+ mgr.deliver("a1", { seq: 1, text: "hello" });
+
+ session.fire("runtime_event", { kind: "session_init", sessionId: "s1" });
+ session.fire("runtime_event", { kind: "turn_end" });
+
+ expect(
+ logger.calls.info.some(
+ ([m, d]) =>
+ m === "agent session ended" && (d[0] as any).reason === "turn_end" && (d[0] as any).sessionId === "s1",
+ ),
+ ).toBe(true);
+ });
+
+ it("logs info on session ended with reason=exit for an ESTABLISHED session's process exit", () => {
+ const logger = stubLogger();
+ const { mgr, session } = makeManager({ logger });
+ mgr.deliver("a1", { seq: 1, text: "hello" });
+
+ session.fire("runtime_event", { kind: "session_init", sessionId: "s1" });
+ session.fire("exit");
+
+ expect(
+ logger.calls.info.some(
+ ([m, d]) => m === "agent session ended" && (d[0] as any).reason === "exit" && (d[0] as any).sessionId === "s1",
+ ),
+ ).toBe(true);
+ });
+
+ it("does NOT log session-ended for a pre-handshake exit (already a spawn-failed warning)", () => {
+ const logger = stubLogger();
+ const { mgr, session } = makeManager({ logger });
+ mgr.deliver("a1", { seq: 1, text: "hello" });
+
+ session.fire("exit");
+
+ expect(logger.calls.info.some(([m]) => m === "agent session ended")).toBe(false);
+ });
+
+ it("does NOT double-log session-ended when a per_turn runtime's natural post-turn_end exit fires (turn_end already logged)", () => {
+ const logger = stubLogger();
+ const { mgr, session } = makeManager({ logger }); // fakeDriver's lifecycle.kind is "per_turn"
+ mgr.deliver("a1", { seq: 1, text: "hello" });
+
+ session.fire("runtime_event", { kind: "session_init", sessionId: "s1" });
+ session.fire("runtime_event", { kind: "turn_end" });
+ // The per_turn process exits on its own right after turn_end — this
+ // must NOT produce a second, contradictory "session ended" line.
+ session.fire("exit");
+
+ const ended = logger.calls.info.filter(([m]) => m === "agent session ended");
+ expect(ended).toHaveLength(1);
+ expect((ended[0]![1][0] as any).reason).toBe("turn_end");
+ });
+
+ it("does NOT double-log session-ended when the process exit follows an explicit stop/terminate_stalled", async () => {
+ vi.useFakeTimers();
+ try {
+ let currentTime = 0;
+ const logger = stubLogger();
+ const { mgr, session } = makeManager({ logger, now: () => currentTime, tickIntervalMs: 5, staleThresholdMs: 100 });
+ mgr.start();
+ mgr.deliver("a1", { seq: 1, text: "hello" });
+ session.startResolver?.();
+ await Promise.resolve();
+ session.fire("runtime_event", { kind: "session_init", sessionId: "s1" });
+
+ currentTime = 200;
+ await vi.advanceTimersByTimeAsync(10);
+ // The stall watchdog issued session.stop() — simulate the underlying
+ // process actually exiting shortly after.
+ session.fire("exit");
+
+ const ended = logger.calls.info.filter(([m]) => m === "agent session ended");
+ expect(ended).toHaveLength(1);
+ expect((ended[0]![1][0] as any).reason).toBe("terminate_stalled");
+ } finally {
+ vi.useRealTimers();
+ }
+ });
+
+ it("logs info on session ended with reason=terminate_stalled from the stall watchdog", async () => {
+ vi.useFakeTimers();
+ try {
+ let currentTime = 0;
+ const logger = stubLogger();
+ const { mgr, session } = makeManager({ logger, now: () => currentTime, tickIntervalMs: 5, staleThresholdMs: 100 });
+ mgr.start();
+ mgr.deliver("a1", { seq: 1, text: "hello" });
+ session.startResolver?.();
+ await Promise.resolve();
+ session.fire("runtime_event", { kind: "session_init", sessionId: "s1" });
+
+ currentTime = 200;
+ await vi.advanceTimersByTimeAsync(10);
+
+ expect(
+ logger.calls.info.some(
+ ([m, d]) =>
+ m === "agent session ended" &&
+ (d[0] as any).reason === "terminate_stalled" &&
+ (d[0] as any).sessionId === "s1",
+ ),
+ ).toBe(true);
+ } finally {
+ vi.useRealTimers();
+ }
+ });
+
+ it("logs info on session ended with reason=stopped from the idle-hibernation tick", async () => {
+ vi.useFakeTimers();
+ try {
+ let currentTime = 0;
+ const logger = stubLogger();
+ const persistentDriver = {
+ ...fakeDriver("codex"),
+ lifecycle: { kind: "persistent", start: "immediate", exit: "natural", inFlightWake: "queue" } as never,
+ } as Driver;
+ const session = fakeSession();
+ const factory: SessionFactory = () => session;
+ const mgr = new AgentProcessManager({
+ driverFor: () => persistentDriver,
+ baseContextFor: () => ({
+ workingDirectory: "/tmp",
+ agentId: "a1",
+ standingPrompt: "",
+ config: {} as LaunchContext["config"],
+ credentialProxy: {} as LaunchContext["credentialProxy"],
+ }),
+ sessionFactory: factory,
+ logger,
+ now: () => currentTime,
+ tickIntervalMs: 5,
+ idleTimeoutMs: 50,
+ });
+ mgr.register("a1");
+ mgr.deliver("a1", { seq: 1, text: "hello" });
+ session.startResolver?.();
+ await Promise.resolve();
+ session.fire("runtime_event", { kind: "session_init", sessionId: "s1" });
+ session.fire("runtime_event", { kind: "turn_end" });
+
+ mgr.start();
+ currentTime = 100;
+ await vi.advanceTimersByTimeAsync(10);
+
+ expect(
+ logger.calls.info.some(
+ ([m, d]) =>
+ m === "agent session ended" && (d[0] as any).reason === "stopped" && (d[0] as any).sessionId === "s1",
+ ),
+ ).toBe(true);
+ } finally {
+ vi.useRealTimers();
+ }
+ });
+});
diff --git a/src/daemon/src/manager/managerRuntime.ts b/src/daemon/src/manager/managerRuntime.ts
index b1eee69ab..236b414ba 100644
--- a/src/daemon/src/manager/managerRuntime.ts
+++ b/src/daemon/src/manager/managerRuntime.ts
@@ -22,6 +22,7 @@ import {
import type { Driver, LaunchContext } from "../types.js";
import type { RuntimeConfig } from "../runtimeConfig.js";
import { createChildProcessRuntimeSession, type ChildProcessRuntimeSession } from "../runtime/runtimeSession.js";
+import { createLogger, type Logger } from "../logger.js";
/** Minimal shape the executor needs from a runtime session. */
export interface ManagedSession {
@@ -102,6 +103,8 @@ export interface ManagerRuntimeOpts {
* their install (or after a genuine transient failure).
*/
onRuntimeSessionEstablished?: (runtimeId: string) => void;
+ /** Defaults to `createLogger({ header: "@alook/daemon:manager" })`. */
+ logger?: Logger;
}
/**
@@ -138,6 +141,15 @@ export class AgentProcessManager {
private readonly launchIds = new Map<string, string>();
/** agentId → live runtime sessionId (learned from session_init), for resync. */
private readonly liveSessions = new Map<string, string>();
+ /**
+ * agentId → the current spawn's per-session end-tracking flags, shared
+ * between `doSpawn`'s closure (turn_end / exit) and `applyEffect` (stop /
+ * terminate_stalled) — see `logSessionEnded`'s `suppressExitLog` handling.
+ */
+ private readonly activeSpawnState = new Map<
+ string,
+ { hasEstablished: boolean; hasReportedSpawnFailure: boolean; suppressExitLog: boolean }
+ >();
private readonly opts: Required<
Omit<
ManagerRuntimeOpts,
@@ -149,6 +161,7 @@ export class AgentProcessManager {
| "wakePromptFooter"
| "onRuntimeSpawnFailed"
| "onRuntimeSessionEstablished"
+ | "logger"
>
> &
Pick<
@@ -161,9 +174,11 @@ export class AgentProcessManager {
| "wakePromptFooter"
| "onRuntimeSpawnFailed"
| "onRuntimeSessionEstablished"
+ | "logger"
>;
private tickTimer: ReturnType<typeof setInterval> | null = null;
private readonly now: () => number;
+ private readonly log: Logger;
constructor(opts: ManagerRuntimeOpts) {
this.opts = {
@@ -173,6 +188,7 @@ export class AgentProcessManager {
...opts,
};
this.now = opts.now ?? (() => Date.now());
+ this.log = opts.logger ?? createLogger({ header: "@alook/daemon:manager" });
this.state = createInitialManagerState(this.opts.staleThresholdMs, this.opts.idleTimeoutMs);
}
@@ -261,19 +277,31 @@ export class AgentProcessManager {
case "send": {
const session = this.sessions.get(effect.agentId);
session?.send({ text: this.withFooter(effect.text), mode: effect.mode });
+ this.log.info("steering message sent to running agent", { agentId: effect.agentId, mode: effect.mode });
break;
}
case "stop":
case "terminate_stalled": {
const session = this.sessions.get(effect.agentId);
void Promise.resolve(session?.stop({ reason: effect.type, forceAfterMs: 5_000 }));
+ // The stop we just issued will make the underlying process emit its
+ // own `exit` shortly after — suppress that follow-up log so a single
+ // termination doesn't produce two contradictory "session ended" lines.
+ const spawnState = this.activeSpawnState.get(effect.agentId);
+ if (spawnState) spawnState.suppressExitLog = true;
+ this.logSessionEnded(effect.agentId, effect.type === "stop" ? "stopped" : "terminate_stalled");
break;
}
}
}
+ private logSessionEnded(agentId: string, reason: "turn_end" | "stopped" | "terminate_stalled" | "exit"): void {
+ this.log.info("agent session ended", { agentId, sessionId: this.liveSessions.get(agentId) ?? "", reason });
+ }
+
private doSpawn(agentId: string, prompt: string, resumeSessionId: string | null): void {
const driver = this.opts.driverFor(agentId, this.runtimeConfigs.get(agentId));
+ this.log.info("spawning agent", { agentId, runtime: driver.id });
const base = this.opts.baseContextFor(agentId);
// The server-pushed RuntimeConfig (from agent:wake) takes precedence over
// any baseContextFor default; the resume sessionId likewise prefers the
@@ -326,10 +354,18 @@ export class AgentProcessManager {
// path to see the failure gets to name the reason — subsequent paths
// no-op instead of clobbering a specific `ENOENT` with generic
// `pre_handshake_exit`.
- const state = { hasEstablished: false, hasReportedSpawnFailure: false };
+ // - suppressExitLog: set once this session's end has already been
+ // logged via a more specific reason (`turn_end` for a `per_turn`
+ // runtime that's about to exit on its own, or `stopped`/
+ // `terminate_stalled` from `applyEffect`) so the process's eventual
+ // `exit` event doesn't ALSO log a redundant/contradictory
+ // "session ended" line for the same termination.
+ const state = { hasEstablished: false, hasReportedSpawnFailure: false, suppressExitLog: false };
+ this.activeSpawnState.set(agentId, state);
const reportSpawnFailure = (reason: string) => {
if (state.hasEstablished || state.hasReportedSpawnFailure) return;
state.hasReportedSpawnFailure = true;
+ this.log.warn("spawn failed", { agentId, runtime: driver.id, reason });
this.opts.onRuntimeSpawnFailed?.(driver.id, reason);
};
@@ -345,7 +381,13 @@ export class AgentProcessManager {
// where session A established, session B failed and flipped the runtime
// unhealthy, and A's ongoing runtime_events never heal it back.
this.opts.onRuntimeSessionEstablished?.(driver.id);
- this.onRuntimeEvent(agentId, e);
+ // A `per_turn` runtime handles exactly one turn per spawn and exits on
+ // its own right after (see managerPolicy's onTurnEnd) — that upcoming
+ // `exit` is expected, not a new termination, so don't double-log it.
+ if ((e as { kind?: string })?.kind === "turn_end" && driver.lifecycle.kind === "per_turn") {
+ state.suppressExitLog = true;
+ }
+ this.onRuntimeEvent(agentId, e, driver.id);
});
// Child-process `error` (ENOENT etc.) — Node EE emits this before or in
// parallel with `exit`. Without this subscriber the raw `error` would
@@ -362,8 +404,14 @@ export class AgentProcessManager {
// Guarded by `hasReportedSpawnFailure` so an ENOENT (already reported
// via `error`) doesn't get overwritten with generic `pre_handshake_exit`.
reportSpawnFailure("pre_handshake_exit");
+ // Only an ESTABLISHED session "ended" — a pre-handshake exit is
+ // already covered by the spawn-failed warning above. And only if this
+ // termination wasn't already logged under a more specific reason (see
+ // `suppressExitLog` above).
+ if (state.hasEstablished && !state.suppressExitLog) this.logSessionEnded(agentId, "exit");
this.sessions.delete(agentId);
this.liveSessions.delete(agentId);
+ if (this.activeSpawnState.get(agentId) === state) this.activeSpawnState.delete(agentId);
this.dispatch({ type: "exit", agentId });
});
@@ -384,7 +432,7 @@ export class AgentProcessManager {
});
}
- private onRuntimeEvent(agentId: string, e: unknown): void {
+ private onRuntimeEvent(agentId: string, e: unknown, runtimeId: string): void {
const ev = e as { kind?: string; sessionId?: string; text?: string };
if (!ev?.kind) return;
if (ev.kind === "session_init" && ev.sessionId) {
@@ -396,6 +444,7 @@ export class AgentProcessManager {
sessionId: ev.sessionId,
launchId: this.launchIds.get(agentId) ?? "",
});
+ this.log.info("agent session established", { agentId, sessionId: ev.sessionId, runtime: runtimeId });
}
// Accumulate the agent's text output onto its latest timeline entry, so the
// log records "what the agent said" — the basis for using it as memory.
@@ -405,6 +454,7 @@ export class AgentProcessManager {
// Any event is progress for stall detection.
this.dispatch({ type: "progress", agentId, nowMs: this.now() });
if (ev.kind === "turn_end") {
+ this.logSessionEnded(agentId, "turn_end");
this.dispatch({ type: "turn_end", agentId, nowMs: this.now() });
}
}
diff --git a/src/daemon/src/server/wsControlChannel.test.ts b/src/daemon/src/server/wsControlChannel.test.ts
index ebbc83ac7..400506994 100644
--- a/src/daemon/src/server/wsControlChannel.test.ts
+++ b/src/daemon/src/server/wsControlChannel.test.ts
@@ -1,6 +1,7 @@
import { describe, it, expect } from "vitest";
import { WsControlChannel } from "./wsControlChannel";
import type { WebSocketLike, HostReady, AgentSessionReport } from "./contract";
+import type { Logger } from "../logger";
/**
* A controllable fake socket: records sent frames, lets the test drive open/close
@@ -28,7 +29,7 @@ class FakeSocket implements WebSocketLike {
}
}
-function makeChannel() {
+function makeChannel(overrides: Partial<ConstructorParameters<typeof WsControlChannel>[0]> = {}) {
const sockets: FakeSocket[] = [];
const ch = new WsControlChannel({
url: "ws://test",
@@ -40,10 +41,30 @@ function makeChannel() {
// No real timers needed; reconnect uses setTimeout(unref) — we drive openSocket
// indirectly by emitting close then letting the scheduled reconnect fire.
reconnect: { baseMs: 1, maxMs: 1 },
+ ...overrides,
});
return { ch, sockets };
}
+/** Stub logger — records calls per level for assertions. */
+function stubLogger(): Logger & { calls: Record<"debug" | "info" | "warn" | "error", Array<[string, unknown[]]>> } {
+ const calls: Record<"debug" | "info" | "warn" | "error", Array<[string, unknown[]]>> = {
+ debug: [],
+ info: [],
+ warn: [],
+ error: [],
+ };
+ const logger = {
+ calls,
+ debug: (m: string, ...d: unknown[]) => calls.debug.push([m, d]),
+ info: (m: string, ...d: unknown[]) => calls.info.push([m, d]),
+ warn: (m: string, ...d: unknown[]) => calls.warn.push([m, d]),
+ error: (m: string, ...d: unknown[]) => calls.error.push([m, d]),
+ child: () => logger,
+ };
+ return logger;
+}
+
describe("WsControlChannel — resync on (re)connect", () => {
it("re-announces ready + live sessions on the new socket after a reconnect", async () => {
const { ch, sockets } = makeChannel();
@@ -291,3 +312,83 @@ describe("WsControlChannel — reconnect timer keeps the event loop alive", () =
}
});
});
+
+describe("WsControlChannel — logging", () => {
+ it("logs info on open, and info on resync with runtime/session counts", async () => {
+ const logger = stubLogger();
+ const { ch, sockets } = makeChannel({ logger });
+ ch.onResync(() => ({
+ ready: { runtimeReport: [{ id: "claude" }], runningAgents: ["a1"] },
+ sessions: [{ agentId: "a1", sessionId: "s1", launchId: "l1" }],
+ }));
+ ch.connect();
+ sockets[0].emit("open");
+
+ expect(logger.calls.info.some(([m, d]) => m === "control channel open" && (d[0] as any).attempt === 0)).toBe(
+ true,
+ );
+ expect(
+ logger.calls.info.some(
+ ([m, d]) => m === "resync sent" && (d[0] as any).ready === 1 && (d[0] as any).sessions === 1,
+ ),
+ ).toBe(true);
+ });
+
+ it("logs warn on close", async () => {
+ const logger = stubLogger();
+ const { ch, sockets } = makeChannel({ logger });
+ ch.onResync(() => ({ ready: { runtimeReport: [], runningAgents: [] }, sessions: [] }));
+ ch.connect();
+ sockets[0].emit("open");
+ sockets[0].emit("close", 1006, "abnormal");
+
+ expect(
+ logger.calls.warn.some(([m, d]) => m === "control channel closed" && (d[0] as any).code === 1006),
+ ).toBe(true);
+ });
+
+ it("logs info on each scheduled reconnect with the computed delayMs", async () => {
+ const logger = stubLogger();
+ const { ch, sockets } = makeChannel({ logger, reconnect: { baseMs: 10, maxMs: 100 } });
+ ch.onResync(() => ({ ready: { runtimeReport: [], runningAgents: [] }, sessions: [] }));
+ ch.connect();
+ sockets[0].emit("open");
+ sockets[0].emit("close");
+
+ expect(
+ logger.calls.info.some(([m, d]) => m === "reconnecting" && (d[0] as any).attempt === 1 && (d[0] as any).delayMs === 10),
+ ).toBe(true);
+ });
+
+ it("logs error on AUTH_REJECTED", async () => {
+ const logger = stubLogger();
+ const { ch, sockets } = makeChannel({ logger });
+ ch.onResync(() => ({ ready: { runtimeReport: [], runningAgents: [] }, sessions: [] }));
+ ch.connect();
+ sockets[0].emit("open");
+ sockets[0].emit("message", JSON.stringify({ type: "error", code: "AUTH_REJECTED" }));
+
+ expect(logger.calls.error.some(([m]) => m === "AUTH_REJECTED received — machine key rejected, not reconnecting")).toBe(
+ true,
+ );
+ });
+
+ it("logs warn when heartbeat pong times out", async () => {
+ const logger = stubLogger();
+ let now = 0;
+ const { ch, sockets } = makeChannel({
+ logger,
+ now: () => now,
+ heartbeat: { pingIntervalMs: 10, pongTimeoutMs: 20 },
+ });
+ ch.onResync(() => ({ ready: { runtimeReport: [], runningAgents: [] }, sessions: [] }));
+ ch.connect();
+ sockets[0].emit("open");
+ // Advance the injected clock past the pong deadline, then let the
+ // heartbeat interval fire against real timers.
+ now = 1000;
+ await new Promise((r) => setTimeout(r, 30));
+
+ expect(logger.calls.warn.some(([m]) => m === "heartbeat pong timeout — forcing reconnect")).toBe(true);
+ });
+});
diff --git a/src/daemon/src/server/wsControlChannel.ts b/src/daemon/src/server/wsControlChannel.ts
index fe1f65cc8..a8c96ac3a 100644
--- a/src/daemon/src/server/wsControlChannel.ts
+++ b/src/daemon/src/server/wsControlChannel.ts
@@ -34,6 +34,7 @@ import type {
WebSocketLike,
WebSocketFactory,
} from "./contract.js";
+import { createLogger, type Logger } from "../logger.js";
// Re-export so existing importers of these from this module keep working.
export type { WebSocketLike, WebSocketFactory } from "./contract.js";
@@ -60,6 +61,8 @@ export interface WsControlChannelOpts {
*/
onAuthRejected?: () => void;
now?: () => number;
+ /** Defaults to `createLogger({ header: "@alook/daemon:ws" })`. */
+ logger?: Logger;
}
/**
@@ -110,6 +113,10 @@ type OutboundFrame =
type ResyncProvider = () => { ready: HostReady; sessions: AgentSessionReport[] };
+function describeErr(err: unknown): string {
+ return err instanceof Error ? err.message : String(err);
+}
+
export class WsControlChannel implements HostControlChannel {
private statusValue: ControlChannelStatus = "idle";
// Multiple listeners so consumers can layer behavior (e.g. bot-cache pre-hook
@@ -123,8 +130,11 @@ export class WsControlChannel implements HostControlChannel {
private pingTimer: ReturnType<typeof setInterval> | null = null;
private pongDeadline = 0;
private resyncProvider: ResyncProvider | null = null;
+ private readonly log: Logger;
- constructor(private readonly opts: WsControlChannelOpts) {}
+ constructor(private readonly opts: WsControlChannelOpts) {
+ this.log = opts.logger ?? createLogger({ header: "@alook/daemon:ws" });
+ }
get status(): ControlChannelStatus {
return this.statusValue;
@@ -233,7 +243,10 @@ export class WsControlChannel implements HostControlChannel {
// ready/agent_session are point-in-time state; if the socket isn't open we
// drop them here and let the resync provider regenerate fresh state on the
// next (re)connect — never replay a stale snapshot.
- if (this.statusValue !== "open" || !this.ws) return;
+ if (this.statusValue !== "open" || !this.ws) {
+ this.log.debug("frame dropped — socket not open", { type: frame.type });
+ return;
+ }
this.ws.send(JSON.stringify(frame));
}
@@ -247,6 +260,7 @@ export class WsControlChannel implements HostControlChannel {
const { ready, sessions } = this.resyncProvider();
this.sendFrame({ type: "ready", ...ready });
for (const s of sessions) this.sendFrame({ type: "agent_session", ...s });
+ this.log.info("resync sent", { ready: ready.runtimeReport.length, sessions: sessions.length });
}
for (const hook of this.resyncHooks) {
try {
@@ -264,6 +278,7 @@ export class WsControlChannel implements HostControlChannel {
ws.on("open", () => {
this.statusValue = "open";
+ this.log.info("control channel open", { attempt: this.attempt });
this.startHeartbeat();
this.resyncOnConnect();
});
@@ -271,8 +286,9 @@ export class WsControlChannel implements HostControlChannel {
ws.on("pong", () => {
this.attempt = 0;
this.pongDeadline = this.now() + (this.opts.heartbeat?.pongTimeoutMs ?? 30_000);
+ this.log.debug("heartbeat pong");
});
- ws.on("close", () => this.onSocketClosed());
+ ws.on("close", (code?: number, reason?: unknown) => this.onSocketClosed(code, reason));
// Errors surface via the socket's own close; a host factory may also log.
ws.on("error", () => {
/* swallow — close handler drives reconnect */
@@ -290,6 +306,7 @@ export class WsControlChannel implements HostControlChannel {
if (frame.type === "error" && frame.code === "AUTH_REJECTED") {
this.authRejected = true;
+ this.log.error("AUTH_REJECTED received — machine key rejected, not reconnecting");
this.opts.onAuthRejected?.();
return;
}
@@ -303,16 +320,17 @@ export class WsControlChannel implements HostControlChannel {
// listener that throws would surface as an unhandled promise rejection
// and, under Node ≥15 defaults, could terminate the daemon.
try {
- Promise.resolve(cb(cmd)).catch(() => {
- /* listener failure — swallowed, transport keeps going */
+ Promise.resolve(cb(cmd)).catch((err: unknown) => {
+ this.log.warn("command listener threw", { type: cmd.type, err: describeErr(err) });
});
- } catch {
- /* sync throw from a listener — same policy */
+ } catch (err) {
+ this.log.warn("command listener threw synchronously", { type: cmd.type, err: describeErr(err) });
}
}
}
- private onSocketClosed(): void {
+ private onSocketClosed(code?: number, reason?: unknown): void {
+ this.log.warn("control channel closed", { code, reason: reason ? String(reason) : "" });
this.clearHeartbeat();
this.ws = null;
if (this.closedByUser) return;
@@ -337,6 +355,7 @@ export class WsControlChannel implements HostControlChannel {
this.attempt += 1;
const delayMs = Math.min(max, base * 2 ** (this.attempt - 1));
this.statusValue = "reconnecting";
+ this.log.info("reconnecting", { attempt: this.attempt, delayMs });
// NOTE: do NOT `t.unref()` — this timer is what keeps the daemon alive
// while it's waiting to reconnect. Unrefing it here caused the daemon
// to silently exit(0) when the server dropped the socket (no other
@@ -351,9 +370,11 @@ export class WsControlChannel implements HostControlChannel {
this.pingTimer = setInterval(() => {
if (this.now() > this.pongDeadline) {
// Watchdog: no pong in time → treat as dead, force reconnect.
+ this.log.warn("heartbeat pong timeout — forcing reconnect");
this.ws?.close();
return;
}
+ this.log.debug("heartbeat ping");
this.ws?.ping?.();
}, interval);
this.pingTimer.unref?.();
diff --git a/src/web/src/hooks/community/use-community-ws.test.ts b/src/web/src/hooks/community/use-community-ws.test.ts
index 91cdd1a8b..8725d5bbc 100644
--- a/src/web/src/hooks/community/use-community-ws.test.ts
+++ b/src/web/src/hooks/community/use-community-ws.test.ts
@@ -80,10 +80,12 @@ vi.mock("@tanstack/react-query", async () => {
// level `activeSend` guard in `useCommunityWs` sees the same identity — a
// fresh spy per mount would trip the double-mount detector on every remount.
let capturedOnMessage: ((msg: unknown) => void) | null = null
+let capturedOnReconnect: (() => void) | null = null
let stableSend: ReturnType<typeof vi.fn> = vi.fn()
vi.mock("@/lib/use-user-ws", () => ({
- useUserWs: (onMessage: (msg: unknown) => void) => {
+ useUserWs: (onMessage: (msg: unknown) => void, options?: { onReconnect?: () => void }) => {
capturedOnMessage = onMessage
+ capturedOnReconnect = options?.onReconnect ?? null
return { send: stableSend }
},
}))
@@ -108,6 +110,7 @@ function resetHarness() {
callbackCounter = 0
pendingEffects = []
capturedOnMessage = null
+ capturedOnReconnect = null
capturedQueryClient = new QueryClient()
stableSend = vi.fn()
markReadMutate.mockClear()
@@ -888,6 +891,24 @@ describe("useCommunityWs — server.delete resets store when focused server dies
})
})
+// ── "stuck offline" fix — resync machines on WS reconnect ───────────────
+describe("useCommunityWs — resyncs machines on WS reconnect", () => {
+ it("invalidates communityKeys.machines() when the captured onReconnect fires", async () => {
+ await mountHook()
+ const spy = vi.spyOn(capturedQueryClient, "invalidateQueries")
+
+ expect(capturedOnReconnect).not.toBeNull()
+ capturedOnReconnect!()
+
+ expect(
+ spy.mock.calls.some((c) => {
+ const key = c[0]?.queryKey as unknown[] | undefined
+ return Array.isArray(key) && key.includes("machines")
+ }),
+ ).toBe(true)
+ })
+})
+
// ── Regression #15 — double-mount guard warns ───────────────────────────
describe("useCommunityWs — double-mount detection", () => {
it("emits console.warn when a second instance mounts with a different send", async () => {
diff --git a/src/web/src/hooks/community/use-community-ws.ts b/src/web/src/hooks/community/use-community-ws.ts
index f3601e79e..f5834660e 100644
--- a/src/web/src/hooks/community/use-community-ws.ts
+++ b/src/web/src/hooks/community/use-community-ws.ts
@@ -745,7 +745,18 @@ export function useCommunityWs(options?: UseCommunityWsOptions) {
[queryClient, scheduleInboxInvalidate],
)
- const { send } = useUserWs(handleMessage)
+ // Machines are WS-live-patched with no query refetch (see `use-machines.ts`)
+ // — but that only works while THIS browser tab's own socket stays connected.
+ // If the socket drops and an offline→online transition happens while it's
+ // down, the event never arrives and the card is stuck stale until a full
+ // page reload. Mirror `AgentProvider`'s reconnect pattern
+ // (`contexts/agent-context.tsx`): resync the machines query on every
+ // reconnect so a missed transition self-corrects within the reconnect
+ // window instead of requiring a manual reload.
+ const handleReconnect = useCallback(() => {
+ queryClient.invalidateQueries({ queryKey: communityKeys.machines() })
+ }, [queryClient])
+ const { send } = useUserWs(handleMessage, { onReconnect: handleReconnect })
// Publish the send binding so free helpers (`communityWsSendTyping`) can
// dispatch without holding a hook reference. Single-instance assumption