@linzumi/cli 0.0.1-beta → 0.0.3-beta

package/README.md

@@ -1,32 +1,33 @@
 # @linzumi/cli
 
 ```text
-        .  *  .        .      *
-   *       _.-"""-._        .
-        .-'  _   _  '-.  *
-       /    (o)_(o)    \
-      |        .-.       |       mouse in the grove
-      |     .-(   )-.    |       listening for Kandan
-       \   /   '-'   \  /
-        '-.\__     __/.-'
-            /|     |\
-          _/ |  |  | \_
-        .'   |__|__|   '.
-       /   .  /___\  .   \
-      '._.'  /_____\  '._.'
+            ___       ___
+         .-'   '-. .-'   '-.
+       .'         '         '.
+      /     _           _     \
+     |    .' '.       .' '.    |
+     |   /     \ .-. /     \   |
+      \  \      (o o)      /  /
+       '._'._    \_/    _.'_.'
+            |     |     |
+            |    /|\    |
+            |___/ | \___|
+                \_|_/
+                 / \
 ```
 
 Linzumi's CLI package. It installs the `linzumi` executable.
 
-The current CLI is intentionally small: it connects this machine to Kandan as a
-local Codex runner.
+The initial CLI command connects this computer to Kandan as a local Codex
+runner. It wraps the same local runner that was previously started with
+`bun run start -- ...`.
 
 ## Install
 
 Install the exact beta version:
 
 ```bash
-npm install -g @linzumi/cli@0.0.1-beta
+npm install -g @linzumi/cli@0.0.3-beta
 ```
 
 Or install the current beta tag:
@@ -35,68 +36,76 @@ Or install the current beta tag:
 npm install -g @linzumi/cli@beta
 ```
 
-Check that the executable is available:
+This beta expects Bun and Codex to be available locally:
 
 ```bash
+bun --version
+codex --version
 linzumi --version
 ```
 
-Expected output for this beta:
+Expected CLI output:
 
 ```bash
-linzumi 0.0.1-beta
+linzumi 0.0.3-beta
 ```
 
-## Basic Use
+## Prod Quick Start
 
-Run the CLI without arguments to start the default connection command:
+For the Linzumi workspace in prod, this is the first command to try:
 
 ```bash
-linzumi
+npm install -g @linzumi/cli@0.0.3-beta
+
+linzumi connect \
+  --kandan-url wss://serve.kandanai.com \
+  --workspace linzumi \
+  --channel seans-playground \
+  --listen-user sean \
+  --codex-bin codex \
+  --launch-tui
 ```
 
-That prints the connection guide and tells you to start the local runner
-connection flow from Kandan.
+The runner handles OAuth itself. If the cached Kandan token is missing or
+rejected, it opens the OAuth flow and saves the refreshed auth cache.
 
-You can print the same guide directly:
+For a more explicit launch that pins the Codex model, reasoning effort, and
+fast service tier:
 
 ```bash
-linzumi connect
+linzumi connect \
+  --kandan-url wss://serve.kandanai.com \
+  --workspace linzumi \
+  --channel seans-playground \
+  --listen-user sean \
+  --codex-bin codex \
+  --model gpt-5.5 \
+  --reasoning-effort low \
+  --fast \
+  --launch-tui
 ```
 
-`linzumi connect` is the user-facing command. The CLI runs on your local
-computer; Kandan does not execute this binary for you. Kandan shows the command
-or connection details, and you run them locally.
-
-## Connect To The Linzumi Workspace
+## Basic Use
 
-1. Install the CLI:
+Running `linzumi` without arguments prints the local runner guide:
 
 ```bash
-npm install -g @linzumi/cli@0.0.1-beta
+linzumi
 ```
 
-2. Confirm the CLI is installed:
+Start the runner for a Kandan workspace/channel:
 
 ```bash
-linzumi --version
+linzumi connect \
+  --kandan-url wss://serve.kandanai.com \
+  --workspace linzumi \
+  --channel seans-playground \
+  --listen-user sean \
+  --codex-bin codex \
+  --launch-tui
 ```
 
-3. Open Kandan in your browser and switch to the Linzumi workspace.
-
-4. Start the local runner connection flow in Kandan.
-
-5. Copy the command Kandan shows you and run it in a terminal on this computer.
-
-6. Leave that terminal process running while you use the local runner from
-Kandan.
-
-For orientation, running the CLI without arguments prints the local connection
-guide:
-
-```bash
-linzumi
-```
+Leave that terminal process running while Kandan uses the local runner.
 
 ## Commands
 
@@ -104,74 +113,42 @@ Supported commands right now:
 
 ```bash
 linzumi
