subconscious-cli 6.0.1 → 6.2.0

package/bin/agent-help.js

@@ -0,0 +1,114 @@
+import {
+  agentBinary,
+  agentCommandName,
+  agentInputs,
+  agentSetupActions,
+  installAdvice,
+} from './agent-data.js';
+import { c } from './colors.js';
+import { profileSettingsForAgent, resolvedProfileValues } from './profiles.js';
+
+export function isAgentHelpRequest(argv = []) {
+  return ['help', '-h', '--help'].includes(argv[0]);
+}
+
+function displayProfileValue(setting, value, values) {
+  if (setting.type === 'secret') {
+    if (value) return '(set)';
+    return setting.key !== 'API_KEY' && values.API_KEY
+      ? '(shared key)'
+      : '(not set)';
+  }
+  if (!value && setting.model) return 'UNSET';
+  return value || '(auto)';
+}
+
+function optionText(description) {
+  if (typeof description === 'string') return description;
+  return description[process.platform] ?? description.default;
+}
+
+/** Static options, then documented flags, then the pass-through argument. */
+function helpOptions(agent) {
+  const { options, args } = agent.help;
+  const flags = agentInputs(agent)
+    .filter((input) => input.flag && input.help)
+    .map((input) => [
+      input.metavar ? `${input.flag} ${input.metavar}` : input.flag,
+      input.help,
+    ]);
+  const listed = [...options, ...flags, ...(args ? [args] : [])].map(
+    ([option, description]) => [option, optionText(description)],
+  );
+  const headless =
+    agent.launch?.headless_argv &&
+    !listed.some(([option]) => option.startsWith('headless'));
+  return headless
+    ? [
+        ...listed,
+        ['headless PROMPT', 'Run one task without prompting, then exit'],
+      ]
+    : listed;
+}
+
+function printSettings(agent, profile) {
+  const settings = profileSettingsForAgent(agent.id);
+  const values = resolvedProfileValues(profile);
+  const width = Math.max(0, ...settings.map((setting) => setting.key.length));
+  console.log(
+    `  ${c.bold}Profile settings${c.reset} ${c.dim}(${profile?.name || 'default'})${c.reset}`,
+  );
+  for (const setting of settings) {
+    const value = displayProfileValue(setting, values[setting.key], values);
+    console.log(
+      `    ${c.cyan}${setting.key.padEnd(width)}${c.reset}  ${value}`,
+    );
+    console.log(
+      `    ${' '.repeat(width)}  ${c.dim}${setting.description}${c.reset}`,
+    );
+  }
+}
+
+function printSetupHints(agent, profile) {
+  const command = agentCommandName(agent);
+  console.log(
+    `\n  Edit the env file with ${c.cyan}subc -p ${profile?.name || 'default'} config edit${c.reset}.`,
+  );
+  if (agentBinary(agent)) {
+    const { command: install, url } = installAdvice(agent);
+    const how = install
+      ? `with ${c.cyan}${install}${c.reset}, or see ${c.cyan}${url}${c.reset}`
+      : `from ${c.cyan}${url}${c.reset}`;
+    console.log(`  subc doesn't install ${agent.name}. Install it ${how}.`);
+  }
+  const actions = agentSetupActions(agent);
+  if (actions.includes('install')) {
+    console.log(
+      `  Install the persistent integration with ${c.cyan}subc ${command} install${c.reset}.`,
+    );
+  }
+  if (actions.includes('uninstall')) {
+    console.log(
+      `  Remove it with ${c.cyan}subc ${command} uninstall${c.reset}.`,
+    );
+  }
+}
+
+export function printAgentHelp(agent, profile) {
+  const options = helpOptions(agent);
+  const width = Math.max(0, ...options.map(([option]) => option.length));
+  console.log(`\n  ${c.bold}${agent.name} + Subconscious${c.reset}\n`);
+  console.log(`  ${agent.help.behavior}\n`);
+  console.log(`  ${c.bold}Usage${c.reset}\n    ${agent.help.usage}\n`);
+  if (options.length) {
+    console.log(`  ${c.bold}Commands and options${c.reset}`);
+    for (const [option, description] of options)
+      console.log(
+        `    ${c.cyan}${option.padEnd(width)}${c.reset}  ${description}`,
+      );
+    console.log();
+  }
+  printSettings(agent, profile);
+  printSetupHints(agent, profile);
+  console.log();
+}

package/bin/agent-install.js

@@ -0,0 +1,238 @@
+import { execFileSync } 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,
+  installAdvice,
+} from './agent-data.js';
+import { c } from './colors.js';
+import { compareVersions } from './update-check.js';
+
+/**
+ * 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);
+}
+
+function waitForEnter(prompt) {
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout,
+    });
+    rl.question(prompt, () => {
+      rl.close();
+      resolve();
+    });
+  });
+}
+
+/** Print the install command and official install page; subc runs neither. */
+function printInstallAdvice(agent) {
+  const { command, url } = installAdvice(agent);
+  if (command) console.error(`    ${c.cyan}${command}${c.reset}`);
+  console.error(
+    `  ${c.dim}Official install page:${c.reset} ${c.cyan}${url}${c.reset}\n`,
+  );
+}
+
+/**
+ * Return the directory that holds the agent's binary. subc never installs a
+ * third-party agent: when the binary is missing it prints how to install it
+ * and exits 127, in every shell.
+ */
+export async function ensureInstalled(agent) {
+  const bin = agentBinary(agent);
+  const existing = await resolveBinPath(bin, preferredBinDirsForAgent(agent));
+  if (existing) return existing;
+
+  console.error(
+    `\n  ${c.red}${agent.name} isn't installed${c.reset} ${c.dim}(\`${bin}\` not found on PATH).${c.reset}`,
+  );
+  console.error(
+    `  subc doesn't install ${agent.name}. Install it yourself, then re-run ${c.cyan}subc ${agentCommandName(agent)}${c.reset}.\n`,
+  );
+  printInstallAdvice(agent);
+  process.exit(127);
+}
+
+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`,
+  );
+  console.error(`  Upgrade it with:`);
+  printInstallAdvice(agent);
+  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);
+}