@chinhae/atw-cli 0.1.0

package/dist/commands/channel/supervisor/stdout.js

@@ -0,0 +1,229 @@
+/**
+ * stdout pipeline: line-buffered reader → adapter.parseLine → append
+ * events into events.jsonl + persist session/thread IDs + write any
+ * adapter `reply` back to the worker's stdin.
+ *
+ * Step 3 of the supervisor refactor: pulled out of supervisor.ts so the
+ * orchestrator stays thin. The pump itself is pure (no fs / process), so
+ * unit testing the line-splitting logic is straightforward once we want
+ * to. `applyParseResult` still touches fs for session-id persistence —
+ * that's intentional, it's the only place that needs to.
+ */
+import fs from "node:fs";
+import { appendEvent } from "../store/events.js";
+import { workerFile } from "../store/paths.js";
+/**
+ * Coordinate early stdout capture with the durable `spawned` event.
+ *
+ * Startup failures discard captured lines because no `spawned` event exists.
+ * Normal shutdown may stop waiting for inherited pipe owners, but must leave
+ * the processing decision to the in-flight `spawned` append so stdout events
+ * can never overtake it in events.jsonl.
+ */
+export function createStdoutDrainControl() {
+    let resolveProcessLines;
+    const processLines = new Promise((resolve) => {
+        resolveProcessLines = resolve;
+    });
+    const controller = new AbortController();
+    return {
+        processLines,
+        signal: controller.signal,
+        allowProcessing: () => resolveProcessLines(true),
+        discard: () => {
+            resolveProcessLines(false);
+            controller.abort();
+        },
+        abortReading: () => controller.abort(),
+    };
+}
+/**
+ * 按行读取 stdout，并把非空行串行交给 onLine
+ *
+ * @param stream 子进程 stdout 可读流
+ * @param onLine stdout 单行处理器，按读取顺序串行执行
+ * @param onError onLine 抛错时的错误处理器，也在同一队列中执行
+ * @param signal 中止等待并排空已读取内容的可选信号
+ * @returns stdout 结束且所有已排队行处理完成后 resolved 的 Promise
+ */
+export function pumpStdout(stream, onLine, onError, signal) {
+    let buf = "";
+    let queue = Promise.resolve();
+    let pending = 0;
+    let paused = false;
+    let finished = false;
+    /**
+     * 在有待处理行时暂停 stdout 读取
+     *
+     * @returns 无返回值
+     */
+    const pauseForBackpressure = () => {
+        if (!paused) {
+            stream.pause();
+            paused = true;
+        }
+    };
+    /**
+     * 在待处理行全部完成后恢复 stdout 读取
+     *
+     * @returns 无返回值
+     */
+    const resumeIfDrained = () => {
+        if (paused && pending === 0) {
+            paused = false;
+            stream.resume();
+        }
+    };
+    /**
+     * 将 stdout 单行追加到串行处理队列
+     *
+     * @param line 已切分出的 stdout 单行文本
+     * @returns 无返回值
+     */
+    const enqueue = (line) => {
+        pending += 1;
+        pauseForBackpressure();
+        queue = queue
+            .then(async () => {
+            try {
+                await onLine(line);
+            }
+            catch (err) {
+                if (onError) {
+                    try {
+                        await onError(err instanceof Error ? err : new Error(String(err)));
+                    }
+                    catch {
+                        // 吞掉错误处理器自身的错误
+                    }
+                }
+            }
+            finally {
+                pending -= 1;
+                resumeIfDrained();
+            }
+        })
+            .catch(() => undefined);
+    };
+    const onData = (chunk) => {
+        buf += chunk.toString("utf-8");
+        let nl;
+        while ((nl = buf.indexOf("\n")) !== -1) {
+            const line = buf.slice(0, nl);
+            buf = buf.slice(nl + 1);
+            if (line.trim()) {
+                enqueue(line);
+            }
+        }
+    };
+    let resolveFinished;
+    const streamFinished = new Promise((resolve) => {
+        resolveFinished = resolve;
+    });
+    const finish = () => {
+        if (finished)
+            return;
+        finished = true;
+        stream.off("data", onData);
+        stream.off("end", finish);
+        stream.off("close", finish);
+        signal?.removeEventListener("abort", finish);
+        if (buf.trim()) {
+            enqueue(buf);
+        }
+        buf = "";
+        resolveFinished();
+    };
+    stream.on("data", onData);
+    stream.once("end", finish);
+    stream.once("close", finish);
+    signal?.addEventListener("abort", finish, { once: true });
+    if (signal?.aborted ||
+        stream.readableEnded ||
+        stream.closed ||
+        stream.destroyed) {
+        queueMicrotask(finish);
+    }
+    return streamFinished.then(() => queue);
+}
+/**
+ * Translate an adapter `ParseResult` into channel events + adapter-level
+ * side-effects (session-id persistence, stdin writes). Also tells the
+ * shutdown controller when the adapter emits a `done`/`error` so the
+ * fallback synthesiser in `finalizeOnExit` doesn't duplicate.
+ */
+export async function applyParseResult(channelName, workerName, result, child, shutdown, turnTracker) {
+    for (const ev of result.events) {
+        // Claim the terminal slot SYNCHRONOUSLY before the await so a
+        // racing `child.on("exit") → finalizeOnExit` can't see
+        // `terminalEmitted=false` and synthesise a duplicate fallback while
+        // we're in the middle of writing the real terminal event.
+        if (ev.kind === "done" || ev.kind === "error") {
+            shutdown.markTerminalEmitted();
+        }
+        await appendEvent(channelName, {
+            kind: ev.kind,
+            by: workerName,
+            ...(ev.payload ?? {}),
+        });
+        if (ev.kind === "done" || ev.kind === "error") {
+            const turn = turnTracker?.finish();
+            if (turn) {
+                const outcome = ev.kind === "done" ? "done" : "error";
+                await appendEvent(channelName, {
+                    kind: "turn_finished",
+                    by: workerName,
+                    worker: workerName,
+                    inputSeq: turn.inputSeq,
+                    turnId: turn.turnId,
+                    outcome,
+                });
+            }
+        }
+    }
+    if (result.side) {
+        const { reply, persistSessionId, persistThreadId } = result.side;
+        if (persistSessionId) {
+            fs.writeFileSync(workerFile(channelName, workerName, "session-id"), persistSessionId);
+        }
+        if (persistThreadId) {
+            fs.writeFileSync(workerFile(channelName, workerName, "thread-id"), persistThreadId);
+        }
+        if (reply) {
+            for (const r of reply) {
+                try {
+                    child.stdin.write(r);
+                }
+                catch {
+                    // worker stdin closed — supervisor will exit soon
+                }
+            }
+        }
+    }
+}
+/**
+ * Convenience wrapper: wire `pumpStdout` to `applyParseResult` with
+ * standard error-event-on-failure handling. The orchestrator just calls
+ * this and forgets about line buffering / parse plumbing.
+ */
+export function startStdoutPump(args) {
+    const { channelName, workerName, child, adapter, adapterCtx, log, shutdown, turnTracker, processLines, signal, } = args;
+    const drained = pumpStdout(child.stdout, async (line) => {
+        if (processLines && !(await processLines))
+            return;
+        log.write(line + "\n");
+        const result = adapter.parseLine(line, adapterCtx);
+        await applyParseResult(channelName, workerName, result, child, shutdown, turnTracker);
+    }, async (err) => {
+        log.write(`[supervisor] stdout line handler failed: ${err.message}\n`);
+        await appendEvent(channelName, {
+            kind: "error",
+            by: `supervisor:${workerName}`,
+            message: `stdout pipeline error: ${err.message}`,
+        }).catch(() => undefined);
+    }, signal);
+    return processLines
+        ? Promise.all([drained, processLines]).then(() => undefined)
+        : drained;
+}
+//# sourceMappingURL=stdout.js.map

