subconscious-cli 6.0.0 → 6.1.0

package/bin/agent-install.js

@@ -0,0 +1,354 @@
+import { execFileSync, spawn } from 'node:child_process';
+import { constants as fsConstants } from 'node:fs';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import readline from 'node:readline';
+import {
+  agentBinary,
+  agentById,
+  agentCommandName,
+  agentInstallDirs,
+  installCommands,
+} from './agent-data.js';
+import { runbookScriptPath } from './agent-spawn.js';
+import { c } from './colors.js';
+import { compareVersions } from './update-check.js';
+
+/**
+ * The install command for this OS, falling back to the Linux one, then any
+ * command present; plus the optional fallback command.
+ */
+export function resolveInstall(agent) {
+  const commands = installCommands(agent);
+  if (!commands) return { command: undefined, fallback: undefined };
+  const command =
+    commands[process.platform] ||
+    commands.linux ||
+    Object.entries(commands).find(([os]) => os !== 'fallback')?.[1];
+  return { command, fallback: commands.fallback };
+}
+
+/**
+ * Common locations a freshly-installed coding-agent binary lands in but which
+ * are often NOT on the current process's PATH (e.g. aider/claude install into
+ * `~/.local/bin`; npm globals into the npm prefix bin). Best-effort, deduped.
+ */
+export function candidateBinDirs() {
+  const home = os.homedir();
+  const dirs = [];
+
+  if (process.platform === 'win32') {
+    if (process.env.APPDATA) dirs.push(path.join(process.env.APPDATA, 'npm'));
+    if (process.env.USERPROFILE) {
+      dirs.push(path.join(process.env.USERPROFILE, '.local', 'bin'));
+    }
+    if (home) dirs.push(path.join(home, '.local', 'bin'));
+  } else {
+    dirs.push(path.join(home, '.local', 'bin'));
+    dirs.push(path.join(home, '.cargo', 'bin'));
+    dirs.push('/opt/homebrew/bin');
+    dirs.push('/usr/local/bin');
+  }
+
+  // npm global bin (best-effort — npm may be absent).
+  try {
+    const prefix = execFileSync('npm', ['prefix', '-g'], {
+      encoding: 'utf-8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+    if (prefix) {
+      dirs.push(
+        process.platform === 'win32' ? prefix : path.join(prefix, 'bin'),
+      );
+    }
+  } catch {
+    // npm not available — skip.
+  }
+
+  // Dedupe, drop empties.
+  return [...new Set(dirs.filter(Boolean))];
+}
+
+/** The binary directory the agent's own installer uses, if it declares one. */
+export function preferredBinDirsForAgent(
+  agent,
+  environment = process.env,
+  home = os.homedir(),
+) {
+  return agentInstallDirs(agent, environment, home);
+}
+
+/** Executable extensions to probe (Windows uses PATHEXT). */
+function binExts() {
+  return process.platform === 'win32'
+    ? (process.env.PATHEXT || '.EXE;.CMD;.BAT;.COM').split(';')
+    : [''];
+}
+
+/**
+ * Resolve `bin` against PATH plus the candidate bin dirs. Returns the directory
+ * containing the executable if found, otherwise null. Searching the candidate
+ * dirs lets us find binaries installed this session that aren't on PATH yet.
+ */
+async function resolveBinPath(bin, preferredDirs = []) {
+  const pathDirs = (process.env.PATH || '')
+    .split(path.delimiter)
+    .filter(Boolean);
+  const dirs = [
+    ...new Set([...preferredDirs, ...pathDirs, ...candidateBinDirs()]),
+  ];
+  const exts = binExts();
+  for (const dir of dirs) {
+    for (const ext of exts) {
+      const candidate = path.join(dir, bin + ext);
+      try {
+        await fs.access(candidate, fsConstants.F_OK);
+        return dir;
+      } catch {
+        // keep scanning
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * Build a PATH string with `extraDirs` prepended (deduped against PATH).
+ * Returns the augmented PATH value for use in a child env.
+ */
+export function augmentPath(
+  extraDirs,
+  preferredDir,
+  currentPath = process.env.PATH || '',
+) {
+  const current = currentPath.split(path.delimiter).filter(Boolean);
+  const seen = new Set(current);
+  const prepend = extraDirs.filter(
+    (dir, index) =>
+      dir &&
+      dir !== preferredDir &&
+      !seen.has(dir) &&
+      extraDirs.indexOf(dir) === index,
+  );
+  const remaining = current.filter((dir) => dir !== preferredDir);
+  return [
+    ...(preferredDir ? [preferredDir] : []),
+    ...prepend,
+    ...remaining,
+  ].join(path.delimiter);
+}
+
+/** Ask a yes/no question on the TTY. Empty answer counts as yes. */
+function askYesNo(question) {
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout,
+    });
+    rl.question(question, (answer) => {
+      rl.close();
+      const a = answer.trim().toLowerCase();
+      resolve(a === '' || a === 'y' || a === 'yes');
+    });
+  });
+}
+
+function waitForEnter(prompt) {
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout,
+    });
+    rl.question(prompt, () => {
+      rl.close();
+      resolve();
+    });
+  });
+}
+
+/** Run the agent's packaged binary installer, or its shell install command. */
+function runInstaller(
+  agent,
+  install = resolveInstall(agent).command,
+  usePackagedScript = true,
+) {
+  return new Promise((resolve) => {
+    const installScript =
+      usePackagedScript && agent.runbook.binary_install_script;
+    const child = installScript
+      ? spawn('bash', [runbookScriptPath(agent, installScript), 'install'], {
+          stdio: 'inherit',
+        })
+      : spawn(install, { shell: true, stdio: 'inherit' });
+    child.on('error', () => resolve(false));
+    child.on('exit', (code) => resolve(code === 0));
+  });
+}
+
+/** Print the resolved install command (plus any fallback) for an agent. */
+function printInstallCommands(agent) {
+  const { command, fallback } = resolveInstall(agent);
+  console.error(`    ${c.cyan}${command}${c.reset}`);
+  if (fallback) {
+    console.error(`  ${c.dim}or, as a fallback:${c.reset}`);
+    console.error(`    ${c.cyan}${fallback}${c.reset}`);
+  }
+  console.error('');
+}
+
+/**
+ * Ensure the agent's binary is resolvable. If missing:
+ *   - interactive TTY: offer to run the per-OS installer (with fallback), then
+ *     re-resolve against PATH + candidate dirs.
+ *   - non-interactive: print the resolved install command (+ fallback) and
+ *     exit 127 without running anything.
+ *
+ * Returns the directory containing the bin (to prepend to the child's PATH) on
+ * success. May exit the process on failure or when manual action is needed.
+ */
+export async function ensureInstalled(agent, { mayPrompt = true } = {}) {
+  const bin = agentBinary(agent);
+  const { command: install, fallback } = resolveInstall(agent);
+  const preferredDirs = preferredBinDirsForAgent(agent);
+  const existing = await resolveBinPath(bin, preferredDirs);
+  if (existing) return existing;
+
+  // Agents without an installer are launch-only. Their setup integration may
+  // configure the provider, but `subc <agent>` must never install the binary.
+  if (!install) {
+    console.error(
+      `\n  ${c.red}${agent.name} isn't installed${c.reset} ${c.dim}(\`${bin}\` not found on PATH).${c.reset}`,
+    );
+    console.error(
+      `  Install ${agent.name} separately, then re-run ${c.cyan}subc ${agentCommandName(agent)}${c.reset}.\n`,
+    );
+    process.exit(127);
+  }
+
+  const interactive = mayPrompt && process.stdin.isTTY && process.stdout.isTTY;
+
+  if (!interactive) {
+    console.error(
+      `\n  ${c.red}${agent.name} isn't installed${c.reset} ${c.dim}(\`${bin}\` not found on PATH).${c.reset}`,
+    );
+    console.error(`  Install it with:\n`);
+    printInstallCommands(agent);
+    process.exit(127);
+  }
+
+  console.error(`\n  ${c.bold}${agent.name}${c.reset} isn't installed.`);
+  const ok = await askYesNo(`  Install it now? ${c.dim}[Y/n]${c.reset} `);
+  if (!ok) {
+    console.error(`\n  No problem. Install it yourself with:\n`);
+    printInstallCommands(agent);
+    process.exit(127);
+  }
+
+  console.error(
+    `\n  ${c.dim}Running ${c.reset}${c.cyan}${install}${c.reset}\n`,
+  );
+  let installed = await runInstaller(agent);
+
+  // Primary failed and a fallback exists — try it once.
+  if (!installed && fallback) {
+    console.error(
+      `\n  ${c.dim}That didn't work. Trying the fallback: ${c.reset}${c.cyan}${fallback}${c.reset}\n`,
+    );
+    installed = await runInstaller(agent, fallback, false);
+  }
+
+  if (!installed) {
+    console.error(`\n  ${c.red}Install failed.${c.reset} Try it manually:\n`);
+    printInstallCommands(agent);
+    process.exit(127);
+  }
+
+  // PATH hardening: the freshly-installed binary is often not on the current
+  // process's PATH. Re-resolve against PATH + candidate dirs.
+  const found = await resolveBinPath(bin, preferredDirs);
+  if (found) return found;
+
+  console.error(
+    `\n  ${c.dim}Installed ${agent.name}, but it isn't on this shell's PATH yet. ` +
+      `Open a new terminal (or add a bin dir to PATH) and re-run \`subc ${agentCommandName(agent)}\`.${c.reset}\n`,
+  );
+  process.exit(0);
+}
+
+export function parseClaudeVersion(text) {
+  const match = String(text ?? '').match(/v?(\d+\.\d+\.\d+)/);
+  return match?.[1] ?? null;
+}
+
+export const MIN_CLAUDE_CODE_VERSION =
+  agentById('claude-code').install.minimum_version;
+export const MIN_CODEX_VERSION = agentById('codex').install.minimum_version;
+
+export function claudeVersionNeedsUpgrade(
+  installed,
+  minimum = MIN_CLAUDE_CODE_VERSION,
+) {
+  return versionNeedsUpgrade(installed, minimum);
+}
+
+export function versionNeedsUpgrade(installed, minimum) {
+  return Boolean(
+    installed && minimum && compareVersions(installed, minimum) < 0,
+  );
+}
+
+export function readClaudeVersion(bin, binDir, options = {}) {
+  const execFile = options.execFileSync || execFileSync;
+  try {
+    const stdout = execFile(bin, ['--version'], {
+      encoding: 'utf-8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+      env: {
+        ...process.env,
+        PATH: augmentPath(
+          [binDir, ...candidateBinDirs()].filter(Boolean),
+          binDir,
+        ),
+      },
+      timeout: options.timeoutMs ?? 3000,
+    });
+    return parseClaudeVersion(
+      typeof stdout === 'string' ? stdout : stdout?.toString?.(),
+    );
+  } catch {
+    return null;
+  }
+}
+
+/** Warn, without blocking, when the agent is older than its minimum version. */
+export async function ensureMinimumVersion(
+  agent,
+  binDir,
+  { mayPrompt = true } = {},
+) {
+  const minimum = agent.install.minimum_version;
+  if (!minimum) return;
+  const version = readClaudeVersion(agentBinary(agent), binDir);
+  if (!versionNeedsUpgrade(version, minimum)) return;
+
+  console.error(
+    `\n  Minimum supported ${agent.name} version is ${minimum}. Your version is ${version}. Upgrade to get the best experience.\n`,
+  );
+  const { command, fallback } = resolveInstall(agent);
+  console.error(`  Upgrade it with:`);
+  console.error(`    ${c.cyan}${command}${c.reset}`);
+  if (fallback) {
+    console.error(`  or`);
+    console.error(`    ${c.cyan}${fallback}${c.reset}`);
+  }
+  console.error('');
+  if (
+    mayPrompt &&
+    process.stdin.isTTY === true &&
+    process.stdout.isTTY === true
+  ) {
+    await waitForEnter(`  ${c.dim}Press Enter to continue.${c.reset} `);
+    console.error('');
+  }
+}

