@linzumi/cli 0.0.1-beta → 0.0.2-beta

package/src/runner.ts

@@ -0,0 +1,524 @@
+/*
+- Date: 2026-04-24
+  Spec: plans/2026-04-24-local-codex-runner-plan.md
+  Relationship: Bridges the spec's desired local instance lifecycle between
+  Kandan controls, Codex app-server JSON-RPC, and optional remote TUI launch.
+
+- Date: 2026-04-24
+  Spec: plans/2026-04-24-local-codex-channel-thread-binding-spec.md
+  Relationship: Hosts the process lifecycle used by the channel-bound local
+  Codex product flow while delegating session behavior to `channelSession.ts`.
+
+- Date: 2026-04-24
+  Spec: plans/2026-04-24-local-codex-runner-quality-pass-spec.md
+  Relationship: Keeps the runner focused on transport lifecycle and Codex
+  process orchestration instead of embedding pure channel-session policy.
+
+- Date: 2026-04-24
+  Spec: plans/2026-04-24-local-codex-channel-session-module-spec.md
+  Relationship: Delegates channel-bound Kandan/Codex session orchestration to
+  the dedicated channel session module.
+
+- Date: 2026-04-24
+  Spec: plans/2026-04-24-local-codex-runner-deep-quality-spec.md
+  Relationship: Owns channel-mode startup cost and process-level cleanup
+  requirements for the deep quality pass, including cleanup of partially
+  opened resources when startup fails.
+
+- Date: 2026-04-25
+  Spec: plans/2026-04-24-local-codex-runner-deep-quality-spec.md
+  Relationship: Leaves channel-scoped approval controls to `channelSession.ts`
+  so the process runner remains lifecycle-only while Kandan safely resolves
+  Codex app-server approval requests from the thread UI.
+*/
+import { spawn, type ChildProcess } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { hostname } from "node:os";
+import { join } from "node:path";
+import { attachChannelSession } from "./channelSession";
+import { connectCodexAppServer, startCodexAppServer } from "./codexAppServer";
+import { arrayValue, integerValue, objectValue, stringValue } from "./json";
+import { connectPhoenixClient } from "./phoenix";
+import {
+  type JsonObject,
+  type JsonValue,
+  type KandanChannelSessionOptions,
+  type KandanControl,
+  extractCodexIds,
+  isJsonObject,
+} from "./protocol";
+import { createRunnerLogger, type RunnerLogger } from "./runnerLogger";
+import { reportRunnerConsoleEvent } from "./runnerConsoleReporter";
+
+export type RunnerOptions = {
+  readonly kandanUrl: string;
+  readonly token: string;
+  readonly runnerId: string;
+  readonly cwd: string;
+  readonly codexBin: string;
+  readonly codexUrl: string | undefined;
+  readonly launchTui: boolean;
+  readonly fast?: boolean | undefined;
+  readonly logFile?: string | undefined;
+  readonly channelSession: KandanChannelSessionOptions | undefined;
+};
+
+export type LocalCodexRunnerHandle = {
+  readonly instanceId: string;
+  readonly codexUrl: string;
+  readonly close: () => Promise<void>;
+};
+
+type CleanupAction = () => void | Promise<void>;
+
+type CleanupStack = {
+  readonly actions: CleanupAction[];
+  closePromise: Promise<void> | undefined;
+  removeHandlers: (() => void) | undefined;
+};
+
+export async function runLocalCodexRunner(
+  options: RunnerOptions,
+): Promise<LocalCodexRunnerHandle> {
+  const log = makeRunnerLogger(options);
+  const cleanup: CleanupStack = {
+    actions: [() => log.close()],
+    closePromise: undefined,
+    removeHandlers: undefined,
+  };
+  const close = () => closeCleanupStack(cleanup);
+  cleanup.removeHandlers = installCleanupHandlers(close);
+
+  log("runner.starting", {
+    runnerId: options.runnerId,
+    cwd: options.cwd,
+    kandanUrl: options.kandanUrl,
+  });
+
+  try {
+    return await openLocalCodexRunner(options, log, cleanup, close);
+  } catch (error) {
+    await close().catch(() => undefined);
+    throw error;
+  }
+}
+
+async function openLocalCodexRunner(
+  options: RunnerOptions,
+  log: RunnerLogger,
+  cleanup: CleanupStack,
+  close: () => Promise<void>,
+): Promise<LocalCodexRunnerHandle> {
+  const kandan = await connectPhoenixClient(options.kandanUrl, options.token);
+  cleanup.actions.push(() => kandan.close());
+  const topic = `local_runner:${options.runnerId}`;
+  await kandan.join(topic, {
+    clientName: "kandan-local-codex-runner",
+    version: "0.0.1",
+    capabilities: {
+      codexAppServer: true,
+      codexRemoteTui: true,
+    },
+  });
+
+  const started =
+    options.codexUrl === undefined
+      ? await startCodexAppServer(options.codexBin, options.cwd, {
+          model: options.channelSession?.model,
+          reasoningEffort: options.channelSession?.reasoningEffort,
+          fast: options.fast,
+        })
+      : undefined;
+
+  if (started !== undefined) {
+    cleanup.actions.push(() => {
+      started.process.kill("SIGINT");
+    });
+  }
+
+  const codexUrl = options.codexUrl ?? started?.url;
+
+  if (codexUrl === undefined) {
+    throw new Error("missing codex app-server websocket URL");
+  }
+
+  const instanceId = `codex-${randomUUID()}`;
+  const codex = await connectCodexAppServer(codexUrl);
+  cleanup.actions.push(() => codex.close());
+
+  const seq = { value: 0 };
+  const codexThreads =
+    options.channelSession === undefined
+      ? await discoverCodexThreads(codex, options.cwd)
+      : [];
+
+  const runnerHost = hostname();
+  const instancePayload = {
+    instanceId,
+    codexUrl,
+    tuiLaunched: options.launchTui,
+    cwd: options.cwd,
+    hostname: runnerHost,
+    codexThreads,
+    model: options.channelSession?.model ?? null,
+    reasoningEffort: options.channelSession?.reasoningEffort ?? null,
+    fast: options.fast ?? false,
+  };
+
+  await kandan.push(topic, "instance_started", instancePayload);
+  log("runner.instance_started", { instanceId, codexUrl });
+
+  const channelSession =
+    options.channelSession === undefined
+      ? undefined
+      : await attachChannelSession({
+          kandan,
+          codex,
+          topic,
+          instanceId,
+          options: {
+            token: options.token,
+            runnerId: options.runnerId,
+            cwd: options.cwd,
+            codexBin: options.codexBin,
+            fast: options.fast,
+            launchTui: options.launchTui,
+            channelSession: options.channelSession,
+          },
+          log,
+        });
+
+  if (channelSession !== undefined) {
+    cleanup.actions.push(() => channelSession.close());
+    kandan.onReconnect(() => channelSession.handleKandanReconnect());
+  }
+
+  const heartbeatPayload = (): JsonObject => ({
+    instanceId,
+    codexUrl,
+    cwd: options.cwd,
+    hostname: runnerHost,
+    workspace: options.channelSession?.workspaceSlug ?? null,
+    channel: options.channelSession?.channelSlug ?? null,
+    threadId: channelSession?.currentKandanThreadId() ?? null,
+    codexThreadId: channelSession?.currentCodexThreadId() ?? null,
+    model: options.channelSession?.model ?? null,
+    reasoningEffort: options.channelSession?.reasoningEffort ?? null,
+    fast: options.fast ?? false,
+  });
+  const pushHeartbeat = () =>
+    kandan.push(topic, "heartbeat", heartbeatPayload()).catch(error => {
+      log("kandan.heartbeat_push_failed", {
+        message: error instanceof Error ? error.message : String(error),
+      });
+    });
+  const heartbeatInterval = setInterval(() => {
+    void pushHeartbeat();
+  }, 15_000);
+  cleanup.actions.push(() => clearInterval(heartbeatInterval));
+  kandan.onReconnect(() => pushHeartbeat().then(() => undefined));
+  void pushHeartbeat();
+
+  const channelCodexThreadId = channelSession?.currentCodexThreadId();
+  if (options.launchTui && channelCodexThreadId !== undefined) {
+    await prepareCodexThreadForTuiResume(codex, channelCodexThreadId);
+  }
+
+  const tui = options.launchTui
+    ? launchCodexTui(
+        options.codexBin,
+        codexUrl,
+        options.cwd,
+        channelCodexThreadId,
+        options.channelSession,
+        options.fast,
+      )
+    : undefined;
+
+  if (tui !== undefined) {
+    cleanup.actions.push(() => {
+      tui.kill("SIGINT");
+    });
+  }
+
+  codex.onNotification(notification => {
+    seq.value += 1;
+    const params = (notification.params ?? {}) as JsonObject;
+    const metadata = extractCodexIds(params);
+
+    if (channelSession === undefined) {
+      void kandan.push(topic, "codex_notification", {
+        instanceId,
+        seq: seq.value,
+        method: notification.method,
+        params,
+        metadata,
+        receivedAt: new Date().toISOString(),
+      }).catch(error => {
+        log("kandan.codex_notification_push_failed", {
+          message: error instanceof Error ? error.message : String(error),
+        });
+      });
+    }
+
+    log("codex.notification", {
+      method: notification.method,
+      metadata,
+    });
+    channelSession?.handleCodexNotification(notification.method, params);
+  });
+
+  kandan.onControl(control => {
+    log("kandan.control", { control });
+    void (channelSession?.handleControl(control) ?? Promise.resolve(undefined))
+      .then(handled => {
+        if (handled !== undefined) {
+          return handled;
+        }
+
+        return applyControl(codex, instanceId, control);
+      })
+      .then(response => {
+        return kandan.push(topic, "codex_response", response);
+      })
+      .catch(error => {
+        return kandan.push(topic, "codex_error", {
+          instanceId,
+          message: error instanceof Error ? error.message : String(error),
+        });
+      });
+  });
+
+  return { instanceId, codexUrl, close };
+}
+
+async function closeCleanupStack(cleanup: CleanupStack): Promise<void> {
+  if (cleanup.closePromise !== undefined) {
+    return cleanup.closePromise;
+  }
+
+  cleanup.closePromise = (async () => {
+    const errors: Error[] = [];
+    cleanup.removeHandlers?.();
+    cleanup.removeHandlers = undefined;
+
+    for (const action of [...cleanup.actions].reverse()) {
+      try {
+        await action();
+      } catch (error) {
+        errors.push(error instanceof Error ? error : new Error(String(error)));
+      }
+    }
+
+    cleanup.actions.splice(0);
+
+    if (errors[0] !== undefined) {
+      throw errors[0];
+    }
+  })();
+
+  return cleanup.closePromise;
+}
+
+async function discoverCodexThreads(
+  codex: Awaited<ReturnType<typeof connectCodexAppServer>>,
+  cwd: string,
+): Promise<JsonValue[]> {
+  const response = await codex.request("thread/list", { cwd });
+
+  if ("error" in response) {
+    return [];
+  }
+
+  const result = objectValue(response.result);
+  const data = arrayValue(result?.data);
+
+  return data === undefined
+    ? []
+    : data
+        .filter(isJsonObject)
+        .map(thread => ({
+          id: stringValue(thread.id) ?? "",
+          preview: stringValue(thread.preview) ?? "",
+          cwd: stringValue(thread.cwd) ?? "",
+          source: stringValue(thread.source) ?? "",
+          updatedAt: integerValue(thread.updatedAt) ?? null,
+          status: objectValue(thread.status) ?? null,
+        }))
+        .filter(thread => thread.id !== "");
+}
+
+function makeRunnerLogger(options: RunnerOptions): RunnerLogger {
+  return createRunnerLogger(
+    options.logFile ?? join(options.cwd, ".kandan-local-codex-runner.log"),
+    options.launchTui ? undefined : reportRunnerConsoleEvent,
+  );
+}
+
+function installCleanupHandlers(close: () => Promise<void>): () => void {
+  const closeAndExit = () => {
+    void close().catch(() => undefined).finally(() => process.exit(0));
+  };
+  const closeOnExit = () => {
+    void close().catch(() => undefined);
+  };
+
+  process.once("SIGINT", closeAndExit);
+  process.once("SIGTERM", closeAndExit);
+  process.once("SIGHUP", closeAndExit);
+  process.once("exit", closeOnExit);
+
+  return () => {
+    process.off("SIGINT", closeAndExit);
+    process.off("SIGTERM", closeAndExit);
+    process.off("SIGHUP", closeAndExit);
+    process.off("exit", closeOnExit);
+  };
+}
+
+function launchCodexTui(
+  codexBin: string,
+  codexUrl: string,
+  cwd: string,
+  codexThreadId: string | undefined,
+  session: KandanChannelSessionOptions | undefined,
+  fast: boolean | undefined,
+): ChildProcess {
+  return spawn(codexBin, codexTuiArgs(codexUrl, codexThreadId, session, fast), {
+    cwd,
+    env: process.env,
+    stdio: "inherit",
+  });
+}
+
+export function codexTuiArgs(
+  codexUrl: string,
+  codexThreadId: string | undefined,
+  session?: KandanChannelSessionOptions | undefined,
+  fast?: boolean | undefined,
+): string[] {
+  const overrides = codexTuiConfigArgs(session, fast);
+
+  return codexThreadId === undefined
+    ? ["--remote", codexUrl, ...overrides]
+    : ["resume", "--remote", codexUrl, ...overrides, codexThreadId];
+}
+
+function codexTuiConfigArgs(
+  session: KandanChannelSessionOptions | undefined,
+  fast: boolean | undefined,
+): string[] {
+  const modelArgs =
+    session?.model === undefined ? [] : ["--model", session.model];
+  const reasoningArgs =
+    session?.reasoningEffort === undefined
+      ? []
+      : ["-c", `model_reasoning_effort="${session.reasoningEffort}"`];
+  const tierArgs = fast === true ? ["-c", 'service_tier="fast"'] : [];
+
+  return [...modelArgs, ...reasoningArgs, ...tierArgs];
+}
+
+export async function prepareCodexThreadForTuiResume(
+  codex: Pick<Awaited<ReturnType<typeof connectCodexAppServer>>, "request">,
+  codexThreadId: string,
+): Promise<void> {
+  const resume = await codex.request("thread/resume", {
+    threadId: codexThreadId,
+  });
+
+  if (!("error" in resume)) {
+    return;
+  }
+
+  if (!resume.error.message.includes("no rollout found")) {
+    throw new Error(
+      `failed to prepare Codex TUI resume: ${resume.error.message}`,
+    );
+  }
+
+  const injected = await codex.request("thread/inject_items", {
+    threadId: codexThreadId,
+    items: [{ type: "agentMessage", text: "" }],
+  });
+
+  if ("error" in injected) {
+    throw new Error(
+      `failed to prepare Codex TUI resume: ${injected.error.message}`,
+    );
+  }
+
+  const verified = await codex.request("thread/resume", {
+    threadId: codexThreadId,
+  });
+
+  if ("error" in verified) {
+    throw new Error(
+      `failed to verify Codex TUI resume: ${verified.error.message}`,
+    );
+  }
+}
+
+async function applyControl(
+  codex: Awaited<ReturnType<typeof connectCodexAppServer>>,
+  instanceId: string,
+  control: KandanControl,
+): Promise<JsonObject> {
+  switch (control.type) {
+    case "start_turn": {
+      const response = await codex.request("turn/start", {
+        threadId: control.threadId,
+        input: control.input,
+      });
+      return {
+        instanceId,
+        controlType: control.type,
+        response: response as JsonObject,
+      };
+    }
+
+    case "steer_turn": {
+      const response = await codex.request("turn/steer", {
+        threadId: control.threadId,
+        turnId: control.turnId,
+        input: control.input,
+      });
+      return {
+        instanceId,
+        controlType: control.type,
+        response: response as JsonObject,
+      };
+    }
+
+    case "interrupt_turn": {
+      const response = await codex.request("turn/interrupt", {
+        threadId: control.threadId,
+        turnId: control.turnId ?? null,
+      });
+      return {
+        instanceId,
+        controlType: control.type,
+        response: response as JsonObject,
+      };
+    }
+
+    case "read_thread": {
+      const response = await codex.request("thread/read", {
+        threadId: control.threadId,
+        includeTurns: control.includeTurns ?? true,
+      });
+      return {
+        instanceId,
+        controlType: control.type,
+        response: response as JsonObject,
+      };
+    }
+
+    case "stop_instance":
+    case "kill_instance":
+    case "start_instance":
+    case "interrupt_queued_messages":
+    case "resolve_codex_approval_request":
+      return { instanceId, controlType: control.type, skipped: true };
+  }
+}

