@inbrowser/agent 0.0.0-placeholder → 0.1.0

package/dist/cli/commands/events.js

@@ -0,0 +1,59 @@
+/**
+ * `agent events` — read + filter the per-project mutation event log.
+ *
+ * Emits one event per NDJSON line. Field filtering (`--fields`)
+ * applies to each event. Read-only — never appends.
+ *
+ * Bookkeeping markers (`migrate_applied`, `migrate_intent`) are
+ * **excluded by default** so users querying "what changed?" don't
+ * see audit-of-the-audit rows mixed in. Pass `--include-bookkeeping`
+ * to opt back in.
+ */
+import { openEventLog } from '../../events/log.js';
+export function eventsCommand(args, io) {
+    const projectId = args.options['project'];
+    if (!projectId) {
+        throw new Error('agent events: --project is required');
+    }
+    const eventsDir = args.options['events-dir'];
+    const openLog = io.openLog ?? openEventLog;
+    const log = openLog({
+        projectId,
+        ...(eventsDir ? { logDir: eventsDir } : {}),
+    });
+    const filter = {};
+    if (typeof args.options['session'] === 'string')
+        filter.sessionId = args.options['session'];
+    if (typeof args.options['tool'] === 'string')
+        filter.tool = args.options['tool'];
+    if (typeof args.options['agent'] === 'string')
+        filter.agent = args.options['agent'];
+    if (typeof args.options['phase'] === 'string')
+        filter.phase = args.options['phase'];
+    if (typeof args.options['since'] === 'string')
+        filter.since = args.options['since'];
+    if (typeof args.options['until'] === 'string')
+        filter.until = args.options['until'];
+    if (typeof args.options['target-kind'] === 'string') {
+        filter.targetKind = args.options['target-kind'];
+    }
+    const includeBookkeeping = Boolean(args.options['include-bookkeeping']);
+    try {
+        const events = log.read(filter).filter((e) => {
+            if (includeBookkeeping)
+                return true;
+            const type = e.metadata?.type;
+            return type !== 'migrate_applied' && type !== 'migrate_intent';
+        });
+        for (const event of events) {
+            io.emit.event(event, () => `${event.ts} ${event.phase.padEnd(8)} ${event.tool.padEnd(20)} ${event.target.kind}:${event.target.path}` +
+                (event.reversible ? '' : ' [irreversible]'));
+        }
+        io.emit.finish();
+        return 0;
+    }
+    finally {
+        log.close();
+    }
+}
+//# sourceMappingURL=events.js.map

package/dist/cli/commands/events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../../../src/cli/commands/events.ts"],"names":[],"mappings":"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"}

package/dist/cli/commands/fleet.d.ts

@@ -0,0 +1,15 @@
+/**
+ * `agent fleet` — launch N concurrent sessions for isolation testing.
+ * Reuses the same event vocabulary as `agent run` but adds a final
+ * `fleet_summary` event with per-session totals + the isolation flag.
+ */
+import type { Emitter } from '../output.js';
+import type { ParsedArgs } from '../parse.js';
+import { openSessionLog } from '../session-log.js';
+export interface FleetCommandIO {
+    emit: Emitter;
+    now?: () => string;
+    openLog?: typeof openSessionLog;
+}
+export declare function fleetCommand(args: ParsedArgs, io: FleetCommandIO): Promise<number>;
+//# sourceMappingURL=fleet.d.ts.map

package/dist/cli/commands/fleet.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fleet.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/fleet.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAQH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAEnD,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,OAAO,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,OAAO,cAAc,CAAC;CACjC;AAoBD,wBAAsB,YAAY,CAAC,IAAI,EAAE,UAAU,EAAE,EAAE,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CA4JxF"}

package/dist/cli/commands/fleet.js