package/dist/commands/channel/supervisor/stdout.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stdout.js","sourceRoot":"","sources":["../../../../src/commands/channel/supervisor/stdout.ts"],"names":[],"mappings":"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"}

package/dist/commands/channel/supervisor/turns.d.ts

@@ -0,0 +1,31 @@
+export interface ActiveTurn {
+    inputSeq: number;
+    turnId: string;
+}
+export type TurnOutcome = "done" | "error" | "aborted";
+export interface TurnTrackerHooks {
+    /** Called when the tracker transitions from idle to mid-turn. */
+    onIdleExit?: () => void;
+    /** Called when the tracker transitions back to idle. */
+    onIdleEnter?: () => void;
+}
+/**
+ * Host-local turn tracker for one supervisor process.
+ *
+ * The durable SOT is events.jsonl. This object only remembers the input
+ * message seq long enough for the inbox watcher and stdout pump to emit
+ * matching `turn_started` / `turn_finished` events.
+ *
+ * Optional hooks fire on the idle ↔ mid-turn transition so the
+ * supervisor idle-timer (OOM guard) can pause / reset without each
+ * inbox or stdout call site having to know about it.
+ */
+export declare class TurnTracker {
+    #private;
+    constructor(hooks?: TurnTrackerHooks);
+    begin(inputSeq: number): ActiveTurn;
+    finish(): ActiveTurn | undefined;
+    abortCurrent(): ActiveTurn | undefined;
+    current(): ActiveTurn | undefined;
+}
+//# sourceMappingURL=turns.d.ts.map

