@fitlab-ai/agent-infra 0.7.0 → 0.7.1

package/lib/builtin-tuis.ts

@@ -0,0 +1,55 @@
+const BUILTIN_TUI_IDS = ['claude-code', 'codex', 'gemini-cli', 'opencode'] as const;
+type BuiltinTUIId = (typeof BUILTIN_TUI_IDS)[number];
+
+const BUILTIN_TUI_DISPLAY: Record<BuiltinTUIId, string> = {
+  'claude-code': 'Claude Code',
+  'codex': 'Codex',
+  'gemini-cli': 'Gemini CLI',
+  'opencode': 'OpenCode'
+};
+
+const BUILTIN_TUI_OWNED_PATH_PREFIXES: Record<BuiltinTUIId, string[]> = {
+  'claude-code': ['.claude/'],
+  'codex': ['.codex/'],
+  'gemini-cli': ['.gemini/'],
+  'opencode': ['.opencode/']
+};
+
+function isBuiltinTUIId(value: unknown): value is BuiltinTUIId {
+  return typeof value === 'string' && (BUILTIN_TUI_IDS as readonly string[]).includes(value);
+}
+
+function resolveEnabledTUIs(value: unknown): Set<BuiltinTUIId> {
+  // Missing field / null / non-array → full set (backward compat for legacy
+  // .airc.json predating the `tuis` field).
+  if (!Array.isArray(value)) return new Set(BUILTIN_TUI_IDS);
+  // Empty array is a meaningful, user-set value: "no built-in TUI managed".
+  // This supports the customTUI-only project layout.
+  const set = new Set<BuiltinTUIId>();
+  for (const v of value) {
+    if (isBuiltinTUIId(v)) set.add(v);
+  }
+  return set;
+}
+
+function isPathOwnedByDisabledTUI(rel: string, enabled: Set<BuiltinTUIId>): boolean {
+  const normalized = String(rel || '').replace(/\\/g, '/').replace(/^\.\//, '');
+  for (const tui of BUILTIN_TUI_IDS) {
+    if (enabled.has(tui)) continue;
+    for (const prefix of BUILTIN_TUI_OWNED_PATH_PREFIXES[tui]) {
+      const trimmed = prefix.replace(/\/$/, '');
+      if (normalized === trimmed || normalized.startsWith(prefix)) return true;
+    }
+  }
+  return false;
+}
+
+export {
+  BUILTIN_TUI_IDS,
+  BUILTIN_TUI_DISPLAY,
+  BUILTIN_TUI_OWNED_PATH_PREFIXES,
+  isBuiltinTUIId,
+  resolveEnabledTUIs,
+  isPathOwnedByDisabledTUI
+};
+export type { BuiltinTUIId };

package/lib/defaults.json

@@ -21,6 +21,9 @@
       "disk": null
     }
   },
+  "task": {
+    "shortIdLength": 2
+  },
   "labels": {
     "in": {}
   },

package/lib/init.ts

@@ -3,11 +3,18 @@ import path from 'node:path';
 import { execSync } from 'node:child_process';
 import { platform } from 'node:os';
 import { info, ok, err } from './log.ts';
-import { prompt, select, closePrompt } from './prompt.ts';
+import { prompt, select, multiSelect, closePrompt } from './prompt.ts';
 import { resolveTemplateDir } from './paths.ts';
 import { renderFile, copySkillDir, KNOWN_PLATFORMS } from './render.ts';
 import { enginesForPlatform } from './sandbox/engines/index.ts';
 import { VERSION } from './version.ts';