@@ -0,0 +1,149 @@
+/**
+ * `agent fleet` — launch N concurrent sessions for isolation testing.
+ * Reuses the same event vocabulary as `agent run` but adds a final
+ * `fleet_summary` event with per-session totals + the isolation flag.
+ */
+import { createMetricsCollector } from '../../metrics.js';
+import { createAgentSession } from '../../session.js';
+import { createReactLoopStrategy } from '../../strategy.js';
+import { createDispatch, createToolRegistry } from '../../tools.js';
+import { fakeSandbox, scriptedLlm, writeRulesTool } from '../fixtures.js';
+import { openSessionLog } from '../session-log.js';
+function plan(size) {
+    const presets = ['chess', 'lobby', 'owner', 'corpus', 'forum'];
+    return Array.from({ length: size }, (_, i) => {
+        const preset = presets[i % presets.length];
+        return {
+            id: `s${i + 1}`,
+            presetId: preset,
+            prompt: `Session ${i + 1}: write rules for ${preset}`,
+        };
+    });
+}
+export async function fleetCommand(args, io) {
+    const emit = io.emit;
+    const now = io.now ?? (() => new Date().toISOString());
+    const openLog = io.openLog ?? openSessionLog;
+    const size = args.options['size'] ?? 3;
+    if (size < 1 || size > 64) {
+        throw new Error('--size must be 1..64');
+    }
+    const logDir = args.options['log-dir'] ?? null;
+    const disableLog = Boolean(args.options['no-log']);
+    const members = plan(size);
+    if (args.options['dry-run']) {
+        emit.event({
+            type: 'dry_run_plan',
+            ts: now(),
+            command: 'fleet',
+            size,
+            members: members.map((m) => ({ id: m.id, presetId: m.presetId })),
+            logDir: logDir ?? '~/.pyric/sessions',
+        }, () => `[plan] fleet · size=${size} · members=${members.map((m) => m.id).join(',')}`);
+        emit.finish();
+        return 0;
+    }
+    emit.event({ type: 'fleet_start', ts: now(), size, members: members.map((m) => m.id) }, () => `[fleet] launching ${size} sessions`);
+    const startedAt = performance.now();
+    const results = await Promise.all(members.map(async (member) => {
+        const registry = createToolRegistry();
+        registry.register(writeRulesTool);
+        const metrics = createMetricsCollector();
+        const sandbox = fakeSandbox();
+        const log = openLog({ logDir, sessionId: member.id, disabled: disableLog });
+        const session = createAgentSession({
+            strategy: createReactLoopStrategy(),
+            llm: scriptedLlm('write-rules', member.id),
+            tools: createDispatch(registry),
+            toolList: registry.list(),
+            toolContext: () => ({
+                workspace: session.workspace,
+                runtime: session.runtime,
+                sandbox,
+                lint: () => ({ warnings: [] }),
+                signal: new AbortController().signal,
+            }),
+            systemPromptBuilder: (w) => `Session ${member.id} preset=${w.presetId || member.presetId}`,
+            metrics,
+            history: [],
+            id: member.id,
+        });
+        log.write({
+            type: 'session_start',
+            ts: now(),
+            sessionId: member.id,
+            scenario: 'write-rules',
+        });
+        let eventCount = 0;
+        for await (const ev of session.submit(member.prompt, AbortSignal.timeout(30_000))) {
+            eventCount += 1;
+            if (ev.kind === 'turn_completed') {
+                const turnEvent = {
+                    type: 'turn_end',
+                    ts: now(),
+                    sessionId: member.id,
+                    turn: ev.turnId,
+                    metrics: {
+                        tokensIn: ev.metrics.tokensIn,
+                        tokensOut: ev.metrics.tokensOut,
+                        costUsd: ev.metrics.costUsd,
+                    },
+                };
+                log.write(turnEvent);
+                emit.event(turnEvent, () => `[${member.id}] turn done · ${ev.metrics.tokensIn}+${ev.metrics.tokensOut}t`);
+            }
+            else if (ev.kind === 'tool_finished') {
+                const toolEvent = {
+                    type: 'tool_result',
+                    ts: now(),
+                    sessionId: member.id,
+                    callId: ev.callId,
+                    ok: ev.result.ok,
+                    summary: ev.result.summary,
+                };
+                log.write(toolEvent);
+                emit.event(toolEvent, () => `[${member.id}] tool ${ev.callId} ${ev.result.ok ? 'ok' : 'fail'}`);
+            }
+            else if (ev.kind === 'error') {
+                const errEvent = {
+                    type: 'session_error',
+                    ts: now(),
+                    sessionId: member.id,
+                    message: ev.message,
+                };
+                log.write(errEvent);
+                emit.event(errEvent, () => `[${member.id}] error: ${ev.message}`);
+            }
+        }
+        const totals = metrics.totals();
+        const summary = {
+            id: member.id,
+            presetId: member.presetId,
+            rulesLength: session.workspace.rules.length,
+            ownIdInRules: session.workspace.rules.includes(member.id),
+            tokens: totals.tokensTotal,
+            costUsd: totals.costUsdTotal,
+            turns: totals.turnCount,
+            events: eventCount,
+            logPath: log.path,
+        };
+        log.write({ type: 'session_end', ts: now(), sessionId: member.id, totals: summary });
+        log.close();
+        return summary;
+    }));
+    const elapsedMs = performance.now() - startedAt;
+    const allIsolated = results.every((r) => r.ownIdInRules);
+    emit.event({
+        type: 'fleet_summary',
+        ts: now(),
+        size,
+        elapsedMs,
+        isolated: allIsolated,
+        aggregateTokens: results.reduce((sum, r) => sum + r.tokens, 0),
+        aggregateCostUsd: results.reduce((sum, r) => sum + r.costUsd, 0),
+        results,
+    }, () => `[fleet] done · ${size} sessions · ${elapsedMs.toFixed(1)}ms · isolation=${allIsolated ? 'ok' : 'LEAK'} · tokens=${results.reduce((s, r) => s + r.tokens, 0)}`);
+    emit.finish();
+    return allIsolated ? 0 : 1;
+}
+//# sourceMappingURL=fleet.js.map

