@aibridge/cli 0.0.1

package/src/models.test.ts

@@ -0,0 +1,107 @@
+import { describe, expect, it } from 'vitest';
+import {
+  backendModelId,
+  formatImageGenModelError,
+  formatUnknownModelError,
+  listModelHelpLines,
+  resolveModel,
+  supportsImageGen,
+} from './models.ts';
+
+describe('models registry', () => {
+  it('resolves canonical slugs', () => {
+    const grok = resolveModel('xai-grok/grok-4.5');
+    expect(grok).toBeDefined();
+    expect(grok?.spec.slug).toBe('xai-grok/grok-4.5');
+    expect(grok?.effort).toBeUndefined();
+
+    const gemini = resolveModel('google-antigravity/gemini-3.6-flash');
+    expect(gemini).toBeDefined();
+    expect(gemini?.spec.slug).toBe('google-antigravity/gemini-3.6-flash');
+    expect(gemini?.effort).toBe('high');
+  });
+
+  it('rejects short aliases — canonical slugs only', () => {
+    for (const alias of ['grok', 'gemini', 'codex', 'sonnet', 'opus', 'gemini-3.6', 'gpt-oss']) {
+      expect(resolveModel(alias)).toBeUndefined();
+    }
+  });
+
+  it('resolves effort suffixes', () => {
+    const grokMedium = resolveModel('xai-grok/grok-4.5-medium');
+    expect(grokMedium?.spec.slug).toBe('xai-grok/grok-4.5');
+    expect(grokMedium?.effort).toBe('medium');
+
+    const sonnetMax = resolveModel('anthropic-claude/sonnet-max');
+    expect(sonnetMax?.spec.slug).toBe('anthropic-claude/sonnet');
+    expect(sonnetMax?.effort).toBe('max');
+  });
+
+  it('rejects unsupported efforts', () => {
+    const grokXhigh = resolveModel('xai-grok/grok-4.5-xhigh');
+    expect(grokXhigh).toBeUndefined();
+
+    const gptOssHigh = resolveModel('google-antigravity/gpt-oss-120b-medium-high');
+    expect(gptOssHigh).toBeUndefined();
+  });
+
+  it('handles unknown models', () => {
+    expect(resolveModel('nonexistent-model')).toBeUndefined();
+    const err = formatUnknownModelError('nonexistent-model');
+    expect(err).toContain('Unknown model "nonexistent-model".');
+  });
+
+  it('prioritizes exact matches over effort splitting', () => {
+    const gptOss = resolveModel('google-antigravity/gpt-oss-120b-medium');
+    expect(gptOss).toBeDefined();
+    expect(gptOss?.spec.slug).toBe('google-antigravity/gpt-oss-120b-medium');
+    expect(gptOss?.effort).toBeUndefined();
+  });
+
+  it('computes backendModelId correctly for agy vs others', () => {
+    const gemini = resolveModel('google-antigravity/gemini-3.6-flash');
+    if (!gemini) throw new Error('gemini resolution failed');
+    expect(backendModelId(gemini)).toBe('gemini-3.6-flash-high');
+
+    const geminiLow = resolveModel('google-antigravity/gemini-3.6-flash-low');
+    if (!geminiLow) throw new Error('geminiLow resolution failed');
+    expect(backendModelId(geminiLow)).toBe('gemini-3.6-flash-low');
+
+    const grok = resolveModel('xai-grok/grok-4.5');
+    if (!grok) throw new Error('grok resolution failed');
+    expect(backendModelId(grok)).toBe('grok-4.5');
+
+    const sonnet = resolveModel('anthropic-claude/sonnet');
+    if (!sonnet) throw new Error('sonnet resolution failed');
+    expect(backendModelId(sonnet)).toBe('sonnet');
+  });
+
+  it('marks only codex and grok seats as image-gen capable', () => {
+    const codex = resolveModel('openai-codex/gpt-5.6-sol');
+    const grok = resolveModel('xai-grok/grok-4.5');
+    const gemini = resolveModel('google-antigravity/gemini-3.6-flash');
+    if (!codex || !grok || !gemini) throw new Error('resolution failed');
+    expect(supportsImageGen(codex)).toBe(true);
+    expect(supportsImageGen(grok)).toBe(true);
+    expect(supportsImageGen(gemini)).toBe(false);
+  });
+
+  it('lists only image-capable seats when imageOnly', () => {
+    const lines = listModelHelpLines({ imageOnly: true }).join('\n');
+    expect(lines).toContain('xai-grok/grok-4.5');
+    expect(lines).toContain('openai-codex/gpt-5.6-sol');
+    expect(lines).not.toContain('google-antigravity/gemini-3.6-flash');
+  });
+
+  it('formats image-gen model errors with capable seats only', () => {
+    const gemini = resolveModel('google-antigravity/gemini-3.6-flash');
+    if (!gemini) throw new Error('gemini resolution failed');
+    const err = formatImageGenModelError('google-antigravity/gemini-3.6-flash', gemini);
+    expect(err).toContain('cannot generate images');
+    expect(err).toContain('backend "agy"');
+    expect(err).toContain('xai-grok/grok-4.5');
+    expect(err).toContain('openai-codex/gpt-5.6-sol');
+    const seatsSection = err.slice(err.indexOf('Image-gen seats'));
+    expect(seatsSection).not.toContain('google-antigravity/gemini-3.6-flash');
+  });
+});