package/src/runnerConsoleReporter.ts

@@ -0,0 +1,142 @@
+/*
+- Date: 2026-04-24
+  Spec: plans/2026-04-24-local-codex-channel-thread-binding-spec.md
+  Relationship: Provides the headless local-runner stdout status feed required
+  for operators to see accepted, ignored, forwarded, and Codex-output events
+  without printing message bodies or raw Codex payload contents.
+
+- Date: 2026-04-25
+  Spec: plans/2026-04-24-local-codex-runner-deep-quality-spec.md
+  Relationship: Surfaces live reasoning, command-output, and search-progress
+  projection status in headless runner stdout while keeping transcript content
+  out of the console stream.
+*/
+
+type ConsolePayload = Record<string, unknown>;
+
+export function reportRunnerConsoleEvent(event: string, payload: ConsolePayload): void {
+  const line = formatRunnerConsoleEvent(event, payload);
+
+  if (line !== undefined) {
+    process.stdout.write(`${line}\n`);
+  }
+}
+
+export function formatRunnerConsoleEvent(
+  event: string,
+  payload: ConsolePayload,
+): string | undefined {
+  switch (event) {
+    case "runner.instance_started":
+      return `Runner connected: instance=${text(payload.instanceId)} codex=${text(payload.codexUrl)}`;
+
+    case "kandan.message_ignored":
+      return `Incoming message from ${sender(payload)}: ignored for reason ${text(payload.reason)}`;
+
+    case "kandan.message_queued":
+      return `Incoming message from ${sender(payload)}: queued seq=${text(payload.seq)} depth=${text(payload.queue_depth)}`;
+
+    case "kandan.chat_event_failed":
+      return `Incoming message handling failed: seq=${text(payload.seq)} reason=${text(payload.message)}`;
+
+    case "kandan.reconnected":
+      return `Kandan reconnected: codex_session=${text(payload.codex_thread_id)} cursor=${text(payload.min_seq)}`;
+
+    case "codex.turn_starting":
+      return `Incoming message from ${sender(payload)}: forwarding to Codex session ${text(payload.codex_thread_id)} seq=${text(payload.queued_seq)}`;
+
+    case "codex.turn_started":
+      return `Codex turn started: id=${text(payload.turn_id)}`;
+
+    case "codex.notification":
+      return `Codex event [id=${codexEventId(payload)}]: ${text(payload.method)}`;
+
+    case "codex.turn_completed":
+      return `Codex turn completed: id=${text(payload.turn_id)} outputs=${text(payload.output_count)}`;
+
+    case "kandan.codex_output_forwarded":
+      return `Codex event [id=${text(payload.item_key)}]: ${codexOutputLabel(payload)}`;
+
+    case "kandan.codex_reasoning_delta_forwarded":
+      return `Codex event [id=${text(payload.item_key)}]: reasoning_delta chars=${text(payload.content_length)}`;
+
+    case "kandan.codex_command_output_forwarded":
+      return `Codex event [id=${text(payload.item_key)}]: command_output ${text(payload.stream)} chars=${text(payload.output_length)}`;
+
+    case "kandan.codex_web_search_progress_forwarded":
+      return `Codex event [id=${text(payload.item_key)}]: search_progress queries=${text(payload.query_count)}`;
+
+    case "codex.queued_messages_interrupted":
+      return `Queued messages interrupted: selected=${text(payload.selected_count)} remaining=${text(payload.remaining_count)}`;
+
+    case "codex.turn_start_failed":
+      return `Codex turn start failed: seq=${text(payload.queued_seq)} reason=${text(payload.message)}`;
+
+    case "codex.turn_forward_failed":
+      return `Codex turn forward failed: id=${text(payload.turn_id)} reason=${text(payload.message)}`;
+
+    default:
+      return undefined;
+  }
+}
+
+function sender(payload: ConsolePayload): string {
+  const slug = stringValue(payload.actor_slug);
+  const userId = numberValue(payload.actor_user_id);
+
+  if (slug !== undefined && userId !== undefined) {
+    return `${slug}#${userId}`;
+  }
+
+  return slug ?? (userId === undefined ? "unknown" : `user#${userId}`);
+}
+
+function codexOutputLabel(payload: ConsolePayload): string {
+  const kind = stringValue(payload.structured_kind) ?? "output";
+
+  switch (kind) {
+    case "codex_assistant_message":
+      return "assistant_message";
+    case "codex_reasoning":
+      return "reasoning";
+    case "codex_command_execution":
+      return `command ${text(payload.command)}`;
+    case "codex_terminal_input":
+      return "terminal_input";
+    case "codex_file_change":
+      return `file_change ${fileChangePaths(payload)}`;
+    default:
+      return kind;
+  }
+}
+
+function fileChangePaths(payload: ConsolePayload): string {
+  const paths = Array.isArray(payload.file_paths)
+    ? payload.file_paths.filter((value): value is string => typeof value === "string")
+    : [];
+
+  return paths.length === 0 ? "(unknown file)" : paths.slice(0, 3).join(", ");
+}
+
+function codexEventId(payload: ConsolePayload): string {
+  const metadata = payload.metadata;
+
+  if (typeof metadata === "object" && metadata !== null && !Array.isArray(metadata)) {
+    const record = metadata as Record<string, unknown>;
+    return stringValue(record.turnId) ?? stringValue(record.itemId) ?? stringValue(record.threadId) ?? "?";
+  }
+
+  return "?";
+}
+
+function text(value: unknown): string {
+  return stringValue(value) ?? numberValue(value)?.toString() ?? "?";
+}
+
+function stringValue(value: unknown): string | undefined {
+  return typeof value === "string" && value.trim() !== "" ? value : undefined;
+}
+
+function numberValue(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}

