@ai-devkit/agent-manager 0.28.1 → 0.30.0

package/src/__tests__/providers/pi/durable/PiPrintAgentService.test.ts

@@ -0,0 +1,69 @@
+import { describe, expect, it, vi } from 'vitest';
+const SESSION = '22222222-2222-4222-8222-222222222222';
+const base = { id: 'id', name: 'reviewer', provider: 'pi', providerSessionId: SESSION, sessionHealth: 'uninitialized' };
+
+describe('PiPrintAgentService', () => {
+    it('probes before provider-aware create', async () => {
+        const api = await import('../../../../index.js') as Record<string, unknown>; expect(api).toHaveProperty('PiPrintAgentService');
+        const probe = { validate: vi.fn() }; const repository = { create: vi.fn().mockResolvedValue(base), list: vi.fn() }; const runner = { run: vi.fn() };
+        const Service = api.PiPrintAgentService as new (options: unknown) => any;
+        await new Service({ repository, probe, runner }).create({ name: 'reviewer', cwd: '/project' });
+        expect(probe.validate).toHaveBeenCalledOnce(); expect(repository.create).toHaveBeenCalledWith({ name: 'reviewer', cwd: '/project', provider: 'pi' });
+    });
+
+    it('records successful first and resumed sends', async () => {
+        const api = await import('../../../../index.js') as Record<string, unknown>;
+        const repository = { list: vi.fn(), resolve: vi.fn().mockResolvedValue(base), acquireRun: vi.fn()
+            .mockResolvedValueOnce({ agent: base, token: 'one' }).mockResolvedValueOnce({ agent: { ...base, sessionHealth: 'healthy' }, token: 'two' }),
+            recordProviderProcess: vi.fn(), completeRun: vi.fn() };
+        const runner = { run: vi.fn(async (request) => { await request.onSpawn({ pid: 42, startedAt: 'start' }); return { sessionId: SESSION, result: 'answer', messages: ['answer'], exitCode: 0 }; }) };
+        const Service = api.PiPrintAgentService as new (options: unknown) => any; const service = new Service({ repository, probe: { validate: vi.fn() }, runner });
+        await service.send('reviewer', 'first'); await service.send('reviewer', 'later');
+        expect(repository.completeRun).toHaveBeenCalledWith('id', 'one', expect.objectContaining({ status: 'succeeded', sessionHealth: 'healthy' }));
+    });
+
+    it('records mismatches and rejects missing and ambiguous records', async () => {
+        const api = await import('../../../../index.js') as Record<string, unknown>; const ErrorType = api.PiPrintError as new (message: string, code: string) => Error;
+        const completeRun = vi.fn(); const repository = { list: vi.fn(), resolve: vi.fn().mockResolvedValue(base), acquireRun: vi.fn().mockResolvedValue({ agent: base, token: 'one' }), recordProviderProcess: vi.fn(), completeRun };
+        const Service = api.PiPrintAgentService as new (options: unknown) => any;
+        await expect(new Service({ repository, probe: { validate: vi.fn() }, runner: { run: vi.fn().mockRejectedValue(new ErrorType('bad', 'PI_SESSION_MISMATCH')) } }).send('reviewer', 'x'))
+            .rejects.toMatchObject({ code: 'PI_SESSION_MISMATCH' });
+        expect(completeRun).toHaveBeenCalledWith('id', 'one', expect.objectContaining({ sessionHealth: 'mismatch' }));
+        const earlyRepository = { ...repository, resolve: vi.fn().mockResolvedValueOnce(null).mockResolvedValueOnce([base, base]), acquireRun: vi.fn() };
+        const early = new Service({ repository: earlyRepository, probe: { validate: vi.fn() }, runner: { run: vi.fn() } });
+        await expect(early.send('missing', 'x')).rejects.toMatchObject({ code: 'DURABLE_AGENT_NOT_FOUND' });
+        await expect(early.send('many', 'x')).rejects.toMatchObject({ code: 'PI_UNSUPPORTED' });
+    });
+
+    it('rejects a non-Pi target without acquiring or mutating it', async () => {
+        const api = await import('../../../../index.js') as Record<string, unknown>;
+        const Service = api.PiPrintAgentService as new (options: unknown) => any;
+        const repository = {
+            resolve: vi.fn().mockResolvedValue({ ...base, provider: 'claude' }),
+            acquireRun: vi.fn(), recordProviderProcess: vi.fn(), completeRun: vi.fn(),
+        };
+
+        await expect(new Service({ repository, probe: { validate: vi.fn() }, runner: { run: vi.fn() } })
+            .send('reviewer', 'x')).rejects.toMatchObject({ code: 'PI_UNSUPPORTED' });
+        expect(repository.acquireRun).not.toHaveBeenCalled();
+        expect(repository.completeRun).not.toHaveBeenCalled();
+    });
+
+    it('does not turn a successful completion write failure into a second completion', async () => {
+        const api = await import('../../../../index.js') as Record<string, unknown>;
+        const Service = api.PiPrintAgentService as new (options: unknown) => any;
+        const completionFailure = new Error('completion failed');
+        const repository = {
+            resolve: vi.fn().mockResolvedValue(base),
+            acquireRun: vi.fn().mockResolvedValue({ agent: base, token: 'one' }),
+            recordProviderProcess: vi.fn(), completeRun: vi.fn().mockRejectedValue(completionFailure),
+        };
+        const runner = { run: vi.fn().mockResolvedValue({
+            sessionId: SESSION, result: 'answer', messages: ['answer'], exitCode: 0,
+        }) };
+
+        await expect(new Service({ repository, probe: { validate: vi.fn() }, runner })
+            .send('reviewer', 'x')).rejects.toBe(completionFailure);
+        expect(repository.completeRun).toHaveBeenCalledOnce();
+    });
+});