-linzumi connect
 linzumi --help
 linzumi --version
 linzumi connect --help
-linzumi connect --version
+linzumi connect [runner options]
+linzumi auth [auth options]
 ```
 
-`local-codex-runner` is still accepted as a compatibility alias:
+`linzumi local-codex-runner` is accepted as a compatibility alias for
+`linzumi connect`.
 
-```bash
-linzumi local-codex-runner
-```
-
-## Runner Protocol
-
-During the connection flow, Kandan may tell you to run a command shaped like:
-
-```bash
-linzumi connect app-server --listen ws://127.0.0.1:45021
-```
-
-That trailing `app-server --listen <url>` is runner protocol. It is not a
-separate Linzumi feature; it is the Codex app-server mode that lets this local
-process open the websocket Kandan will connect to.
-
-## Configuration
-
-The Kandan local runner flow should give you the command or configuration to run
-on your machine. For manual testing, the same configuration can be supplied with
-environment variables:
+## Useful Options
 
 ```bash
-export LINZUMI_LOCAL_CODEX_RUNNER_LINZ_BIN=/path/to/kandan-local-bridge-linz
-export LINZUMI_LOCAL_CODEX_RUNNER_VM_ID=lzrunner123
-export LINZUMI_LOCAL_CODEX_RUNNER_REMOTE_CODEX_BIN=.kandan/tools/codex/0.116.0/bin/codex
-export LINZUMI_LOCAL_CODEX_RUNNER_REMOTE_ENV=.kandan/runtime/agents/13/channels/8/codex_app_server/runtime.env.sh
+--kandan-url <ws-url>       Kandan websocket URL, for example wss://serve.kandanai.com
+--workspace <slug>          Workspace slug, for example linzumi
+--channel <slug|w/c>        Channel slug, or workspace/channel
+--kandan-thread-id <uuid>   Resume an existing Kandan thread
+--listen-user <user|all>    User whose replies are accepted, or all
+--cwd <path>                Working directory for Codex
+--codex-bin <path>          Codex executable, default codex
+--model <name>              Codex model
+--reasoning-effort <value>  Codex reasoning effort
+--fast                      Request the fast service tier
+--launch-tui                Launch codex --remote against the app-server
+--oauth-callback-host <ip>  Callback host reachable by your browser
 ```
 
-Or with flags:
-
-```bash
-linzumi connect \
-  --linz-bin /path/to/kandan-local-bridge-linz \
-  --vm-id lzrunner123 \
-  --remote-codex-bin .kandan/tools/codex/0.116.0/bin/codex \
-  --remote-env .kandan/runtime/agents/13/channels/8/codex_app_server/runtime.env.sh \
-  app-server --listen ws://127.0.0.1:45021
-```
-
-The runner executes:
-
-```bash
-<linz-bin> exec <vm-id> -- sh -lc "exec <remote-kandan-linz> app-server --env-file <remote-env> <remote-codex-bin> <listen-url>"
-```
+Run `linzumi connect --help` for the full option list.
 
 ## Troubleshooting
 
 If `linzumi` is not found, confirm the global npm bin directory is on your
-`PATH`:
-
-```bash
-npm bin -g
-```
+`PATH`.
 
-If `linzumi connect` reports missing configuration, use the full command or
-configuration shown by Kandan's local runner connection flow. Manual launches
-need the environment variables or flags listed above.
+If `bun` is not found, install Bun first. This beta wraps the existing Bun local
+runner implementation instead of a Node rewrite.
 
-If the runner starts but Kandan cannot connect, check that the `--listen` URL
-was supplied by Kandan and that the configured LINZ bridge command can reach the
-runner VM.
+If OAuth opens but does not return to the CLI, pass `--oauth-callback-host` with
+an IP address that your browser can reach, such as your Tailscale IP.

package/bin/linzumi.js

@@ -1,15 +1,23 @@
 #!/usr/bin/env node
 
-import { runCli } from "../src/cli.js";
+import { spawnSync } from "node:child_process";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
 
-const result = runCli({
-  argv: process.argv.slice(2),
-  env: process.env,
+const packageRoot = dirname(dirname(fileURLToPath(import.meta.url)));
+const entrypoint = join(packageRoot, "src", "index.ts");
+const result = spawnSync("bun", ["run", entrypoint, ...process.argv.slice(2)], {
   cwd: process.cwd(),
-  stdout: process.stdout,
-  stderr: process.stderr,
+  env: process.env,
+  stdio: "inherit",
 });
 
-if (result.exitCode !== 0) {
-  process.exit(result.exitCode);
+if (result.error !== undefined) {
+  process.stderr.write(
+    `failed to launch linzumi runner with bun: ${result.error.message}\n` +
+      "Install Bun, then rerun the linzumi command.\n",
+  );
+  process.exit(127);
 }
+
+process.exit(result.status ?? 1);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@linzumi/cli",
-  "version": "0.0.1-beta",
+  "version": "0.0.3-beta",
   "description": "Linzumi local Codex runner CLI.",
   "type": "module",
   "bin": {
@@ -12,9 +12,11 @@
     "README.md"
   ],
   "scripts": {
-    "test": "node ./test/local-codex-runner.test.js"
+    "start": "bun run src/index.ts",
+    "test": "bun test"
   },
   "engines": {
+    "bun": ">=1.1.0",
     "node": ">=22.0.0"
   },
   "publishConfig": {

package/src/authCache.ts

@@ -0,0 +1,157 @@
+/*
+- Date: 2026-04-24
+  Spec: plans/2026-04-24-local-codex-channel-thread-binding-spec.md
+  Relationship: Stores scoped local-runner OAuth tokens so users can log in
+  once and then start local Codex runners without pasting tokens repeatedly.
+*/
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { kandanHttpBaseUrl } from "./oauth";
+
+export type CachedLocalRunnerToken = {
+  readonly accessToken: string;
+  readonly kandanBaseUrl: string;
+  readonly issuedAt: string;
+  readonly expiresAt?: string | undefined;
+};
+
+type AuthFile = {
+  readonly version: 1;
+  readonly local_codex_runner?: Record<string, CachedTokenJson> | undefined;
+};
+
+type CachedTokenJson = {
+  readonly access_token: string;
+  readonly issued_at: string;
+  readonly expires_at?: string | undefined;
+};
+
+export function defaultAuthFilePath(): string {
+  const base = process.env.KANDAN_HOME ?? join(homedir(), ".kandan");
+  return join(base, "auth.json");
+}
+
+export function readCachedLocalRunnerToken(
+  kandanUrl: string,
+  authFilePath: string = defaultAuthFilePath(),
+): CachedLocalRunnerToken | undefined {
+  if (!existsSync(authFilePath)) {
+    return undefined;
+  }
+
+  const authFile = parseAuthFile(readFileSync(authFilePath, "utf8"));
+  const kandanBaseUrl = kandanHttpBaseUrl(kandanUrl);
+  const entry = authFile.local_codex_runner?.[kandanBaseUrl];
+
+  if (entry === undefined || entry.access_token.trim() === "") {
+    return undefined;
+  }
+
+  if (entry.expires_at !== undefined && Date.parse(entry.expires_at) <= Date.now()) {
+    return undefined;
+  }
+
+  return {
+    accessToken: entry.access_token,
+    kandanBaseUrl,
+    issuedAt: entry.issued_at,
+    expiresAt: entry.expires_at,
+  };
+}
+
+export function writeCachedLocalRunnerToken(args: {
+  readonly kandanUrl: string;
+  readonly accessToken: string;
+  readonly expiresInSeconds?: number | undefined;
+  readonly authFilePath?: string | undefined;
+}): CachedLocalRunnerToken {
+  const authFilePath = args.authFilePath ?? defaultAuthFilePath();
+  const existing = existsSync(authFilePath)
+    ? parseAuthFile(readFileSync(authFilePath, "utf8"))
+    : { version: 1 as const };
+  const kandanBaseUrl = kandanHttpBaseUrl(args.kandanUrl);
+  const issuedAt = new Date();
+  const expiresAt =
+    args.expiresInSeconds === undefined
+      ? undefined
+      : new Date(issuedAt.getTime() + args.expiresInSeconds * 1000).toISOString();
+  const next: AuthFile = {
+    ...existing,
+    version: 1,
+    local_codex_runner: {
+      ...(existing.local_codex_runner ?? {}),
+      [kandanBaseUrl]: {
+        access_token: args.accessToken,
+        issued_at: issuedAt.toISOString(),
+        expires_at: expiresAt,
+      },
+    },
+  };
+
+  mkdirSync(dirname(authFilePath), { recursive: true });
+  writeFileSync(authFilePath, `${JSON.stringify(next, null, 2)}\n`, "utf8");
+
+  return {
+    accessToken: args.accessToken,
+    kandanBaseUrl,
+    issuedAt: issuedAt.toISOString(),
+    expiresAt,
+  };
+}
+
+function parseAuthFile(text: string): AuthFile {
+  const parsed: unknown = JSON.parse(text);
+
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    throw new Error("Kandan auth cache must contain a JSON object");
+  }
+
+  const value = parsed as Record<string, unknown>;
+  const localRunner = value.local_codex_runner;
+
+  if (
+    localRunner !== undefined &&
+    (typeof localRunner !== "object" || localRunner === null || Array.isArray(localRunner))
+  ) {
+    throw new Error("Kandan auth cache local_codex_runner must be an object");
+  }
+
+  return {
+    version: 1,
+    local_codex_runner: normalizeLocalRunnerCache(localRunner),
+  };
+}
+
+function normalizeLocalRunnerCache(value: unknown): Record<string, CachedTokenJson> | undefined {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return undefined;
+  }
+
+  return Object.fromEntries(
+    Object.entries(value).flatMap(([key, entry]) => {
+      if (typeof entry !== "object" || entry === null || Array.isArray(entry)) {
+        return [];
+      }
+
+      const token = (entry as Record<string, unknown>).access_token;
+      const issuedAt = (entry as Record<string, unknown>).issued_at;
+      const expiresAt = (entry as Record<string, unknown>).expires_at;
+
+      if (typeof token !== "string" || typeof issuedAt !== "string") {
+        return [];
+      }
+
+      return [
+        [
+          key,
+          {
+            access_token: token,
+            issued_at: issuedAt,
+            expires_at: typeof expiresAt === "string" ? expiresAt : undefined,
+          },
+        ],
+      ];
+    }),
+  );
+}

package/src/authResolution.ts

@@ -0,0 +1,75 @@
+/*
+- Date: 2026-04-24
+  Spec: plans/2026-04-24-local-codex-channel-thread-binding-spec.md
+  Relationship: Implements the one-command runner auth behavior: use an
+  explicit token when supplied, validate cached scoped runner auth, and fall
+  back to the OAuth flow when cached auth is missing or rejected.
+*/
+import { readCachedLocalRunnerToken, writeCachedLocalRunnerToken } from "./authCache";
+import { acquireLocalRunnerTokenDetails, validateLocalRunnerToken } from "./oauth";
+
+export type LocalRunnerTokenResolutionArgs = {
+  readonly kandanUrl: string;
+  readonly explicitToken?: string | undefined;
+  readonly workspaceSlug?: string | undefined;
+  readonly channelSlug?: string | undefined;
+  readonly authFilePath?: string | undefined;
+  readonly callbackHost?: string | undefined;
+  readonly reportRejectedCachedToken?: (() => void) | undefined;
+};
+
+type LocalRunnerTokenResolutionDeps = {
+  readonly readCachedToken: typeof readCachedLocalRunnerToken;
+  readonly validateToken: typeof validateLocalRunnerToken;
+  readonly acquireAndCacheToken: (args: LocalRunnerTokenResolutionArgs) => Promise<string>;
+};
+
+export async function resolveLocalRunnerToken(
+  args: LocalRunnerTokenResolutionArgs,
+  deps: LocalRunnerTokenResolutionDeps = {
+    readCachedToken: readCachedLocalRunnerToken,
+    validateToken: validateLocalRunnerToken,
+    acquireAndCacheToken,
+  },
+): Promise<string> {
+  if (args.explicitToken !== undefined) {
+    return args.explicitToken;
+  }
+
+  const cached = deps.readCachedToken(args.kandanUrl, args.authFilePath);
+
+  if (cached !== undefined) {
+    const cachedTokenIsUsable = await deps.validateToken({
+      kandanUrl: args.kandanUrl,
+      accessToken: cached.accessToken,
+      workspaceSlug: args.workspaceSlug,
+      channelSlug: args.channelSlug,
+    });
+
+    if (cachedTokenIsUsable) {
+      return cached.accessToken;
+    }
+
+    args.reportRejectedCachedToken?.();
+  }
+
+  return await deps.acquireAndCacheToken(args);
+}
+
+async function acquireAndCacheToken(args: LocalRunnerTokenResolutionArgs): Promise<string> {
+  const token = await acquireLocalRunnerTokenDetails({
+    kandanUrl: args.kandanUrl,
+    workspaceSlug: args.workspaceSlug,
+    channelSlug: args.channelSlug,
+    callbackHost: args.callbackHost,
+  });
+
+  writeCachedLocalRunnerToken({
+    kandanUrl: args.kandanUrl,
+    accessToken: token.accessToken,
+    expiresInSeconds: token.expiresInSeconds,
+    authFilePath: args.authFilePath,
+  });
+
+  return token.accessToken;
+}