@aibridge/cli 0.0.1

package/src/commands/subagent/command.ts

@@ -0,0 +1,62 @@
+import { buildCommand } from '@stricli/core';
+import { DEFAULT_MODEL, listModelHelpLines } from '../../models.ts';
+import { nonEmptyPrompt, positiveIntSeconds } from '../../parsers.ts';
+import subagentImpl from './impl.ts';
+
+const fullDescription = [
+  'Hands a self-contained prompt to another model and returns its answer.',
+  '',
+  'Available models (canonical slug):',
+  ...listModelHelpLines(),
+  `Default: ${DEFAULT_MODEL} (off-budget). The claude-backend slugs are FALLBACKS for`,
+  'when the off-budget CLIs are quota-exhausted — they bill your Claude subscription.',
+].join('\n');
+
+export const subagent = buildCommand({
+  func: subagentImpl,
+  parameters: {
+    flags: {
+      model: {
+        kind: 'parsed',
+        parse: String,
+        optional: true,
+        brief: `Model slug to delegate to (default: ${DEFAULT_MODEL})`,
+      },
+      timeout: {
+        kind: 'parsed',
+        parse: positiveIntSeconds,
+        optional: true,
+        brief: 'Max seconds to wait for the backend (default: 600)',
+      },
+      tools: {
+        kind: 'boolean',
+        default: true,
+        brief: 'Allow delegate model to use tools (use --no-tools to restrict to reasoning only)',
+      },
+      preflight: {
+        kind: 'boolean',
+        default: true,
+        brief: 'Check model quota before running (use --no-preflight to skip)',
+      },
+      json: {
+        kind: 'boolean',
+        withNegated: false,
+        brief: 'Emit a machine-readable JSON result (using canonical slug) instead of prose',
+      },
+    },
+    positional: {
+      kind: 'tuple',
+      parameters: [
+        {
+          brief: 'Self-contained task prompt for the delegate model',
+          parse: nonEmptyPrompt,
+          placeholder: 'prompt',
+        },
+      ],
+    },
+  },
+  docs: {
+    brief: 'Delegate a self-contained task to another model',
+    fullDescription,
+  },
+});

package/src/commands/subagent/impl.ts

@@ -0,0 +1,87 @@
+import type { LocalContext } from '../../context.ts';
+import { delegate } from '../../delegate.ts';
+import {
+  backendModelId,
+  DEFAULT_MODEL,
+  formatUnknownModelError,
+  resolveModel,
+} from '../../models.ts';
+import { preflightModel, renderPreflightRefusal } from '../../quotaPreflight.ts';
+import { startRun } from '../../runlog.ts';
+
+export interface SubagentFlags {
+  readonly model?: string;
+  readonly timeout?: number;
+  readonly tools: boolean;
+  readonly preflight: boolean;
+  readonly json: boolean;
+}
+
+export default async function subagent(
+  this: LocalContext,
+  flags: SubagentFlags,
+  prompt: string,
+): Promise<void> {
+  const inputSlug = flags.model ?? DEFAULT_MODEL;
+  const model = resolveModel(inputSlug);
+  if (!model) {
+    this.process.stderr.write(`${formatUnknownModelError(inputSlug)}\n`);
+    this.process.exitCode = 2;
+    return;
+  }
+
+  if (flags.preflight) {
+    const verdict = await preflightModel(model);
+    if (!verdict.ok) {
+      if (flags.json) {
+        this.process.stdout.write(
+          `${JSON.stringify({
+            error: 'quota_exhausted',
+            message: verdict.message,
+            resetAt: verdict.resetAt ?? null,
+            slug: model.spec.slug,
+          })}\n`,
+        );
+      } else {
+        this.process.stderr.write(`${renderPreflightRefusal('subagent', verdict)}\n`);
+      }
+      this.process.exitCode = 3;
+      return;
+    }
+    if (verdict.warning) this.process.stderr.write(`aibridge subagent: ${verdict.warning}\n`);
+  }
+
+  const timeoutSec = flags.timeout ?? 600;
+  const workDir = this.process.cwd();
+  const promptSnippet = prompt.replace(/\r?\n/g, ' ').slice(0, 80);
+  const run = startRun('subagent', `${model.spec.slug}: ${promptSnippet}`);
+
+  const outcome = await delegate({
+    model,
+    prompt,
+    tools: flags.tools,
+    timeoutSec,
+    cwd: workDir,
+    run,
+  });
+
+  if (!outcome.ok) {
+    this.process.stderr.write(`${outcome.message}\n`);
+    this.process.exitCode = 1;
+    return;
+  }
+
+  if (flags.json) {
+    const modelId = backendModelId(model) ?? null;
+    this.process.stdout.write(
+      `${JSON.stringify({
+        model: modelId,
+        slug: model.spec.slug,
+        response: outcome.response,
+        exitCode: outcome.exitCode,
+      })}\n`,
+    );
+  } else {
+    this.process.stdout.write(`${outcome.response}\n`);
+  }
+}

