@linzumi/cli 0.0.1-beta → 0.0.2-beta

package/src/index.ts

@@ -0,0 +1,354 @@
+/*
+- Date: 2026-04-24
+  Spec: plans/2026-04-24-local-codex-runner-plan.md
+  Relationship: Provides the spec's initial Bun CLI entry point for starting
+  a customer-machine local runner with Kandan and Codex connection options.
+
+- Date: 2026-04-24
+  Spec: plans/2026-04-24-local-codex-channel-thread-binding-spec.md
+  Relationship: Parses the channel-bound runner options that let a local Codex
+  process bind to one Kandan channel/thread and filter accepted senders.
+
+- Date: 2026-04-24
+  Spec: plans/2026-04-24-local-codex-runner-deep-quality-spec.md
+  Relationship: Keeps default local runner identity collision-resistant for
+  concurrent local starts.
+*/
+import { randomUUID } from "node:crypto";
+import { runLocalCodexRunner, type RunnerOptions } from "./runner";
+import { writeCachedLocalRunnerToken } from "./authCache";
+import { resolveLocalRunnerToken } from "./authResolution";
+import { acquireLocalRunnerTokenDetails } from "./oauth";
+
+type FlagDefinition = {
+  readonly kind: "value" | "boolean";
+};
+
+const flagDefinitions = new Map<string, FlagDefinition>([
+  ["version", { kind: "boolean" }],
+  ["kandan-url", { kind: "value" }],
+  ["token", { kind: "value" }],
+  ["runner-id", { kind: "value" }],
+  ["cwd", { kind: "value" }],
+  ["codex-bin", { kind: "value" }],
+  ["codex-url", { kind: "value" }],
+  ["launch-tui", { kind: "boolean" }],
+  ["workspace", { kind: "value" }],
+  ["channel", { kind: "value" }],
+  ["kandan-thread-id", { kind: "value" }],
+  ["listen-user", { kind: "value" }],
+  ["model", { kind: "value" }],
+  ["reasoning-effort", { kind: "value" }],
+  ["sandbox", { kind: "value" }],
+  ["approval-policy", { kind: "value" }],
+  ["fast", { kind: "boolean" }],
+  ["log-file", { kind: "value" }],
+  ["auth-file", { kind: "value" }],
+  ["oauth-callback-host", { kind: "value" }],
+  ["help", { kind: "boolean" }],
+]);
+
+try {
+  await main(process.argv.slice(2));
+} catch (error) {
+  process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+  process.exit(1);
+}
+
+async function main(args: readonly string[]): Promise<void> {
+  const parsed = parseCommand(args);
+
+  switch (parsed.command) {
+    case "guide":
+      process.stdout.write(connectGuideText());
+      return;
+    case "version":
+      process.stdout.write("linzumi 0.0.2-beta\n");
+      return;
+    case "auth":
+      await runAuthCommand(parsed.args);
+      return;
+    case "run": {
+      const options = await parseRunnerArgs(parsed.args);
+      await runLocalCodexRunner(options);
+      return;
+    }
+  }
+}
+
+type ParsedCommand =
+  | { readonly command: "guide"; readonly args: readonly string[] }
+  | { readonly command: "version"; readonly args: readonly string[] }
+  | { readonly command: "auth"; readonly args: readonly string[] }
+  | { readonly command: "run"; readonly args: readonly string[] };
+
+function parseCommand(args: readonly string[]): ParsedCommand {
+  const [first, ...rest] = args;
+
+  switch (first) {
+    case undefined:
+    case "connect":
+    case "local-codex-runner":
+      return rest.length === 0
+        ? { command: "guide", args: [] }
+        : { command: "run", args: rest };
+    case "--version":
+      return { command: "version", args: [] };
+    case "--help":
+    case "-h":
+      return { command: "run", args: ["--help"] };
+    case "auth":
+      return { command: "auth", args: rest };
+    case "run":
+      return { command: "run", args: rest };
+    default:
+      return { command: "run", args };
+  }
+}
+
+async function runAuthCommand(args: readonly string[]): Promise<void> {
+  const values = strictFlagValues(args);
+
+  if (values.get("help") === true) {
+    process.stdout.write(helpText());
+    return;
+  }
+
+  const kandanUrl = required(values, "kandan-url");
+  const target = parseOptionalChannelTarget(values);
+  const token = await acquireLocalRunnerTokenDetails({
+    kandanUrl,
+    workspaceSlug: target?.workspaceSlug,
+    channelSlug: target?.channelSlug,
+    callbackHost: stringValue(values, "oauth-callback-host"),
+  });
+  const cached = writeCachedLocalRunnerToken({
+    kandanUrl,
+    accessToken: token.accessToken,
+    expiresInSeconds: token.expiresInSeconds,
+    authFilePath: stringValue(values, "auth-file"),
+  });
+
+  process.stdout.write(`Saved Kandan local runner auth for ${cached.kandanBaseUrl}\n`);
+}
+
+async function parseRunnerArgs(args: readonly string[]): Promise<RunnerOptions> {
+  const values = strictFlagValues(args);
+
+  if (values.get("help") === true) {
+    process.stdout.write(helpText());
+    process.exit(0);
+  }
+
+  if (values.get("version") === true) {
+    process.stdout.write("linzumi 0.0.2-beta\n");
+    process.exit(0);
+  }
+
+  const channelSession = parseChannelSession(values);
+  const kandanUrl = required(values, "kandan-url");
+  const explicitToken = stringValue(values, "token");
+  const token = await resolveLocalRunnerToken({
+      kandanUrl,
+      explicitToken,
+      workspaceSlug: channelSession?.workspaceSlug,
+      channelSlug: channelSession?.channelSlug,
+      authFilePath: stringValue(values, "auth-file"),
+      callbackHost: stringValue(values, "oauth-callback-host"),
+      reportRejectedCachedToken: () => {
+        process.stderr.write("Cached Kandan local runner auth was rejected; starting OAuth.\n");
+      },
+    });
+
+  return {
+    kandanUrl,
+    token,
+    runnerId: stringValue(values, "runner-id") ?? `runner-${randomUUID()}`,
+    cwd: stringValue(values, "cwd") ?? process.cwd(),
+    codexBin: stringValue(values, "codex-bin") ?? "codex",
+    codexUrl: stringValue(values, "codex-url"),
+    launchTui: values.get("launch-tui") === true,
+    fast: values.get("fast") === true,
+    logFile: stringValue(values, "log-file"),
+    channelSession
+  };
+}
+
+function strictFlagValues(args: readonly string[]): Map<string, string | true> {
+  const values = new Map<string, string | true>();
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+
+    if (arg === undefined || !arg.startsWith("--")) {
+      throw new Error(`invalid argument: ${arg ?? ""}`);
+    }
+
+    const key = arg.slice(2);
+    const definition = flagDefinitions.get(key);
+
+    if (definition === undefined) {
+      throw new Error(`invalid flag: --${key}`);
+    }
+
+    if (definition.kind === "boolean") {
+      values.set(key, true);
+      continue;
+    }
+
+    const next = args[index + 1];
+
+    if (next === undefined || next.startsWith("--")) {
+      throw new Error(`missing value for --${key}`);
+    }
+
+    values.set(key, next);
+    index += 1;
+  }
+
+  return values;
+}
+
+function parseChannelSession(
+  values: Map<string, string | true>
+): RunnerOptions["channelSession"] {
+  const target = parseOptionalChannelTarget(values);
+
+  if (target === undefined) {
+    return undefined;
+  }
+
+  const listenUser = required(values, "listen-user");
+
+  return {
+    workspaceSlug: target.workspaceSlug,
+    channelSlug: target.channelSlug,
+    kandanThreadId: stringValue(values, "kandan-thread-id"),
+    listenUser,
+    model: stringValue(values, "model"),
+    reasoningEffort: stringValue(values, "reasoning-effort"),
+    sandbox: stringValue(values, "sandbox"),
+    approvalPolicy: stringValue(values, "approval-policy"),
+  };
+}
+
+function parseOptionalChannelTarget(
+  values: Map<string, string | true>
+): { readonly workspaceSlug: string; readonly channelSlug: string } | undefined {
+  const channel = stringValue(values, "channel");
+  const workspace = stringValue(values, "workspace");
+
+  if (channel === undefined && workspace === undefined) {
+    return undefined;
+  }
+
+  return channel !== undefined && channel.includes("/")
+    ? parseChannelPath(channel)
+    : {
+        workspaceSlug: workspace ?? required(values, "workspace"),
+        channelSlug: channel ?? required(values, "channel")
+      };
+}
+
+function parseChannelPath(channel: string): {
+  readonly workspaceSlug: string;
+  readonly channelSlug: string;
+} {
+  const [workspaceSlug, channelSlug, ...rest] = channel.split("/");
+
+  if (
+    workspaceSlug === undefined ||
+    workspaceSlug.trim() === "" ||
+    channelSlug === undefined ||
+    channelSlug.trim() === "" ||
+    rest.length > 0
+  ) {
+    throw new Error("--channel must be CHANNEL or WORKSPACE/CHANNEL");
+  }
+
+  return {
+    workspaceSlug: workspaceSlug.trim(),
+    channelSlug: channelSlug.trim()
+  };
+}
+
+function required(values: Map<string, string | true>, key: string): string {
+  const value = stringValue(values, key);
+
+  if (value === undefined) {
+    throw new Error(`missing --${key}`);
+  }
+
+  return value;
+}
+
+function stringValue(values: Map<string, string | true>, key: string): string | undefined {
+  const value = values.get(key);
+
+  if (typeof value === "string" && value.trim() !== "") {
+    return value;
+  }
+
+  return undefined;
+}
+
+function helpText(): string {
+  return `Kandan local Codex runner
+
+Usage:
+  linzumi
+  linzumi connect --kandan-url <ws-url> --workspace <slug> --channel <slug> --listen-user <username|all> [options]
+  linzumi auth --kandan-url <ws-url> [--workspace <slug> --channel <slug>]
+
+Required:
+  --kandan-url <ws-url>       Kandan websocket base URL, for example ws://127.0.0.1:4160
+  --token <jwt>               Optional override token. Otherwise ~/.kandan/auth.json is validated or OAuth opens.
+  --auth-file <path>          Auth cache path, default ~/.kandan/auth.json
+  --oauth-callback-host <ip>  Callback host reachable by your browser, for example a Tailscale IP
+
+Channel binding:
+  --workspace <slug>          Workspace slug
+  --channel <slug|w/c>        Channel slug, or workspace/channel
+  --kandan-thread-id <uuid>   Resume an existing Kandan thread instead of announcing a new root
+  --listen-user <user|all>    User whose replies are accepted, or all
+
+Codex:
+  --cwd <path>                Working directory for Codex, default current directory
+  --codex-bin <path>          Codex executable, default codex
+  --codex-url <ws-url>        Existing Codex app-server websocket URL
+  --launch-tui                Launch codex --remote against the app-server
+  --model <name>              Model requested for the Codex thread and shown in Kandan
+  --reasoning-effort <value>  Reasoning effort requested for Codex and shown in Kandan
+  --sandbox <value>           Sandbox metadata shown in Kandan
+  --approval-policy <value>   Approval-policy metadata shown in Kandan
+  --fast                      Mark this runner as low-latency/fast in the availability message
+  --log-file <path>           JSONL event log path, default <cwd>/.kandan-local-codex-runner.log
+
+Examples:
+  Good:
+    linzumi auth --kandan-url ws://127.0.0.1:4160 --workspace default --channel seans-playground
+    linzumi auth --kandan-url ws://100.71.192.98:4160 --oauth-callback-host 100.71.192.98 --workspace default --channel seans-playground
+    linzumi connect --kandan-url ws://127.0.0.1:4160 --token "$TOKEN" --workspace default --channel seans-playground --listen-user sean --cwd /tmp/kandan-runner-a
+    linzumi connect --kandan-url ws://127.0.0.1:4160 --workspace default --channel seans-playground --listen-user sean
+    linzumi connect --kandan-url ws://127.0.0.1:4160 --token "$TOKEN" --channel default/seans-playground --listen-user all --launch-tui
+
+  Bad:
+    linzumi connect --kandan-url ws://127.0.0.1:4160 --workspace default --channel seans-playground
+      Missing --listen-user.
+    linzumi connect --kandan-url ws://127.0.0.1:4160 --token "$TOKEN" --listen-users sean
+      Invalid flag: use --listen-user.
+`;
+}
+
+function connectGuideText(): string {
+  return `linzumi connect
+
+Connect this computer to Kandan as a local Codex runner.
+
+Use:
+  linzumi connect --kandan-url <ws-url> --workspace <slug> --channel <slug> --listen-user <username|all> [options]
+
+For help:
+  linzumi connect --help
+`;
+}