package/dist/cli/commands/fleet.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fleet.js","sourceRoot":"","sources":["../../../src/cli/commands/fleet.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AAC1D,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,EAAE,uBAAuB,EAAE,MAAM,mBAAmB,CAAC;AAC5D,OAAO,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AACpE,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAG1E,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAcnD,SAAS,IAAI,CAAC,IAAY;IACxB,MAAM,OAAO,GAAG,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,CAAU,CAAC;IACxE,OAAO,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE;QAC3C,MAAM,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,OAAO,CAAC,MAAM,CAAE,CAAC;QAC5C,OAAO;YACL,EAAE,EAAE,IAAI,CAAC,GAAG,CAAC,EAAE;YACf,QAAQ,EAAE,MAAM;YAChB,MAAM,EAAE,WAAW,CAAC,GAAG,CAAC,qBAAqB,MAAM,EAAE;SACtD,CAAC;IACJ,CAAC,CAAC,CAAC;AACL,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,IAAgB,EAAE,EAAkB;IACrE,MAAM,IAAI,GAAG,EAAE,CAAC,IAAI,CAAC;IACrB,MAAM,GAAG,GAAG,EAAE,CAAC,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,CAAC;IACvD,MAAM,OAAO,GAAG,EAAE,CAAC,OAAO,IAAI,cAAc,CAAC;IAE7C,MAAM,IAAI,GAAI,IAAI,CAAC,OAAO,CAAC,MAAM,CAAwB,IAAI,CAAC,CAAC;IAC/D,IAAI,IAAI,GAAG,CAAC,IAAI,IAAI,GAAG,EAAE,EAAE,CAAC;QAC1B,MAAM,IAAI,KAAK,CAAC,sBAAsB,CAAC,CAAC;IAC1C,CAAC;IACD,MAAM,MAAM,GAAI,IAAI,CAAC,OAAO,CAAC,SAAS,CAAwB,IAAI,IAAI,CAAC;IACvE,MAAM,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC;IACnD,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC;IAE3B,IAAI,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC;QAC5B,IAAI,CAAC,KAAK,CACR;YACE,IAAI,EAAE,cAAc;YACpB,EAAE,EAAE,GAAG,EAAE;YACT,OAAO,EAAE,OAAO;YAChB,IAAI;YACJ,OAAO,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,QAAQ,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC;YACjE,MAAM,EAAE,MAAM,IAAI,mBAAmB;SACtC,EACD,GAAG,EAAE,CAAC,uBAAuB,IAAI,cAAc,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CACpF,CAAC;QACF,IAAI,CAAC,MAAM,EAAE,CAAC;QACd,OAAO,CAAC,CAAC;IACX,CAAC;IAED,IAAI,CAAC,KAAK,CACR,EAAE,IAAI,EAAE,aAAa,EAAE,EAAE,EAAE,GAAG,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAC3E,GAAG,EAAE,CAAC,qBAAqB,IAAI,WAAW,CAC3C,CAAC;IAEF,MAAM,SAAS,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC;IAEpC,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,GAAG,CAC/B,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE;QAC3B,MAAM,QAAQ,GAAG,kBAAkB,EAAE,CAAC;QACtC,QAAQ,CAAC,QAAQ,CAAC,cAAc,CAAC,CAAC;QAClC,MAAM,OAAO,GAAG,sBAAsB,EAAE,CAAC;QACzC,MAAM,OAAO,GAAG,WAAW,EAAE,CAAC;QAC9B,MAAM,GAAG,GAAG,OAAO,CAAC,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,CAAC,EAAE,EAAE,QAAQ,EAAE,UAAU,EAAE,CAAC,CAAC;QAE5E,MAAM,OAAO,GAAG,kBAAkB,CAAC;YACjC,QAAQ,EAAE,uBAAuB,EAAE;YACnC,GAAG,EAAE,WAAW,CAAC,aAAa,EAAE,MAAM,CAAC,EAAE,CAAC;YAC1C,KAAK,EAAE,cAAc,CAAC,QAAQ,CAAC;YAC/B,QAAQ,EAAE,QAAQ,CAAC,IAAI,EAAE;YACzB,WAAW,EAAE,GAAgB,EAAE,CAAC,CAAC;gBAC/B,SAAS,EAAE,OAAO,CAAC,SAAS;gBAC5B,OAAO,EAAE,OAAO,CAAC,OAAO;gBACxB,OAAO;gBACP,IAAI,EAAE,GAAG,EAAE,CAAC,CAAC,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC;gBAC9B,MAAM,EAAE,IAAI,eAAe,EAAE,CAAC,MAAM;aACrC,CAAC;YACF,mBAAmB,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,WAAW,MAAM,CAAC,EAAE,WAAW,CAAC,CAAC,QAAQ,IAAI,MAAM,CAAC,QAAQ,EAAE;YAC1F,OAAO;YACP,OAAO,EAAE,EAAE;YACX,EAAE,EAAE,MAAM,CAAC,EAAE;SACd,CAAC,CAAC;QAEH,GAAG,CAAC,KAAK,CAAC;YACR,IAAI,EAAE,eAAe;YACrB,EAAE,EAAE,GAAG,EAAE;YACT,SAAS,EAAE,MAAM,CAAC,EAAE;YACpB,QAAQ,EAAE,aAAa;SACxB,CAAC,CAAC;QAEH,IAAI,UAAU,GAAG,CAAC,CAAC;QACnB,IAAI,KAAK,EAAE,MAAM,EAAE,IAAI,OAAO,CAAC,MAAM,CACnC,MAAM,CAAC,MAAM,EACb,WAAW,CAAC,OAAO,CAAC,MAAM,CAAC,CACG,EAAE,CAAC;YACjC,UAAU,IAAI,CAAC,CAAC;YAChB,IAAI,EAAE,CAAC,IAAI,KAAK,gBAAgB,EAAE,CAAC;gBACjC,MAAM,SAAS,GAAG;oBAChB,IAAI,EAAE,UAAU;oBAChB,EAAE,EAAE,GAAG,EAAE;oBACT,SAAS,EAAE,MAAM,CAAC,EAAE;oBACpB,IAAI,EAAE,EAAE,CAAC,MAAM;oBACf,OAAO,EAAE;wBACP,QAAQ,EAAE,EAAE,CAAC,OAAO,CAAC,QAAQ;wBAC7B,SAAS,EAAE,EAAE,CAAC,OAAO,CAAC,SAAS;wBAC/B,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,OAAO;qBAC5B;iBACF,CAAC;gBACF,GAAG,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;gBACrB,IAAI,CAAC,KAAK,CACR,SAAS,EACT,GAAG,EAAE,CAAC,IAAI,MAAM,CAAC,EAAE,iBAAiB,EAAE,CAAC,OAAO,CAAC,QAAQ,IAAI,EAAE,CAAC,OAAO,CAAC,SAAS,GAAG,CACnF,CAAC;YACJ,CAAC;iBAAM,IAAI,EAAE,CAAC,IAAI,KAAK,eAAe,EAAE,CAAC;gBACvC,MAAM,SAAS,GAAG;oBAChB,IAAI,EAAE,aAAa;oBACnB,EAAE,EAAE,GAAG,EAAE;oBACT,SAAS,EAAE,MAAM,CAAC,EAAE;oBACpB,MAAM,EAAE,EAAE,CAAC,MAAM;oBACjB,EAAE,EAAE,EAAE,CAAC,MAAM,CAAC,EAAE;oBAChB,OAAO,EAAE,EAAE,CAAC,MAAM,CAAC,OAAO;iBAC3B,CAAC;gBACF,GAAG,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;gBACrB,IAAI,CAAC,KAAK,CACR,SAAS,EACT,GAAG,EAAE,CAAC,IAAI,MAAM,CAAC,EAAE,UAAU,EAAE,CAAC,MAAM,IAAI,EAAE,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,EAAE,CACzE,CAAC;YACJ,CAAC;iBAAM,IAAI,EAAE,CAAC,IAAI,KAAK,OAAO,EAAE,CAAC;gBAC/B,MAAM,QAAQ,GAAG;oBACf,IAAI,EAAE,eAAe;oBACrB,EAAE,EAAE,GAAG,EAAE;oBACT,SAAS,EAAE,MAAM,CAAC,EAAE;oBACpB,OAAO,EAAE,EAAE,CAAC,OAAO;iBACpB,CAAC;gBACF,GAAG,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;gBACpB,IAAI,CAAC,KAAK,CAAC,QAAQ,EAAE,GAAG,EAAE,CAAC,IAAI,MAAM,CAAC,EAAE,YAAY,EAAE,CAAC,OAAO,EAAE,CAAC,CAAC;YACpE,CAAC;QACH,CAAC;QAED,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;QAChC,MAAM,OAAO,GAAG;YACd,EAAE,EAAE,MAAM,CAAC,EAAE;YACb,QAAQ,EAAE,MAAM,CAAC,QAAQ;YACzB,WAAW,EAAE,OAAO,CAAC,SAAS,CAAC,KAAK,CAAC,MAAM;YAC3C,YAAY,EAAE,OAAO,CAAC,SAAS,CAAC,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;YACzD,MAAM,EAAE,MAAM,CAAC,WAAW;YAC1B,OAAO,EAAE,MAAM,CAAC,YAAY;YAC5B,KAAK,EAAE,MAAM,CAAC,SAAS;YACvB,MAAM,EAAE,UAAU;YAClB,OAAO,EAAE,GAAG,CAAC,IAAI;SAClB,CAAC;QACF,GAAG,CAAC,KAAK,CAAC,EAAE,IAAI,EAAE,aAAa,EAAE,EAAE,EAAE,GAAG,EAAE,EAAE,SAAS,EAAE,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC;QACrF,GAAG,CAAC,KAAK,EAAE,CAAC;QACZ,OAAO,OAAO,CAAC;IACjB,CAAC,CAAC,CACH,CAAC;IAEF,MAAM,SAAS,GAAG,WAAW,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC;IAChD,MAAM,WAAW,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC;IAEzD,IAAI,CAAC,KAAK,CACR;QACE,IAAI,EAAE,eAAe;QACrB,EAAE,EAAE,GAAG,EAAE;QACT,IAAI;QACJ,SAAS;QACT,QAAQ,EAAE,WAAW;QACrB,eAAe,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC,GAAG,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC;QAC9D,gBAAgB,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC,GAAG,GAAG,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC;QAChE,OAAO;KACR,EACD,GAAG,EAAE,CACH,kBAAkB,IAAI,eAAe,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC,kBAAkB,WAAW,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,aAAa,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,EAAE,CACjK,CAAC;IAEF,IAAI,CAAC,MAAM,EAAE,CAAC;IACd,OAAO,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAC7B,CAAC"}