package/src/__tests__/providers/pi/durable/PiPrintProtocol.test.ts

@@ -0,0 +1,33 @@
+import { describe, expect, it } from 'vitest';
+import { buildPiPrintArgs, readPiAssistantText, readPiSessionId } from '../../../../providers/pi/durable/PiPrintProtocol.js';
+
+const SESSION = '22222222-2222-4222-8222-222222222222';
+
+describe('Pi print pure protocol mapping', () => {
+    it('maps first and resumed runs to exact documented arguments', () => {
+        expect(buildPiPrintArgs(SESSION, true)).toEqual(['--mode', 'json', '--session-id', SESSION]);
+        expect(buildPiPrintArgs(SESSION, false)).toEqual(['--mode', 'json', '--session', SESSION]);
+    });
+
+    it('accepts one expected UUID and rejects invalid, duplicate, and mismatched identities', () => {
+        expect(readPiSessionId({ id: SESSION }, null, SESSION)).toBe(SESSION);
+        expect(() => readPiSessionId({}, null, SESSION)).toThrowError(expect.objectContaining({ code: 'PI_PROTOCOL' }));
+        expect(() => readPiSessionId({ id: [SESSION] }, null, SESSION))
+            .toThrowError(expect.objectContaining({ code: 'PI_PROTOCOL' }));
+        expect(() => readPiSessionId({ id: SESSION }, SESSION, SESSION)).toThrowError(expect.objectContaining({ code: 'PI_PROTOCOL' }));
+        expect(() => readPiSessionId({ id: '33333333-3333-4333-8333-333333333333' }, null, SESSION))
+            .toThrowError(expect.objectContaining({ code: 'PI_SESSION_MISMATCH' }));
+    });
+
+    it('extracts only non-empty completed assistant text', () => {
+        expect(readPiAssistantText({ type: 'future' })).toBeNull();
+        expect(readPiAssistantText({ type: 'message_end' })).toBeNull();
+        expect(readPiAssistantText({ type: 'message_end', message: [] })).toBeNull();
+        expect(readPiAssistantText({ type: 'message_end', message: { role: 'user', content: 'no' } })).toBeNull();
+        expect(readPiAssistantText({ type: 'message_end', message: { role: 'assistant', content: ' ' } })).toBeNull();
+        expect(readPiAssistantText({ type: 'message_end', message: { role: 'assistant', content: 'answer' } })).toBe('answer');
+        expect(readPiAssistantText({ type: 'message_end', message: { role: 'assistant', content: null } })).toBeNull();
+        expect(readPiAssistantText({ type: 'message_end', message: { role: 'assistant', content: [null, [], { type: 'thinking' }] } })).toBeNull();
+        expect(readPiAssistantText({ type: 'message_end', message: { role: 'assistant', content: [{ type: 'text', text: 'a' }, { type: 'text', text: 1 }, { type: 'text', text: 'b' }] } })).toBe('ab');
+    });
+});

package/src/__tests__/providers/pi/durable/PiPrintRunner.test.ts

