@linzumi/cli 0.0.11-beta → 0.0.13-beta

package/src/localConfig.ts

@@ -0,0 +1,99 @@
+/*
+- Date: 2026-05-01
+  Spec: ../../kandan/server_v2/plans/2026-05-01-runner-editor-dropdown-and-thread-controls.md
+  Relationship: Owns the npm-first local runner's trusted-folder config at
+  ~/.linzumi/config.json so README path-management commands are product truth.
+*/
+import { existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, resolve } from "node:path";
+import { expandUserPath } from "./localCapabilities";
+
+export type LinzumiConfig = {
+  readonly version: 1;
+  readonly allowedCwds: readonly string[];
+};
+
+export function localConfigPath(env: NodeJS.ProcessEnv = process.env): string {
+  const override = env.LINZUMI_CONFIG_FILE;
+
+  return override !== undefined && override.trim() !== ""
+    ? resolve(expandUserPath(override))
+    : resolve(homedir(), ".linzumi", "config.json");
+}
+
+export function readLocalConfig(path: string = localConfigPath()): LinzumiConfig {
+  if (!existsSync(path)) {
+    return { version: 1, allowedCwds: [] };
+  }
+
+  const parsed = JSON.parse(readFileSync(path, "utf8")) as unknown;
+
+  if (!isConfigPayload(parsed)) {
+    throw new Error(`invalid Linzumi config: ${path}`);
+  }
+
+  return {
+    version: 1,
+    allowedCwds: uniqueStrings(parsed.allowedCwds),
+  };
+}
+
+export function readConfiguredAllowedCwds(path: string = localConfigPath()): string[] {
+  return readLocalConfig(path).allowedCwds.map((cwd) => {
+    try {
+      return realpathSync(resolve(expandUserPath(cwd)));
+    } catch (_error) {
+      throw new Error(`invalid Linzumi config allowed path: ${cwd} does not exist`);
+    }
+  });
+}
+
+export function addAllowedCwd(pathValue: string, path: string = localConfigPath()): string[] {
+  const normalizedPath = realpathSync(resolve(expandUserPath(pathValue)));
+  const config = readLocalConfig(path);
+  const allowedCwds = uniqueStrings([...config.allowedCwds, normalizedPath]);
+  writeLocalConfig({ version: 1, allowedCwds }, path);
+  return allowedCwds;
+}
+
+export function removeAllowedCwd(pathValue: string, path: string = localConfigPath()): string[] {
+  const requestedPath = resolve(expandUserPath(pathValue));
+  const normalizedRequest = realpathOrResolved(requestedPath);
+  const config = readLocalConfig(path);
+  const allowedCwds = config.allowedCwds.filter((cwd) => {
+    const normalizedExisting = realpathOrResolved(cwd);
+    return cwd !== pathValue && normalizedExisting !== normalizedRequest;
+  });
+  writeLocalConfig({ version: 1, allowedCwds }, path);
+  return allowedCwds;
+}
+
+export function writeLocalConfig(config: LinzumiConfig, path: string = localConfigPath()): void {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, `${JSON.stringify(config, null, 2)}\n`, "utf8");
+}
+
+function isConfigPayload(value: unknown): value is LinzumiConfig {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    (value as { readonly version?: unknown }).version === 1 &&
+    Array.isArray((value as { readonly allowedCwds?: unknown }).allowedCwds) &&
+    (value as { readonly allowedCwds: readonly unknown[] }).allowedCwds.every(
+      (cwd) => typeof cwd === "string" && cwd.trim() !== "",
+    )
+  );
+}
+
+function uniqueStrings(values: readonly string[]): string[] {
+  return [...new Set(values.map((value) => value.trim()).filter((value) => value !== ""))];
+}
+
+function realpathOrResolved(pathValue: string): string {
+  try {
+    return realpathSync(resolve(expandUserPath(pathValue)));
+  } catch (_error) {
+    return resolve(expandUserPath(pathValue));
+  }
+}

package/src/localEditor.ts

@@ -592,7 +592,7 @@ export function prepareLocalEditorCollaboration(
     return undefined;
   }
 
-  const targetPath = `/local-codex-runner-targets/${encodeURIComponent(runnerId)}/forwards/${serverPort}`;
+  const targetPath = `/local-codex-runners/${encodeURIComponent(runnerId)}/forwards/${serverPort}/preview-target`;
   const serverUrl = new URL(targetPath, `${browserBaseUrl}/`).toString();
   const bootstrapServerUrl =
     collaboration.bootstrapToken === undefined || collaboration.bootstrapToken === ""

package/src/localForwarding.ts

