@linzumi/cli 0.0.5-beta → 0.0.6-beta

package/src/runner.ts

@@ -35,6 +35,23 @@
   Spec: plans/2026_04_26_linzumi_cli_review_followups_note.md
   Relationship: Rejects stale Kandan controls for previous local runner
   instances before they can mutate the current Codex app-server session.
+
+- Date: 2026-04-26
+  Spec: plans/2026-04-26-local-codex-driver-worldclass-spec.md
+  Relationship: Enforces local machine cwd capabilities for Kandan-requested
+  Codex session starts and advertises cwd plus local preview-port capabilities
+  to the server on the runner join payload.
+
+- Date: 2026-04-26
+  Spec: plans/2026-04-26-local-runner-forwarding-and-editor-plan.md
+  Relationship: Routes Kandan-authenticated local preview forwarding controls
+  to the local loopback HTTP fetcher after verifying the control targets this
+  runner instance.
+
+- Date: 2026-04-26
+  Spec: plans/2026-04-26-local-runner-port-forward-approval.md
+  Relationship: Lets channel-session approval add descendant listener ports to
+  the runner's live forwarding capability before forwarding requests use them.
 */
 import { spawn, type ChildProcess } from "node:child_process";
 import { randomUUID } from "node:crypto";
@@ -43,6 +60,25 @@ import { join } from "node:path";
 import { attachChannelSession } from "./channelSession";
 import { connectCodexAppServer, startCodexAppServer } from "./codexAppServer";
 import { arrayValue, integerValue, objectValue, stringValue } from "./json";