package/src/context.ts

@@ -0,0 +1,10 @@
+import type { CommandContext } from '@stricli/core';
+
+export interface LocalContext extends CommandContext {
+  /** Full Node process — satisfies stricli WritableStreams + exitCode/env/cwd used by impls. */
+  readonly process: NodeJS.Process;
+}
+
+export function buildContext(process: NodeJS.Process): LocalContext {
+  return { process };
+}

package/src/delegate.test.ts

@@ -0,0 +1,180 @@
+import { describe, expect, it } from 'vitest';
+import { delegate } from './delegate.ts';
+import type { AgentCliDriver, DelegationResult, DelegationTask } from './driver.ts';
+import { resolveModel } from './models.ts';
+import type { RunLog } from './runlog.ts';
+
+const PREAMBLE_PIN =
+  'You are the sole executing agent for this task: do it yourself with your tools, now. ' +
+  'Never defer to, wait for, or claim to hand off to another agent or process — no one ' +
+  'else will act, and work not done in this run does not happen.\n\n';
+
+class StubDriver implements AgentCliDriver {
+  lastTask?: DelegationTask;
+  private readonly result: DelegationResult;
+  private readonly callbacks?: { stdout?: string; stderr?: string; pid?: number };
+
+  constructor(
+    result: DelegationResult,
+    callbacks?: { stdout?: string; stderr?: string; pid?: number },
+  ) {
+    this.result = result;
+    this.callbacks = callbacks;
+  }
+
+  async probe() {
+    return { ok: true, version: '1.0' } as const;
+  }
+
+  async run(task: DelegationTask): Promise<DelegationResult> {
+    this.lastTask = task;
+    if (this.callbacks) {
+      if (this.callbacks.pid !== undefined) task.onSpawn?.(this.callbacks.pid);
+      if (this.callbacks.stdout !== undefined) task.onStdout?.(this.callbacks.stdout);
+      if (this.callbacks.stderr !== undefined) task.onStderr?.(this.callbacks.stderr);
+    }
+    return this.result;
+  }
+}
+
+function createRecordingRunLog() {
+  const calls = {
+    pid: null as number | null,
+    stdout: [] as string[],
+    stderr: [] as string[],
+    finish: null as { status: string; exitCode: number | null } | null,
+  };
+  const runLog: RunLog = {
+    id: 'test-id',
+    dir: '/test/dir',
+    setPid(pid) {
+      calls.pid = pid;
+    },
+    stdout(chunk) {
+      calls.stdout.push(chunk);
+    },
+    stderr(chunk) {
+      calls.stderr.push(chunk);
+    },
+    finish(status, exitCode) {
+      calls.finish = { status, exitCode };
+    },
+  };
+  return { runLog, calls };
+}
+
+describe('delegate stub-driver tests', () => {
+  const model = resolveModel('xai-grok/grok-4.5');
+  if (!model) throw new Error('model resolution failed');
+
+  it('prepends preamble when tools: true, passes untouched when tools: false', async () => {
+    const stubTrue = new StubDriver({ ok: true, response: 'ok', exitCode: 0 });
+    const { runLog: runLogTrue } = createRecordingRunLog();
+    await delegate(
+      {
+        model,
+        prompt: 'do work',
+        tools: true,
+        timeoutSec: 60,
+        cwd: '/test',
+        run: runLogTrue,
+      },
+      stubTrue,
+    );
+    expect(stubTrue.lastTask?.prompt).toBe(`${PREAMBLE_PIN}do work`);
+
+    const stubFalse = new StubDriver({ ok: true, response: 'ok', exitCode: 0 });
+    const { runLog: runLogFalse } = createRecordingRunLog();
+    await delegate(
+      {
+        model,
+        prompt: 'do work',
+        tools: false,
+        timeoutSec: 60,
+        cwd: '/test',
+        run: runLogFalse,
+      },
+      stubFalse,
+    );
+    expect(stubFalse.lastTask?.prompt).toBe('do work');
+  });
+
+  it('forwards stdout/stderr/spawn callbacks to RunLog', async () => {
+    const stub = new StubDriver(
+      { ok: true, response: 'ok', exitCode: 0 },
+      { pid: 999, stdout: 'out chunk', stderr: 'err chunk' },
+    );
+    const { runLog, calls } = createRecordingRunLog();
+
+    await delegate(
+      {
+        model,
+        prompt: 'test callbacks',
+        tools: true,
+        timeoutSec: 60,
+        cwd: '/test',
+        run: runLog,
+      },
+      stub,
+    );
+
+    expect(calls.pid).toBe(999);
+    expect(calls.stdout).toEqual(['out chunk']);
+    expect(calls.stderr).toEqual(['err chunk']);
+  });
+
+  it('maps finish status and exitCode correctly for all outcome kinds', async () => {
+    const outcomes: Array<{
+      result: DelegationResult;
+      expectedStatus: string;
+      expectedExitCode: number | null;
+    }> = [
+      {
+        result: { ok: true, response: 'all good', exitCode: 0 },
+        expectedStatus: 'done',
+        expectedExitCode: 0,
+      },
+      {
+        result: { ok: false, kind: 'timeout', message: 'Timed out', exitCode: null },
+        expectedStatus: 'timeout',
+        expectedExitCode: null,
+      },
+      {
+        result: { ok: false, kind: 'no-answer', message: 'Nonzero exit', exitCode: 1 },
+        expectedStatus: 'error',
+        expectedExitCode: 1,
+      },
+      {
+        result: { ok: false, kind: 'not-found', message: 'CLI not found', exitCode: null },
+        expectedStatus: 'error',
+        expectedExitCode: null,
+      },
+      {
+        result: { ok: false, kind: 'spawn', message: 'Spawn error', exitCode: null },
+        expectedStatus: 'error',
+        expectedExitCode: null,
+      },
+    ];
+
+    for (const { result, expectedStatus, expectedExitCode } of outcomes) {
+      const stub = new StubDriver(result);
+      const { runLog, calls } = createRecordingRunLog();
+      await delegate(
+        {
+          model,
+          prompt: 'test finish mapping',
+          tools: true,
+          timeoutSec: 60,
+          cwd: '/test',
+          run: runLog,
+        },
+        stub,
+      );
+
+      expect(calls.finish).toEqual({
+        status: expectedStatus,
+        exitCode: expectedExitCode,
+      });
+    }
+  });
+});