@@ -0,0 +1,107 @@
+import { EventEmitter } from 'node:events';
+import { PassThrough, Writable } from 'node:stream';
+import { describe, expect, it, vi } from 'vitest';
+import type { PiDurableAgent } from '../../../../index.js';
+
+const SESSION = '22222222-2222-4222-8222-222222222222';
+function agent(sessionHealth: PiDurableAgent['sessionHealth'] = 'uninitialized'): PiDurableAgent {
+    return { id: '11111111-1111-4111-8111-111111111111', name: 'reviewer', provider: 'pi', mode: 'durable',
+        cwd: '/project', providerSessionId: SESSION, state: 'running', sessionHealth, createdAt: '',
+        updatedAt: '', lastActiveAt: null, lastResult: null, activeRun: null };
+}
+function fakeSpawn(lines: string[], exitCode = 0) {
+    const promptChunks: Buffer[] = [];
+    const child = new EventEmitter() as any;
+    child.pid = 4242; child.stdout = new PassThrough(); child.stderr = new PassThrough(); child.kill = vi.fn();
+    child.stdin = new Writable({
+        write(chunk, _encoding, callback) { promptChunks.push(Buffer.from(chunk)); callback(); },
+        final(callback) { child.stdout.end(lines.join('\n')); queueMicrotask(() => child.emit('close', exitCode, null)); callback(); },
+    });
+    return { child, spawn: vi.fn(() => child), promptChunks };
+}
+function events(session = SESSION): string[] { return [
+    JSON.stringify({ type: 'session', version: 3, id: session, cwd: '/project' }),
+    JSON.stringify({ type: 'message_end', message: { role: 'assistant', content: [{ type: 'text', text: 'first' }] } }),
+    JSON.stringify({ type: 'message_end', message: { role: 'assistant', content: [{ type: 'thinking', thinking: 'hidden' }, { type: 'text', text: 'final' }] } }),
+    JSON.stringify({ type: 'agent_end', messages: [] }), '',
+]; }
+async function runner(fixture: ReturnType<typeof fakeSpawn>, maxLineBytes?: number) {
+    const api = await import('../../../../index.js') as Record<string, unknown>;
+    expect(api).toHaveProperty('PiPrintRunner');
+    const Runner = api.PiPrintRunner as new (options: unknown) => any;
+    return new Runner({ spawn: fixture.spawn, maxLineBytes, processInspector: { getIdentity: () => ({ pid: 4242, startedAt: 'start' }) } });
+}
+
+describe('PiPrintRunner', () => {
+    it('binds a first session and returns the last completed assistant text', async () => {
+        const fixture = fakeSpawn(events()); const instance = await runner(fixture); const order: string[] = [];
+        const result = await instance.run({ agent: agent(), prompt: 'secret', executable: 'fake-pi',
+            onSpawn: async () => { expect(fixture.promptChunks).toHaveLength(0); order.push('spawn'); } });
+        expect(order).toEqual(['spawn']);
+        expect(fixture.spawn).toHaveBeenCalledWith('fake-pi', ['--mode', 'json', '--session-id', SESSION], expect.objectContaining({ cwd: '/project', shell: false }));
+        expect(Buffer.concat(fixture.promptChunks).toString()).toBe('secret');
+        expect(result).toEqual({ sessionId: SESSION, result: 'final', messages: ['first', 'final'], exitCode: 0 });
+    });
+
+    it('resumes the exact stored session and rejects mismatch', async () => {
+        const fixture = fakeSpawn(events('33333333-3333-4333-8333-333333333333'));
+        await expect((await runner(fixture)).run({ agent: agent('healthy'), prompt: 'later', onSpawn: vi.fn() }))
+            .rejects.toMatchObject({ code: 'PI_SESSION_MISMATCH' });
+        expect(fixture.spawn.mock.calls[0]![1]).toEqual(['--mode', 'json', '--session', SESSION]);
+    });
+
+    it.each([
+        ['malformed', ['{bad\n'], 'PI_PROTOCOL'], ['non-object', ['[]\n'], 'PI_PROTOCOL'],
+        ['truncated', ['{}'], 'PI_PROTOCOL'], ['missing session', [JSON.stringify({ type: 'agent_end' }), ''], 'PI_PROTOCOL'],
+        ['missing result', [JSON.stringify({ type: 'session', id: SESSION }), JSON.stringify({ type: 'agent_end' }), ''], 'PI_RESULT_MISSING'],
+        ['missing end', [JSON.stringify({ type: 'session', id: SESSION }), JSON.stringify({ type: 'message_end', message: { role: 'assistant', content: [{ type: 'text', text: 'x' }] } }), ''], 'PI_PROTOCOL'],
+    ])('rejects %s output', async (_name, lines, code) => {
+        await expect((await runner(fakeSpawn(lines as string[]))).run({ agent: agent(), prompt: 'x', onSpawn: vi.fn() }))
+            .rejects.toMatchObject({ code });
+    });
+
+    it('rejects oversized output, failed processes, and unverifiable identities', async () => {
+        await expect((await runner(fakeSpawn(['x'.repeat(20)]), 10)).run({ agent: agent(), prompt: 'x', onSpawn: vi.fn() }))
+            .rejects.toMatchObject({ code: 'PI_PROTOCOL' });
+        await expect((await runner(fakeSpawn(events(), 1))).run({ agent: agent(), prompt: 'x', onSpawn: vi.fn() }))
+            .rejects.toMatchObject({ code: 'PI_PROCESS' });
+        const fixture = fakeSpawn([]); const api = await import('../../../../index.js') as Record<string, unknown>;
+        const Runner = api.PiPrintRunner as new (options: unknown) => any;
+        await expect(new Runner({ spawn: fixture.spawn, processInspector: { getIdentity: () => null } }).run({ agent: agent(), prompt: 'x', onSpawn: vi.fn() }))
+            .rejects.toMatchObject({ code: 'PI_PROCESS' });
+        expect(fixture.child.kill).toHaveBeenCalledOnce();
+    });
+
+    it('rejects invalid and duplicate session identities', async () => {
+        for (const lines of [
+            [JSON.stringify({ type: 'session', id: 'bad' }), ''],
+            [JSON.stringify({ type: 'session', id: SESSION }), JSON.stringify({ type: 'session', id: SESSION }), ''],
+        ]) await expect((await runner(fakeSpawn(lines))).run({ agent: agent(), prompt: 'x', onSpawn: vi.fn(), onSession: vi.fn() }))
+            .rejects.toMatchObject({ code: 'PI_PROTOCOL' });
+    });
+
+    it('kills on spawn persistence failure', async () => {
+        const spawnFailure = fakeSpawn([]); const failure = new Error('cannot persist');
+        await expect((await runner(spawnFailure)).run({ agent: agent(), prompt: 'x', onSpawn: vi.fn().mockRejectedValue(failure), onSession: vi.fn() })).rejects.toBe(failure);
+        expect(spawnFailure.child.kill).toHaveBeenCalledOnce();
+    });
+
+    it('classifies spawn errors and a missing PID as process failures', async () => {
+        const errored = fakeSpawn([]);
+        errored.child.stdin = new Writable({ write(_chunk, _encoding, callback) { callback(); }, final(callback) { queueMicrotask(() => errored.child.emit('error', new Error('spawn'))); callback(); } });
+        await expect((await runner(errored)).run({ agent: agent(), prompt: 'x', onSpawn: vi.fn(), onSession: vi.fn() })).rejects.toMatchObject({ code: 'PI_PROCESS' });
+        const missing = fakeSpawn([]); missing.child.pid = undefined;
+        await expect((await runner(missing)).run({ agent: agent(), prompt: 'x', onSpawn: vi.fn(), onSession: vi.fn() })).rejects.toMatchObject({ code: 'PI_PROCESS' });
+        expect(missing.child.kill).toHaveBeenCalledOnce();
+    });
+
+    it('accepts string assistant content and ignores empty or unrelated messages', async () => {
+        const lines = [JSON.stringify({ type: 'session', id: SESSION }), JSON.stringify({ type: 'future' }),
+            JSON.stringify({ type: 'message_end', message: { role: 'user', content: 'ignored' } }),
+            JSON.stringify({ type: 'message_end', message: { role: 'assistant', content: ' ' } }),
+            JSON.stringify({ type: 'message_end', message: { role: 'assistant', content: 'answer' } }),
+            JSON.stringify({ type: 'agent_end' }), ''];
+        await expect((await runner(fakeSpawn(lines))).run({ agent: agent(), prompt: 'x', onSpawn: vi.fn(), onSession: vi.fn() }))
+            .resolves.toMatchObject({ result: 'answer' });
+    });
+});