package/dist/cli/commands/help.d.ts

@@ -0,0 +1,15 @@
+/**
+ * `agent help` — render top-level help in text mode, or emit the full
+ * schema (same as `agent schema`) in ndjson/json mode. Honors a
+ * subcommand argument: `agent help run` scopes to one command.
+ *
+ * Per the Agent DX rubric: `--help --json` MUST give the machine-
+ * readable description. We achieve that by deferring to the emitter
+ * — if the caller passed --output json or stdout isn't a TTY, the
+ * help payload is the JSON schema, not prose.
+ */
+import type { Emitter } from '../output.js';
+import type { ParsedArgs } from '../parse.js';
+export declare function helpCommand(args: ParsedArgs, emit: Emitter): number;
+export declare function versionCommand(emit: Emitter): number;
+//# sourceMappingURL=help.d.ts.map

package/dist/cli/commands/help.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"help.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/help.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAwD9C,wBAAgB,WAAW,CAAC,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,OAAO,GAAG,MAAM,CAgCnE;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,CAOpD"}

package/dist/cli/commands/help.js

@@ -0,0 +1,93 @@
+/**
+ * `agent help` — render top-level help in text mode, or emit the full
+ * schema (same as `agent schema`) in ndjson/json mode. Honors a
+ * subcommand argument: `agent help run` scopes to one command.
+ *
+ * Per the Agent DX rubric: `--help --json` MUST give the machine-
+ * readable description. We achieve that by deferring to the emitter
+ * — if the caller passed --output json or stdout isn't a TTY, the
+ * help payload is the JSON schema, not prose.
+ */
+import { CLI_SPEC, findCommand } from '../spec.js';
+function renderTextHelp(commandName) {
+    if (commandName) {
+        const cmd = findCommand(commandName);
+        if (!cmd)
+            return `unknown command: ${commandName}`;
+        const lines = [];
+        lines.push(`agent ${cmd.name} — ${cmd.description}`);
+        lines.push('');
+        if (cmd.positional)
+            lines.push(`Positional: <${cmd.positional.name}> — ${cmd.positional.description}`);
+        if (cmd.options.length > 0) {
+            lines.push('Options:');
+            for (const o of cmd.options) {
+                const flag = o.short ? `${o.name}, ${o.short}` : o.name;
+                const dflt = o.default !== undefined ? ` (default: ${JSON.stringify(o.default)})` : '';
+                lines.push(`  ${flag.padEnd(24)} ${o.description}${dflt}`);
+            }
+        }
+        if (cmd.examples) {
+            lines.push('');
+            lines.push('Examples:');
+            for (const e of cmd.examples) {
+                lines.push(`  $ ${e.input}`);
+                lines.push(`    ${e.description}`);
+            }
+        }
+        return lines.join('\n');
+    }
+    const lines = [];
+    lines.push(`${CLI_SPEC.name} v${CLI_SPEC.version} — ${CLI_SPEC.description}`);
+    lines.push('');
+    lines.push('Commands:');
+    for (const c of CLI_SPEC.commands) {
+        lines.push(`  ${c.name.padEnd(10)} ${c.description}`);
+    }
+    lines.push('');
+    lines.push('Global options:');
+    for (const o of CLI_SPEC.globalOptions) {
+        const flag = o.short ? `${o.name}, ${o.short}` : o.name;
+        lines.push(`  ${flag.padEnd(20)} ${o.description}`);
+    }
+    lines.push('');
+    lines.push('Agent integration tips:\n' +
+        '  • Pipe-friendly: NDJSON is the default when stdout is not a TTY.\n' +
+        '  • Discover the full schema with `agent schema` or `agent describe`.\n' +
+        '  • Always validate with `--dry-run` before mutating commands.\n' +
+        '  • Filter event fields with `--fields ts,type,sessionId,...` to save tokens.\n' +
+        '  • See AGENTS.md for invariants.');
+    return lines.join('\n');
+}
+export function helpCommand(args, emit) {
+    const subject = args.positional[0];
+    if (subject) {
+        const cmd = findCommand(subject);
+        if (!cmd) {
+            emit.event({ type: 'error', name: 'UsageError', message: `unknown command: ${subject}` }, () => `unknown command: ${subject}`);
+            emit.finish();
+            return 64;
+        }
+        emit.event({ type: 'help', command: cmd }, () => renderTextHelp(subject));
+        emit.finish();
+        return 0;
+    }
+    emit.event({
+        type: 'help',
+        cli: { name: CLI_SPEC.name, version: CLI_SPEC.version, description: CLI_SPEC.description },
+        commands: CLI_SPEC.commands.map((c) => ({
+            name: c.name,
+            description: c.description,
+            mutating: c.mutating,
+        })),
+        globalOptions: CLI_SPEC.globalOptions,
+    }, () => renderTextHelp());
+    emit.finish();
+    return 0;
+}
+export function versionCommand(emit) {
+    emit.event({ type: 'version', version: CLI_SPEC.version, name: CLI_SPEC.name }, () => CLI_SPEC.version);
+    emit.finish();
+    return 0;
+}
+//# sourceMappingURL=help.js.map