package/src/delegate.ts

@@ -0,0 +1,46 @@
+import type { AgentCliDriver, DelegationResult } from './driver.ts';
+import { getDriver } from './drivers.ts';
+import { backendModelId, type ResolvedModel } from './models.ts';
+import type { RunLog } from './runlog.ts';
+
+export interface DelegateOptions {
+  readonly model: ResolvedModel;
+  readonly prompt: string;
+  readonly tools: boolean;
+  readonly timeoutSec: number;
+  readonly cwd: string;
+  readonly run: RunLog;
+}
+
+export type DelegateOutcome = DelegationResult;
+
+const PREAMBLE =
+  'You are the sole executing agent for this task: do it yourself with your tools, now. ' +
+  'Never defer to, wait for, or claim to hand off to another agent or process — no one ' +
+  'else will act, and work not done in this run does not happen.\n\n';
+
+export async function delegate(
+  opts: DelegateOptions,
+  driver: AgentCliDriver = getDriver(opts.model.spec.backend),
+): Promise<DelegateOutcome> {
+  const effectivePrompt = opts.tools ? PREAMBLE + opts.prompt : opts.prompt;
+  const result = await driver.run({
+    prompt: effectivePrompt,
+    tools: opts.tools,
+    timeoutSec: opts.timeoutSec,
+    cwd: opts.cwd,
+    backendModel: backendModelId(opts.model) ?? opts.model.spec.backendModel,
+    effort: opts.model.effort,
+    onStdout: c => opts.run.stdout(c),
+    onStderr: c => opts.run.stderr(c),
+    onSpawn: pid => opts.run.setPid(pid),
+  });
+
+  if (result.ok) {
+    opts.run.finish('done', result.exitCode);
+  } else {
+    opts.run.finish(result.kind === 'timeout' ? 'timeout' : 'error', result.exitCode);
+  }
+
+  return result;
+}