package/src/models.ts

@@ -0,0 +1,159 @@
+/**
+ * Canonical model registry and resolution for aibridge.
+ *
+ * Models are registered by canonical, provider-qualified slug —
+ * `<vendor>-<cli>/<model>[-<effort>]`, e.g. `openai-codex/gpt-5.6-sol-high`.
+ * Canonical slugs only — no short aliases, by design.
+ */
+
+export type Backend = 'agy' | 'claude' | 'codex' | 'grok';
+export type Effort = 'low' | 'medium' | 'high' | 'xhigh' | 'max';
+
+export interface ModelSpec {
+  readonly slug: string; // canonical, effort-less
+  readonly backend: Backend;
+  readonly backendModel: string | undefined; // undefined = CLI default
+  readonly efforts: readonly Effort[] | null;
+  readonly defaultEffort?: Effort; // only when backend REQUIRES one (agy gemini)
+  readonly brief: string;
+}
+
+export interface ResolvedModel {
+  readonly spec: ModelSpec;
+  readonly effort: Effort | undefined;
+}
+
+export const MODELS: Record<string, ModelSpec> = {
+  'xai-grok/grok-4.5': {
+    slug: 'xai-grok/grok-4.5',
+    backend: 'grok',
+    backendModel: 'grok-4.5',
+    efforts: ['low', 'medium', 'high'],
+    brief: 'xAI Grok 4.5 via grok CLI — default for plan & review; off-budget',
+  },
+  'google-antigravity/gemini-3.6-flash': {
+    slug: 'google-antigravity/gemini-3.6-flash',
+    backend: 'agy',
+    backendModel: 'gemini-3.6-flash',
+    efforts: ['low', 'medium', 'high'],
+    defaultEffort: 'high',
+    brief: 'Google Gemini 3.6 Flash via agy — default for implement; off-budget',
+  },
+  'google-antigravity/claude-sonnet-4-6': {
+    slug: 'google-antigravity/claude-sonnet-4-6',
+    backend: 'agy',
+    backendModel: 'claude-sonnet-4-6',
+    efforts: null,
+    brief: 'Claude Sonnet 4.6 (thinking) via agy — off-budget',
+  },
+  'google-antigravity/claude-opus-4-6-thinking': {
+    slug: 'google-antigravity/claude-opus-4-6-thinking',
+    backend: 'agy',
+    backendModel: 'claude-opus-4-6-thinking',
+    efforts: null,
+    brief: 'Claude Opus 4.6 (thinking) via agy — off-budget heavyweight',
+  },
+  'google-antigravity/gpt-oss-120b-medium': {
+    slug: 'google-antigravity/gpt-oss-120b-medium',
+    backend: 'agy',
+    backendModel: 'gpt-oss-120b-medium',
+    efforts: null,
+    brief: 'GPT-OSS 120B (medium) via agy — off-budget',
+  },
+  'openai-codex/gpt-5.6-sol': {
+    slug: 'openai-codex/gpt-5.6-sol',
+    backend: 'codex',
+    backendModel: 'gpt-5.6-sol',
+    efforts: ['low', 'medium', 'high', 'xhigh'],
+    brief: 'OpenAI Codex gpt-5.6-sol via codex CLI',
+  },
+  'anthropic-claude/sonnet': {
+    slug: 'anthropic-claude/sonnet',
+    backend: 'claude',
+    backendModel: 'sonnet',
+    efforts: ['low', 'medium', 'high', 'xhigh', 'max'],
+    brief: 'Claude Sonnet via claude CLI — bills your Claude subscription',
+  },
+  'anthropic-claude/opus': {
+    slug: 'anthropic-claude/opus',
+    backend: 'claude',
+    backendModel: 'opus',
+    efforts: ['low', 'medium', 'high', 'xhigh', 'max'],
+    defaultEffort: 'high',
+    brief: 'Claude Opus via claude CLI (default effort: high) — bills subscription',
+  },
+} as const satisfies Record<string, ModelSpec>;
+
+export const DEFAULT_MODEL = 'xai-grok/grok-4.5';
+export const DEFAULT_IMPLEMENTER = 'google-antigravity/gemini-3.6-flash';
+export const DEFAULT_IMAGE_GEN = 'openai-codex/gpt-5.6-sol';
+
+const IMAGE_GEN_BACKENDS: ReadonlySet<Backend> = new Set(['codex', 'grok']);
+
+export function supportsImageGen(resolved: ResolvedModel): boolean {
+  return IMAGE_GEN_BACKENDS.has(resolved.spec.backend);
+}
+
+const EFFORTS_SET: ReadonlySet<string> = new Set<Effort>(['low', 'medium', 'high', 'xhigh', 'max']);
+
+export function resolveModel(input: string): ResolvedModel | undefined {
+  if (MODELS[input]) {
+    const spec = MODELS[input];
+    return { spec, effort: spec.defaultEffort };
+  }
+
+  const lastDashIdx = input.lastIndexOf('-');
+  if (lastDashIdx > 0) {
+    const prefix = input.slice(0, lastDashIdx);
+    const token = input.slice(lastDashIdx + 1);
+
+    const spec = MODELS[prefix];
+
+    if (
+      spec &&
+      EFFORTS_SET.has(token) &&
+      spec.efforts &&
+      (spec.efforts as readonly string[]).includes(token)
+    ) {
+      return { spec, effort: token as Effort };
+    }
+  }
+
+  return undefined;
+}
+
+export function backendModelId(resolved: ResolvedModel): string | undefined {
+  if (!resolved.spec.backendModel) {
+    return undefined;
+  }
+  if (resolved.spec.backend === 'agy') {
+    const effort = resolved.effort ?? resolved.spec.defaultEffort;
+    if (effort) {
+      return `${resolved.spec.backendModel}-${effort}`;
+    }
+  }
+  return resolved.spec.backendModel;
+}
+
+export function listModelHelpLines(opts: { readonly imageOnly?: boolean } = {}): string[] {
+  const lines: string[] = [];
+  for (const [slug, spec] of Object.entries(MODELS)) {
+    if (opts.imageOnly && !IMAGE_GEN_BACKENDS.has(spec.backend)) continue;
+    lines.push(`  ${slug}`);
+    lines.push(`    ${spec.brief}`);
+  }
+  return lines;
+}
+
+export function formatUnknownModelError(input: string): string {
+  const lines = [`Unknown model "${input}".`, 'Available models:', ...listModelHelpLines()];
+  return lines.join('\n');
+}
+
+export function formatImageGenModelError(input: string, resolved: ResolvedModel): string {
+  return [
+    `Model "${input}" (${resolved.spec.slug}) cannot generate images — backend "${resolved.spec.backend}" has no image path.`,
+    'Image-gen seats (canonical slug):',
+    ...listModelHelpLines({ imageOnly: true }),
+  ].join('\n');
+}