package/dist/cli/commands/help.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"help.js","sourceRoot":"","sources":["../../../src/cli/commands/help.ts"],"names":[],"mappings":"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"}

package/dist/cli/commands/migrate.d.ts

@@ -0,0 +1,27 @@
+/**
+ * `agent migrate` — plan + record the forward replay of a project's
+ * mutation event log against a (host-supplied) production dispatch.
+ *
+ * Mirrors the controller/runtime split established by `agent undo`:
+ *   - The CLI plans the replay (lists every commit event that would
+ *     fire) and optionally records a `migrate_intent` marker. It does
+ *     NOT dispatch tools — that requires a real dispatch wired to
+ *     services (e.g. live Firestore).
+ *   - The host (a script, a deploy agent, an automation pipeline)
+ *     reads the intent and calls `replayEvents()` from the library
+ *     surface against its production registry. The library function
+ *     writes `migrate_applied` markers as it goes.
+ *
+ * Output: NDJSON, one `migrate_plan` event per commit + a final
+ * `migrate_intent_recorded` line when `--record` is set.
+ */
+import { openEventLog } from '../../events/log.js';
+import type { Emitter } from '../output.js';
+import type { ParsedArgs } from '../parse.js';
+export interface MigrateCommandIO {
+    emit: Emitter;
+    openLog?: typeof openEventLog;
+    now?: () => string;
+}
+export declare function migrateCommand(args: ParsedArgs, io: MigrateCommandIO): number;
+//# sourceMappingURL=migrate.d.ts.map