package/src/driver.ts

@@ -0,0 +1,56 @@
+import type { AgyQuotaSnapshot } from '@aibridge/agy';
+import type { ClaudeQuotaSnapshot } from '@aibridge/claude';
+import type { CodexQuotaSnapshot } from '@aibridge/codex';
+import type { Effort } from './models.ts';
+
+export type Availability =
+  | { readonly ok: true; readonly version: string }
+  | { readonly ok: false; readonly error: string };
+
+export interface DelegationTask {
+  readonly prompt: string;
+  readonly tools: boolean;
+  readonly timeoutSec: number;
+  readonly cwd: string;
+  readonly backendModel: string | undefined;
+  readonly effort: Effort | undefined;
+  readonly onStdout?: (chunk: string) => void;
+  readonly onStderr?: (chunk: string) => void;
+  readonly onSpawn?: (pid: number) => void;
+}
+
+export type DelegationResult =
+  | { readonly ok: true; readonly response: string; readonly exitCode: number }
+  | {
+      readonly ok: false;
+      readonly kind: 'not-found' | 'spawn' | 'timeout' | 'no-answer';
+      readonly message: string;
+      readonly exitCode: number | null;
+    };
+
+export type QuotaSnapshot = AgyQuotaSnapshot | CodexQuotaSnapshot | ClaudeQuotaSnapshot;
+
+export interface ImageGenRequest {
+  readonly prompt: string;
+  readonly workDir: string;
+  readonly backendModel: string | undefined;
+  readonly effort: Effort | undefined;
+  readonly quality: string;
+  readonly size: { readonly w: number; readonly h: number } | undefined;
+  readonly imagePaths: readonly string[];
+  readonly timeoutSec: number;
+  readonly forceful: boolean;
+  readonly minBytes: number;
+}
+
+export type ImageResult =
+  | { readonly kind: 'ok'; readonly path: string; readonly bytes: number }
+  | { readonly kind: 'suspect' }
+  | { readonly kind: 'error'; readonly reason: string };
+
+export interface AgentCliDriver {
+  probe(): Promise<Availability>;
+  run(task: DelegationTask): Promise<DelegationResult>;
+  quota?(): Promise<QuotaSnapshot>;
+  generateImage?(req: ImageGenRequest): Promise<ImageResult>;
+}

package/src/drivers.ts

@@ -0,0 +1,44 @@
+import * as agy from '@aibridge/agy';
+import * as claude from '@aibridge/claude';
+import * as codex from '@aibridge/codex';
+import * as grok from '@aibridge/grok';
+import type { AgentCliDriver } from './driver.ts';
+import type { Backend } from './models.ts';
+
+const agyDriver: AgentCliDriver = {
+  probe: () => agy.probe(),
+  run: task => agy.run(task),
+  quota: () => agy.fetchAgyQuota(),
+};
+
+const grokDriver: AgentCliDriver = {
+  probe: () => grok.probe(),
+  run: task => grok.run(task),
+  generateImage: req => grok.generateImage(req),
+};
+
+const codexDriver: AgentCliDriver = {
+  probe: () => codex.probe(),
+  run: task => codex.run(task),
+  quota: () => codex.fetchCodexQuota(),
+  generateImage: req => codex.generateImage(req),
+};
+
+const claudeDriver: AgentCliDriver = {
+  probe: () => claude.probe(),
+  run: task => claude.run(task),
+  quota: () => claude.fetchClaudeQuota(),
+};
+
+const DRIVERS: Record<Backend, AgentCliDriver> = {
+  agy: agyDriver,
+  grok: grokDriver,
+  codex: codexDriver,
+  claude: claudeDriver,
+};
+
+export function getDriver(backend: Backend): AgentCliDriver {
+  const driver = DRIVERS[backend];
+  if (!driver) throw new Error(`Unknown backend "${backend}"`);
+  return driver;
+}

