@inbrowser/agent 0.0.0-placeholder → 0.2.0

package/AGENTS.md

@@ -0,0 +1,270 @@
+# AGENTS.md — `@inbrowser/agent`
+
+This file is for AI agents driving the `agent` CLI. Read it before
+your first invocation. Invariants are listed first; rationale and
+worked examples follow.
+
+## Invariants (always-do)
+
+1. **Pipe NDJSON.** The CLI auto-selects `--output ndjson` when stdout
+   is not a TTY. Parse each line as a JSON object. Never grep prose.
+2. **Use `--json -` for mutating commands** when the input contains
+   anything non-trivial (newlines, JSON, long prompts). The raw
+   payload maps 1:1 to the run signature — no flag translation loss.
+3. **Use `--dry-run` first** when you're about to mutate state. `run`
+   and `fleet` honor it; the response is a single `dry_run_plan`
+   event you can inspect before re-invoking without the flag.
+4. **Filter with `--fields`** when you only need a slice of each
+   event. Example: `--fields ts,type,sessionId,ok,summary`. Saves
+   tokens proportional to event payload size.
+5. **Trust `--help --json` (or pipe to `cat`).** When stdout is not a
+   TTY, `agent help <command>` emits a structured object. When it
+   is, you get prose. The structure is the contract.
+6. **Treat `session_end` as the source of truth.** Its `totals` field
+   has the canonical cost / tokens summary; everything before it can
+   be transient.
+
+## Don't (anti-patterns)
+
+- Don't parse text output. It's for humans. The TTY format is not
+  versioned.
+- Don't infer the schema from `--help`. Call `agent schema` or
+  `agent describe` and cache the result.
+- Don't write session ids by hand if you can let the CLI generate
+  them. Generated ids are guaranteed to pass hardening.
+- Don't pass paths with `..` or URL-encoded segments. The hardening
+  layer rejects them and you'll burn a turn on the retry.
+
+## Workflow patterns
+
+### Run a single session, capture totals
+
+```bash
+agent run --json - <<'EOF'
+{"prompt": "build a chess board", "scenario": "write-rules", "maxTurns": 4}
+EOF
+```
+
+Or programmatically: take the last NDJSON line, parse it, and read
+`totals.tokensTotal` and `totals.costUsd`.
+
+### Discover the schema
+
+```bash
+agent schema                    # full CliSpec
+agent describe --target events  # NDJSON event catalog only
+```
+
+The schema's `commands[*].options[*]` includes the same `validate`
+rules the parser enforces — you can pre-validate inputs in your
+agent before invoking.
+
+### Validate without side effects
+
+```bash
+agent run --prompt "$PROMPT" --dry-run
+agent fleet --size 10 --dry-run
+```
+
+Each emits exactly one `dry_run_plan` event.
+
+### Run many sessions in parallel
+
+```bash
+agent fleet --size 10
+```
+
+The `fleet_summary` event at the end reports per-session totals plus
+an `isolated` boolean. Treat `isolated: false` as a hard failure.
+
+## Per-session logs
+
+Every `run` writes its full event stream to:
+
+```
+~/.pyric/sessions/<sessionId>.ndjson
+```
+
+Last line is always `session_end` with totals. Tail with:
+
+```bash
+tail -1 ~/.pyric/sessions/<sessionId>.ndjson | jq '.totals'
+```
+
+Override with `--log-dir <abs-path>`. Disable with `--no-log`.
+
+## Wrap on the producer, NOT on the consumer
+
+**Critical invariant for anyone using `wrapMutating()` + `replayEvents()`.**
+
+Wrap your handlers on the system that **produces** the log (the dev
+environment, the agent session that generates mutations). Do NOT
+wrap on the system that **consumes** the log via `replayEvents`. If
+you do, each replayed event spawns its own plan+commit cascade on
+the target log — and a subsequent replay run would try to re-replay
+those, ad infinitum.
+
+```
+   DEV (producer)                         PROD (replay consumer)
+   ──────────────                         ──────────────────────
+   wrapMutating(setDoc, { log, ... })     setDoc                  ← bare!
+                                          deleteDoc               ← bare!
+```
+
+`isWrappedHandler(handler)` returns `true` for any output of
+`wrapMutating`. Use it to assert your prod registry is safe before
+calling `replayEvents` against it.
+
+## Non-JSON-safe types — use a codec
+
+`wrapMutating` stores `args`, `before`, `after` in the log. The
+default `JSON.stringify` is lossy for the exact types real Firebase
+code uses (`Timestamp`, `FieldValue.serverTimestamp()`,
+`DocumentReference`, `Date`, `Uint8Array`, `bigint`). Without a
+codec, replay can silently write the wrong types to prod.
+
+The shipped default `defaultEventValueCodec` handles the universal
+non-JSON types — `Date`, `Uint8Array`, `bigint` — via tagged
+envelopes. For Firestore-specific types, compose your own codec on
+top using `walkValue`:
+
+```ts
+import { composeCodecs, defaultEventValueCodec, openEventLog, walkValue, type EventValueCodec, ENVELOPE_KEY } from '@inbrowser/agent';
+import { Timestamp } from 'firebase-admin/firestore';
+
+const firestoreCodec: EventValueCodec = {
+  encode: (v) => walkValue(v, (n) => {
+    if (n instanceof Timestamp) return { [ENVELOPE_KEY]: 'Timestamp', seconds: n.seconds, nanoseconds: n.nanoseconds };
+    return undefined;
+  }),
+  decode: (v) => walkValue(v, (n) => {
+    if (typeof n === 'object' && n !== null && (n as any).__pyric === 'Timestamp') {
+      return new Timestamp((n as any).seconds, (n as any).nanoseconds);
+    }
+    return undefined;
+  }),
+};
+
+const codec = composeCodecs(firestoreCodec, defaultEventValueCodec);
+const log = openEventLog({ projectId: 'my-app', codec });
+// Pass the same codec to `openEventLog` on the prod side so decode matches.
+```
+
+`identityCodec` is also available for tests / when args are known
+JSON-clean (slightly cheaper since it skips the walk).
+
+## Per-project event log (observability + undo)
+
+Distinct from the per-session log above. Every **mutating tool** that
+wraps itself in `wrapMutating()` from `@inbrowser/agent` emits one or more
+events to:
+
+```
+~/.pyric/projects/<projectId>/events.ndjson
+```
+
+Each event has a stable id, a phase (`plan` | `commit` | `rollback`),
+a target (`{kind, path}`), optional `before`/`after` snapshots, and —
+when the API permits rollback — a `reverseOp` (`{tool, args}`) that
+`agent undo` can invoke.
+
+Read the log:
+
+```bash
+agent events --project my-app                                 # full log
+agent events --project my-app --phase commit                  # just commits
+agent events --project my-app --tool writeRules               # one tool
+agent events --project my-app --session sess-2026-05-11-abc   # one session
+agent events --project my-app --since 2026-05-11T00:00:00Z    # time range
+```
+
+Reverse a commit:
+
+```bash
+agent undo --project my-app --event <id> --dry-run            # show plan
+agent undo --project my-app --event <id>                      # record rollback
+```
+
+Important:
+- `agent undo` **does not invoke the reverse tool itself.** It records
+  a `rollback` event referencing the original and surfaces the
+  recorded `reverseOp`. Your host (the playground, a specialized-agent
+  process) is responsible for dispatching the tool — the CLI is a
+  controller surface, not a Firebase admin runtime.
+- Events with `reversible: false` are rejected up front with the
+  recorded `irreversibleReason`.
+- Idempotent — undoing the same event twice returns `AlreadyUndone`
+  (exit 64), never double-rolls.
+
+## Forward replay (dev → prod migrations)
+
+The same log that powers `agent undo` is a forward-replayable migration
+record. Every `commit` event carries the original `args`, so a different
+`ToolDispatch` can re-execute the same operations against a different
+environment (typical case: `dev` simulator log → live Firestore).
+
+CLI surface (planning only):
+
+```bash
+# Plan: list every replayable commit (NDJSON, one `migrate_plan` per event).
+agent migrate --project my-app
+
+# Filter: from a known anchor, restricted to specific tools.
+agent migrate --project my-app --since-event <id> --tools setDoc,writeRules
+
+# Record an intent marker the host can pick up.
+agent migrate --project my-app --record
+```
+
+Host surface (actually replays):
+
+```ts
+import { openEventLog, replayEvents } from '@inbrowser/agent';
+
+const log = openEventLog({ projectId: 'my-app' });           // dev log
+const dispatch = buildProdToolDispatch();                     // your prod registry
+for await (const ev of replayEvents({ log, dispatch, toolContext })) {
+  if (ev.type === 'error') break;
+}
+```
+
+Important:
+- Same controller/runtime split as `agent undo`: the CLI does NOT
+  invoke tools. It records intent + lists the plan; the host calls
+  `replayEvents()` against its production registry.
+- Idempotent across re-runs. Each successfully-applied event gets a
+  `migrate_applied` marker; a re-run skips events whose marker is
+  already present.
+- Legacy events (no `args` field — emitted before the field was added)
+  are skipped by default. Pass `legacyEventPolicy: 'abort'` to fail
+  loudly instead.
+- Reverse direction is `agent undo`; forward direction is `replayEvents()`.
+  They share the same log.
+
+## Exit codes
+
+| Code | Meaning                                     |
+| ---- | ------------------------------------------- |
+| 0    | Success                                     |
+| 1    | Runtime error (session-level)               |
+| 2    | Unhandled exception (CLI bug — file a bug)  |
+| 64   | Usage error or input hardening rejection    |
+
+## Scoring (per agent-dx-cli-scale)
+
+| Axis                                  | Score | Notes                                                                          |
+| ------------------------------------- | ----- | ------------------------------------------------------------------------------ |
+| 1. Machine-Readable Output            | 3     | NDJSON streaming default in non-TTY; JSON errors; structured everywhere.       |
+| 2. Raw Payload Input                  | 3     | `--json -` (stdin) or `--json <file>` for `run`; payload mirrors handler sig.  |
+| 3. Schema Introspection               | 2     | `agent schema`, `agent describe`, `--help --json`. All commands covered.       |
+| 4. Context Window Discipline          | 3     | `--fields` allowlist + per-event NDJSON streaming + `agent events` filters.    |
+| 5. Input Hardening                    | 3     | Rejects control chars, `..`, `%2e`, `?`, `#`, oversized strings; path sandbox. |
+| 6. Safety Rails                       | 3     | `--dry-run` on `run`/`fleet`/`undo`; idempotent undo + replay; irreversible-event gate. |
+| 7. Agent Knowledge Packaging          | 2     | This file + `skills/agent-cli.md`. Versioned with the package.                 |
+| **Total**                             | **19** | **Agent-first**                                                              |
+
+The event log lifts the score on axes 4 and 6: it gives agents a
+typed substrate to audit, reverse, and replay mutations without
+re-scraping provider APIs. `agent migrate` extends the
+controller/runtime split (CLI plans, host dispatches) that `agent undo`
+established — same shape, opposite direction.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 David East
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,118 @@
-# agent.js
+# `@inbrowser/agent`
 