package/src/parsers.ts

@@ -0,0 +1,24 @@
+/**
+ * stricli `parse` functions (string -> T). Throwing inside one makes stricli
+ * reject the argument up-front with a clean, flag-named error — instead of
+ * silently letting a bad value (NaN, Infinity, "") flow into an impl where it
+ * gets masked or, worse, breaks `setTimeout`.
+ */
+
+export function positiveIntSeconds(input: string): number {
+  const n = Number(input);
+  if (!Number.isInteger(n) || n <= 0) {
+    throw new RangeError(`expected a positive whole number of seconds, got "${input}"`);
+  }
+  if (n > 86_400) {
+    throw new RangeError(`timeout too large: ${n}s (max 86400 = 24h)`);
+  }
+  return n;
+}
+
+export function nonEmptyPrompt(input: string): string {
+  if (input.trim().length === 0) {
+    throw new Error('prompt must not be empty');
+  }
+  return input;
+}

package/src/quotaPreflight.test.ts

@@ -0,0 +1,178 @@
+import assert from 'node:assert/strict';
+import type { AgyQuotaSnapshot } from '@aibridge/agy';
+import type { CodexQuotaSnapshot } from '@aibridge/codex';
+import { test } from 'vitest';
+import { evaluateAgyPreflight, evaluateCodexPreflight } from './quotaPreflight.ts';
+
+test('evaluateAgyPreflight: exhausted model returns ok:false with resetTime', () => {
+  const snapshot: AgyQuotaSnapshot = {
+    fetchedAt: '2024-01-01T12:00:00Z',
+    groups: [],
+    models: [
+      {
+        modelId: 'test-model-id',
+        label: 'Gemini 3.5 Flash (High)',
+        remainingFraction: 0,
+        exhausted: true,
+        resetTime: '2024-01-02T12:00:00Z',
+      },
+    ],
+  };
+
+  const result = evaluateAgyPreflight(snapshot, 'Gemini 3.5 Flash (High)');
+
+  assert.deepEqual(result, {
+    ok: false,
+    message: 'agy model "Gemini 3.5 Flash (High)" is quota-exhausted',
+    resetAt: '2024-01-02T12:00:00Z',
+  });
+});
+
+test('evaluateAgyPreflight: exhausted model with undefined resetTime falls back to Gemini group', () => {
+  const snapshot: AgyQuotaSnapshot = {
+    fetchedAt: '2024-01-01T12:00:00Z',
+    groups: [
+      {
+        displayName: 'Gemini 3.5 Flash',
+        description: undefined,
+        buckets: [
+          {
+            bucketId: 'weekly',
+            displayName: 'weekly',
+            window: 'weekly',
+            remainingFraction: 0,
+            resetTime: '2024-01-08T12:00:00Z',
+          },
+          {
+            bucketId: '5h',
+            displayName: '5h',
+            window: '5h',
+            remainingFraction: 0,
+            resetTime: '2024-01-01T17:00:00Z',
+          },
+        ],
+      },
+    ],
+    models: [
+      {
+        modelId: 'test-model-id',
+        label: 'Gemini 3.5 Flash (High)',
+        remainingFraction: 0,
+        exhausted: true,
+        resetTime: undefined,
+      },
+    ],
+  };
+
+  const result = evaluateAgyPreflight(snapshot, 'Gemini 3.5 Flash (High)');
+
+  assert.strictEqual(result.ok, false);
+  assert.strictEqual(result.message, 'agy model "Gemini 3.5 Flash (High)" is quota-exhausted');
+  assert.strictEqual(result.resetAt, '2024-01-01T17:00:00Z');
+});
+
+test('evaluateAgyPreflight: healthy model returns ok:true', () => {
+  const snapshot: AgyQuotaSnapshot = {
+    fetchedAt: '2024-01-01T12:00:00Z',
+    groups: [],
+    models: [
+      {
+        modelId: 'test-model-id',
+        label: 'Gemini 3.5 Flash (Low)',
+        remainingFraction: 0.5,
+        exhausted: false,
+        resetTime: undefined,
+      },
+    ],
+  };
+
+  const result = evaluateAgyPreflight(snapshot, 'Gemini 3.5 Flash (Low)');
+
+  assert.deepEqual(result, { ok: true });
+});
+
+test('evaluateAgyPreflight: model not found returns ok:true with warning', () => {
+  const snapshot: AgyQuotaSnapshot = {
+    fetchedAt: '2024-01-01T12:00:00Z',
+    groups: [],
+    models: [],
+  };
+
+  const result = evaluateAgyPreflight(snapshot, 'NonExistent Model');
+
+  assert.strictEqual(result.ok, true);
+  assert.strictEqual(result.warning, 'model "NonExistent Model" not in quota snapshot; proceeding');
+});
+
+test('evaluateCodexPreflight: limitReached returns ok:false', () => {
+  const snapshot: CodexQuotaSnapshot = {
+    fetchedAt: '2024-01-01T12:00:00Z',
+    planType: 'pro',
+    limitReached: true,
+    windows: [
+      {
+        window: '5h',
+        usedPercent: 100,
+        resetAt: '2024-01-01T17:00:00Z',
+      },
+    ],
+  };
+
+  const result = evaluateCodexPreflight(snapshot);
+
+  assert.deepEqual(result, {
+    ok: false,
+    message: 'codex quota limit reached',
+    resetAt: '2024-01-01T17:00:00Z',
+  });
+});
+
+test('evaluateCodexPreflight: window at usedPercent 100 returns ok:false', () => {
+  const snapshot: CodexQuotaSnapshot = {
+    fetchedAt: '2024-01-01T12:00:00Z',
+    planType: 'pro',
+    limitReached: false,
+    windows: [
+      {
+        window: '5h',
+        usedPercent: 100,
+        resetAt: '2024-01-01T17:00:00Z',
+      },
+      {
+        window: 'weekly',
+        usedPercent: 50,
+        resetAt: '2024-01-08T12:00:00Z',
+      },
+    ],
+  };
+
+  const result = evaluateCodexPreflight(snapshot);
+
+  assert.strictEqual(result.ok, false);
+  assert.strictEqual(result.message, 'codex quota limit reached');
+  assert.strictEqual(result.resetAt, '2024-01-01T17:00:00Z');
+});
+
+test('evaluateCodexPreflight: healthy (77% used) returns ok:true', () => {
+  const snapshot: CodexQuotaSnapshot = {
+    fetchedAt: '2024-01-01T12:00:00Z',
+    planType: 'pro',
+    limitReached: false,
+    windows: [
+      {
+        window: '5h',
+        usedPercent: 77,
+        resetAt: '2024-01-01T17:00:00Z',
+      },
+      {
+        window: 'weekly',
+        usedPercent: 50,
+        resetAt: '2024-01-08T12:00:00Z',
+      },
+    ],
+  };
+
+  const result = evaluateCodexPreflight(snapshot);
+
+  assert.deepEqual(result, { ok: true });
+});