package/src/exitCode.test.ts

@@ -0,0 +1,44 @@
+import { ExitCode } from '@stricli/core';
+import { describe, expect, it } from 'vitest';
+import type { LocalContext } from './context.ts';
+import { normalizeExitCode } from './exitCode.ts';
+
+function createMockCtx(exitCode?: number): LocalContext {
+  return {
+    process: {
+      exitCode,
+    } as unknown as NodeJS.Process,
+  };
+}
+
+describe('normalizeExitCode', () => {
+  it('leaves undefined exitCode untouched', () => {
+    const ctx = createMockCtx(undefined);
+    normalizeExitCode(ctx);
+    expect(ctx.process.exitCode).toBeUndefined();
+  });
+
+  it.each([0, 1, 2, 3])('preserves valid contract exit code %i', code => {
+    const ctx = createMockCtx(code);
+    normalizeExitCode(ctx);
+    expect(ctx.process.exitCode).toBe(code);
+  });
+
+  it('maps ExitCode.InvalidArgument (-4) to 2', () => {
+    const ctx = createMockCtx(ExitCode.InvalidArgument);
+    normalizeExitCode(ctx);
+    expect(ctx.process.exitCode).toBe(2);
+  });
+
+  it('maps ExitCode.UnknownCommand (-5) to 2', () => {
+    const ctx = createMockCtx(ExitCode.UnknownCommand);
+    normalizeExitCode(ctx);
+    expect(ctx.process.exitCode).toBe(2);
+  });
+
+  it.each([-1, -2, -3, -6, -99, 4, 127])('maps other non-contract code %i to 1', code => {
+    const ctx = createMockCtx(code);
+    normalizeExitCode(ctx);
+    expect(ctx.process.exitCode).toBe(1);
+  });
+});

package/src/exitCode.ts

@@ -0,0 +1,24 @@
+import { ExitCode } from '@stricli/core';
+import type { LocalContext } from './context.ts';
+
+/**
+ * Stricli uses negative ExitCode values for parse/route failures.
+ * Our public contract is Unix-style: 0 ok, 1 op fail, 2 bad args, 3 quota refuse.
+ * Call after `run()`; never overwrite a code already set by an impl (run uses ??=).
+ */
+export function normalizeExitCode(ctx: LocalContext): void {
+  const code = ctx.process.exitCode;
+  if (typeof code !== 'number') return;
+  if (code === ExitCode.InvalidArgument || code === ExitCode.UnknownCommand) {
+    ctx.process.exitCode = 2;
+    return;
+  }
+  // Contract-space fallback: impls only ever set 0/1/2/3. Anything else on
+  // the process at this point is a stricli framework code (whatever its
+  // actual numeric value in this stricli version) → operational failure.
+  // Do NOT assume framework codes are negative — compare against the
+  // ExitCode constants and the contract space only.
+  if (code !== 0 && code !== 1 && code !== 2 && code !== 3) {
+    ctx.process.exitCode = 1;
+  }
+}

package/src/flagMapping.test.ts