package/src/runnerLogger.ts

@@ -0,0 +1,50 @@
+/*
+- Date: 2026-04-24
+  Spec: plans/2026-04-24-local-codex-channel-thread-binding-spec.md
+  Relationship: Writes the runner's local event log without blocking the
+  websocket/control loop on synchronous filesystem appends.
+*/
+import { openSync } from "node:fs";
+import { createWriteStream, type WriteStream } from "node:fs";
+import { dirname } from "node:path";
+import { mkdirSync } from "node:fs";
+
+export type RunnerConsoleReporter = (event: string, payload: Record<string, unknown>) => void;
+
+export type RunnerLogger = ((event: string, payload: Record<string, unknown>) => void) & {
+  readonly close: () => Promise<void>;
+};
+
+export function createRunnerLogger(
+  logFile: string,
+  consoleReporter?: RunnerConsoleReporter | undefined,
+): RunnerLogger {
+  mkdirSync(dirname(logFile), { recursive: true });
+  const fd = openSync(logFile, "a");
+  const stream = createWriteStream("", { fd, flags: "a", autoClose: true });
+
+  const logger = ((event: string, payload: Record<string, unknown>) => {
+    stream.write(
+      `${JSON.stringify({ ts: new Date().toISOString(), event, ...payload })}\n`,
+      "utf8",
+    );
+    consoleReporter?.(event, payload);
+  }) as RunnerLogger;
+
+  Object.defineProperty(logger, "close", {
+    value: () => closeStream(stream),
+  });
+
+  return logger;
+}
+
+function closeStream(stream: WriteStream): Promise<void> {
+  if (stream.closed || stream.destroyed) {
+    return Promise.resolve();
+  }
+
+  return new Promise((resolve, reject) => {
+    stream.once("error", reject);
+    stream.end(resolve);
+  });
+}