package/src/json.ts

@@ -0,0 +1,49 @@
+/*
+- Date: 2026-04-24
+  Spec: plans/2026-04-24-local-codex-channel-thread-binding-spec.md
+  Relationship: Provides small JSON readers used by the local runner's
+  channel binding and Codex transcript normalization without ad hoc casts.
+*/
+import { type JsonObject, type JsonValue, isJsonObject } from "./protocol";
+
+export function objectValue(value: JsonValue | undefined): JsonObject | undefined {
+  return value !== undefined && isJsonObject(value) ? value : undefined;
+}
+
+export function arrayValue(
+  value: JsonValue | undefined,
+): readonly JsonValue[] | undefined {
+  return Array.isArray(value) ? value : undefined;
+}
+
+export function stringValue(value: JsonValue | undefined): string | undefined {
+  return typeof value === "string" && value.trim() !== ""
+    ? value.trim()
+    : undefined;
+}
+
+export function integerValue(value: JsonValue | undefined): number | undefined {
+  return typeof value === "number" && Number.isInteger(value)
+    ? value
+    : undefined;
+}
+
+export function stringListValue(value: JsonValue | undefined): string[] {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+
+  return value.flatMap((entry) => {
+    const normalized = stringValue(entry);
+    return normalized === undefined ? [] : [normalized];
+  });
+}
+
+export function parseJsonObjectOrUndefined(text: string): JsonObject | undefined {
+  try {
+    const parsed: unknown = JSON.parse(text);
+    return isJsonObject(parsed) ? parsed : undefined;
+  } catch (_error) {
+    return undefined;
+  }
+}