@@ -211,14 +211,15 @@ function openLocalWebSocket(
   scheme: "ws" | "wss",
 ): void {
   let opened = false;
-  const websocket = new WebSocket(
-    localForwardUrl(
-      scheme === "ws" ? "http" : "https",
-      control.port,
-      control.path,
-      control.queryString,
-    ).replace(/^http/, scheme),
-  );
+  const url = localForwardUrl(
+    scheme === "ws" ? "http" : "https",
+    control.port,
+    control.path,
+    control.queryString,
+  ).replace(/^http/, scheme);
+  const protocols = webSocketProtocols(control.headers);
+  const websocket =
+    protocols === undefined ? new WebSocket(url) : new WebSocket(url, protocols);
   sockets.set(control.socketId, websocket);
   websocket.addEventListener("open", () => {
     opened = true;
@@ -260,6 +261,28 @@ function openLocalWebSocket(
   });
 }
 
+function webSocketProtocols(headers: JsonValue | undefined): string[] | undefined {
+  if (!Array.isArray(headers)) {
+    return undefined;
+  }
+
+  const protocols = headers.flatMap(header => {
+    if (
+      !isWireHeader(header) ||
+      header.name.toLowerCase() !== "sec-websocket-protocol"
+    ) {
+      return [];
+    }
+
+    return header.value
+      .split(",")
+      .map(protocol => protocol.trim())
+      .filter(protocol => protocol !== "");
+  });
+
+  return protocols.length === 0 ? undefined : protocols;
+}
+
 function localForwardUrl(
   scheme: "http" | "https",
   port: number,

package/src/protocol.ts

@@ -37,6 +37,11 @@
   Spec: plans/2026-04-26-local-runner-subdomain-forwarding-epr.md
   Relationship: Defines the typed WebSocket forwarding controls used by
   isolated preview subdomains.
+
+- Date: 2026-05-02
+  Spec: plans/2026-05-02-agent-first-zero-to-codex-launch-plan.md
+  Relationship: Keeps the npm CLI runner protocol in parity with the legacy
+  runner for runtime session setting updates.
 */
 export type JsonValue =
   | null
@@ -133,6 +138,7 @@ export type KandanControl =
       readonly type: "start_instance";
       readonly instanceId?: string;
       readonly cwd?: string;
+      readonly workDescription?: string;
       readonly launchTui?: boolean;
       readonly model?: string;
       readonly reasoningEffort?: string;
@@ -181,6 +187,16 @@ export type KandanControl =
       readonly requestId: string;
       readonly decision: "approve" | "deny";
     }
+  | {
+      readonly type: "update_session_settings";
+      readonly instanceId?: string;
+      readonly threadId: string;
+      readonly model?: string | null;
+      readonly reasoningEffort?: string | null;
+      readonly approvalPolicy?: string | null;
+      readonly sandbox?: string | null;
+      readonly fast?: boolean;
+    }
   | {
       readonly type: "resolve_port_forward_request";
       readonly instanceId: string;

package/src/runner.ts

@@ -60,7 +60,6 @@ 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,
@@ -82,6 +81,7 @@ import {
 import { connectPhoenixClient } from "./phoenix";
 import {
   type JsonObject,
+  type JsonRpcResponse,
   type JsonValue,
   type KandanChannelSessionOptions,
   type KandanControl,
@@ -183,8 +183,6 @@ async function openLocalCodexRunner(
     allowedPorts: Array.from(liveForwardPorts).sort(
       (left, right) => left - right,
     ),
-    streamingForwarding: true,
-    streamingForwardingVersion: 1,
     toolStatus:
       options.dependencyStatus === undefined
         ? null
@@ -209,18 +207,26 @@ async function openLocalCodexRunner(
   const joinPayload = (): JsonObject => ({
     clientName: "kandan-local-codex-runner",
     version: "0.0.1",
+    workspace: options.channelSession?.workspaceSlug ?? null,
+    channel: options.channelSession?.channelSlug ?? null,
     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,
+
+  const pendingControls: KandanControl[] = [];
+  const controlDispatcher: {
+    value: ((control: KandanControl) => void) | undefined;
+  } = { value: undefined };
+  kandan.onControl((control) => {
+    const dispatcher = controlDispatcher.value;
+    if (dispatcher === undefined) {
+      pendingControls.push(control);
+      return;
+    }
+
+    dispatcher(control);
   });
-  cleanup.actions.push(() => forwardTunnel.close());
+
+  await kandan.join(topic, joinPayload(), { rejoinPayload: joinPayload });
 
   const started =
     options.codexUrl === undefined
@@ -440,7 +446,7 @@ async function openLocalCodexRunner(
     channelSession?.handleCodexNotification(notification.method, params);
   });
 
-  kandan.onControl((control) => {
+  const handleControl = (control: KandanControl) => {
     log("kandan.control", { control });
     if (!controlTargetsInstance(control, instanceId)) {
       log("kandan.control_ignored", {
@@ -593,7 +599,10 @@ async function openLocalCodexRunner(
           message: error instanceof Error ? error.message : String(error),
         });
       });
-  });
+  };
+
+  controlDispatcher.value = handleControl;
+  pendingControls.splice(0).forEach(handleControl);
 
   return { instanceId, codexUrl, close };
 }
@@ -661,9 +670,25 @@ async function discoverCodexThreads(
         .filter((thread) => thread.id !== "");
 }
 
+function extractStartedThreadId(response: JsonRpcResponse): string | undefined {
+  if ("error" in response) {
+    return undefined;
+  }
+
+  return stringValue(objectValue(objectValue(response.result)?.thread)?.id);
+}
+
+function normalizedWorkDescription(value: string | undefined): string | undefined {
+  const normalized = value?.trim();
+
+  return normalized === undefined || normalized === ""
+    ? undefined
+    : normalized;
+}
+
 function makeRunnerLogger(options: RunnerOptions): RunnerLogger {
   return createRunnerLogger(
-    options.logFile ?? join(options.cwd, ".kandan-local-codex-runner.log"),
+    options.logFile ?? join(options.cwd, ".linzumi-runner.log"),
     options.launchTui ? undefined : reportRunnerConsoleEvent,
   );
 }
@@ -808,6 +833,15 @@ async function applyControl(
         ...(control.sandbox === undefined ? {} : { sandbox: control.sandbox }),
         ...(control.fast === true ? { serviceTier: "fast" } : {}),
       });
+      const codexThreadId = extractStartedThreadId(response);
+      const workDescription = normalizedWorkDescription(control.workDescription);
+
+      if (codexThreadId !== undefined && workDescription !== undefined) {
+        await codex.request("turn/start", {
+          threadId: codexThreadId,
+          input: [{ type: "text", text: workDescription }],
+        });
+      }
 
       return {
         instanceId,