package/src/__tests__/providers/pi/durable/PiStreamParser.test.ts

@@ -0,0 +1,24 @@
+import { describe, expect, it } from 'vitest';
+import { PiStreamParser } from '../../../../providers/pi/durable/PiStreamParser.js';
+
+const SESSION = '22222222-2222-4222-8222-222222222222';
+
+describe('PiStreamParser', () => {
+    it('ignores blank lines and normalizes unexpected parser failures', () => {
+        const parser = new PiStreamParser(SESSION, 1024);
+        parser.accept('\n');
+        parser.fail(new Error('unexpected'));
+
+        expect(parser.hasFailed()).toBe(true);
+        expect(() => parser.result({ code: 0, signal: null }))
+            .toThrowError(expect.objectContaining({ code: 'PI_PROTOCOL', message: 'Pi stream processing failed.' }));
+    });
+
+    it('includes the terminating signal in process failures', () => {
+        const parser = new PiStreamParser(SESSION, 1024);
+        parser.accept(`${JSON.stringify({ type: 'session', id: SESSION })}\n`);
+
+        expect(() => parser.result({ code: null, signal: 'SIGTERM' }))
+            .toThrowError(expect.objectContaining({ code: 'PI_PROCESS', message: 'Pi print run failed (SIGTERM)' }));
+    });
+});