package/dist/cli/commands/migrate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrate.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/migrate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,OAAO,CAAC;IACd,OAAO,CAAC,EAAE,OAAO,YAAY,CAAC;IAC9B,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,UAAU,EAAE,EAAE,EAAE,gBAAgB,GAAG,MAAM,CA+G7E"}

package/dist/cli/commands/migrate.js

@@ -0,0 +1,109 @@
+/**
+ * `agent migrate` — plan + record the forward replay of a project's
+ * mutation event log against a (host-supplied) production dispatch.
+ *
+ * Mirrors the controller/runtime split established by `agent undo`:
+ *   - The CLI plans the replay (lists every commit event that would
+ *     fire) and optionally records a `migrate_intent` marker. It does
+ *     NOT dispatch tools — that requires a real dispatch wired to
+ *     services (e.g. live Firestore).
+ *   - The host (a script, a deploy agent, an automation pipeline)
+ *     reads the intent and calls `replayEvents()` from the library
+ *     surface against its production registry. The library function
+ *     writes `migrate_applied` markers as it goes.
+ *
+ * Output: NDJSON, one `migrate_plan` event per commit + a final
+ * `migrate_intent_recorded` line when `--record` is set.
+ */
+import { openEventLog } from '../../events/log.js';
+export function migrateCommand(args, io) {
+    const projectId = args.options['project'];
+    if (!projectId)
+        throw new Error('agent migrate: --project is required');
+    const eventsDir = args.options['events-dir'];
+    const since = args.options['since-event'];
+    const toolsCsv = args.options['tools'];
+    const recordIntent = Boolean(args.options['record']);
+    const openLog = io.openLog ?? openEventLog;
+    const now = io.now ?? (() => new Date().toISOString());
+    const toolAllow = (() => {
+        if (Array.isArray(toolsCsv))
+            return new Set(toolsCsv);
+        if (typeof toolsCsv === 'string')
+            return new Set(toolsCsv
+                .split(',')
+                .map((s) => s.trim())
+                .filter(Boolean));
+        return null;
+    })();
+    const log = openLog({
+        projectId,
+        ...(eventsDir ? { logDir: eventsDir } : {}),
+    });
+    try {
+        const candidates = log
+            .read({ phase: 'commit' })
+            // Don't replay our own bookkeeping markers from prior runs.
+            .filter((e) => e.metadata?.type !== 'migrate_applied' &&
+            e.metadata?.type !== 'migrate_intent')
+            .filter((e) => (since ? e.id >= since : true))
+            .filter((e) => (toolAllow ? toolAllow.has(e.tool) : true));
+        const eligibleWithArgs = candidates.filter((e) => e.args !== undefined);
+        const skippedLegacy = candidates.length - eligibleWithArgs.length;
+        for (const event of eligibleWithArgs) {
+            io.emit.event({
+                type: 'migrate_plan',
+                ts: now(),
+                eventId: event.id,
+                tool: event.tool,
+                target: event.target,
+                args: event.args,
+            }, () => `[plan] ${event.id} → ${event.tool}(${JSON.stringify(event.args)}) on ${event.target.kind}:${event.target.path}`);
+        }
+        if (recordIntent) {
+            const intent = log.append({
+                agent: 'host',
+                sessionId: `migrate-${Date.now().toString(36)}`,
+                tool: 'migrate',
+                phase: 'commit',
+                target: { kind: 'other', path: `migrate/intent` },
+                reversible: false,
+                irreversibleReason: 'migrate_intent markers are bookkeeping, not state changes',
+                metadata: {
+                    type: 'migrate_intent',
+                    ...(since ? { sinceEventId: since } : {}),
+                    ...(toolAllow ? { toolAllowlist: Array.from(toolAllow) } : {}),
+                    plannedEventIds: eligibleWithArgs.map((e) => e.id),
+                },
+            });
+            io.emit.event({
+                type: 'migrate_intent_recorded',
+                ts: now(),
+                intentEventId: intent.id,
+                plannedCount: eligibleWithArgs.length,
+                skippedLegacy,
+                nextStep: `Invoke replayEvents() from @inbrowser/agent against your production ToolDispatch. ` +
+                    `Pass { log, dispatch, toolContext } plus the same filters (sinceEventId, toolAllowlist) recorded on this intent.`,
+            }, () => `[recorded] migrate intent ${intent.id}\n` +
+                `  planned: ${eligibleWithArgs.length} events\n` +
+                (skippedLegacy > 0 ? `  skipped (legacy / no args): ${skippedLegacy}\n` : '') +
+                `  next: invoke replayEvents() against your production ToolDispatch.`);
+        }
+        else {
+            io.emit.event({
+                type: 'migrate_summary',
+                ts: now(),
+                plannedCount: eligibleWithArgs.length,
+                skippedLegacy,
+            }, () => `[summary] ${eligibleWithArgs.length} replayable events` +
+                (skippedLegacy > 0 ? ` · ${skippedLegacy} legacy (no args)` : '') +
+                `\n  add --record to append a migrate_intent marker for host pickup.`);
+        }
+        io.emit.finish();
+        return 0;
+    }
+    finally {
+        log.close();
+    }
+}
+//# sourceMappingURL=migrate.js.map