+import {
+  BUILTIN_TUI_IDS,
+  BUILTIN_TUI_DISPLAY,
+  isPathOwnedByDisabledTUI,
+  resolveEnabledTUIs
+} from './builtin-tuis.ts';
+import type { BuiltinTUIId } from './builtin-tuis.ts';
 
 type FileRegistry = {
   managed: string[];
@@ -23,6 +30,7 @@ type SourceEntry = {
 type Defaults = {
   files: FileRegistry;
   sandbox: Record<string, unknown>;
+  task: { shortIdLength: number };
   labels: Record<string, unknown>;
   requiresPullRequest: boolean;
 };
@@ -35,8 +43,10 @@ type AgentConfig = {
   requiresPullRequest: boolean;
   templateVersion: string;
   sandbox: Record<string, unknown>;
+  task: { shortIdLength: number };
   labels: Record<string, unknown>;
   files: FileRegistry;
+  tuis: string[];
   templates?: { sources: SourceEntry[] };
   skills?: { sources: SourceEntry[] };
 };
@@ -60,10 +70,15 @@ function isPathOwnedByOtherPlatform(relativePath: string, platformType: string):
   return candidate !== platformType;
 }
 
-function buildDefaultFiles(platformType: string): FileRegistry {
+function buildDefaultFiles(platformType: string, enabledTUIs: Set<BuiltinTUIId>): FileRegistry {
+  const ownedByDisabled = (entry: string) => isPathOwnedByDisabledTUI(entry, enabledTUIs);
   return {
-    managed: (defaults.files.managed || []).filter((entry) => !isPathOwnedByOtherPlatform(entry, platformType)),
-    merged: (defaults.files.merged || []).filter((entry) => !isPathOwnedByOtherPlatform(entry, platformType)),
+    managed: (defaults.files.managed || []).filter(
+      (entry) => !isPathOwnedByOtherPlatform(entry, platformType) && !ownedByDisabled(entry)
+    ),
+    merged: (defaults.files.merged || []).filter(
+      (entry) => !isPathOwnedByOtherPlatform(entry, platformType) && !ownedByDisabled(entry)
+    ),
     ejected: structuredClone(defaults.files.ejected || [])
   };
 }
@@ -216,6 +231,20 @@ async function cmdInit(): Promise<void> {
   );
   const requiresPullRequest = requiresPRChoice !== 'no';
 
+  let enabledTUIs: string[];
+  try {
+    enabledTUIs = await multiSelect(
+      'Built-in TUI command files to install/manage',
+      BUILTIN_TUI_IDS.map((id) => ({ id, label: BUILTIN_TUI_DISPLAY[id] }))
+    );
+  } catch (e) {
+    err(e instanceof Error ? e.message : String(e));
+    closePrompt();
+    process.exitCode = 1;
+    return;
+  }
+  const enabledTUISet = resolveEnabledTUIs(enabledTUIs);
+
   const templateSources = parseLocalSources(await prompt(
     'Template sources (optional, comma-separated local paths, e.g. ~/my-templates; Enter to skip)',
     ''
@@ -259,29 +288,35 @@ async function cmdInit(): Promise<void> {
   );
   ok('Installed .agents/skills/update-agent-infra/');
 
-  // install Claude command
-  renderFile(
-    path.join(templateDir, '.claude', 'commands', claudeSrc),
-    path.join('.claude', 'commands', 'update-agent-infra.md'),
-    replacements
-  );
-  ok('Installed .claude/commands/update-agent-infra.md');
+  // install Claude command (only if enabled)
+  if (enabledTUISet.has('claude-code')) {
+    renderFile(
+      path.join(templateDir, '.claude', 'commands', claudeSrc),
+      path.join('.claude', 'commands', 'update-agent-infra.md'),
+      replacements
+    );
+    ok('Installed .claude/commands/update-agent-infra.md');
+  }
 
-  // install Gemini command
-  renderFile(
-    path.join(templateDir, '.gemini', 'commands', '_project_', geminiSrc),
-    path.join('.gemini', 'commands', project, 'update-agent-infra.toml'),
-    replacements
-  );
-  ok(`Installed .gemini/commands/${project}/update-agent-infra.toml`);
+  // install Gemini command (only if enabled)
+  if (enabledTUISet.has('gemini-cli')) {
+    renderFile(
+      path.join(templateDir, '.gemini', 'commands', '_project_', geminiSrc),
+      path.join('.gemini', 'commands', project, 'update-agent-infra.toml'),
+      replacements
+    );
+    ok(`Installed .gemini/commands/${project}/update-agent-infra.toml`);
+  }
 
-  // install OpenCode command
-  renderFile(
-    path.join(templateDir, '.opencode', 'commands', opencodeSrc),
-    path.join('.opencode', 'commands', 'update-agent-infra.md'),
-    replacements
-  );
-  ok('Installed .opencode/commands/update-agent-infra.md');
+  // install OpenCode command (only if enabled)
+  if (enabledTUISet.has('opencode')) {
+    renderFile(
+      path.join(templateDir, '.opencode', 'commands', opencodeSrc),
+      path.join('.opencode', 'commands', 'update-agent-infra.md'),
+      replacements
+    );
+    ok('Installed .opencode/commands/update-agent-infra.md');
+  }
 
   // generate .agents/.airc.json
   const config: AgentConfig = {
@@ -292,8 +327,10 @@ async function cmdInit(): Promise<void> {
     requiresPullRequest,
     templateVersion: VERSION,
     sandbox: structuredClone(defaults.sandbox),
+    task: structuredClone(defaults.task),
     labels: structuredClone(defaults.labels),
-    files: buildDefaultFiles(platformType)
+    files: buildDefaultFiles(platformType, enabledTUISet),
+    tuis: enabledTUIs
   };
 
   if (sandboxEngine) {
@@ -320,15 +357,30 @@ async function cmdInit(): Promise<void> {
   console.log('');
   ok('Project initialized successfully!');
   console.log('');
-  console.log('  Next step: open this project in any AI TUI and run:');
-  console.log('');
-  console.log('    Claude Code / OpenCode:  /update-agent-infra');
-  console.log(`    Gemini CLI:              /${project}:update-agent-infra`);
-  console.log('    Codex CLI:               $update-agent-infra');
-  console.log('');
-  console.log('  This will render all templates and set up the full');
-  console.log('  AI collaboration infrastructure.');
-  console.log('');
+  if (enabledTUISet.size === 0) {
+    console.log('  No built-in TUI selected.');
+    console.log(`  Configure "customTUIs" in ${configPath} before running update-agent-infra.`);
+    console.log('');
+  } else {
+    console.log('  Next step: open this project in any AI TUI and run:');
+    console.log('');
+    const claudeOrOpencode: string[] = [];
+    if (enabledTUISet.has('claude-code')) claudeOrOpencode.push('Claude Code');
+    if (enabledTUISet.has('opencode')) claudeOrOpencode.push('OpenCode');
+    if (claudeOrOpencode.length > 0) {
+      console.log(`    ${claudeOrOpencode.join(' / ')}:  /update-agent-infra`);
+    }
+    if (enabledTUISet.has('gemini-cli')) {
+      console.log(`    Gemini CLI:              /${project}:update-agent-infra`);
+    }
+    if (enabledTUISet.has('codex')) {
+      console.log('    Codex CLI:               $update-agent-infra');
+    }
+    console.log('');
+    console.log('  This will render all templates and set up the full');
+    console.log('  AI collaboration infrastructure.');
+    console.log('');
+  }
 }
 
 export { cmdInit };

package/lib/prompt.ts

@@ -86,6 +86,59 @@ async function select(question: string, choices: string[], defaultValue?: string
   return trimmed;
 }
 
+async function multiSelect(
+  question: string,
+  choices: { id: string; label: string }[]
+): Promise<string[]> {
+  process.stdout.write(`  ${question}:\n`);
+  const idWidth = Math.max(...choices.map((c) => c.id.length));
+  choices.forEach((c, i) => {
+    process.stdout.write(`      ${i + 1}) ${c.id.padEnd(idWidth)}  (${c.label})\n`);
+  });
+  ask('Enter comma-separated numbers or ids to keep, or "none" to select nothing [default: all]: ');
+
+  setupInterface();
+
+  const line = await nextLine();
+  // Strictly distinguish bare Enter (null/empty string) from whitespace input.
+  if (line === null || line === '') return choices.map((c) => c.id);
+  // Explicit empty selection: "none" means deliberately zero built-in choices.
+  if (line.trim().toLowerCase() === 'none') return [];
+
+  const tokens = line.split(',').map((t) => t.trim());
+  if (tokens.some((t) => t === '')) {
+    throw new Error(`Invalid selection input: "${line}" (empty token)`);
+  }
+
+  const idSet = new Set(choices.map((c) => c.id));
+  const seenIds = new Set<string>();
+  for (const t of tokens) {
+    let resolvedId: string | undefined;
+    if (/^[0-9]+$/.test(t)) {
+      const n = Number.parseInt(t, 10);
+      if (n < 1 || n > choices.length) {
+        throw new Error(`Selection out of range: "${t}" (expected 1..${choices.length})`);
+      }
+      resolvedId = choices[n - 1]!.id;
+    } else if (idSet.has(t)) {
+      resolvedId = t;
+    } else {
+      throw new Error(`Unknown TUI selection token: "${t}"`);
+    }
+    if (seenIds.has(resolvedId)) {
+      throw new Error(`Duplicate selection: "${t}" resolves to already-selected "${resolvedId}"`);
+    }
+    seenIds.add(resolvedId);
+  }
+
+  // Normalize to prompt order: users can type tokens in any order, but the
+  // persisted array follows the canonical choices order to keep .airc.json
+  // diffs stable. An empty result here is impossible (tokens.length > 0 and
+  // every token resolves to an id), so no separate empty guard is needed —
+  // explicit "none" handled above.
+  return choices.map((c) => c.id).filter((id) => seenIds.has(id));
+}
+
 function closePrompt(): void {
   if (_rl) {
     _rl.close();
@@ -94,4 +147,4 @@ function closePrompt(): void {
   }
 }
 
-export { prompt, select, closePrompt };
+export { prompt, select, multiSelect, closePrompt };

package/lib/sandbox/commands/enter.ts

@@ -123,7 +123,7 @@ export async function enter(args: string[]): Promise<number> {
   let branch: string;
   if (isTaskShortRef(firstArg)) {
     const { running } = fetchSandboxRows(engine, sandboxLabel(config), sandboxBranchLabel(config));
-    branch = resolveTaskShortRef(firstArg, { running });
+    branch = resolveTaskShortRef(firstArg, { running, repoRoot: config.repoRoot });
   } else {
     branch = resolveTaskBranch(firstArg, config.repoRoot);
   }

package/lib/sandbox/commands/list-running.ts

@@ -1,3 +1,6 @@
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
 import { runSafeEngine } from '../shell.ts';
 
 export type SandboxRow = {
@@ -94,29 +97,56 @@ export function isTaskShortRef(arg: string): boolean {
   return /^#\d+$/.test(arg);
 }
 
+type RegistryLookup =
+  | { status: 'miss' }
+  | { status: 'hit'; branch: string };
+
 /**
- * Resolve a task short reference ('#N') to a branch name.
- *
- * Current implementation: treats the digits as a 1-based index into the
- * supplied running-sandbox list (ls view order). This is the *only*
- * resolution path until the global task-short-id registry lands in a
- * follow-up task; do NOT read task.md or scan .agents/workspace/ from this
- * helper here.
+ * Try to resolve a short ref against the global task-short-id registry.
  *
- * Precondition: callers MUST gate on isTaskShortRef(arg) === true before
- * constructing ctx and calling this function. Throws when arg is a valid
- * short ref but cannot be resolved (out of range, no running sandboxes,
- * etc.); the caller surfaces the error to the user.
+ * Tri-state semantics (review-code Round 1 M-1 fix):
+ *   - 'miss'     → script reports no entry (or registry script missing). Caller may fall back.
+ *   - 'hit'      → registry resolved to a task id and branch is found in task.md.
+ *   - throws     → registry hit but task.md is missing or branch metadata is unparseable;
+ *                   surfacing this error is critical — never silently fall back to running index.
  */
-export function resolveTaskShortRef(
-  arg: string,
-  ctx: { running: SandboxRow[] }
-): string {
+function tryResolveFromRegistry(arg: string, repoRoot: string): RegistryLookup {
+  const scriptPath = path.join(repoRoot, '.agents', 'scripts', 'task-short-id.js');
+  if (!fs.existsSync(scriptPath)) return { status: 'miss' };
+  const result = spawnSync('node', [scriptPath, 'resolve', arg], { encoding: 'utf8', cwd: repoRoot });
+  if (result.status !== 0) return { status: 'miss' };
+  const taskId = (result.stdout || '').trim();
+  if (!/^TASK-\d{8}-\d{6}$/.test(taskId)) {
+    throw new Error(
+      `Registry returned malformed task id for '${arg}': ${JSON.stringify(taskId)}`
+    );
+  }
+  for (const sub of ['active', 'completed', 'blocked', 'archive']) {
+    const taskMdPath = path.join(repoRoot, '.agents', 'workspace', sub, taskId, 'task.md');
+    if (!fs.existsSync(taskMdPath)) continue;
+    const content = fs.readFileSync(taskMdPath, 'utf8');
+    const fm = content.match(/^branch:\s*(.+)$/m);
+    if (fm?.[1]?.trim()) {
+      return { status: 'hit', branch: fm[1].trim().replace(/^(["'])(.*)\1$/, '$2') };
+    }
+    const ctx = content.match(/^- \*\*(?:分支|Branch)\*\*：[ \t]*`?([^`\n]+)`?$/m);
+    if (ctx?.[1]?.trim()) {
+      return { status: 'hit', branch: ctx[1].trim().replace(/^(["'])(.*)\1$/, '$2') };
+    }
+    throw new Error(
+      `Short ref '${arg}' resolved to task ${taskId} but task.md has no branch field`
+    );
+  }
+  throw new Error(
+    `Short ref '${arg}' resolved to task ${taskId} but task.md was not found under any workspace dir`
+  );
+}
+
+function resolveByRunningIndex(arg: string, running: SandboxRow[]): string {
   const n = Number(arg.slice(1));
   if (n < 1) {
     throw new Error(`Invalid sandbox index '${arg}': must be >= 1`);
   }
-  const { running } = ctx;
   if (running.length === 0) {
     throw new Error(`No running sandbox to reference with '${arg}'`);
   }
@@ -133,3 +163,26 @@ export function resolveTaskShortRef(
   }
   return row.branch;
 }
+
+/**
+ * Resolve a task short reference ('#N') to a branch name for the sandbox entrypoint.
+ *
+ * Resolution order (sandbox fallback mode, plan-r7 C2):
+ *   1. Try the global task-short-id registry under repoRoot. If hit, look up the
+ *      branch from the matching task.md.
+ *   2. Fallback to the running-sandbox list index (preserves the #414 ls-index
+ *      behaviour; long-term contract per analysis-r5).
+ *
+ * Precondition: callers MUST gate on isTaskShortRef(arg) === true.
+ */
+export function resolveTaskShortRef(
+  arg: string,
+  ctx: { running: SandboxRow[]; repoRoot?: string }
+): string {
+  if (ctx.repoRoot) {
+    const lookup = tryResolveFromRegistry(arg, ctx.repoRoot);
+    if (lookup.status === 'hit') return lookup.branch;
+    // 'miss' falls through to ls-index fallback (preserves #414 behaviour); 'hit-but-invalid' already threw above.
+  }
+  return resolveByRunningIndex(arg, ctx.running);
+}

package/lib/sandbox/commands/rebuild.ts

@@ -7,7 +7,8 @@ import type { SandboxConfig } from '../config.ts';
 import { prepareDockerfile } from '../dockerfile.ts';
 import { sandboxImageConfigLabel, sandboxLabel } from '../constants.ts';
 import { detectEngine, ensureDocker } from '../engine.ts';
-import { runEngine, runOkEngine, runSafeEngine, runVerboseEngine } from '../shell.ts';
+import { runEngine, runSafeEngine, runVerboseEngine } from '../shell.ts';
+import { pruneSandboxDanglingImages } from '../image-prune.ts';
 import {
   imageSignatureFields,
   resolveTools,
@@ -89,12 +90,6 @@ export function buildArgs(
   return args;
 }
 
-function removeImageIfPresent(imageName: string, engine: string): void {
-  if (runOkEngine(engine, 'docker', ['image', 'inspect', imageName])) {
-    runEngine(engine, 'docker', ['rmi', imageName]);
-  }
-}
-
 export async function rebuild(args: string[]): Promise<void> {
   const { values } = parseArgs({
     args,
@@ -126,17 +121,12 @@ export async function rebuild(args: string[]): Promise<void> {
   try {
     if (quiet) {
       const spinner = p.spinner();
-      spinner.start(`Removing old image ${config.imageName}...`);
-      removeImageIfPresent(config.imageName, engine);
-      spinner.stop('Old image removed');
       spinner.start('Building image...');
       runEngine(engine, 'docker', buildArgs(config, tools, preparedDockerfile.path, imageSignature, { engine, refresh }), {
         cwd: config.repoRoot
       });
       spinner.stop(pc.green('Sandbox image rebuilt'));
     } else {
-      p.log.step(`Removing old image ${config.imageName}`);
-      removeImageIfPresent(config.imageName, engine);
       p.log.step('Building image');
       runVerboseEngine(
         engine,
@@ -146,6 +136,7 @@ export async function rebuild(args: string[]): Promise<void> {
       );
       p.log.success(pc.green('Sandbox image rebuilt'));
     }
+    pruneSandboxDanglingImages(config, engine);
   } finally {
     preparedDockerfile.cleanup();
   }

package/lib/sandbox/commands/rm.ts

@@ -15,6 +15,7 @@ import {
   worktreeDirCandidates
 } from '../constants.ts';
 import { ENGINES, detectEngine, engineDisplayName, isManagedEngine, stopManagedVm } from '../engine.ts';
+import { pruneSandboxDanglingImages } from '../image-prune.ts';
 import { removeManagedDir, removeWorktreeDir } from '../managed-fs.ts';
 import { runOk, runSafe, runSafeEngine } from '../shell.ts';
 import { resolveTaskBranch } from '../task-resolver.ts';
@@ -208,6 +209,8 @@ async function rmAll(config: SandboxConfig, tools: SandboxTool[]): Promise<void>
     runSafeEngine(engine, 'docker', ['rmi', config.imageName]);
   }
 
+  pruneSandboxDanglingImages(config, engine);
+
   if (isManagedEngine(engine)) {
     if (engine === ENGINES.WSL2) {
       p.log.warn('Windows uses Docker Desktop with WSL2. Stop it from Docker Desktop or run "wsl --shutdown" manually.');

package/lib/sandbox/image-prune.ts

@@ -0,0 +1,23 @@
+import * as p from '@clack/prompts';
+import type { SandboxConfig } from './config.ts';
+import { sandboxLabel } from './constants.ts';
+import { runEngine } from './shell.ts';
+
+export function pruneSandboxDanglingImages(
+  config: Pick<SandboxConfig, 'project'>,
+  engine: string
+): void {
+  try {
+    runEngine(engine, 'docker', [
+      'image',
+      'prune',
+      '-f',
+      '--filter',
+      `label=${sandboxLabel(config)}`
+    ]);
+  } catch {
+    p.log.warn(
+      `Failed to prune dangling sandbox images (label=${sandboxLabel(config)}); leaving them in place.`
+    );
+  }
+}

package/lib/sandbox/task-resolver.ts

@@ -1,9 +1,27 @@
+import { spawnSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
 
 const TASK_ID_RE = /^TASK-\d{8}-\d{6}$/;
+const SHORT_ID_RE = /^#\d+$/;
 const WORKSPACE_DIRS = ['active', 'completed', 'blocked', 'archive'];
 
+function resolveShortIdStrict(arg: string, repoRoot: string): string {
+  const scriptPath = path.join(repoRoot, '.agents', 'scripts', 'task-short-id.js');
+  if (!fs.existsSync(scriptPath)) {
+    throw new Error(
+      `Short id '${arg}' provided but task-short-id.js script is missing at ${scriptPath}`
+    );
+  }
+  const result = spawnSync('node', [scriptPath, 'resolve', arg], { encoding: 'utf8', cwd: repoRoot });
+  if (result.status !== 0) {
+    throw new Error(
+      `Short id '${arg}' not found in active task registry: ${(result.stderr || '').trim()}`
+    );
+  }
+  return result.stdout.trim();
+}
+
 function stripQuotes(value: string): string {
   return value.replace(/^(["'])(.*)\1$/, '$2');
 }
@@ -33,10 +51,14 @@ function resolveBranchFromTaskContent(content: string, taskId: string): string {
 }
 
 export function resolveTaskBranch(arg: string, repoRoot: string): string {
+  if (SHORT_ID_RE.test(arg)) {
+    const taskId = resolveShortIdStrict(arg, repoRoot);
+    const content = readTaskContent(repoRoot, taskId);
+    return resolveBranchFromTaskContent(content, taskId);
+  }
   if (!TASK_ID_RE.test(arg)) {
     return arg;
   }
-
   const content = readTaskContent(repoRoot, arg);
   return resolveBranchFromTaskContent(content, arg);
 }