package/bin/agent-launch.js

@@ -0,0 +1,199 @@
+import { agentInputs, agentKeyName } from './agent-data.js';
+import { openCodeConfigFromEnv } from './opencode-provider.js';
+import { isUnsetSetting } from './profiles.js';
+
+// One pass, so a substituted value (a prompt, a settings document) is never
+// scanned again for placeholders.
+const PLACEHOLDER = /\$\{([A-Z_][A-Z0-9_]*)\}(\/)?|\{([A-Za-z][A-Za-z0-9]*)\}/g;
+const present = (value) =>
+  value !== undefined && value !== null && value !== '';
+
+function tokensFor(agent, env, extra) {
+  const baseUrl = String(env.GATEWAY_URL ?? '').replace(/\/+$/, '');
+  const keyName = agentKeyName(agent);
+  return {
+    baseUrl,
+    baseUrlV1: `${baseUrl}/v1`,
+    apiKey: (keyName && env[keyName]) || env.API_KEY || '',
+    model: env.MODEL ?? '',
+    // Left for the runbook, which writes the file and substitutes its path.
+    tempFile: '{tempFile}',
+    opencodeConfig: () => JSON.stringify(openCodeConfigFromEnv(env)),
+    ...extra,
+  };
+}
+
+/**
+ * Fill `{token}` placeholders and `${NAME}` env references. A reference
+ * followed by `/` drops the value's trailing slashes, so URLs join cleanly.
+ */
+export function render(template, agent, env, extra = {}) {
+  const tokens = tokensFor(agent, env, extra);
+  return String(template).replace(PLACEHOLDER, (match, ref, slash, token) => {
+    if (ref) {
+      const value = String(env[ref] ?? '');
+      return slash ? `${value.replace(/\/+$/, '')}/` : value;
+    }
+    if (!(token in tokens) || tokens[token] === undefined)
+      throw new Error(`${agent.id}: ${match} has no value here`);
+    const value = tokens[token];
+    return typeof value === 'function' ? value() : value;
+  });
+}
+
+/**
+ * Pull the agent's declared flags out of `args`, up to the first `--`, which
+ * is dropped. Everything else passes through in order.
+ */
+export function takeFlags(agent, args, { skip = [] } = {}) {
+  const flags = new Map(
+    agentInputs(agent)
+      .filter((input) => input.flag && !skip.includes(input.name))
+      .map((input) => [input.flag, input]),
+  );
+  const values = {};
+  const rest = [];
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '--') {
+      rest.push(...args.slice(i + 1));
+      break;
+    }
+    const equals = arg.startsWith('--') ? arg.indexOf('=') : -1;
+    const name = equals > 0 ? arg.slice(0, equals) : arg;
+    const input = flags.get(name);
+    if (!input) {
+      rest.push(arg);
+    } else if ('flag_value' in input) {
+      if (equals > 0) throw new Error(`${name} does not take a value`);
+      values[input.name] = input.flag_value;
+    } else if (equals > 0) {
+      values[input.name] = arg.slice(equals + 1);
+    } else if (i + 1 < args.length) {
+      values[input.name] = args[++i];
+    } else {
+      throw new Error(`${name} requires a value`);
+    }
+  }
+  return { values, rest };
+}
+
+function inputValue(input, env, agent) {
+  const own = env[input.name];
+  const usable = (value) =>
+    present(value) && !(input.unset_words && isUnsetSetting(value));
+  if (usable(own)) return own;
+  const alias = (input.aliases || []).map((name) => env[name]).find(usable);
+  if (alias !== undefined) return alias;
+  if (own === '' && input.keep_empty) return own;
+  if (input.default === undefined) return own;
+  return render(input.default, agent, env);
+}
+
+/**
+ * Apply flags, then each input's aliases and default, in file order. A
+ * launch rejects a strict input outside its choices; status and uninstall
+ * pass `{ strict: false }` so a bad setting cannot block the way out.
+ */
+export function resolveInputs(
+  agent,
+  env,
+  flagged = {},
+  { strict = true } = {},
+) {
+  const resolved = { ...env, ...flagged };
+  for (const input of agentInputs(agent)) {
+    if (input.name in flagged) continue;
+    const value = inputValue(input, resolved, agent);
+    if (value !== undefined) resolved[input.name] = String(value);
+  }
+  for (const input of agentInputs(agent)) {
+    if (!strict || !input.strict) continue;
+    if (input.choices.includes(resolved[input.name])) continue;
+    const source = input.name in flagged ? input.flag : input.name;
+    throw new Error(`${source} must be one of: ${input.choices.join(', ')}`);
+  }
+  return resolved;
+}
+
+/** Set each env entry: the first non-empty override, otherwise its value. */
+export function resolveAgentEnv(agent, env) {
+  const resolved = { ...env };
+  for (const entry of agent.env) {
+    const override = (entry.override || [])
+      .map((name) => resolved[name])
+      .find(present);
+    resolved[entry.name] =
+      override !== undefined ? override : render(entry.value, agent, resolved);
+  }
+  return resolved;
+}
+
+function holds(when, env) {
+  return Object.entries(when || {}).every(([name, test]) => {
+    const value = env[name] ?? '';
+    if (test === 'set') return value !== '';
+    if (test === 'empty') return value === '';
+    if (test && 'not' in test) return value !== test.not;
+    throw new Error(`Unknown condition for ${name}: ${JSON.stringify(test)}`);
+  });
+}
+
+/** `-c name=value` pairs (or the agent's config flag) for cli-config entries. */
+export function configArgs(agent, env) {
+  const flag = agent.launch?.config_flag;
+  return agent.config
+    .filter((entry) => entry.kind === 'cli-config' && holds(entry.when, env))
+    .flatMap((entry) => [
+      flag,
+      `${entry.name}=${render(entry.value, agent, env)}`,
+    ]);
+}
+
+function expandArgv(agent, template, env, args, prompt) {
+  const argv = [];
+  let templateWords;
+  for (const word of template) {
+    if (word === '{args}') {
+      templateWords ??= argv.length;
+      argv.push(...args);
+    } else if (word === '{config}') {
+      argv.push(...configArgs(agent, env));
+    } else {
+      if (word.includes('{prompt}')) templateWords ??= argv.length;
+      argv.push(render(word, agent, env, { prompt }));
+    }
+  }
+  return { argv, templateWords: templateWords ?? argv.length };
+}
+
+/**
+ * Everything needed to start an agent: its argv, env, and stdin. `args` are
+ * the words after the agent name with subc's own flags already removed;
+ * `prompt` is set for a headless run. `templateWords` counts the leading argv
+ * words that came from the template, the only ones a runbook may rewrite.
+ */
+export function launchPlan(agent, { env, args = [], prompt } = {}) {
+  const headless = prompt !== undefined;
+  const { launch } = agent;
+  const words =
+    !headless && launch.mode_word && args[0] === launch.mode_word
+      ? args.slice(1)
+      : args;
+  const { values, rest } = takeFlags(agent, words);
+  const resolved = resolveAgentEnv(agent, resolveInputs(agent, env, values));
+  const template = headless ? launch.headless_argv : launch.argv;
+  const { argv, templateWords } = expandArgv(
+    agent,
+    template,
+    resolved,
+    rest,
+    prompt,
+  );
+  if (!headless)
+    return { argv, env: resolved, stdin: 'inherit', templateWords };
+  if (!launch.headless_stdin)
+    return { argv, env: resolved, stdin: 'ignore', templateWords };
+  const input = render(launch.headless_stdin, agent, resolved, { prompt });
+  return { argv, env: resolved, stdin: 'pipe', input, templateWords };
+}