package/dist/cli/commands/migrate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrate.js","sourceRoot":"","sources":["../../../src/cli/commands/migrate.ts"],"names":[],"mappings":"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"}

package/dist/cli/commands/run.d.ts

@@ -0,0 +1,38 @@
+/**
+ * `agent run` — single-session headless runner.
+ *
+ * Inputs (via parsed args): prompt (positional or --prompt) OR a full
+ * JSON payload via --json (stdin or file). Emits events to the chosen
+ * Emitter (ndjson default in non-TTY, text default in TTY) AND writes
+ * the same NDJSON stream to <log-dir>/<sessionId>.ndjson unless
+ * --no-log is set. The final `session_end` event includes the metrics
+ * totals so the log file is self-describing.
+ *
+ * --dry-run short-circuits: emits a single `dry_run_plan` event and
+ * returns 0. No LLM call, no tool dispatch, no sandbox.
+ */
+import type { ChatMessage } from '../../index.js';
+import type { ScenarioId } from '../fixtures.js';
+import type { Emitter } from '../output.js';
+import type { ParsedArgs } from '../parse.js';
+import { openSessionLog } from '../session-log.js';
+export interface RunPayload {
+    prompt: string;
+    scenario?: ScenarioId;
+    maxTurns?: number;
+    sessionId?: string;
+    history?: ChatMessage[];
+}
+export interface RunCommandIO {
+    emit: Emitter;
+    /** Reads --json file content. Defaults to fs.readFileSync. */
+    readFile?: (path: string) => string;
+    /** Reads stdin synchronously. Defaults to a Bun/Node compatible reader. */
+    readStdin?: () => string;
+    /** Override the timer for deterministic tests. */
+    now?: () => string;
+    /** Inject a session-log factory (tests pass a no-op or an in-memory one). */
+    openLog?: typeof openSessionLog;
+}
+export declare function runCommand(args: ParsedArgs, io: RunCommandIO): Promise<number>;
+//# sourceMappingURL=run.d.ts.map

package/dist/cli/commands/run.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/run.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAMH,OAAO,KAAK,EACV,WAAW,EAKZ,MAAM,gBAAgB,CAAC;AAOxB,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAEjD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAE5C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EAAmB,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAEpE,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,UAAU,CAAC;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,WAAW,EAAE,CAAC;CACzB;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,OAAO,CAAC;IACd,8DAA8D;IAC9D,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC;IACpC,2EAA2E;IAC3E,SAAS,CAAC,EAAE,MAAM,MAAM,CAAC;IACzB,kDAAkD;IAClD,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,6EAA6E;IAC7E,OAAO,CAAC,EAAE,OAAO,cAAc,CAAC;CACjC;AAkQD,wBAAsB,UAAU,CAAC,IAAI,EAAE,UAAU,EAAE,EAAE,EAAE,YAAY,GAAG,OAAO,CAAC,MAAM,CAAC,CA4UpF"}