+import { connectForwardTunnel } from "./forwardTunnel";
+import { resolveAllowedCwd } from "./localCapabilities";
+import {
+  createForwardWebSocketManager,
+  handleForwardHttpRequest,
+  isForwardHttpRequestControl,
+  isForwardWebSocketControl,
+} from "./localForwarding";
+import {
+  isStartLocalEditorControl,
+  localEditorCapabilities,
+  startLocalEditor,
+  type LocalEditorState,
+} from "./localEditor";
+import type { InstalledEditorRuntime } from "./localEditorRuntime";
+import {
+  dependencyStatusPayload,
+  type RunnerDependencyStatus,
+} from "./dependencyStatus";
 import { connectPhoenixClient } from "./phoenix";
 import {
   type JsonObject,
@@ -65,6 +101,12 @@ export type RunnerOptions = {
   readonly launchTui: boolean;
   readonly fast?: boolean | undefined;
   readonly logFile?: string | undefined;
+  readonly allowedCwds: readonly string[];
+  readonly allowedForwardPorts?: readonly number[] | undefined;
+  readonly codeServerBin?: string | undefined;
+  readonly editorRuntime?: InstalledEditorRuntime | undefined;
+  readonly dependencyStatus?: RunnerDependencyStatus | undefined;
+  readonly socketFactory?: ((url: string) => WebSocket) | undefined;
   readonly channelSession: KandanChannelSessionOptions | undefined;
 };
 
@@ -114,17 +156,71 @@ async function openLocalCodexRunner(
   cleanup: CleanupStack,
   close: () => Promise<void>,
 ): Promise<LocalCodexRunnerHandle> {
-  const kandan = await connectPhoenixClient(options.kandanUrl, options.token);
+  const allowedForwardPorts = options.allowedForwardPorts ?? [];
+  const liveForwardPorts = new Set<number>(allowedForwardPorts);
+  const managedForwardPorts = new Set<number>();
+  const allowedCwds = { value: [...options.allowedCwds] };
+  const localEditorState: { value: LocalEditorState } = {
+    value: { status: "disabled" },
+  };
+  const localEditorGeneration = { value: 0 };
+  cleanup.actions.push(() => {
+    if (localEditorState.value.status === "running") {
+      localEditorState.value.process.kill("SIGINT");
+      localEditorState.value.collaboration?.process.kill("SIGINT");
+    }
+  });
+  const capabilitiesPayload = (): JsonObject => ({
+    codexAppServer: true,
+    codexRemoteTui: true,
+    startInstance: allowedCwds.value.length > 0,
+    allowedCwds: allowedCwds.value,
+    allowedCwdSuggestions: allowedCwdSuggestions(
+      options.cwd,
+      allowedCwds.value,
+    ),
+    portForwarding: liveForwardPorts.size > 0,
+    allowedPorts: Array.from(liveForwardPorts).sort(
+      (left, right) => left - right,
+    ),
+    streamingForwarding: true,
+    streamingForwardingVersion: 1,
+    toolStatus:
+      options.dependencyStatus === undefined
+        ? null
+        : dependencyStatusPayload(options.dependencyStatus),
+    editorRuntime:
+      options.dependencyStatus?.editorRuntime === undefined
+        ? null
+        : dependencyStatusPayload(options.dependencyStatus).editorRuntime,
+    ...localEditorCapabilities(
+      options.editorRuntime,
+      allowedCwds.value,
+      localEditorState.value,
+    ),
+  });
+  const kandan = await connectPhoenixClient(
+    options.kandanUrl,
+    options.token,
+    options.socketFactory,
+  );
   cleanup.actions.push(() => kandan.close());
   const topic = `local_runner:${options.runnerId}`;
-  await kandan.join(topic, {
+  const joinPayload = (): JsonObject => ({
     clientName: "kandan-local-codex-runner",
     version: "0.0.1",
-    capabilities: {
-      codexAppServer: true,
-      codexRemoteTui: true,
-    },
+    capabilities: capabilitiesPayload(),
+  });
+  await kandan.join(topic, joinPayload(), { rejoinPayload: joinPayload });
+  const forwardTunnel = await connectForwardTunnel({
+    kandanUrl: options.kandanUrl,
+    token: options.token,
+    runnerId: options.runnerId,
+    allowedPorts: () => Array.from(liveForwardPorts),
+    log,
+    socketFactory: options.socketFactory,
   });
+  cleanup.actions.push(() => forwardTunnel.close());
 
   const started =
     options.codexUrl === undefined
@@ -148,6 +244,58 @@ async function openLocalCodexRunner(
   }
 
   const instanceId = `codex-${randomUUID()}`;
+  const publishLocalEditorStatus = (payload: JsonObject): void => {
+    void kandan.push(topic, "local_editor_status", payload).catch((error) => {
+      log("kandan.local_editor_status_push_failed", {
+        message: error instanceof Error ? error.message : String(error),
+      });
+    });
+  };
+  const watchLocalEditorExit = (
+    state: Extract<LocalEditorState, { status: "running" }>,
+    generation: number,
+    initialStatusPushed: Promise<unknown>,
+  ): void => {
+    const handleExit = () => {
+      if (
+        localEditorGeneration.value !== generation ||
+        localEditorState.value.status !== "running" ||
+        localEditorState.value.process !== state.process
+      ) {
+        return;
+      }
+
+      localEditorState.value = { status: "disabled" };
+      liveForwardPorts.delete(state.port);
+      managedForwardPorts.delete(state.port);
+      if (state.collaboration !== undefined) {
+        liveForwardPorts.delete(state.collaboration.serverPort);
+        managedForwardPorts.delete(state.collaboration.serverPort);
+      }
+      publishLocalEditorStatus({
+        instanceId,
+        ok: true,
+        cwd: state.cwd,
+        capabilities: {
+          ...capabilitiesPayload(),
+          revokedPorts:
+            state.collaboration === undefined
+              ? [state.port]
+              : [state.port, state.collaboration.serverPort],
+        },
+      });
+    };
+
+    const handleExitAfterInitialStatus = () => {
+      void initialStatusPushed.then(handleExit).catch((error) => {
+        log("kandan.local_editor_initial_status_failed", {
+          message: error instanceof Error ? error.message : String(error),
+        });
+      });
+    };
+
+    void state.exited.then(handleExitAfterInitialStatus);
+  };
   const codex = await connectCodexAppServer(codexUrl);
   cleanup.actions.push(() => codex.close());
 
@@ -188,6 +336,17 @@ async function openLocalCodexRunner(
             codexBin: options.codexBin,
             fast: options.fast,
             launchTui: options.launchTui,
+            enablePortForwardWatch: true,
+            initialForwardPorts: allowedForwardPorts,
+            suppressedForwardPorts: () => Array.from(managedForwardPorts),
+            onForwardPortApproved: (port) => {
+              liveForwardPorts.add(port);
+              return capabilitiesPayload();
+            },
+            onForwardPortRevoked: (port) => {
+              liveForwardPorts.delete(port);
+              return capabilitiesPayload();
+            },
             channelSession: options.channelSession,
           },
           log,
@@ -210,9 +369,10 @@ async function openLocalCodexRunner(
     model: options.channelSession?.model ?? null,
     reasoningEffort: options.channelSession?.reasoningEffort ?? null,
     fast: options.fast ?? false,
+    capabilities: capabilitiesPayload(),
   });
   const pushHeartbeat = () =>
-    kandan.push(topic, "heartbeat", heartbeatPayload()).catch(error => {
+    kandan.push(topic, "heartbeat", heartbeatPayload()).catch((error) => {
       log("kandan.heartbeat_push_failed", {
         message: error instanceof Error ? error.message : String(error),
       });
@@ -224,6 +384,11 @@ async function openLocalCodexRunner(
   kandan.onReconnect(() => pushHeartbeat().then(() => undefined));
   void pushHeartbeat();
 
+  const forwardWebSockets = createForwardWebSocketManager(kandan, topic, () =>
+    Array.from(liveForwardPorts),
+  );
+  cleanup.actions.push(() => forwardWebSockets.close());
+
   const channelCodexThreadId = channelSession?.currentCodexThreadId();
   if (options.launchTui && channelCodexThreadId !== undefined) {
     await prepareCodexThreadForTuiResume(codex, channelCodexThreadId);
@@ -246,24 +411,26 @@ async function openLocalCodexRunner(
     });
   }
 
-  codex.onNotification(notification => {
+  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),
+      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", {
@@ -273,7 +440,7 @@ async function openLocalCodexRunner(
     channelSession?.handleCodexNotification(notification.method, params);
   });
 
-  kandan.onControl(control => {
+  kandan.onControl((control) => {
     log("kandan.control", { control });
     if (!controlTargetsInstance(control, instanceId)) {
       log("kandan.control_ignored", {
@@ -285,24 +452,143 @@ async function openLocalCodexRunner(
       return;
     }
 
+    if (isForwardHttpRequestControl(control)) {
+      void handleForwardHttpRequest(control, Array.from(liveForwardPorts))
+        .then((response) =>
+          kandan.push(topic, "forward:http_response", response),
+        )
+        .catch((error) =>
+          kandan.push(topic, "forward:http_response", {
+            requestId: control.requestId,
+            ok: false,
+            error: error instanceof Error ? error.message : String(error),
+          }),
+        )
+        .catch((error) => {
+          log("kandan.forward_response_push_failed", {
+            message: error instanceof Error ? error.message : String(error),
+          });
+        });
+      return;
+    }
+
+    if (isForwardWebSocketControl(control)) {
+      forwardWebSockets.handle(control);
+      return;
+    }
+
+    if (isStartLocalEditorControl(control)) {
+      void startLocalEditor(control, {
+        codeServerBin: options.codeServerBin,
+        editorRuntime: options.editorRuntime,
+        allowedCwds: allowedCwds.value,
+        currentState: localEditorState.value,
+        browserBaseUrl:
+          control.browserBaseUrl ?? process.env.KANDAN_LOCAL_RUNNER_PUBLIC_BASE_URL,
+        runnerId: options.runnerId,
+      })
+        .then((result) => {
+          if (result.ok) {
+            localEditorGeneration.value += 1;
+            const editorGeneration = localEditorGeneration.value;
+            if (localEditorState.value.status === "running") {
+              liveForwardPorts.delete(localEditorState.value.port);
+              managedForwardPorts.delete(localEditorState.value.port);
+              if (localEditorState.value.collaboration !== undefined) {
+                liveForwardPorts.delete(
+                  localEditorState.value.collaboration.serverPort,
+                );
+                managedForwardPorts.delete(
+                  localEditorState.value.collaboration.serverPort,
+                );
+              }
+            }
+            localEditorState.value = result.state;
+            liveForwardPorts.add(result.event.port);
+            managedForwardPorts.add(result.event.port);
+            if (result.event.collaboration !== undefined) {
+              liveForwardPorts.add(result.event.collaboration.serverPort);
+              managedForwardPorts.add(result.event.collaboration.serverPort);
+            }
+            const initialStatusPushed = kandan.push(
+              topic,
+              "local_editor_status",
+              {
+                instanceId,
+                requestId: control.requestId,
+                ok: true,
+                capabilities: capabilitiesPayload(),
+                ...result.event,
+              },
+            );
+
+            if (result.state.status === "running") {
+              watchLocalEditorExit(
+                result.state,
+                editorGeneration,
+                initialStatusPushed,
+              );
+            }
+
+            return initialStatusPushed;
+          }
+
+          localEditorState.value = result.state;
+          return kandan.push(topic, "local_editor_status", {
+            instanceId,
+            requestId: control.requestId,
+            ok: false,
+            reason: result.reason,
+            capabilities: capabilitiesPayload(),
+          });
+        })
+        .catch((error) =>
+          kandan.push(topic, "local_editor_status", {
+            instanceId,
+            requestId: control.requestId,
+            ok: false,
+            reason: error instanceof Error ? error.message : String(error),
+            capabilities: capabilitiesPayload(),
+          }),
+        )
+        .catch((error) => {
+          log("kandan.local_editor_status_push_failed", {
+            message: error instanceof Error ? error.message : String(error),
+          });
+        });
+      return;
+    }
+
+    if (isUpdateRunnerConfigControl(control)) {
+      allowedCwds.value = normalizeAllowedCwds(control.allowedCwds);
+      void pushHeartbeat();
+      return;
+    }
+
     void (channelSession?.handleControl(control) ?? Promise.resolve(undefined))
-      .then(handled => {
+      .then((handled) => {
         if (handled !== undefined) {
           return handled;
         }
 
-        return applyControl(codex, instanceId, control);
+        return applyControl(
+          codex,
+          instanceId,
+          options,
+          allowedCwds.value,
+          control,
+        );
       })
-      .then(response => {
+      .then((response) => {
         return kandan.push(topic, "codex_response", response);
       })
-      .catch(error => {
+      .catch((error) => {
         return kandan.push(topic, "codex_error", {
           instanceId,
           message: error instanceof Error ? error.message : String(error),
         });
       })
-      .catch(error => {
+      .catch((error) => {
         log("kandan.control_response_push_failed", {
           message: error instanceof Error ? error.message : String(error),
         });
@@ -312,7 +598,10 @@ async function openLocalCodexRunner(
   return { instanceId, codexUrl, close };
 }
 
-function controlTargetsInstance(control: KandanControl, instanceId: string): boolean {
+function controlTargetsInstance(
+  control: KandanControl,
+  instanceId: string,
+): boolean {
   return control.instanceId === undefined || control.instanceId === instanceId;
 }
 
@@ -361,7 +650,7 @@ async function discoverCodexThreads(
     ? []
     : data
         .filter(isJsonObject)
-        .map(thread => ({
+        .map((thread) => ({
           id: stringValue(thread.id) ?? "",
           preview: stringValue(thread.preview) ?? "",
           cwd: stringValue(thread.cwd) ?? "",
@@ -369,7 +658,7 @@ async function discoverCodexThreads(
           updatedAt: integerValue(thread.updatedAt) ?? null,
           status: objectValue(thread.status) ?? null,
         }))
-        .filter(thread => thread.id !== "");
+        .filter((thread) => thread.id !== "");
 }
 
 function makeRunnerLogger(options: RunnerOptions): RunnerLogger {
@@ -381,7 +670,9 @@ function makeRunnerLogger(options: RunnerOptions): RunnerLogger {
 
 function installCleanupHandlers(close: () => Promise<void>): () => void {
   const closeAndExit = () => {
-    void close().catch(() => undefined).finally(() => process.exit(0));
+    void close()
+      .catch(() => undefined)
+      .finally(() => process.exit(0));
   };
   const closeOnExit = () => {
     void close().catch(() => undefined);
@@ -486,9 +777,47 @@ export async function prepareCodexThreadForTuiResume(
 async function applyControl(
   codex: Awaited<ReturnType<typeof connectCodexAppServer>>,
   instanceId: string,
+  options: RunnerOptions,
+  allowedCwds: readonly string[],
   control: KandanControl,
 ): Promise<JsonObject> {
   switch (control.type) {
+    case "start_instance": {
+      const cwd = resolveAllowedCwd(control.cwd, allowedCwds);
+
+      if (!cwd.ok) {
+        return {
+          instanceId,
+          controlType: control.type,
+          ok: false,
+          error: cwd.reason,
+        };
+      }
+
+      const response = await codex.request("thread/start", {
+        cwd: cwd.cwd,
+        serviceName: "kandan-local-runner",
+        personality: "pragmatic",
+        ...(control.model === undefined ? {} : { model: control.model }),
+        ...(control.reasoningEffort === undefined
+          ? {}
+          : { reasoningEffort: control.reasoningEffort }),
+        ...(control.approvalPolicy === undefined
+          ? {}
+          : { approvalPolicy: control.approvalPolicy }),
+        ...(control.sandbox === undefined ? {} : { sandbox: control.sandbox }),
+        ...(control.fast === true ? { serviceTier: "fast" } : {}),
+      });
+
+      return {
+        instanceId,
+        controlType: control.type,
+        cwd: cwd.cwd,
+        matchedRoot: cwd.matchedRoot,
+        response: response as JsonObject,
+      };
+    }
+
     case "start_turn": {
       const response = await codex.request("turn/start", {
         threadId: control.threadId,
@@ -540,9 +869,41 @@ async function applyControl(
 
     case "stop_instance":
     case "kill_instance":
-    case "start_instance":
     case "interrupt_queued_messages":
     case "resolve_codex_approval_request":
+    case "forward_http_request":
+    case "forward_websocket_open":
+    case "forward_websocket_send":
+    case "forward_websocket_close":
+    case "start_local_editor":
+    case "update_runner_config":
       return { instanceId, controlType: control.type, skipped: true };
   }
 }
+
+function isUpdateRunnerConfigControl(
+  control: KandanControl,
+): control is Extract<
+  KandanControl,
+  { readonly type: "update_runner_config" }
+> {
+  return control.type === "update_runner_config";
+}
+
+function normalizeAllowedCwds(values: readonly string[]): string[] {
+  return Array.from(
+    new Set(
+      values.flatMap((value) => {
+        const normalized = value.trim();
+        return normalized === "" ? [] : [normalized];
+      }),
+    ),
+  );
+}
+
+function allowedCwdSuggestions(
+  cwd: string,
+  allowedCwds: readonly string[],
+): string[] {
+  return normalizeAllowedCwds([cwd, ...allowedCwds]);
+}

package/src/streamDeltaCoalescing.ts

@@ -0,0 +1,129 @@
+/*
+- Date: 2026-04-26
+  Spec: plans/2026-04-26-local-codex-driver-worldclass-spec.md
+  Relationship: Pure coalescing helpers for runner-batched Codex stream
+  updates, keeping one logical Codex item mapped to one Kandan row while
+  avoiding per-delta state churn in the session orchestrator.
+*/
+import type {
+  CodexAssistantDelta,
+  CodexCommandOutputDelta,
+  CodexFileChangeDelta,
+  CodexReasoningDelta,
+} from "./codexOutput";
+
+type StreamDelta = {
+  readonly itemKey: string;
+  readonly turnId: string | undefined;
+};
+
+type TextDelta = StreamDelta & {
+  readonly delta?: string | undefined;
+  readonly patchText?: string | undefined;
+};
+
+export function coalesceAssistantDeltas(
+  deltas: readonly CodexAssistantDelta[],
+): CodexAssistantDelta[] {
+  return coalesceTextDeltas(deltas, (delta) => ({
+    itemKey: delta.itemKey,
+    turnId: delta.turnId,
+    delta: delta.delta,
+  }));
+}
+
+export function coalesceReasoningDeltas(
+  deltas: readonly CodexReasoningDelta[],
+): CodexReasoningDelta[] {
+  return coalesceTextDeltas(deltas, (delta) => ({
+    itemKey: delta.itemKey,
+    turnId: delta.turnId,
+    delta: delta.delta,
+  }));
+}
+
+export function coalesceFileChangeDeltas(
+  deltas: readonly CodexFileChangeDelta[],
+): CodexFileChangeDelta[] {
+  return coalesceTextDeltas(deltas, (delta) => ({
+    itemKey: delta.itemKey,
+    turnId: delta.turnId,
+    patchText: delta.patchText,
+  }));
+}
+
+export function coalesceCommandOutputDeltas(
+  deltas: readonly CodexCommandOutputDelta[],
+): CodexCommandOutputDelta[] {
+  const coalesced = new Map<string, CodexCommandOutputDelta>();
+
+  for (const delta of deltas) {
+    const key = commandOutputStreamingKey(delta);
+    const existing = coalesced.get(key);
+
+    if (existing === undefined) {
+      coalesced.set(key, delta);
+      continue;
+    }
+
+    coalesced.set(key, {
+      ...delta,
+      processId: delta.processId ?? existing.processId,
+      delta: `${existing.delta}${delta.delta}`,
+    });
+  }
+
+  return [...coalesced.values()];
+}
+
+export function firstDeltaTurnId(
+  deltas: readonly { readonly turnId: string | undefined }[],
+): string | undefined {
+  return deltas.find((delta) => delta.turnId !== undefined)?.turnId;
+}
+
+function coalesceTextDeltas<TDelta extends TextDelta>(
+  deltas: readonly TDelta[],
+  clone: (delta: TDelta) => TDelta,
+): TDelta[] {
+  const coalesced = new Map<string, TDelta>();
+
+  for (const delta of deltas) {
+    const key = streamingItemKey(delta);
+    const existing = coalesced.get(key);
+
+    if (existing === undefined) {
+      coalesced.set(key, clone(delta));
+      continue;
+    }
+
+    coalesced.set(key, mergeTextDelta(existing, delta));
+  }
+
+  return [...coalesced.values()];
+}
+
+function mergeTextDelta<TDelta extends TextDelta>(
+  existing: TDelta,
+  incoming: TDelta,
+): TDelta {
+  if (existing.delta !== undefined || incoming.delta !== undefined) {
+    return {
+      ...incoming,
+      delta: `${existing.delta ?? ""}${incoming.delta ?? ""}`,
+    };
+  }
+
+  return {
+    ...incoming,
+    patchText: `${existing.patchText ?? ""}${incoming.patchText ?? ""}`,
+  };
+}
+
+function streamingItemKey(delta: StreamDelta): string {
+  return `${delta.turnId ?? "turn"}:${delta.itemKey}`;
+}
+
+function commandOutputStreamingKey(delta: CodexCommandOutputDelta): string {
+  return `${streamingItemKey(delta)}:${delta.stream}`;
+}