package/src/quotaPreflight.ts

@@ -0,0 +1,103 @@
+import { type AgyQuotaSnapshot, fetchAgyQuota, findModelQuota } from '@aibridge/agy';
+import { type CodexQuotaSnapshot, fetchCodexQuota } from '@aibridge/codex';
+import { backendModelId, type ResolvedModel } from './models.ts';
+
+export type PreflightVerdict =
+  | { readonly ok: true; readonly warning?: string }
+  | { readonly ok: false; readonly message: string; readonly resetAt: string | undefined };
+
+export function evaluateAgyPreflight(
+  snapshot: AgyQuotaSnapshot,
+  backendModel: string,
+): PreflightVerdict {
+  const quota = findModelQuota(snapshot, backendModel);
+
+  if (!quota) {
+    return { ok: true, warning: `model "${backendModel}" not in quota snapshot; proceeding` };
+  }
+
+  if (quota.exhausted) {
+    let resetAt = quota.resetTime;
+    if (!resetAt) {
+      for (const group of snapshot.groups) {
+        if (group.displayName.includes('Gemini')) {
+          for (const bucket of group.buckets) {
+            if (bucket.resetTime) {
+              if (!resetAt || new Date(bucket.resetTime).getTime() < new Date(resetAt).getTime()) {
+                resetAt = bucket.resetTime;
+              }
+            }
+          }
+        }
+      }
+    }
+    return { ok: false, message: `agy model "${backendModel}" is quota-exhausted`, resetAt };
+  }
+
+  return { ok: true };
+}
+
+export function evaluateCodexPreflight(snapshot: CodexQuotaSnapshot): PreflightVerdict {
+  if (snapshot.limitReached) {
+    const resetAt = snapshot.windows.find(w => w.resetAt)?.resetAt;
+    return { ok: false, message: 'codex quota limit reached', resetAt };
+  }
+
+  const exhaustedWindow = snapshot.windows.find(w => w.usedPercent >= 100);
+  if (exhaustedWindow) {
+    return { ok: false, message: 'codex quota limit reached', resetAt: exhaustedWindow.resetAt };
+  }
+
+  return { ok: true };
+}
+
+export async function preflightModel(resolved: ResolvedModel): Promise<PreflightVerdict> {
+  if (resolved.spec.backend === 'codex') {
+    return preflightCodex();
+  }
+
+  if (resolved.spec.backend !== 'agy') {
+    return { ok: true };
+  }
+
+  try {
+    const snapshot = await fetchAgyQuota();
+    const modelId = backendModelId(resolved) ?? '';
+    return evaluateAgyPreflight(snapshot, modelId);
+  } catch (err) {
+    return {
+      ok: true,
+      warning: `quota preflight failed (${(err as Error).message}); proceeding`,
+    };
+  }
+}
+
+export async function preflightCodex(): Promise<PreflightVerdict> {
+  try {
+    const snapshot = await fetchCodexQuota();
+    return evaluateCodexPreflight(snapshot);
+  } catch (err) {
+    return {
+      ok: true,
+      warning: `quota preflight failed (${(err as Error).message}); proceeding`,
+    };
+  }
+}
+
+function formatReset(resetTime: string | undefined): string {
+  if (!resetTime) return '-';
+  const ms = new Date(resetTime).getTime() - Date.now();
+  if (Number.isNaN(ms)) return resetTime;
+  if (ms <= 0) return 'now';
+  const mins = Math.round(ms / 60_000);
+  const rel = mins < 60 ? `${mins}m` : `${Math.floor(mins / 60)}h${mins % 60}m`;
+  return `${new Date(resetTime).toLocaleTimeString()} (in ${rel})`;
+}
+
+export function renderPreflightRefusal(
+  cmd: string,
+  verdict: { message: string; resetAt: string | undefined },
+): string {
+  const resetClause = verdict.resetAt ? ` Resets ${formatReset(verdict.resetAt)}.` : '';
+  return `aibridge ${cmd}: refusing — ${verdict.message}.${resetClause} Use --no-preflight to override, or a claude-backend fallback (subagent --model sonnet|opus — bills the Claude subscription).`;
+}