@cordfuse/llmux 0.11.0 → 0.12.1

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@cordfuse/llmux",
-  "version": "0.11.0",
-  "description": "Thin HTTP client for llmuxd — send prompts to running AI agent CLI sessions over REST",
+  "version": "0.12.1",
+  "description": "tmux-based AI agent dispatcher — REST/WS daemon + CLI client in one binary",
   "license": "MIT",
   "type": "module",
   "bin": {
@@ -20,16 +20,29 @@
   },
   "scripts": {
     "start": "tsx src/index.ts",
-    "build": "tsup src/index.ts --target node20 --format esm --out-dir dist --clean",
+    "build": "tsup src/index.ts --target node20 --format esm --out-dir dist --external node-pty --external ws --external yaml --external qrcode-terminal --clean",
     "prepublishOnly": "cp ../../README.md ../../LICENSE . && npm run build",
     "postpublish": "rm -f README.md LICENSE",
     "typecheck": "tsc --noEmit"
   },
+  "dependencies": {
+    "@types/ws": "^8.18.1",
+    "node-pty": "^1.1.0",
+    "qrcode-terminal": "^0.12.0",
+    "ws": "^8.21.0",
+    "yaml": "^2.5.0"
+  },
+  "devDependencies": {
+    "@types/qrcode-terminal": "^0.12.2"
+  },
   "keywords": [
     "tmux",
     "ai",
     "agent",
-    "llmux",
+    "claude",
+    "codex",
+    "session-manager",
+    "llm",
     "cordfuse"
   ],
   "repository": {

package/src/cli.ts

@@ -0,0 +1,100 @@
+export type FlagKind = 'boolean' | 'string';
+
+export interface FlagSpec {
+  kind: FlagKind;
+  alias?: string;
+  description: string;
+}
+
+export type FlagSpecs = Record<string, FlagSpec>;
+
+export interface ParsedArgs {
+  positional: string[];
+  flags: Record<string, string | boolean>;
+}
+
+export function parseArgs(argv: readonly string[], specs: FlagSpecs): ParsedArgs {
+  const aliasMap = new Map<string, string>();
+  for (const [name, spec] of Object.entries(specs)) {
+    if (spec.alias) aliasMap.set(spec.alias, name);
+  }
+
+  const resolveName = (raw: string): string => aliasMap.get(raw) ?? raw;
+
+  const positional: string[] = [];
+  const flags: Record<string, string | boolean> = {};
+
+  for (let i = 0; i < argv.length; i++) {
+    const token = argv[i]!;
+
+    if (token === '--') {
+      positional.push(...argv.slice(i + 1));
+      break;
+    }
+
+    if (token.startsWith('--')) {
+      const body = token.slice(2);
+      const eq = body.indexOf('=');
+      const rawName = eq >= 0 ? body.slice(0, eq) : body;
+      const name = resolveName(rawName);
+      const spec = specs[name];
+      if (!spec) {
+        throw new Error(`unknown flag --${rawName}`);
+      }
+      if (spec.kind === 'boolean') {
+        flags[name] = eq >= 0 ? body.slice(eq + 1) !== 'false' : true;
+      } else {
+        if (eq >= 0) {
+          flags[name] = body.slice(eq + 1);
+        } else {
+          const next = argv[i + 1];
+          if (next === undefined || next.startsWith('-')) {
+            throw new Error(`--${rawName} requires a value`);
+          }
+          flags[name] = next;
+          i++;
+        }
+      }
+      continue;
+    }
+
+    if (token.startsWith('-') && token.length > 1) {
+      const body = token.slice(1);
+      const name = resolveName(body);
+      const spec = specs[name];
+      if (!spec) {
+        throw new Error(`unknown flag -${body}`);
+      }
+      if (spec.kind === 'boolean') {
+        flags[name] = true;
+      } else {
+        const next = argv[i + 1];
+        if (next === undefined || next.startsWith('-')) {
+          throw new Error(`-${body} requires a value`);
+        }
+        flags[name] = next;
+        i++;
+      }
+      continue;
+    }
+
+    positional.push(token);
+  }
+
+  return { positional, flags };
+}
+
+export function renderFlagHelp(specs: FlagSpecs): string {
+  const lines: string[] = [];
+  for (const [name, spec] of Object.entries(specs)) {
+    const lead = spec.alias ? `-${spec.alias}, --${name}` : `    --${name}`;
+    const value = spec.kind === 'string' ? ' <value>' : '';
+    lines.push(`  ${(lead + value).padEnd(28)}${spec.description}`);
+  }
+  return lines.join('\n');
+}
+
+export function notImplemented(commandPath: string): never {
+  console.error(`llmux ${commandPath}: not yet implemented (scaffold)`);
+  process.exit(70);
+}

package/src/{client.ts → client/client.ts}

@@ -18,7 +18,7 @@ function help(name: string, summary: string, usage: string): () => string {
       `  ${usage}`,
       '',
       'Environment:',
-      '  LLMUX_SERVER  base URL of the llmuxd daemon (e.g. http://localhost:3030)',
+      '  LLMUX_SERVER  base URL of the llmux daemon (e.g. http://localhost:3030)',
       '  LLMUX_TOKEN   auth token (sas_…); not required for localhost',
       '',
     ].join('\n');
@@ -32,7 +32,7 @@ interface ClientContext {
 export function resolveContext(): ClientContext {
   const baseUrl = process.env.LLMUX_SERVER;
   if (!baseUrl) {
-    throw new Error('LLMUX_SERVER is not set. Point it at your llmuxd (e.g. http://localhost:3030).');
+    throw new Error('LLMUX_SERVER is not set. Point it at your llmux daemon (e.g. http://localhost:3030).');
   }
   return { baseUrl: baseUrl.replace(/\/$/, ''), token: process.env.LLMUX_TOKEN };
 }
@@ -62,7 +62,7 @@ async function request<T = unknown>(
   }
   if (r.status === 401) {
     throw new Error(
-      'unauthorized — set LLMUX_TOKEN (use `llmuxd token create` on the daemon host to mint one)',
+      'unauthorized — set LLMUX_TOKEN (use `llmux token create` on the daemon host to mint one)',
     );
   }
   if (r.status === 404) {

package/src/daemon/agents.ts

@@ -0,0 +1,193 @@
+import { accessSync, constants, existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, delimiter } from 'node:path';
+
+export interface Conversation {
+  id: string;
+  title: string;
+  startedAt: string;
+  lastMessageAt: string;
+  messageCount: number;
+}
+
+export interface AgentHistoryAdapter {
+  /** Past conversations for this agent in this cwd, newest-first. */
+  listConversations(cwd: string): Conversation[];
+  /** Build the launch flag fragment to resume a specific conversation. */
+  resumeFlag(conversationId: string): string;
+}
+
+export interface AgentDefinition {
+  /** Key under `agents:` in .llmux.yaml; default tmux-session name. */
+  key: string;
+  /** Human-readable name shown in UI surfaces (picker dropdown, etc.). */
+  displayName: string;
+  /** Executable to launch in the tmux pane. */
+  cmd: string;
+  /** Default args appended after `cmd`. */
+  flags?: string;
+  /** Regex matched against the bottom of the pane to detect "ready for input". */
+  readyPrompt: string;
+  /** Custom install detection (overrides the default PATH lookup). */
+  detectInstalled?: () => boolean;
+  /** One-line install command (shell). Shown in the agent-help modal. */
+  installHint?: string;
+  /** Homepage / docs URL. Shown alongside installHint as a fallback. */
+  docsUrl?: string;
+  /** Environment variables baked in at spawn time. Per-session env overrides win. */
+  envDefaults?: Record<string, string>;
+  /** Conversation-history adapter — enables the "resume past conversation" picker. */
+  history?: AgentHistoryAdapter;
+}
+
+/**
+ * Claude Code stores each conversation as a `~/.claude/projects/<encoded-cwd>/<uuid>.jsonl`
+ * file. The encoding is a literal `/`-to-`-` substitution. Each line is a JSON
+ * event; the first user message defines the conversation's title, and the
+ * event timestamps frame `startedAt` / `lastMessageAt`. Synthetic events
+ * (permission-mode, local-command-stdout, /resume command stubs) are skipped
+ * when picking the title so the picker shows the actual conversation opener.
+ */
+function encodeClaudeCwd(cwd: string): string {
+  return cwd.replace(/\//g, '-');
+}
+
+function extractClaudeUserText(msg: unknown): string | undefined {
+  if (typeof msg !== 'object' || msg === null) return undefined;
+  const content = (msg as { content?: unknown }).content;
+  if (typeof content === 'string') return content;
+  if (Array.isArray(content)) {
+    for (const block of content) {
+      if (typeof block === 'object' && block !== null) {
+        const b = block as { type?: string; text?: string };
+        if (b.type === 'text' && typeof b.text === 'string') return b.text;
+      }
+    }
+  }
+  return undefined;
+}
+
+function looksLikeRealUserMessage(text: string): boolean {
+  if (!text) return false;
+  if (text.startsWith('<local-command')) return false;
+  if (text.startsWith('<command-name>')) return false;
+  if (text.startsWith('<command-message>')) return false;
+  return true;
+}
+
+const claudeHistory: AgentHistoryAdapter = {
+  listConversations(cwd: string): Conversation[] {
+    const dir = join(homedir(), '.claude', 'projects', encodeClaudeCwd(cwd));
+    if (!existsSync(dir)) return [];
+    let entries: string[];
+    try {
+      entries = readdirSync(dir).filter((f) => f.endsWith('.jsonl'));
+    } catch {
+      return [];
+    }
+    const out: Conversation[] = [];
+    for (const fname of entries) {
+      const id = fname.slice(0, -'.jsonl'.length);
+      const fpath = join(dir, fname);
+      try {
+        const raw = readFileSync(fpath, 'utf8');
+        const lines = raw.split('\n').filter((l) => l.length > 0);
+        let title: string | undefined;
+        let firstTs: string | undefined;
+        let lastTs: string | undefined;
+        for (const line of lines) {
+          let evt: { type?: string; timestamp?: string; message?: unknown };
+          try {
+            evt = JSON.parse(line);
+          } catch {
+            continue;
+          }
+          if (evt.timestamp) {
+            if (!firstTs) firstTs = evt.timestamp;
+            lastTs = evt.timestamp;
+          }
+          if (!title && evt.type === 'user') {
+            const text = extractClaudeUserText(evt.message);
+            if (text && looksLikeRealUserMessage(text)) {
+              title = text.split('\n')[0]!.slice(0, 100).trim();
+            }
+          }
+        }
+        const stat = statSync(fpath);
+        out.push({
+          id,
+          title: title ?? '(no opener)',
+          startedAt: firstTs ?? new Date(stat.ctimeMs).toISOString(),
+          lastMessageAt: lastTs ?? new Date(stat.mtimeMs).toISOString(),
+          messageCount: lines.length,
+        });
+      } catch {
+        // skip unreadable / malformed files
+      }
+    }
+    return out.sort((a, b) => b.lastMessageAt.localeCompare(a.lastMessageAt));
+  },
+  resumeFlag(id: string): string {
+    return `--resume ${id}`;
+  },
+};
+
+const which = (cmd: string): boolean => {
+  const pathDirs = (process.env.PATH ?? '').split(delimiter);
+  for (const dir of pathDirs) {
+    if (!dir) continue;
+    try {
+      accessSync(join(dir, cmd), constants.X_OK);
+      return true;
+    } catch {
+      // not in this dir
+    }
+  }
+  return false;
+};
+
+const copilotInstalled = (): boolean => {
+  // `gh copilot` is a built-in subcommand of gh 2.92+ (not an extension), and
+  // the actual Copilot CLI binary is downloaded on first invocation to
+  // ~/.local/share/gh/copilot. Treat the binary's presence as the install
+  // signal — `gh extension list` no longer surfaces copilot.
+  return existsSync(join(homedir(), '.local/share/gh/copilot'));
+};
+
+export const DEFAULT_AGENTS: Record<string, AgentDefinition> = {
+  claude:   { key: 'claude',   displayName: 'Claude Code',         cmd: 'claude',       flags: '--dangerously-skip-permissions',             readyPrompt: '^>',     installHint: 'curl -fsSL https://claude.ai/install.sh | bash', docsUrl: 'https://docs.claude.com/en/docs/claude-code/overview', history: claudeHistory },
+  codex:    { key: 'codex',    displayName: 'Codex CLI',           cmd: 'codex',        flags: '--dangerously-bypass-approvals-and-sandbox', readyPrompt: '^>',     installHint: 'npm install -g @openai/codex',                    docsUrl: 'https://github.com/openai/codex' },
+  agy:      { key: 'agy',      displayName: 'Antigravity CLI',     cmd: 'agy',          flags: '--dangerously-skip-permissions',             readyPrompt: '^agy>',  installHint: 'curl -fsSL https://antigravity.google/cli/install.sh | bash', docsUrl: 'https://antigravity.google/docs/cli-install' },
+  gemini:   { key: 'gemini',   displayName: 'Gemini CLI',          cmd: 'gemini',       flags: '--yolo',                                     readyPrompt: '^>',     installHint: 'npm install -g @google/gemini-cli',               docsUrl: 'https://github.com/google-gemini/gemini-cli' },
+  qwen:     { key: 'qwen',     displayName: 'Qwen Code',           cmd: 'qwen',         flags: '--yolo',                                     readyPrompt: '^>',     installHint: 'npm install -g @qwen-code/qwen-code',             docsUrl: 'https://github.com/QwenLM/qwen-code' },
+  // OpenCode's --dangerously-skip-permissions only applies to `opencode run`
+  // (one-shot). The TUI default mode rejects it and exits — danger mode in
+  // the TUI is controlled via OPENCODE_YOLO=1 instead.
+  // No model flag set — OpenCode honors the operator's own config at
+  // ~/.config/opencode/opencode.json (provider + default model). Operator
+  // overrides per-spawn via the flags field if they want a specific model
+  // (e.g. `-m openrouter/anthropic/claude-sonnet-4.6` or
+  // `-m ollama/qwen2.5-coder:14b`).
+  opencode: { key: 'opencode', displayName: 'OpenCode',            cmd: 'opencode',                                                          readyPrompt: '^>',     installHint: 'curl -fsSL https://opencode.ai/install | bash',   docsUrl: 'https://opencode.ai',          envDefaults: { OPENCODE_YOLO: '1' } },
+  amp:      { key: 'amp',      displayName: 'Sourcegraph Amp',     cmd: 'amp',          flags: '--dangerously-allow-all',                    readyPrompt: '^>',     installHint: 'npm install -g @sourcegraph/amp',                 docsUrl: 'https://ampcode.com/manual' },
+  grok:     { key: 'grok',     displayName: 'Grok Build CLI',      cmd: 'grok',         flags: '--always-approve',                           readyPrompt: '^grok>', installHint: 'curl -fsSL https://x.ai/cli/install.sh | bash',   docsUrl: 'https://x.ai/cli' },
+  aider:    { key: 'aider',    displayName: 'Aider',               cmd: 'aider',        flags: '--yes-always --model claude-opus-4-6',       readyPrompt: '^> $',   installHint: 'python -m pip install aider-chat',                docsUrl: 'https://aider.chat' },
+  continue: { key: 'continue', displayName: 'Continue CLI',        cmd: 'cn',           flags: '--auto',                                     readyPrompt: '^>',     installHint: 'npm install -g @continuedev/cli',                 docsUrl: 'https://docs.continue.dev/guides/cli' },
+  kiro:     { key: 'kiro',     displayName: 'Kiro CLI',            cmd: 'kiro-cli',     flags: '--trust-all-tools',                          readyPrompt: '^>',     installHint: 'brew install kiro  # or see docs for Linux/Windows', docsUrl: 'https://kiro.dev/docs/cli/installation/' },
+  cursor:   { key: 'cursor',   displayName: 'Cursor CLI',          cmd: 'cursor-agent',                                                      readyPrompt: '^>',     installHint: 'curl https://cursor.com/install -fsSL | bash',    docsUrl: 'https://cursor.com/docs/cli/installation' },
+  plandex:  { key: 'plandex',  displayName: 'Plandex',             cmd: 'plandex',                                                           readyPrompt: '^>',     installHint: 'curl -fsSL https://plandex.ai/install.sh | bash', docsUrl: 'https://docs.plandex.ai' },
+  // goose has no launch flag — auto-approve is controlled via GOOSE_MODE=auto.
+  goose:    { key: 'goose',    displayName: 'Goose',               cmd: 'goose',                                                             readyPrompt: 'Goose❯', installHint: 'curl -fsSL https://github.com/block/goose/releases/download/stable/download_cli.sh | bash', docsUrl: 'https://block.github.io/goose', envDefaults: { GOOSE_MODE: 'auto' } },
+  copilot:  { key: 'copilot',  displayName: 'GitHub Copilot CLI',  cmd: 'gh copilot',                                                        readyPrompt: '●',      detectInstalled: copilotInstalled, installHint: 'gh copilot suggest "hi"  # gh prerequisite; first run downloads', docsUrl: 'https://docs.github.com/en/copilot/how-tos/use-copilot-in-the-cli' },
+};
+
+export function isAgentInstalled(agent: AgentDefinition): boolean {
+  if (agent.detectInstalled) return agent.detectInstalled();
+  // For multi-word commands, check only the first token.
+  const head = agent.cmd.split(/\s+/)[0]!;
+  return which(head);
+}
+
+export function installedAgents(defs: Record<string, AgentDefinition> = DEFAULT_AGENTS): AgentDefinition[] {
+  return Object.values(defs).filter(isAgentInstalled);
+}

package/src/daemon/auth-store.ts

@@ -0,0 +1,85 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { stateDir } from './state.ts';
+import { generateToken, tokenId } from './token.ts';
+
+export interface AuthToken {
+  id: string;
+  token: string;
+  name?: string;
+  createdAt: string;
+  expiresAt?: string;
+}
+
+interface AuthFile {
+  version: 1;
+  tokens: AuthToken[];
+}
+
+const EMPTY: AuthFile = { version: 1, tokens: [] };
+
+export function authPath(): string {
+  return join(stateDir(), 'auth.json');
+}
+
+function load(): AuthFile {
+  const p = authPath();
+  if (!existsSync(p)) return structuredClone(EMPTY);
+  try {
+    const parsed = JSON.parse(readFileSync(p, 'utf8')) as Partial<AuthFile>;
+    if (parsed.version === 1 && Array.isArray(parsed.tokens)) {
+      return { version: 1, tokens: parsed.tokens };
+    }
+  } catch {}
+  return structuredClone(EMPTY);
+}
+
+function save(file: AuthFile): void {
+  const p = authPath();
+  mkdirSync(dirname(p), { recursive: true });
+  writeFileSync(p, JSON.stringify(file, null, 2) + '\n', { mode: 0o600 });
+}
+
+export function listAuthTokens(): AuthToken[] {
+  return load().tokens;
+}
+
+export function createAuthToken(opts: { name?: string; expiresAt?: string } = {}): AuthToken {
+  const token = generateToken();
+  const rec: AuthToken = {
+    id: tokenId(token),
+    token,
+    createdAt: new Date().toISOString(),
+    ...(opts.name !== undefined ? { name: opts.name } : {}),
+    ...(opts.expiresAt !== undefined ? { expiresAt: opts.expiresAt } : {}),
+  };
+  const file = load();
+  file.tokens.push(rec);
+  save(file);
+  return rec;
+}
+
+/** Revoke by id prefix (the 8-char display id). Returns true if anything was removed. */
+export function revokeAuthToken(idPrefix: string): boolean {
+  const file = load();
+  const before = file.tokens.length;
+  file.tokens = file.tokens.filter((t) => t.id !== idPrefix);
+  if (file.tokens.length === before) return false;
+  save(file);
+  return true;
+}
+
+export function validateAuthToken(candidate: string | undefined): boolean {
+  if (!candidate) return false;
+  const now = Date.now();
+  return load().tokens.some((t) => {
+    if (t.token !== candidate) return false;
+    if (t.expiresAt && new Date(t.expiresAt).getTime() < now) return false;
+    return true;
+  });
+}
+
+/** Auth is enabled when at least one token has been provisioned. */
+export function authEnabled(): boolean {
+  return load().tokens.length > 0;
+}

package/src/daemon/config.ts

@@ -0,0 +1,77 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { parse as parseYaml } from 'yaml';
+
+export interface ServerConfig {
+  port: number;
+  token?: string;
+  tokenExpiry?: string;
+  noQr: boolean;
+}
+
+export interface SessionConfig {
+  name: string;
+  agent: string;
+  cwd?: string;
+  autoSpawn: boolean;
+  restart: 'always' | 'on-failure' | 'never';
+}
+
+export interface AgentOverrides {
+  cmd?: string;
+  flags?: string;
+  readyPrompt?: string;
+}
+
+export interface LlmuxConfig {
+  server: ServerConfig;
+  agents: Record<string, AgentOverrides>;
+  sessions: SessionConfig[];
+  sourcePath?: string;
+}
+
+export const DEFAULT_CONFIG: LlmuxConfig = {
+  server: { port: 3000, noQr: false },
+  agents: {},
+  sessions: [],
+};
+
+export interface DiscoverOptions {
+  /** Path passed via `--config` (highest priority). */
+  explicit?: string;
+  /** Override cwd (defaults to process.cwd()). */
+  cwd?: string;
+  /** Override $HOME (defaults to os.homedir()). */
+  home?: string;
+  /** $LLMUX_CONFIG value (defaults to process.env.LLMUX_CONFIG). */
+  envVar?: string;
+}
+
+/** Resolve config path per discovery rules; null = no config, use defaults. */
+export function discoverConfigPath(opts: DiscoverOptions = {}): string | null {
+  if (opts.explicit) return opts.explicit;
+  const cwd = opts.cwd ?? process.cwd();
+  const projectLocal = join(cwd, '.llmux.yaml');
+  if (existsSync(projectLocal)) return projectLocal;
+  const home = opts.home ?? homedir();
+  const globalDefault = join(home, '.config', 'llmux', 'config.yaml');
+  if (existsSync(globalDefault)) return globalDefault;
+  const env = opts.envVar ?? process.env.LLMUX_CONFIG;
+  if (env && existsSync(env)) return env;
+  return null;
+}
+
+export function loadConfig(opts: DiscoverOptions = {}): LlmuxConfig {
+  const path = discoverConfigPath(opts);
+  if (!path) return DEFAULT_CONFIG;
+  const raw = readFileSync(path, 'utf8');
+  const parsed = parseYaml(raw) as Partial<LlmuxConfig> | null;
+  const merged: LlmuxConfig = {
+    server: { ...DEFAULT_CONFIG.server, ...(parsed?.server ?? {}) },
+    agents: { ...DEFAULT_CONFIG.agents, ...(parsed?.agents ?? {}) },
+    sessions: parsed?.sessions ?? [],
+    sourcePath: path,
+  };
+  return merged;
+}