package/dist/commands/channel/supervisor/turns.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"turns.d.ts","sourceRoot":"","sources":["../../../../src/commands/channel/supervisor/turns.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC;AAEvD,MAAM,WAAW,gBAAgB;IAC/B,iEAAiE;IACjE,UAAU,CAAC,EAAE,MAAM,IAAI,CAAC;IACxB,wDAAwD;IACxD,WAAW,CAAC,EAAE,MAAM,IAAI,CAAC;CAC1B;AAED;;;;;;;;;;GAUG;AACH,qBAAa,WAAW;;gBAIV,KAAK,GAAE,gBAAqB;IAIxC,KAAK,CAAC,QAAQ,EAAE,MAAM,GAAG,UAAU;IAWnC,MAAM,IAAI,UAAU,GAAG,SAAS;IAMhC,YAAY,IAAI,UAAU,GAAG,SAAS;IAMtC,OAAO,IAAI,UAAU,GAAG,SAAS;CAGlC"}

package/dist/commands/channel/supervisor/turns.js

@@ -0,0 +1,45 @@
+/**
+ * Host-local turn tracker for one supervisor process.
+ *
+ * The durable SOT is events.jsonl. This object only remembers the input
+ * message seq long enough for the inbox watcher and stdout pump to emit
+ * matching `turn_started` / `turn_finished` events.
+ *
+ * Optional hooks fire on the idle ↔ mid-turn transition so the
+ * supervisor idle-timer (OOM guard) can pause / reset without each
+ * inbox or stdout call site having to know about it.
+ */
+export class TurnTracker {
+    #turns = [];
+    #hooks;
+    constructor(hooks = {}) {
+        this.#hooks = hooks;
+    }
+    begin(inputSeq) {
+        const wasIdle = this.#turns.length === 0;
+        const turn = {
+            inputSeq,
+            turnId: `msg:${inputSeq}`,
+        };
+        this.#turns.push(turn);
+        if (wasIdle)
+            this.#hooks.onIdleExit?.();
+        return turn;
+    }
+    finish() {
+        const turn = this.#turns.pop();
+        if (turn && this.#turns.length === 0)
+            this.#hooks.onIdleEnter?.();
+        return turn;
+    }
+    abortCurrent() {
+        const turn = this.#turns.pop();
+        if (turn && this.#turns.length === 0)
+            this.#hooks.onIdleEnter?.();
+        return turn;
+    }
+    current() {
+        return this.#turns.at(-1);
+    }
+}
+//# sourceMappingURL=turns.js.map

package/dist/commands/channel/supervisor/turns.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"turns.js","sourceRoot":"","sources":["../../../../src/commands/channel/supervisor/turns.ts"],"names":[],"mappings":"AAcA;;;;;;;;;;GAUG;AACH,MAAM,OAAO,WAAW;IACtB,MAAM,GAAiB,EAAE,CAAC;IAC1B,MAAM,CAAmB;IAEzB,YAAY,QAA0B,EAAE;QACtC,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC;IACtB,CAAC;IAED,KAAK,CAAC,QAAgB;QACpB,MAAM,OAAO,GAAG,IAAI,CAAC,MAAM,CAAC,MAAM,KAAK,CAAC,CAAC;QACzC,MAAM,IAAI,GAAe;YACvB,QAAQ;YACR,MAAM,EAAE,OAAO,QAAQ,EAAE;SAC1B,CAAC;QACF,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACvB,IAAI,OAAO;YAAE,IAAI,CAAC,MAAM,CAAC,UAAU,EAAE,EAAE,CAAC;QACxC,OAAO,IAAI,CAAC;IACd,CAAC;IAED,MAAM;QACJ,MAAM,IAAI,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC;QAC/B,IAAI,IAAI,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,KAAK,CAAC;YAAE,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE,EAAE,CAAC;QAClE,OAAO,IAAI,CAAC;IACd,CAAC;IAED,YAAY;QACV,MAAM,IAAI,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC;QAC/B,IAAI,IAAI,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,KAAK,CAAC;YAAE,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE,EAAE,CAAC;QAClE,OAAO,IAAI,CAAC;IACd,CAAC;IAED,OAAO;QACL,OAAO,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;IAC5B,CAAC;CACF"}

package/dist/commands/channel/supervisor/warning.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Supervisor pre-timeout warning scheduler.
+ *
+ * Emits a one-shot `supervisor_warning` channel event when the worker
+ * is approaching its lifetime timeout, so observers (dispatchers /
+ * `atw channel messages`) can see the impending kill without
+ * having to poll. The event is observability-only — it never replaces
+ * the eventual `killed` / `done` / `error` terminal event, and is
+ * not part of the meaningful-event set so plain `wait` does not wake
+ * on it unless `--kind supervisor_warning` is explicit.
+ *
+ * Scheduling lives outside `createShutdown()` because the warning is a
+ * pre-terminal observability event, not a terminal one — the shutdown
+ * funnel deliberately only owns kill ladder + `killed` append.
+ */
+/** Default lead time before the supervisor timeout (ms) to fire the warning. */
+export declare const SUPERVISOR_TIMEOUT_WARNING_REMAINING_MS: number;
+export interface SupervisorShutdownProbe {
+    isShuttingDown(): boolean;
+    hasTerminalEvent(): boolean;
+}
+export interface ScheduleSupervisorTimeoutWarningArgs {
+    channelName: string;
+    workerName: string;
+    timeoutMs: number;
+    /** Warning lead time in ms. `<= 0` disables the pre-timeout warning. */
+    warnBeforeMs?: number;
+    shutdown: SupervisorShutdownProbe;
+    /** Returns true once the child process has exited (exitCode/signalCode set). */
+    isChildExited: () => boolean;
+    log: {
+        write: (data: string) => void;
+    };
+    project?: string;
+}
+/**
+ * Schedule a single `supervisor_warning` append at `timeoutMs - warnBeforeMs`
+ * (clamped at 0 when the warning lead time is greater than the timeout).
+ * Guarded so the warning is emitted at most once, never after shutdown
+ * has been requested, never after a terminal event has been emitted,
+ * and never after the worker child has exited.
+ *
+ * Returns a cancel handle that callers can invoke to drop the pending
+ * timer (e.g. on supervisor teardown). Append failures are logged via
+ * `log.write` only and do not affect worker lifecycle.
+ */
+export declare function scheduleSupervisorTimeoutWarning(args: ScheduleSupervisorTimeoutWarningArgs): () => void;
+//# sourceMappingURL=warning.d.ts.map

package/dist/commands/channel/supervisor/warning.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"warning.d.ts","sourceRoot":"","sources":["../../../../src/commands/channel/supervisor/warning.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH,gFAAgF;AAChF,eAAO,MAAM,uCAAuC,QAAa,CAAC;AAElE,MAAM,WAAW,uBAAuB;IACtC,cAAc,IAAI,OAAO,CAAC;IAC1B,gBAAgB,IAAI,OAAO,CAAC;CAC7B;AAED,MAAM,WAAW,oCAAoC;IACnD,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,wEAAwE;IACxE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,uBAAuB,CAAC;IAClC,gFAAgF;IAChF,aAAa,EAAE,MAAM,OAAO,CAAC;IAC7B,GAAG,EAAE;QAAE,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;KAAE,CAAC;IACvC,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gCAAgC,CAC9C,IAAI,EAAE,oCAAoC,GACzC,MAAM,IAAI,CAuDZ"}

package/dist/commands/channel/supervisor/warning.js

@@ -0,0 +1,77 @@
+/**
+ * Supervisor pre-timeout warning scheduler.
+ *
+ * Emits a one-shot `supervisor_warning` channel event when the worker
+ * is approaching its lifetime timeout, so observers (dispatchers /
+ * `atw channel messages`) can see the impending kill without
+ * having to poll. The event is observability-only — it never replaces
+ * the eventual `killed` / `done` / `error` terminal event, and is
+ * not part of the meaningful-event set so plain `wait` does not wake
+ * on it unless `--kind supervisor_warning` is explicit.
+ *
+ * Scheduling lives outside `createShutdown()` because the warning is a
+ * pre-terminal observability event, not a terminal one — the shutdown
+ * funnel deliberately only owns kill ladder + `killed` append.
+ */
+import { appendEvent } from "../store/events.js";
+/** Default lead time before the supervisor timeout (ms) to fire the warning. */
+export const SUPERVISOR_TIMEOUT_WARNING_REMAINING_MS = 5 * 60_000;
+/**
+ * Schedule a single `supervisor_warning` append at `timeoutMs - warnBeforeMs`
+ * (clamped at 0 when the warning lead time is greater than the timeout).
+ * Guarded so the warning is emitted at most once, never after shutdown
+ * has been requested, never after a terminal event has been emitted,
+ * and never after the worker child has exited.
+ *
+ * Returns a cancel handle that callers can invoke to drop the pending
+ * timer (e.g. on supervisor teardown). Append failures are logged via
+ * `log.write` only and do not affect worker lifecycle.
+ */
+export function scheduleSupervisorTimeoutWarning(args) {
+    const { channelName, workerName, timeoutMs, shutdown, isChildExited, log } = args;
+    if (timeoutMs <= 0)
+        return () => undefined;
+    const warnBeforeMs = args.warnBeforeMs ?? SUPERVISOR_TIMEOUT_WARNING_REMAINING_MS;
+    if (warnBeforeMs <= 0)
+        return () => undefined;
+    const remaining = Math.min(timeoutMs, warnBeforeMs);
+    const delay = Math.max(0, timeoutMs - remaining);
+    let warningEmitted = false;
+    let cancelled = false;
+    const fire = () => {
+        if (cancelled || warningEmitted)
+            return;
+        if (shutdown.isShuttingDown() ||
+            shutdown.hasTerminalEvent() ||
+            isChildExited()) {
+            return;
+        }
+        // Claim the slot synchronously so a re-entrant fire (or future
+        // caller wiring) cannot race two appends.
+        warningEmitted = true;
+        void (async () => {
+            try {
+                await appendEvent(channelName, {
+                    kind: "supervisor_warning",
+                    by: `supervisor:${workerName}`,
+                    worker: workerName,
+                    reason: "approaching_timeout",
+                    timeout_ms: timeoutMs,
+                    remaining_ms: remaining,
+                }, args.project);
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                log.write(`[supervisor] warning append failed: ${msg}\n`);
+            }
+        })();
+    };
+    const timer = setTimeout(fire, delay);
+    // Don't keep the supervisor alive solely for the warning timer.
+    timer.unref?.();
+    return () => {
+        cancelled = true;
+        clearTimeout(timer);
+    };
+}
+//# sourceMappingURL=warning.js.map

package/dist/commands/channel/supervisor/warning.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"warning.js","sourceRoot":"","sources":["../../../../src/commands/channel/supervisor/warning.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEjD,gFAAgF;AAChF,MAAM,CAAC,MAAM,uCAAuC,GAAG,CAAC,GAAG,MAAM,CAAC;AAoBlE;;;;;;;;;;GAUG;AACH,MAAM,UAAU,gCAAgC,CAC9C,IAA0C;IAE1C,MAAM,EAAE,WAAW,EAAE,UAAU,EAAE,SAAS,EAAE,QAAQ,EAAE,aAAa,EAAE,GAAG,EAAE,GACxE,IAAI,CAAC;IACP,IAAI,SAAS,IAAI,CAAC;QAAE,OAAO,GAAG,EAAE,CAAC,SAAS,CAAC;IAC3C,MAAM,YAAY,GAChB,IAAI,CAAC,YAAY,IAAI,uCAAuC,CAAC;IAC/D,IAAI,YAAY,IAAI,CAAC;QAAE,OAAO,GAAG,EAAE,CAAC,SAAS,CAAC;IAE9C,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,SAAS,EAAE,YAAY,CAAC,CAAC;IACpD,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,SAAS,GAAG,SAAS,CAAC,CAAC;IAEjD,IAAI,cAAc,GAAG,KAAK,CAAC;IAC3B,IAAI,SAAS,GAAG,KAAK,CAAC;IAEtB,MAAM,IAAI,GAAG,GAAS,EAAE;QACtB,IAAI,SAAS,IAAI,cAAc;YAAE,OAAO;QACxC,IACE,QAAQ,CAAC,cAAc,EAAE;YACzB,QAAQ,CAAC,gBAAgB,EAAE;YAC3B,aAAa,EAAE,EACf,CAAC;YACD,OAAO;QACT,CAAC;QACD,+DAA+D;QAC/D,0CAA0C;QAC1C,cAAc,GAAG,IAAI,CAAC;QACtB,KAAK,CAAC,KAAK,IAAI,EAAE;YACf,IAAI,CAAC;gBACH,MAAM,WAAW,CACf,WAAW,EACX;oBACE,IAAI,EAAE,oBAAoB;oBAC1B,EAAE,EAAE,cAAc,UAAU,EAAE;oBAC9B,MAAM,EAAE,UAAU;oBAClB,MAAM,EAAE,qBAAqB;oBAC7B,UAAU,EAAE,SAAS;oBACrB,YAAY,EAAE,SAAS;iBACxB,EACD,IAAI,CAAC,OAAO,CACb,CAAC;YACJ,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,MAAM,GAAG,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;gBAC7D,GAAG,CAAC,KAAK,CAAC,uCAAuC,GAAG,IAAI,CAAC,CAAC;YAC5D,CAAC;QACH,CAAC,CAAC,EAAE,CAAC;IACP,CAAC,CAAC;IAEF,MAAM,KAAK,GAAG,UAAU,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;IACtC,gEAAgE;IAChE,KAAK,CAAC,KAAK,EAAE,EAAE,CAAC;IAEhB,OAAO,GAAG,EAAE;QACV,SAAS,GAAG,IAAI,CAAC;QACjB,YAAY,CAAC,KAAK,CAAC,CAAC;IACtB,CAAC,CAAC;AACJ,CAAC"}

package/dist/commands/channel/supervisor.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Supervisor process: owns a single worker (claude or codex) and bridges
+ * worker ↔ channel events.jsonl.
+ *
+ * Run as: `atw channel __supervisor <channel> <worker> <config-path>`
+ *
+ * Three concurrent loops:
+ *   1. stdout reader  — parse worker stdout → adapter → append events
+ *   2. inbox watcher  — read events.jsonl for `to=<worker>` say events,
+ *                       translate via adapter.encodeUserMessage → worker stdin
+ *   3. signal handler — SIGTERM → close worker stdin → 3s → SIGTERM → 3s → SIGKILL
+ *                       → write `killed` event → exit
+ */
+import { type InboxPolicy } from "@chinhae/atw-core/channel";
+import type { CodexSandboxMode } from "./adapters/codex.js";
+import { type Provider } from "./adapters/index.js";
+export interface SupervisorConfig {
+    provider: Provider;
+    cwd: string;
+    /** Combined worker system prompt: channel protocol prefix + agent body.
+     *  Injected via Claude `--append-system-prompt(-file)` or Codex
+     *  `developerInstructions`. The supervisor also persists it to
+     *  `<worker>.system-prompt.md` and exposes the path as
+     *  `view.systemPromptFile` so adapters can avoid OS argv-length limits.
+     *  No "initial user prompt" — the worker stays idle until the first
+     *  inbox `send --to <worker>` arrives. */
+    systemPrompt: string;
+    /** Extra env vars (ATW_HOOKS=0 etc. are added automatically). */
+    env?: Record<string, string>;
+    /** Optional model override. */
+    model?: string;
+    /** Resume an existing session/thread if id is provided. */
+    resume?: string;
+    /** Codex-only: overrides the `thread/start` sandbox mode (default `workspace-write`). */
+    sandbox?: CodexSandboxMode;
+    /** Auto-kill worker after this many ms (anti-zombie). */
+    timeoutMs?: number;
+    /** Emit supervisor_warning this many ms before timeout. `<=0` disables it. */
+    warnBeforeMs?: number;
+    /**
+     * OOM-guard idle-cleanup TTL in ms. When a running worker stays idle
+     * for this long (no active turn), the supervisor self-terminates with
+     * `killed{reason:"idle-timeout"}`. `<=0` or undefined disables.
+     */
+    idleTimeoutMs?: number;
+    /** Caller identity recorded on the `spawned` event (default "main"). */
+    spawnedBy?: string;
+    /** Agent definition name loaded for this worker, if any (recorded on `spawned`). */
+    agent?: string;
+    /** Relative paths injected via --file / --jsonl (recorded on `spawned`). */
+    contextFiles?: string[];
+    /** Relative paths of every `--jsonl` manifest processed, even if empty
+     *  (recorded on `spawned` for observability — "I passed --jsonl X but
+     *  X contained no real entries"). */
+    contextManifests?: string[];
+    /** Worker inbox delivery policy (recorded on `spawned`; default
+     *  `explicitOnly`). */
+    inboxPolicy?: InboxPolicy;
+}
+interface ResolvedProviderPath {
+    command: string;
+    prefixArgs: string[];
+}
+/**
+ * Drain worker stdout before synthesising terminal state and removing the
+ * supervisor's runtime files.
+ */
+export declare function finalizeSupervisorExit(args: {
+    stdoutDrained: Promise<void>;
+    drainTimeoutMs: number;
+    abortStdoutDrain: () => void;
+    onDrainTimeout?: () => void;
+    finalizeOnExit: () => Promise<void>;
+    cleanup: () => Promise<void>;
+    exit: () => void;
+}): Promise<void>;
+/**
+ * Resolve the real launch target for npm `.cmd` shims on Windows.
+ *
+ * @param provider CLI basename for the provider, such as `codex` or `claude`.
+ * @param cwd Worker launch directory, used to check local `node_modules/.bin` first.
+ * @returns Command and prefix arguments that can be passed directly to `spawn()`.
+ */
+export declare function resolveProviderPath(provider: string, cwd?: string): ResolvedProviderPath;
+/**
+ * Entry point invoked by `atw channel __supervisor <channel> <worker> <config>`.
+ */
+export declare function runSupervisor(channelName: string, workerName: string, configPath: string): Promise<void>;
+export declare function writeSupervisorConfig(channelName: string, workerName: string, config: SupervisorConfig, project?: string): string;
+export {};
+//# sourceMappingURL=supervisor.d.ts.map

package/dist/commands/channel/supervisor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"supervisor.d.ts","sourceRoot":"","sources":["../../../src/commands/channel/supervisor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAOH,OAAO,EAEL,KAAK,WAAW,EACjB,MAAM,2BAA2B,CAAC;AAGnC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAC5D,OAAO,EAAc,KAAK,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAahE,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,QAAQ,CAAC;IACnB,GAAG,EAAE,MAAM,CAAC;IACZ;;;;;;8CAM0C;IAC1C,YAAY,EAAE,MAAM,CAAC;IACrB,iEAAiE;IACjE,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,+BAA+B;IAC/B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,2DAA2D;IAC3D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,yFAAyF;IACzF,OAAO,CAAC,EAAE,gBAAgB,CAAC;IAC3B,yDAAyD;IACzD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,8EAA8E;IAC9E,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,wEAAwE;IACxE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,oFAAoF;IACpF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,4EAA4E;IAC5E,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB;;yCAEqC;IACrC,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC5B;2BACuB;IACvB,WAAW,CAAC,EAAE,WAAW,CAAC;CAC3B;AAMD,UAAU,oBAAoB;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB;AAED;;;GAGG;AACH,wBAAsB,sBAAsB,CAAC,IAAI,EAAE;IACjD,aAAa,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7B,cAAc,EAAE,MAAM,CAAC;IACvB,gBAAgB,EAAE,MAAM,IAAI,CAAC;IAC7B,cAAc,CAAC,EAAE,MAAM,IAAI,CAAC;IAC5B,cAAc,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IACpC,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7B,IAAI,EAAE,MAAM,IAAI,CAAC;CAClB,GAAG,OAAO,CAAC,IAAI,CAAC,CAkBhB;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,MAAM,EAChB,GAAG,CAAC,EAAE,MAAM,GACX,oBAAoB,CAsCtB;AAED;;GAEG;AACH,wBAAsB,aAAa,CACjC,WAAW,EAAE,MAAM,EACnB,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,IAAI,CAAC,CA2Wf;AA0DD,wBAAgB,qBAAqB,CACnC,WAAW,EAAE,MAAM,EACnB,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,gBAAgB,EACxB,OAAO,CAAC,EAAE,MAAM,GACf,MAAM,CAKR"}