package/src/__tests__/utils/ClaudeSessionParser.test.ts

@@ -1,5 +1,5 @@
 /**
- * Tests for utils/ClaudeSessionParser.ts — focused on stripping
+ * Tests for providers/claude/ClaudeSessionParser.ts — focused on stripping
  * harness-injected XML tags from conversation content.
  */
 
@@ -7,7 +7,7 @@
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
-import { ClaudeSessionParser } from '../../utils/ClaudeSessionParser.js';
+import { ClaudeSessionParser } from '../../providers/claude/ClaudeSessionParser.js';
 
 interface JsonlEntry {
     type: 'user' | 'assistant' | 'system';

package/src/adapters/index.ts

@@ -1,4 +1,4 @@
-export { ClaudeCodeAdapter } from './ClaudeCodeAdapter.js';
+export { ClaudeCodeAdapter } from '../providers/claude/ClaudeCodeAdapter.js';
 export { CodexAdapter } from './CodexAdapter.js';
 export { CopilotAdapter } from './CopilotAdapter.js';
 export { GeminiCliAdapter } from './GeminiCliAdapter.js';

package/src/capacity/codex.ts

@@ -0,0 +1,320 @@
+import { spawn } from 'node:child_process';
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import type { CapacityReport, CapacityWindow } from './types.js';
+
+type CodexUsageSource = 'pat' | 'oauth' | 'cli';
+type UsageSnapshot = { windows: CapacityWindow[]; creditsRemaining: number | null; source: CodexUsageSource };
+
+type UnknownRecord = Record<string, unknown>;
+type RpcMessage = { id?: number; method: string; params?: UnknownRecord };
+type CliResponses = { rateLimits: unknown; account: unknown };
+type CodexRpc = (messages: RpcMessage[]) => Promise<CliResponses>;
+
+export const CODEX_APP_SERVER_ARGS = ['-s', 'read-only', '-a', 'untrusted', 'app-server'] as const;
+
+type CodexProbeOptions = {
+  installed: boolean;
+  checkedAt: string;
+  readFile?: (path: string, encoding: BufferEncoding) => Promise<string>;
+  fetch?: typeof globalThis.fetch;
+  rpc?: CodexRpc;
+  timeoutMs?: number;
+  env?: NodeJS.ProcessEnv;
+  now?: () => Date;
+};
+
+function record(value: unknown): UnknownRecord | null {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+    ? value as UnknownRecord
+    : null;
+}
+
+function finiteNumber(value: unknown): number | null {
+  return typeof value === 'number' && Number.isFinite(value) ? value : null;
+}
+
+function nonEmptyText(value: unknown): string | null {
+  return typeof value === 'string' && value.length > 0 ? value : null;
+}
+
+function resetTime(value: unknown): string | null {
+  const seconds = finiteNumber(value);
+  if (seconds !== null) return new Date(seconds * 1000).toISOString();
+  if (typeof value === 'string' && !Number.isNaN(Date.parse(value))) return new Date(value).toISOString();
+  return null;
+}
+
+function safeIdentifier(value: unknown): string | null {
+  const candidate = nonEmptyText(value);
+  if (!candidate || !/^[a-z][a-z0-9_-]{0,63}$/i.test(candidate)) return null;
+  if (/(?:account|token|secret|key)[_-]?\d{6,}/i.test(candidate)) return null;
+  return candidate;
+}
+
+export function resolveCodexAuthPath(env: NodeJS.ProcessEnv = process.env): string {
+  const root = env.CODEX_HOME || join(env.HOME || '', '.codex');
+  return join(root, 'auth.json');
+}
+
+export function toRateWindow(
+  value: unknown,
+  id: string,
+  label: string
+): CapacityWindow | null {
+  const input = record(value);
+  if (!input) return null;
+  const used = finiteNumber(input.used_percent);
+  const seconds = finiteNumber(input.limit_window_seconds);
+  return {
+    id,
+    label,
+    durationMinutes: seconds === null ? null : seconds / 60,
+    usedPercent: used,
+    resetsAt: resetTime(input.reset_at)
+  };
+}
+
+function extraWindows(value: unknown): CapacityWindow[] {
+  if (!Array.isArray(value)) return [];
+  return value.flatMap((entry, index) => {
+    const limit = record(entry);
+    if (!limit) return [];
+    const scope = safeIdentifier(limit.limit_name) ?? `extra-${index + 1}`;
+    const windows = record(limit.rate_limit) ?? limit;
+    return [
+      toRateWindow(windows.primary_window, `${scope}:primary`, `${scope} primary`),
+      toRateWindow(windows.secondary_window, `${scope}:secondary`, `${scope} secondary`)
+    ].filter((window): window is CapacityWindow => window !== null);
+  });
+}
+
+export function parseUsage(raw: unknown, source: 'pat' | 'oauth'): UsageSnapshot {
+  const response = record(raw) ?? {};
+  const limits = record(response.rate_limit) ?? {};
+  const credits = record(response.credits) ?? {};
+  return {
+    windows: [
+      toRateWindow(limits.primary_window, 'session', 'Session'),
+      toRateWindow(limits.secondary_window, 'weekly', 'Weekly'),
+      ...extraWindows(response.additional_rate_limits)
+    ].filter((window): window is CapacityWindow => window !== null),
+    creditsRemaining: finiteNumber(credits.balance),
+    source
+  };
+}
+
+function cliWindow(value: unknown, id: string, label: string): CapacityWindow | null {
+  const input = record(value);
+  if (!input) return null;
+  return {
+    id,
+    label,
+    durationMinutes: finiteNumber(input.windowDurationMins),
+    usedPercent: finiteNumber(input.usedPercent),
+    resetsAt: resetTime(input.resetsAt)
+  };
+}
+
+function cliSnapshotWindows(value: unknown, fallbackId: string): CapacityWindow[] {
+  const snapshot = record(value);
+  if (!snapshot) return [];
+  const scope = safeIdentifier(snapshot.limitId) ?? safeIdentifier(fallbackId) ?? 'codex';
+  return [
+    cliWindow(snapshot.primary, `${scope}:primary`, `${scope} primary`),
+    cliWindow(snapshot.secondary, `${scope}:secondary`, `${scope} secondary`)
+  ].filter((item): item is CapacityWindow => item !== null);
+}
+
+export function parseCliUsage(raw: unknown): UsageSnapshot {
+  const response = record(raw) ?? {};
+  const primary = record(response.rateLimits);
+  const windows = primary ? cliSnapshotWindows(primary, 'codex') : [];
+  const buckets = record(response.rateLimitsByLimitId);
+  if (buckets) {
+    for (const [id, snapshot] of Object.entries(buckets)) windows.push(...cliSnapshotWindows(snapshot, id));
+  }
+  const unique = [...new Map(windows.map(window => [window.id, window])).values()];
+  return { windows: unique, creditsRemaining: null, source: 'cli' };
+}
+
+function capacityFromSnapshot(snapshot: UsageSnapshot, context: CodexProbeOptions, raw?: unknown): CapacityReport {
+  const hasUsage = snapshot.windows.some(window => window.usedPercent !== null);
+  const rateLimits = record(record(raw)?.rateLimits);
+  const reached = nonEmptyText(rateLimits?.rateLimitReachedType);
+  const resetCredits = record(record(raw)?.rateLimitResetCredits) ?? record(record(raw)?.usageLimitResetCredits);
+  return {
+    provider: 'codex',
+    generatedAt: context.checkedAt,
+    authenticated: true,
+    available: reached ? 'no' : hasUsage ? 'yes' : 'unknown',
+    windows: snapshot.windows,
+    creditsRemaining: snapshot.creditsRemaining ?? finiteNumber(resetCredits?.availableCount)
+  };
+}
+
+function jwtExpiry(token: string): number | null {
+  const part = token.split('.')[1];
+  if (!part) return null;
+  try {
+    return finiteNumber(record(JSON.parse(Buffer.from(part, 'base64url').toString('utf8')))?.exp);
+  } catch {
+    return null;
+  }
+}
+
+function staleOAuth(tokens: UnknownRecord, token: string, now: Date): boolean {
+  const metadata = tokens.expires_at ?? tokens.expiresAt ?? tokens.expiry;
+  let expiry: number | null = finiteNumber(metadata);
+  if (typeof metadata === 'string') {
+    const parsed = Date.parse(metadata);
+    expiry = Number.isNaN(parsed) ? null : parsed / 1000;
+  }
+  expiry ??= jwtExpiry(token);
+  return expiry !== null && expiry <= now.getTime() / 1000;
+}
+
+async function fetchJson(fetcher: typeof globalThis.fetch, url: string, init: RequestInit, timeoutMs: number): Promise<unknown> {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const response = await fetcher(url, { ...init, signal: controller.signal });
+    if (!response.ok) throw new Error(response.status === 401 ? 'unauthorized' : 'request failed');
+    return await response.json();
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+async function apiSnapshot(
+  token: string,
+  accountId: string,
+  source: 'pat' | 'oauth',
+  options: CodexProbeOptions
+): Promise<UsageSnapshot> {
+  const fetcher = options.fetch ?? globalThis.fetch;
+  const raw = await fetchJson(fetcher, 'https://chatgpt.com/backend-api/wham/usage', {
+    headers: { Authorization: `Bearer ${token}`, 'ChatGPT-Account-Id': accountId }
+  }, options.timeoutMs ?? 5000);
+  return parseUsage(raw, source);
+}
+
+function appServerRpc(messages: RpcMessage[], timeoutMs = 5000): Promise<CliResponses> {
+  return new Promise((resolve, reject) => {
+    const child = spawn('codex', CODEX_APP_SERVER_ARGS, {
+      stdio: ['pipe', 'pipe', 'ignore']
+    });
+    const results: Partial<CliResponses> = {};
+    let buffer = '';
+    let settled = false;
+    const finish = (error?: Error) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      child.kill();
+      if (error) reject(error);
+      else resolve(results as CliResponses);
+    };
+    const timer = setTimeout(() => finish(new Error('codex probe timed out')), timeoutMs);
+    child.once('error', () => finish(new Error('codex app-server unavailable')));
+    child.once('exit', () => { if (!settled) finish(new Error('codex app-server exited')); });
+    child.stdout.setEncoding('utf8');
+    child.stdout.on('data', (chunk: string) => {
+      buffer += chunk;
+      for (;;) {
+        const newline = buffer.indexOf('\n');
+        if (newline < 0) break;
+        const line = buffer.slice(0, newline).trim();
+        buffer = buffer.slice(newline + 1);
+        if (!line) continue;
+        let message: UnknownRecord;
+        try { message = JSON.parse(line) as UnknownRecord; } catch { continue; }
+        if (message.id === 1) {
+          for (const request of messages.slice(1)) child.stdin.write(`${JSON.stringify(request)}\n`);
+        } else if (message.id === 2) {
+          if (message.error) finish(new Error('codex rate-limit method failed'));
+          else results.rateLimits = message.result;
+        } else if (message.id === 3) {
+          if (message.error) finish(new Error('codex account method failed'));
+          else results.account = message.result;
+        }
+        if ('rateLimits' in results && 'account' in results) finish();
+      }
+    });
+    child.stdin.write(`${JSON.stringify(messages[0])}\n`);
+  });
+}
+
+function unavailable(options: CodexProbeOptions): CapacityReport {
+  return {
+    provider: 'codex',
+    generatedAt: options.checkedAt,
+    authenticated: null,
+    available: 'unknown',
+    windows: [],
+    creditsRemaining: null
+  };
+}
+
+async function cliFallback(options: CodexProbeOptions): Promise<CapacityReport> {
+  if (!options.installed) return unavailable(options);
+  const messages: RpcMessage[] = [
+    { id: 1, method: 'initialize', params: {
+      clientInfo: { name: 'ai-devkit', title: null, version: '1' }, capabilities: null
+    } },
+    { method: 'initialized' },
+    { id: 2, method: 'account/rateLimits/read' },
+    { id: 3, method: 'account/read' }
+  ];
+  try {
+    const rpc = options.rpc ?? (requests => appServerRpc(requests, options.timeoutMs));
+    const response = await rpc(messages);
+    const result = capacityFromSnapshot(parseCliUsage(response.rateLimits), options, response.rateLimits);
+    const accountEnvelope = record(response.account);
+    if (accountEnvelope && Object.hasOwn(accountEnvelope, 'account') && !record(accountEnvelope.account)) {
+      result.authenticated = false;
+      result.available = 'unknown';
+    }
+    return result;
+  } catch {
+    return unavailable(options);
+  }
+}
+
+export async function probeCodexCapacity(options: CodexProbeOptions): Promise<CapacityReport> {
+  let parsed: UnknownRecord | null = null;
+  try {
+    const contents = await (options.readFile ?? readFile)(resolveCodexAuthPath(options.env), 'utf8');
+    parsed = record(JSON.parse(contents));
+  } catch {
+    return cliFallback(options);
+  }
+
+  const auth = parsed ?? {};
+  const pat = nonEmptyText(auth.personal_access_token);
+  if (pat) {
+    try {
+      const fetcher = options.fetch ?? globalThis.fetch;
+      const whoami = record(await fetchJson(fetcher,
+        'https://auth.openai.com/api/accounts/v1/user-auth-credential/whoami',
+        { headers: { Authorization: `Bearer ${pat}` } }, options.timeoutMs ?? 5000));
+      const accountId = nonEmptyText(whoami?.chatgpt_account_id);
+      if (!accountId) throw new Error('account unavailable');
+      return capacityFromSnapshot(await apiSnapshot(pat, accountId, 'pat', options), options);
+    } catch {
+      // Continue to a separately available OAuth credential before using the CLI.
+    }
+  }
+
+  const tokens = record(auth.tokens);
+  const accessToken = nonEmptyText(tokens?.access_token);
+  const accountId = nonEmptyText(tokens?.account_id);
+  if (tokens && accessToken && accountId && !staleOAuth(tokens, accessToken, (options.now ?? (() => new Date()))())) {
+    try {
+      return capacityFromSnapshot(await apiSnapshot(accessToken, accountId, 'oauth', options), options);
+    } catch {
+      return cliFallback(options);
+    }
+  }
+  return cliFallback(options);
+}

package/src/capacity/index.ts

@@ -0,0 +1,57 @@
+import { constants } from 'node:fs';
+import { access as fsAccess } from 'node:fs/promises';
+import path from 'node:path';
+import { probeCodexCapacity } from './codex.js';
+import type { CapacityReport } from './types.js';
+
+export type { CapacityReport, CapacityWindow } from './types.js';
+
+export type CapacityProbeOptions = {
+  now?: () => Date;
+  path?: string;
+  access?: (target: string) => Promise<void>;
+  probe?: typeof probeCodexCapacity;
+};
+
+async function canAccess(target: string, mode: number): Promise<boolean> {
+  try {
+    await fsAccess(target, mode);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function isCodexInstalled(pathValue: string, checkAccess?: (target: string) => Promise<void>): Promise<boolean> {
+  const directories = pathValue.split(path.delimiter).filter(Boolean);
+  for (const directory of directories) {
+    const executable = path.join(directory, 'codex');
+    if (checkAccess) {
+      try {
+        await checkAccess(executable);
+        return true;
+      } catch {
+        continue;
+      }
+    }
+    if (await canAccess(executable, constants.X_OK)) return true;
+  }
+  return false;
+}
+
+export async function getCodexCapacityReport(options: CapacityProbeOptions = {}): Promise<CapacityReport> {
+  const generatedAt = (options.now?.() ?? new Date()).toISOString();
+  const installed = await isCodexInstalled(options.path ?? process.env.PATH ?? '', options.access);
+  try {
+    return await (options.probe ?? probeCodexCapacity)({ installed, checkedAt: generatedAt });
+  } catch {
+    return {
+      provider: 'codex',
+      generatedAt,
+      authenticated: null,
+      available: 'unknown',
+      windows: [],
+      creditsRemaining: null
+    };
+  }
+}

package/src/capacity/types.ts

@@ -0,0 +1,18 @@
+export type Availability = 'yes' | 'no' | 'unknown';
+
+export interface CapacityWindow {
+  id: string;
+  label: string;
+  durationMinutes: number | null;
+  usedPercent: number | null;
+  resetsAt: string | null;
+}
+
+export interface CapacityReport {
+  provider: string;
+  generatedAt: string;
+  authenticated: boolean | null;
+  available: Availability;
+  windows: CapacityWindow[];
+  creditsRemaining: number | null;
+}

package/src/database/migrations/004_codex_durable_sessions.sql

@@ -0,0 +1 @@
+ALTER TABLE durable_agents ALTER COLUMN provider_session_id DROP NOT NULL;