package/bin/agent-spawn.js

@@ -0,0 +1,137 @@
+import { spawn } from 'node:child_process';
+import os from 'node:os';
+import path from 'node:path';
+import { RUNBOOK_DIR } from './agent-data.js';
+import { modelIds } from './launch-values.js';
+import { visionModelList } from './model-capabilities.js';
+
+/** Resolve a script inside the agent's own runbook directory. */
+export function runbookScriptPath(agent, relativeScript) {
+  const dir = path.join(RUNBOOK_DIR, agent.id);
+  const script = path.resolve(dir, relativeScript);
+  const relative = path.relative(dir, script);
+  if (relative.startsWith('..') || path.isAbsolute(relative)) {
+    throw new Error(`Invalid runbook script path for ${agent.name}`);
+  }
+  return script;
+}
+
+function forwardStops(child) {
+  // The runbook execs the agent, so it is our direct child: a runner that
+  // stops subc must stop the agent too. A terminal already delivers SIGINT
+  // to the whole process group, so it is not forwarded.
+  const forwarded = ['SIGTERM', 'SIGHUP'];
+  const forward = (signal) => {
+    if (child.exitCode === null && child.signalCode === null) {
+      child.kill(signal);
+    }
+  };
+  for (const signal of forwarded) process.on(signal, forward);
+  return () => {
+    for (const signal of forwarded) process.off(signal, forward);
+  };
+}
+
+/**
+ * Run `file args`, mirror its exit status or signal, and pass SIGTERM/SIGHUP
+ * on to it. `stdin` is 'inherit', 'ignore', or 'pipe' with `input` written
+ * then closed. `notFound` builds the error when `file` does not exist.
+ */
+export function spawnChild(
+  file,
+  args,
+  { env, stdin = 'inherit', input, notFound },
+) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(file, args, {
+      stdio: [stdin, 'inherit', 'inherit'],
+      env,
+    });
+    if (stdin === 'pipe') {
+      // The agent may exit without reading all of it.
+      child.stdin.on('error', () => {});
+      child.stdin.end(input);
+    }
+    const stopForwarding = forwardStops(child);
+
+    child.on('error', (error) => {
+      stopForwarding();
+      reject(error.code === 'ENOENT' && notFound ? notFound() : error);
+    });
+
+    child.on('exit', (code, signal) => {
+      stopForwarding();
+      if (signal) {
+        // Node ignores some signals (SIGPIPE), so re-raising may not end the
+        // process; the shell convention still reports the agent's failure.
+        process.exitCode = 128 + (os.constants.signals[signal] ?? 0);
+        process.kill(process.pid, signal);
+        resolve(process.exitCode);
+        return;
+      }
+      if (code) process.exitCode = code;
+      resolve(code ?? 0);
+    });
+  });
+}
+
+const BASH_MISSING = () =>
+  new Error(
+    'These coding-agent integrations require `bash`, but it was not found on PATH.',
+  );
+
+/**
+ * What a runbook script reads beyond the launch env. With `strict: false`
+ * an invalid model leaves SUBC_MODEL_IDS unset instead of failing, so a
+ * script that needs it sees an empty list.
+ */
+export function scriptEnv(env, { strict = true } = {}) {
+  let ids;
+  try {
+    ids = modelIds(env).join('\n');
+  } catch (error) {
+    if (strict) throw error;
+  }
+  return {
+    ...env,
+    ...(ids === undefined ? {} : { SUBC_MODEL_IDS: ids }),
+    SUBC_VISION_MODELS: visionModelList(),
+  };
+}
+
+/** The command for one of the agent's runbook scripts, given its env. */
+export function scriptCommand(agent, relativeScript, args, env, options) {
+  return {
+    file: 'bash',
+    args: [runbookScriptPath(agent, relativeScript), ...args],
+    env: scriptEnv(env, options),
+    notFound: BASH_MISSING,
+  };
+}
+
+/**
+ * The command that starts a launch plan: the agent's runbook script when it
+ * has one, otherwise the binary itself, from `binDir` when it is known.
+ */
+export function planCommand(agent, plan, binDir) {
+  const io = { stdin: plan.stdin, input: plan.input };
+  const { script } = agent.runbook;
+  if (script) {
+    const command = scriptCommand(agent, script, plan.argv, plan.env);
+    command.env.SUBC_TEMPLATE_WORDS = String(plan.templateWords);
+    return { ...command, ...io };
+  }
+  const [bin, ...args] = plan.argv;
+  return {
+    file: binDir ? path.join(binDir, bin) : bin,
+    args,
+    env: plan.env,
+    ...io,
+    notFound: () => new Error(`Could not launch \`${bin}\`.`),
+  };
+}
+
+/** Run a command built by planCommand or scriptCommand. */
+export function runCommand(command) {
+  return spawnChild(command.file, command.args, command);
+}