-Browser-native agent runtime. Coming soon.
+Agent runtime + agent-friendly CLI in one package. Three consumer surfaces:
+
+- **Library** — `import { createAgentSession, createToolRegistry, ... }`. Pure TypeScript, no React, no DOM, no fetch. The playground UI consumes the same primitives.
+- **CLI** — the `agent` binary. NDJSON output by default, `--json` stdin, `--dry-run`, schema introspection, automatic session logs.
+- **MCP server** — `agent serve` exposes agent tools over stdio so external LLM hosts (Claude Desktop, others) can drive them as MCP tools.
+
+The library is browser-safe; the CLI and MCP server are Node-only.
+
+## Install
+
+```bash
+bun add @inbrowser/agent
+# or
+npm install @inbrowser/agent
+```
+
+The `agent` binary lands in `./node_modules/.bin/`.
+
+## A 30-second example
+
+### Library
+
+```ts
+import {
+  createAgentSession,
+  createReactLoopStrategy,
+  createToolRegistry,
+  createDispatch,
+  createMetricsCollector,
+} from '@inbrowser/agent';
+
+const session = createAgentSession({
+  strategy: createReactLoopStrategy(),
+  llm: yourLlmClient,
+  tools: createDispatch(createToolRegistry()),
+  toolContext: () => ({ workspace, runtime, sandbox, lint, signal: new AbortController().signal }),
+  metrics: createMetricsCollector(),
+  history: [],
+  id: 'sess-1',
+  systemPromptBuilder: (workspace, runtime) => '…',
+});
+
+for await (const event of session.submit('hello')) {
+  // SessionEvent stream — apply to your store / UI / log
+}
+```
+
+### CLI
+
+```bash
+# Headless single session — text in TTY, NDJSON when piped.
+agent run "build a chess rule set"
+
+# JSON payload via stdin.
+echo '{"prompt": "reset rules"}' | agent run --json -
+
+# 10 isolated sessions in parallel.
+agent fleet --size 10
+```
+
+### MCP server
+
+```bash
+# Expose agent tools over stdio for an external host.
+agent serve --project my-project
+```
+
+### CLI commands
+
+| Command | Purpose |
+|---------|---------|
+| `run` | Headless single session — text in a TTY, NDJSON when piped |
+| `fleet` | Run N isolated sessions in parallel |
+| `serve` | Expose agent tools over MCP stdio |
+| `events` | Inspect a session's event log |
+| `undo` | Roll back the last mutating operation via the event log |
+| `describe` | Print tool schemas / session metadata |
+| `schema` | Emit machine-readable schema introspection |
+| `migrate` | Migrate session logs / event-log format |
+| `version`, `help` | Version string and usage |
+
+## Subpath exports
+
+| Entry | Surface |
+|-------|---------|
+| `@inbrowser/agent` | Browser-safe library — `createAgentSession`, `createToolRegistry`, strategies, metrics, storage adapters, event utilities |
+| `@inbrowser/agent/cli` | Node-only CLI internals — `main`, command handlers, arg parsing, the `CLI_SPEC` |
+| `@inbrowser/agent/node` | Node-only event-log writer — `openEventLog`, `buildRollbackEvent`, id generation |
+
+## Where to go next
+
+Documentation is organised under [`docs/`](./docs/) following the [Diataxis](https://diataxis.fr/) framework:
+
+| If you want to | Read |
+|---|---|
+| Follow a complete lesson | [Tutorials](./docs/tutorials/) |
+| Accomplish a specific task | [How-to guides](./docs/how-to/) |
+| Look up a function, event, or CLI flag | [Reference](./docs/reference/) |
+| Understand the design choices | [Explanation](./docs/explanation/) |
+
+### Starting points by role
+
+- **Building an agent in code?** Start with [Drive a session from your code](./docs/tutorials/01-drive-a-session-from-code.md).
+- **Running the CLI?** Start with [Run the agent CLI](./docs/tutorials/02-run-the-agent-cli.md).
+- **Exposing tools to an external host?** Start with [Serve agents over MCP](./docs/tutorials/03-serve-agents-over-mcp.md).
+- **Implementing a new LLM provider?** See [Implement a custom `LlmClient`](./docs/how-to/implement-llm-client.md).
+
+## Position in the stack
+
+`@inbrowser/agent` is the agent runtime — independent of domain packages. Hosts compose it with their own `AgentDefinition`s; the bare CLI ships zero built-ins.
+
+See [Inference vs inverse architectures](./docs/explanation/inference-vs-inverse.md) for the two distinct consumer modes.
+
+## Licence
+
+Same as the parent workspace.

package/bin/agent.ts

@@ -0,0 +1,10 @@
+#!/usr/bin/env bun
+/**
+ * `agent` CLI entry. All logic lives in `src/cli/` so the package
+ * can be both `import { main } from '@inbrowser/agent/cli'` and a
+ * shebang-runnable binary. Treat this file as a one-liner.
+ */
+import { main } from '../src/cli/main.js';
+
+const code = await main();
+process.exit(code);

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

@@ -0,0 +1,14 @@
+/**
+ * `agent describe` — emit machine-readable descriptions of CLI subjects.
+ * Targets:
+ *   - commands: the subcommand tree from `spec.ts`
+ *   - scenarios: scripted LLM fixtures + their turn shapes
+ *   - events: the NDJSON event-type catalog the CLI emits
+ *   - all: a single combined object (default)
+ *
+ * Always emits exactly one event so it's safe to pipe through `jq`.
+ */
+import type { Emitter } from '../output.js';
+import type { ParsedArgs } from '../parse.js';
+export declare function describeCommand(args: ParsedArgs, emit: Emitter): number;
+//# sourceMappingURL=describe.d.ts.map

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

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

package/dist/cli/commands/describe.js

@@ -0,0 +1,179 @@
+/**
+ * `agent describe` — emit machine-readable descriptions of CLI subjects.
+ * Targets:
+ *   - commands: the subcommand tree from `spec.ts`
+ *   - scenarios: scripted LLM fixtures + their turn shapes
+ *   - events: the NDJSON event-type catalog the CLI emits
+ *   - all: a single combined object (default)
+ *
+ * Always emits exactly one event so it's safe to pipe through `jq`.
+ */
+import { CLI_SPEC } from '../spec.js';
+const SCENARIOS = [
+    {
+        id: 'echo',
+        description: 'Echoes the user prompt back as text. Single turn, no tool calls.',
+        turns: 1,
+    },
+    {
+        id: 'write-rules',
+        description: 'Two-turn flow: turn 0 emits a tool_call (writeRules), turn 1 emits a summary text response.',
+        turns: 2,
+    },
+];
+const EVENTS = [
+    {
+        type: 'session_start',
+        whenEmitted: 'first event of every run',
+        fields: ['ts', 'sessionId', 'scenario', 'maxTurns'],
+    },
+    {
+        type: 'turn_start',
+        whenEmitted: 'beginning of each agent turn',
+        fields: ['ts', 'sessionId', 'turn'],
+    },
+    {
+        type: 'thinking',
+        whenEmitted: 'streaming reasoning chunk (if provided)',
+        fields: ['ts', 'sessionId', 'chunk'],
+    },
+    {
+        type: 'text',
+        whenEmitted: 'streaming assistant text chunk',
+        fields: ['ts', 'sessionId', 'chunk'],
+    },
+    {
+        type: 'tool_call',
+        whenEmitted: 'agent invokes a tool',
+        fields: ['ts', 'sessionId', 'name', 'callId', 'args'],
+    },
+    {
+        type: 'tool_result',
+        whenEmitted: 'tool dispatch finishes',
+        fields: ['ts', 'sessionId', 'callId', 'ok', 'summary'],
+    },
+    {
+        type: 'workspace_changed',
+        whenEmitted: 'tool result patches the workspace',
+        fields: ['ts', 'sessionId', 'rulesLength', 'codeLength'],
+    },
+    {
+        type: 'turn_end',
+        whenEmitted: 'turn metrics finalized',
+        fields: ['ts', 'sessionId', 'turn', 'metrics'],
+    },
+    {
+        type: 'sandbox_event',
+        whenEmitted: 'sandbox observer event',
+        fields: ['ts', 'sessionId', 'kind', 'detail'],
+    },
+    {
+        type: 'strategy_event',
+        whenEmitted: 'strategy-level milestone',
+        fields: ['ts', 'sessionId', 'name', 'data'],
+    },
+    {
+        type: 'session_error',
+        whenEmitted: 'session-level error from the strategy',
+        fields: ['ts', 'sessionId', 'message'],
+    },
+    {
+        type: 'session_end',
+        whenEmitted: 'last event of every run, carries totals',
+        fields: ['ts', 'sessionId', 'totals', 'logPath', 'exit'],
+    },
+    {
+        type: 'fleet_start',
+        whenEmitted: 'agent fleet, before launching members',
+        fields: ['ts', 'size', 'members'],
+    },
+    {
+        type: 'fleet_summary',
+        whenEmitted: 'agent fleet, after all members complete',
+        fields: ['ts', 'size', 'elapsedMs', 'isolated', 'aggregateTokens', 'results'],
+    },
+    {
+        type: 'dry_run_plan',
+        whenEmitted: 'when --dry-run is set; replaces all runtime events',
+        fields: ['ts', 'command', 'sessionId?', 'scenario?', 'logPath?'],
+    },
+    {
+        type: 'undo_plan',
+        whenEmitted: '`agent undo --dry-run`: plan only, no rollback recorded',
+        fields: ['ts', 'eventId', 'originalTool', 'target', 'reverseOp'],
+    },
+    {
+        type: 'undo_recorded',
+        whenEmitted: '`agent undo`: rollback event appended to the log',
+        fields: ['ts', 'rollbackEventId', 'eventId', 'reverseOp', 'nextStep'],
+    },
+    {
+        type: 'migrate_plan',
+        whenEmitted: '`agent migrate`: one per replayable commit (the forward direction)',
+        fields: ['ts', 'eventId', 'tool', 'target', 'args'],
+    },
+    {
+        type: 'migrate_summary',
+        whenEmitted: '`agent migrate` (no --record): final summary line',
+        fields: ['ts', 'plannedCount', 'skippedLegacy'],
+    },
+    {
+        type: 'migrate_intent_recorded',
+        whenEmitted: '`agent migrate --record`: intent marker appended to log',
+        fields: ['ts', 'intentEventId', 'plannedCount', 'nextStep'],
+    },
+    {
+        type: 'mutation_event',
+        whenEmitted: '`agent events`: every line is one MutationEvent from the project log',
+        fields: [
+            'id',
+            'ts',
+            'agent',
+            'sessionId',
+            'tool',
+            'args?',
+            'phase',
+            'target',
+            'before?',
+            'after?',
+            'reversible',
+            'reverseOp?',
+            'metadata?',
+        ],
+    },
+    {
+        type: 'error',
+        whenEmitted: 'CLI-level error (parsing, hardening, file resolution)',
+        fields: ['ts', 'name', 'message', 'field?', 'reason?'],
+    },
+];
+export function describeCommand(args, emit) {
+    const target = args.options['target'] ?? 'all';
+    const payload = (() => {
+        if (target === 'commands')
+            return { commands: CLI_SPEC.commands };
+        if (target === 'scenarios')
+            return { scenarios: SCENARIOS };
+        if (target === 'events')
+            return { events: EVENTS };
+        return {
+            cli: { name: CLI_SPEC.name, version: CLI_SPEC.version, description: CLI_SPEC.description },
+            commands: CLI_SPEC.commands,
+            globalOptions: CLI_SPEC.globalOptions,
+            scenarios: SCENARIOS,
+            events: EVENTS,
+        };
+    })();
+    emit.event({ type: 'describe', target, ...payload }, () => {
+        if (target === 'commands' || target === 'all') {
+            return CLI_SPEC.commands.map((c) => `${c.name.padEnd(10)} ${c.description}`).join('\n');
+        }
+        if (target === 'scenarios') {
+            return SCENARIOS.map((s) => `${s.id.padEnd(14)} ${s.description}`).join('\n');
+        }
+        return EVENTS.map((e) => `${e.type.padEnd(20)} ${e.whenEmitted}`).join('\n');
+    });
+    emit.finish();
+    return 0;
+}
+//# sourceMappingURL=describe.js.map

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

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

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

@@ -0,0 +1,21 @@
+/**
+ * `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';
+import type { Emitter } from '../output.js';
+import type { ParsedArgs } from '../parse.js';
+export interface EventsCommandIO {
+    emit: Emitter;
+    /** Injectable for tests; defaults to `openEventLog`. */
+    openLog?: typeof openEventLog;
+}
+export declare function eventsCommand(args: ParsedArgs, io: EventsCommandIO): number;
+//# sourceMappingURL=events.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/events.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAEnD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,OAAO,CAAC;IACd,wDAAwD;IACxD,OAAO,CAAC,EAAE,OAAO,YAAY,CAAC;CAC/B;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,UAAU,EAAE,EAAE,EAAE,eAAe,GAAG,MAAM,CA+C3E"}