@@ -0,0 +1,99 @@
+import { describe, expect, it, vi } from 'vitest';
+import type { LocalContext } from './context.ts';
+
+const mockPlanImpl = vi.fn();
+const mockSubagentImpl = vi.fn();
+
+vi.mock('./commands/plan/impl.ts', () => ({
+  default: function (this: LocalContext, ...args: unknown[]) {
+    return mockPlanImpl.call(this, ...args);
+  },
+}));
+
+vi.mock('./commands/subagent/impl.ts', () => ({
+  default: function (this: LocalContext, ...args: unknown[]) {
+    return mockSubagentImpl.call(this, ...args);
+  },
+}));
+
+// Must import app AFTER mocks
+const { runCli } = await import('./app.ts');
+
+function fakeCtx(): LocalContext {
+  return {
+    process: {
+      stdout: { write: () => true },
+      stderr: { write: () => true },
+      exitCode: undefined as number | undefined,
+      env: { ...process.env, NO_COLOR: '1' },
+      cwd: () => process.cwd(),
+    } as unknown as NodeJS.Process,
+  };
+}
+
+describe('flag mapping & defaults lock', () => {
+  it('plan command maps defaults correctly', async () => {
+    mockPlanImpl.mockReset();
+    const ctx = fakeCtx();
+    await runCli(ctx, ['plan', 'do something']);
+    expect(mockPlanImpl).toHaveBeenCalledTimes(1);
+    const [call] = mockPlanImpl.mock.calls;
+    expect(call).toBeDefined();
+    if (!call) return;
+    const [flags, prompt] = call;
+    expect(prompt).toBe('do something');
+    expect(flags).toEqual({
+      preflight: true,
+    });
+  });
+
+  it('plan command handles --no-preflight and --timeout', async () => {
+    mockPlanImpl.mockReset();
+    const ctx = fakeCtx();
+    await runCli(ctx, ['plan', '--no-preflight', '--timeout', '120', 'task']);
+    expect(mockPlanImpl).toHaveBeenCalledTimes(1);
+    const [call] = mockPlanImpl.mock.calls;
+    expect(call).toBeDefined();
+    if (!call) return;
+    const [flags, prompt] = call;
+    expect(prompt).toBe('task');
+    expect(flags).toEqual({
+      preflight: false,
+      timeout: 120,
+    });
+  });
+
+  it('subagent command maps defaults correctly', async () => {
+    mockSubagentImpl.mockReset();
+    const ctx = fakeCtx();
+    await runCli(ctx, ['subagent', 'hello agent']);
+    expect(mockSubagentImpl).toHaveBeenCalledTimes(1);
+    const [call] = mockSubagentImpl.mock.calls;
+    expect(call).toBeDefined();
+    if (!call) return;
+    const [flags, prompt] = call;
+    expect(prompt).toBe('hello agent');
+    expect(flags).toEqual({
+      tools: true,
+      preflight: true,
+      json: false,
+    });
+  });
+
+  it('subagent command handles --no-tools and --no-preflight', async () => {
+    mockSubagentImpl.mockReset();
+    const ctx = fakeCtx();
+    await runCli(ctx, ['subagent', '--no-tools', '--no-preflight', 'hello agent']);
+    expect(mockSubagentImpl).toHaveBeenCalledTimes(1);
+    const [call] = mockSubagentImpl.mock.calls;
+    expect(call).toBeDefined();
+    if (!call) return;
+    const [flags, prompt] = call;
+    expect(prompt).toBe('hello agent');
+    expect(flags).toEqual({
+      tools: false,
+      preflight: false,
+      json: false,
+    });
+  });
+});

package/src/index.ts

@@ -0,0 +1,37 @@
+export { app, runCli } from './app.ts';
+export { buildContext, type LocalContext } from './context.ts';
+export { type DelegateOptions, type DelegateOutcome, delegate } from './delegate.ts';
+export type { AgentCliDriver, DelegationResult, DelegationTask } from './driver.ts';
+export { getDriver } from './drivers.ts';
+export {
+  type Backend,
+  backendModelId,
+  DEFAULT_IMAGE_GEN,
+  DEFAULT_IMPLEMENTER,
+  DEFAULT_MODEL,
+  type Effort,
+  formatImageGenModelError,
+  formatUnknownModelError,
+  listModelHelpLines,
+  MODELS,
+  type ModelSpec,
+  type ResolvedModel,
+  resolveModel,
+  supportsImageGen,
+} from './models.ts';
+export { nonEmptyPrompt, positiveIntSeconds } from './parsers.ts';
+export {
+  evaluateAgyPreflight,
+  evaluateCodexPreflight,
+  type PreflightVerdict,
+  preflightCodex,
+  preflightModel,
+  renderPreflightRefusal,
+} from './quotaPreflight.ts';
+export {
+  listRuns,
+  type RunLog,
+  type RunMeta,
+  readRunLogs,
+  startRun,
+} from './runlog.ts';