package/src/kandanQueue.ts

@@ -0,0 +1,102 @@
+/*
+- Date: 2026-04-24
+  Spec: plans/2026-04-24-local-codex-channel-thread-binding-spec.md
+  Relationship: Owns deterministic queue formatting and interrupt fusion for
+  Kandan thread replies before they are sent into local Codex.
+
+- Date: 2026-04-24
+  Spec: plans/2026-04-24-local-codex-runner-deep-quality-spec.md
+  Relationship: Carries selected queued message seqs through interrupt fusion
+  so the UI can show which pending replies were accepted by the interrupt.
+*/
+export type QueuedKandanMessage = {
+  readonly seq: number;
+  readonly actorSlug: string | undefined;
+  readonly actorUserId: number | undefined;
+  readonly body: string;
+};
+
+export type QueueInterruptResult =
+  | {
+      readonly ok: true;
+      readonly queue: QueuedKandanMessage[];
+      readonly selectedCount: number;
+      readonly selectedSeqs: number[];
+      readonly remainingCount: number;
+    }
+  | {
+      readonly ok: false;
+      readonly reason: "queue_empty";
+    };
+
+export function formatQueuedKandanMessage(message: QueuedKandanMessage): string {
+  const sender =
+    message.actorSlug === undefined || message.actorSlug.trim() === ""
+      ? "unknown"
+      : message.actorSlug.trim();
+  const userId =
+    message.actorUserId === undefined
+      ? "unknown"
+      : message.actorUserId.toString();
+
+  return [
+    `Kandan message seq=${message.seq} from ${sender} (user_id=${userId}):`,
+    "",
+    message.body,
+  ].join("\n");
+}
+
+export function codexInputForQueuedKandanMessage(message: QueuedKandanMessage): string {
+  const command = message.body.trimStart();
+
+  return command.startsWith("!") ? command : formatQueuedKandanMessage(message);
+}
+
+export function interruptQueuedMessages(
+  queue: readonly QueuedKandanMessage[],
+  throughSeq: number | undefined,
+): QueueInterruptResult {
+  const selected =
+    throughSeq === undefined
+      ? Array.from(queue)
+      : queue.filter((message) => message.seq <= throughSeq);
+  const remaining =
+    throughSeq === undefined
+      ? []
+      : queue.filter((message) => message.seq > throughSeq);
+
+  if (selected.length === 0) {
+    return { ok: false, reason: "queue_empty" };
+  }
+
+  const fused = fuseQueuedMessages(selected);
+
+  if (fused === undefined) {
+    return { ok: false, reason: "queue_empty" };
+  }
+
+  return {
+    ok: true,
+    queue: [fused, ...remaining],
+    selectedCount: selected.length,
+    selectedSeqs: selected.map(message => message.seq),
+    remainingCount: remaining.length,
+  };
+}
+
+function fuseQueuedMessages(
+  selected: readonly QueuedKandanMessage[],
+): QueuedKandanMessage | undefined {
+  const last = selected[selected.length - 1];
+
+  if (last === undefined) {
+    return undefined;
+  }
+
+  return {
+    seq: last.seq,
+    actorSlug: "kandan",
+    actorUserId: undefined,
+    body: selected.map(codexInputForQueuedKandanMessage).join("\n\n---\n\n"),
+  };
+}