@inbrowser/agent 0.0.0-placeholder → 0.2.0

package/dist/events/replay.d.ts

@@ -0,0 +1,106 @@
+/**
+ * `replayEvents()` — forward replay of a project's event log against a
+ * caller-supplied `ToolDispatch`.
+ *
+ * Pair to `wrapMutating()` + `agent undo`:
+ *   - `wrapMutating` writes structured events as a side effect of
+ *     running tools.
+ *   - `undoCommand` walks the log backwards (commit → rollback) to
+ *     reverse a single mutation.
+ *   - `replayEvents()` walks the log forwards (`commit` events in id
+ *     order) and re-dispatches each tool with its recorded args, so
+ *     the same mutations can be re-applied to a *different* dispatch
+ *     (typical case: dev simulator → production registry).
+ *
+ * Idempotency:
+ *   - Each successfully-applied event gets a `migrate_applied` marker
+ *     event written back to the same log (or a separate target log
+ *     when `targetLog` is provided). Re-running `replayEvents()` skips
+ *     events whose marker is already present, so partial-failure +
+ *     retry is safe.
+ *   - The caller can additionally provide `shouldApply` to gate
+ *     events. The callback fires for every event (it is NOT a
+ *     conflict-only hook); the caller is responsible for whatever
+ *     state-read or business logic decides apply / skip / abort.
+ *
+ * Boundaries:
+ *   - This function calls `dispatch.execute()`. It is therefore
+ *     *not* CLI-safe — it expects a real dispatch wired to real
+ *     services. The `agent migrate` subcommand only PLANS replay; the
+ *     host runs `replayEvents()` against its prod dispatch.
+ *   - **The dispatch handlers MUST be unwrapped.** If you re-apply
+ *     `wrapMutating()` at replay time, each replayed event spawns a
+ *     fresh plan/commit pair on the target log — and a subsequent
+ *     replay run would try to re-replay those. Wrap on the system
+ *     that PRODUCES the log; do not wrap on the system that CONSUMES
+ *     it via replay.
+ */
+import type { MutationEvent } from '../types/events.js';
+import type { ToolContext, ToolDispatch, ToolResult } from '../types/tools.js';
+import type { EventLog } from './log-core.js';
+export interface ReplayOptions {
+    /** Source log to read commits from. */
+    log: EventLog;
+    /** Dispatch to invoke each replayed tool against.
+     *  **MUST register unwrapped handlers** — see file header. */
+    dispatch: ToolDispatch;
+    /** Factory producing a fresh `ToolContext` per dispatch call. */
+    toolContext(): ToolContext;
+    /** Replay only events with id >= this id (inclusive). Lexically
+     *  compared — works because event ids are time-prefixed base36. */
+    sinceEventId?: string;
+    /** Restrict to these tool names. Unset → replay every commit. */
+    toolAllowlist?: readonly string[];
+    /** Skip events whose `target.path` matches any of these. */
+    pathDenyList?: readonly string[];
+    /**
+     * Per-event resolver. Fires for every event *after* it passes the
+     * tool / path / already-applied filters. Use it to read target
+     * state and decide apply / skip / abort — replayEvents itself does
+     * not read target state. Default: 'apply' for all events.
+     *
+     * Renamed from the previous `onConflict` to better reflect what it
+     * actually does (it is not a conflict-only hook).
+     */
+    shouldApply?: (event: MutationEvent) => 'apply' | 'skip' | 'abort';
+    /** When true: emit `plan` progress events but do NOT call dispatch.
+     *  No `migrate_applied` markers are written. */
+    dryRun?: boolean;
+    /** Optional separate log to write the `migrate_applied` markers
+     *  into. Defaults to the source log. Useful when the prod
+     *  environment maintains its own event log. */
+    targetLog?: EventLog;
+    /** Agent identifier stamped on the `migrate_applied` markers.
+     *  Defaults to 'replay'. */
+    agent?: string;
+    /** Session id stamped on markers. Defaults to a synthesized id. */
+    sessionId?: string;
+}
+export type ReplayProgress = {
+    type: 'plan';
+    event: MutationEvent;
+} | {
+    type: 'applied';
+    event: MutationEvent;
+    markerId: string;
+    result: ToolResult;
+} | {
+    type: 'skipped';
+    event: MutationEvent;
+    reason: 'already_applied' | 'tool_denied' | 'path_denied' | 'shouldapply_skip';
+} | {
+    type: 'error';
+    event: MutationEvent;
+    message: string;
+} | {
+    type: 'done';
+    total: number;
+    applied: number;
+    skipped: number;
+    errors: number;
+};
+export declare class ReplayInvariantError extends Error {
+    readonly name = "ReplayInvariantError";
+}
+export declare function replayEvents(opts: ReplayOptions): AsyncIterable<ReplayProgress>;
+//# sourceMappingURL=replay.d.ts.map

package/dist/events/replay.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"replay.d.ts","sourceRoot":"","sources":["../../src/events/replay.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC/E,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAE9C,MAAM,WAAW,aAAa;IAC5B,uCAAuC;IACvC,GAAG,EAAE,QAAQ,CAAC;IACd;kEAC8D;IAC9D,QAAQ,EAAE,YAAY,CAAC;IACvB,iEAAiE;IACjE,WAAW,IAAI,WAAW,CAAC;IAC3B;uEACmE;IACnE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,iEAAiE;IACjE,aAAa,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,4DAA4D;IAC5D,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC;;;;;;;;OAQG;IACH,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,OAAO,GAAG,MAAM,GAAG,OAAO,CAAC;IACnE;oDACgD;IAChD,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;;mDAE+C;IAC/C,SAAS,CAAC,EAAE,QAAQ,CAAC;IACrB;gCAC4B;IAC5B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,mEAAmE;IACnE,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,MAAM,cAAc,GACtB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,aAAa,CAAA;CAAE,GACtC;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,KAAK,EAAE,aAAa,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,UAAU,CAAA;CAAE,GAC/E;IACE,IAAI,EAAE,SAAS,CAAC;IAChB,KAAK,EAAE,aAAa,CAAC;IACrB,MAAM,EAAE,iBAAiB,GAAG,aAAa,GAAG,aAAa,GAAG,kBAAkB,CAAC;CAChF,GACD;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,aAAa,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACxD;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAItF,qBAAa,oBAAqB,SAAQ,KAAK;IAC7C,SAAkB,IAAI,0BAA0B;CACjD;AAED,wBAAuB,YAAY,CAAC,IAAI,EAAE,aAAa,GAAG,aAAa,CAAC,cAAc,CAAC,CAyGtF"}

package/dist/events/replay.js

@@ -0,0 +1,137 @@
+/**
+ * `replayEvents()` — forward replay of a project's event log against a
+ * caller-supplied `ToolDispatch`.
+ *
+ * Pair to `wrapMutating()` + `agent undo`:
+ *   - `wrapMutating` writes structured events as a side effect of
+ *     running tools.
+ *   - `undoCommand` walks the log backwards (commit → rollback) to
+ *     reverse a single mutation.
+ *   - `replayEvents()` walks the log forwards (`commit` events in id
+ *     order) and re-dispatches each tool with its recorded args, so
+ *     the same mutations can be re-applied to a *different* dispatch
+ *     (typical case: dev simulator → production registry).
+ *
+ * Idempotency:
+ *   - Each successfully-applied event gets a `migrate_applied` marker
+ *     event written back to the same log (or a separate target log
+ *     when `targetLog` is provided). Re-running `replayEvents()` skips
+ *     events whose marker is already present, so partial-failure +
+ *     retry is safe.
+ *   - The caller can additionally provide `shouldApply` to gate
+ *     events. The callback fires for every event (it is NOT a
+ *     conflict-only hook); the caller is responsible for whatever
+ *     state-read or business logic decides apply / skip / abort.
+ *
+ * Boundaries:
+ *   - This function calls `dispatch.execute()`. It is therefore
+ *     *not* CLI-safe — it expects a real dispatch wired to real
+ *     services. The `agent migrate` subcommand only PLANS replay; the
+ *     host runs `replayEvents()` against its prod dispatch.
+ *   - **The dispatch handlers MUST be unwrapped.** If you re-apply
+ *     `wrapMutating()` at replay time, each replayed event spawns a
+ *     fresh plan/commit pair on the target log — and a subsequent
+ *     replay run would try to re-replay those. Wrap on the system
+ *     that PRODUCES the log; do not wrap on the system that CONSUMES
+ *     it via replay.
+ */
+const APPLIED_MARKER_TYPE = 'migrate_applied';
+export class ReplayInvariantError extends Error {
+    name = 'ReplayInvariantError';
+}
+export async function* replayEvents(opts) {
+    const targetLog = opts.targetLog ?? opts.log;
+    const agent = opts.agent ?? 'replay';
+    const sessionId = opts.sessionId ?? `replay-${Date.now().toString(36)}`;
+    const toolAllow = opts.toolAllowlist ? new Set(opts.toolAllowlist) : null;
+    const pathDeny = opts.pathDenyList ? new Set(opts.pathDenyList) : null;
+    const applied = opts.dryRun ? new Set() : targetLog.appliedEventIds();
+    const all = opts.log
+        .read({ phase: 'commit' })
+        // Markers written by a prior `replayEvents()` run are themselves
+        // commit-phase events — exclude them so re-runs don't try to
+        // replay bookkeeping rows.
+        .filter((e) => e.metadata?.type !== APPLIED_MARKER_TYPE);
+    // Stable in-emission-order (event ids are lexically sortable by ts prefix).
+    all.sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+    let total = 0;
+    let appliedCount = 0;
+    let skippedCount = 0;
+    let errorCount = 0;
+    for (const event of all) {
+        if (opts.sinceEventId && event.id < opts.sinceEventId)
+            continue;
+        total += 1;
+        if (toolAllow && !toolAllow.has(event.tool)) {
+            yield { type: 'skipped', event, reason: 'tool_denied' };
+            skippedCount += 1;
+            continue;
+        }
+        if (pathDeny && pathDeny.has(event.target.path)) {
+            yield { type: 'skipped', event, reason: 'path_denied' };
+            skippedCount += 1;
+            continue;
+        }
+        if (event.args === undefined) {
+            // Every commit event written by wrapMutating carries args. An
+            // event without args is either a bookkeeping marker (caught
+            // above) or a manually-appended commit that didn't follow the
+            // protocol — fail loudly rather than silently skipping.
+            throw new ReplayInvariantError(`event ${event.id} has phase=commit and target.kind=${event.target.kind} but no args. ` +
+                `Commit events emitted by wrapMutating always carry args. ` +
+                `If you're appending commits manually, include args. ` +
+                `Reading log: ${opts.log.path}`);
+        }
+        if (!opts.dryRun && applied.has(event.id)) {
+            yield { type: 'skipped', event, reason: 'already_applied' };
+            skippedCount += 1;
+            continue;
+        }
+        if (opts.dryRun) {
+            yield { type: 'plan', event };
+            continue;
+        }
+        const decision = opts.shouldApply ? opts.shouldApply(event) : 'apply';
+        if (decision === 'abort') {
+            yield { type: 'error', event, message: 'shouldApply returned abort' };
+            errorCount += 1;
+            return;
+        }
+        if (decision === 'skip') {
+            yield { type: 'skipped', event, reason: 'shouldapply_skip' };
+            skippedCount += 1;
+            continue;
+        }
+        try {
+            const result = await opts.dispatch.execute({ id: `replay-${event.id}`, name: event.tool, args: event.args }, opts.toolContext());
+            if (!result.ok) {
+                yield { type: 'error', event, message: result.summary };
+                errorCount += 1;
+                continue;
+            }
+            const marker = targetLog.append({
+                agent,
+                sessionId,
+                tool: event.tool,
+                phase: 'commit',
+                target: { kind: 'other', path: `replay/${event.id}` },
+                reversible: false,
+                irreversibleReason: 'migrate_applied markers are bookkeeping, not state changes',
+                metadata: {
+                    type: APPLIED_MARKER_TYPE,
+                    appliedEventId: event.id,
+                    originalTool: event.tool,
+                    originalTarget: event.target,
+                },
+            });
+            yield { type: 'applied', event, markerId: marker.id, result };
+            appliedCount += 1;
+        }
+        catch (err) {
+            yield { type: 'error', event, message: err instanceof Error ? err.message : String(err) };
+            errorCount += 1;
+        }
+    }
+    yield { type: 'done', total, applied: appliedCount, skipped: skippedCount, errors: errorCount };
+}
+//# sourceMappingURL=replay.js.map

package/dist/events/replay.js.map

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

package/dist/events/wrap.d.ts

@@ -0,0 +1,100 @@
+/**
+ * `wrapMutating()` — decorate a `ToolHandler` so every invocation emits
+ * plan + commit (or plan + rollback) events to a project's event log.
+ *
+ * Each wrapped handler is still a regular `ToolHandler` — it can be
+ * registered in any `ToolRegistry` and dispatched normally. The
+ * wrapping is invisible to the strategy / session.
+ *
+ * ## CRITICAL INVARIANT: wrap on the producer, NOT on the consumer
+ *
+ * Wrap your handlers on the system that PRODUCES the log (the dev
+ * environment, the agent session generating mutations). Do NOT wrap
+ * the handlers on the system that CONSUMES the log via
+ * `replayEvents()`. If you do:
+ *
+ *   1. Each replayed event spawns its own plan/commit pair on the
+ *      target log (not just a `migrate_applied` marker).
+ *   2. A subsequent replay run sees those new commits and tries to
+ *      re-replay them — loop possible.
+ *
+ * In code: dev registers `wrapMutating(setDoc, {...})`. Prod
+ * registers the BARE `setDoc` (no wrap). `replayEvents` dispatches
+ * dev's log against prod's bare registry. Markers go to the log;
+ * mutations go to prod state. Auditable from either side.
+ *
+ * Use `isWrappedHandler(handler)` to assert: a defensive check
+ * before dispatching unknown registries through replay.
+ *
+ * ## Pattern
+ *
+ *   const wrapped = wrapMutating(writeRulesHandler, {
+ *     log,
+ *     sessionId: 'sess-1',
+ *     target: (args) => ({ kind: 'workspace', path: 'workspace.rules' }),
+ *     snapshot: async (_args, ctx) => ctx.workspace.rules,
+ *     reverseOp: (args, _result) => ({
+ *       tool: 'writeRules',
+ *       args: { source: args.previousSource },
+ *     }),
+ *   });
+ *
+ * ## Failure semantics
+ *
+ *   - Handler throws / promise rejects → emit rollback event with
+ *     `reason: 'failure'`, re-throw. The strategy / dispatcher sees
+ *     the error normally.
+ *   - Handler returns `{ ok: false }` → still emit commit (the
+ *     mutation didn't happen, but the *intent* was reached and the
+ *     audit log should show the attempt + result). Most external API
+ *     handlers follow this pattern.
+ */
+import type { MutationTarget, ReverseOp } from '../types/events.js';
+import type { ToolContext, ToolHandler, ToolResult } from '../types/tools.js';
+import { type EventLog } from './log-core.js';
+export interface WrapMutatingOptions<A, D> {
+    /** Where to append events. */
+    log: EventLog;
+    /** Session id used on every event. Same id as the active AgentSession. */
+    sessionId: string;
+    /** Naming the agent that's invoking this tool. Default: `'host'`. */
+    agent?: string;
+    /** Compute the `target` field from the handler's args. Called for
+     *  both the plan and commit events. */
+    target: (args: A, ctx: ToolContext) => MutationTarget;
+    /** Optional snapshot of the *before* state. Called once, before
+     *  execute. Returned value lands on the plan event AND the commit
+     *  event so an auditor can diff. */
+    snapshot?: (args: A, ctx: ToolContext) => Promise<unknown> | unknown;
+    /** Compute the reverse operation. Called after a successful execute.
+     *  Receives the `before` value `opts.snapshot` returned (or `undefined`
+     *  when no snapshot was configured) so the reverse can restore the
+     *  exact pre-mutation state. Return `null` (or omit the option) for
+     *  irreversible mutations — the commit event then carries
+     *  `reversible: false`. */
+    reverseOp?: (args: A, result: ToolResult<D>, ctx: ToolContext, before: unknown) => ReverseOp | null;
+    /** When `reverseOp` is omitted entirely (not just returning null on
+     *  a given call), default to false. Set to true for handlers that
+     *  *could* be reversible but don't need to declare the reverse op
+     *  ahead of time (rare). */
+    reversibleByDefault?: boolean;
+    /** When the mutation is irreversible, why. Surfaced to `agent undo`. */
+    irreversibleReason?: string;
+    /** Optional static metadata stamped on every event from this tool. */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Non-enumerable marker added to every `wrapMutating()` output.
+ * Used by `isWrappedHandler` to assert "this handler is NOT what
+ * you want in a prod replay target."
+ */
+export declare const WRAPPED_MARKER: unique symbol;
+/**
+ * Returns true when `handler` was produced by `wrapMutating()`.
+ * Use this in your replay target's setup to assert that no handler
+ * is wrapped — wrapped handlers in a replay target spawn runaway
+ * plan/commit cascades. See `wrapMutating`'s header.
+ */
+export declare function isWrappedHandler(handler: ToolHandler): boolean;
+export declare function wrapMutating<A = unknown, D = unknown>(handler: ToolHandler<A, D>, opts: WrapMutatingOptions<A, D>): ToolHandler<A, D>;
+//# sourceMappingURL=wrap.d.ts.map

package/dist/events/wrap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wrap.d.ts","sourceRoot":"","sources":["../../src/events/wrap.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AAEH,OAAO,KAAK,EAAiB,cAAc,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AACnF,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC9E,OAAO,EAAE,KAAK,QAAQ,EAAqC,MAAM,eAAe,CAAC;AAEjF,MAAM,WAAW,mBAAmB,CAAC,CAAC,EAAE,CAAC;IACvC,8BAA8B;IAC9B,GAAG,EAAE,QAAQ,CAAC;IACd,0EAA0E;IAC1E,SAAS,EAAE,MAAM,CAAC;IAClB,qEAAqE;IACrE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;2CACuC;IACvC,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,GAAG,EAAE,WAAW,KAAK,cAAc,CAAC;IACtD;;wCAEoC;IACpC,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,GAAG,EAAE,WAAW,KAAK,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC;IACrE;;;;;+BAK2B;IAC3B,SAAS,CAAC,EAAE,CACV,IAAI,EAAE,CAAC,EACP,MAAM,EAAE,UAAU,CAAC,CAAC,CAAC,EACrB,GAAG,EAAE,WAAW,EAChB,MAAM,EAAE,OAAO,KACZ,SAAS,GAAG,IAAI,CAAC;IACtB;;;gCAG4B;IAC5B,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B,wEAAwE;IACxE,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,sEAAsE;IACtE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED;;;;GAIG;AACH,eAAO,MAAM,cAAc,EAAE,OAAO,MAAoD,CAAC;AAEzF;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAE9D;AAED,wBAAgB,YAAY,CAAC,CAAC,GAAG,OAAO,EAAE,CAAC,GAAG,OAAO,EACnD,OAAO,EAAE,WAAW,CAAC,CAAC,EAAE,CAAC,CAAC,EAC1B,IAAI,EAAE,mBAAmB,CAAC,CAAC,EAAE,CAAC,CAAC,GAC9B,WAAW,CAAC,CAAC,EAAE,CAAC,CAAC,CA+EnB"}

package/dist/events/wrap.js

@@ -0,0 +1,141 @@
+/**
+ * `wrapMutating()` — decorate a `ToolHandler` so every invocation emits
+ * plan + commit (or plan + rollback) events to a project's event log.
+ *
+ * Each wrapped handler is still a regular `ToolHandler` — it can be
+ * registered in any `ToolRegistry` and dispatched normally. The
+ * wrapping is invisible to the strategy / session.
+ *
+ * ## CRITICAL INVARIANT: wrap on the producer, NOT on the consumer
+ *
+ * Wrap your handlers on the system that PRODUCES the log (the dev
+ * environment, the agent session generating mutations). Do NOT wrap
+ * the handlers on the system that CONSUMES the log via
+ * `replayEvents()`. If you do:
+ *
+ *   1. Each replayed event spawns its own plan/commit pair on the
+ *      target log (not just a `migrate_applied` marker).
+ *   2. A subsequent replay run sees those new commits and tries to
+ *      re-replay them — loop possible.
+ *
+ * In code: dev registers `wrapMutating(setDoc, {...})`. Prod
+ * registers the BARE `setDoc` (no wrap). `replayEvents` dispatches
+ * dev's log against prod's bare registry. Markers go to the log;
+ * mutations go to prod state. Auditable from either side.
+ *
+ * Use `isWrappedHandler(handler)` to assert: a defensive check
+ * before dispatching unknown registries through replay.
+ *
+ * ## Pattern
+ *
+ *   const wrapped = wrapMutating(writeRulesHandler, {
+ *     log,
+ *     sessionId: 'sess-1',
+ *     target: (args) => ({ kind: 'workspace', path: 'workspace.rules' }),
+ *     snapshot: async (_args, ctx) => ctx.workspace.rules,
+ *     reverseOp: (args, _result) => ({
+ *       tool: 'writeRules',
+ *       args: { source: args.previousSource },
+ *     }),
+ *   });
+ *
+ * ## Failure semantics
+ *
+ *   - Handler throws / promise rejects → emit rollback event with
+ *     `reason: 'failure'`, re-throw. The strategy / dispatcher sees
+ *     the error normally.
+ *   - Handler returns `{ ok: false }` → still emit commit (the
+ *     mutation didn't happen, but the *intent* was reached and the
+ *     audit log should show the attempt + result). Most external API
+ *     handlers follow this pattern.
+ */
+import { HOST_AGENT_ID, buildRollbackEvent } from './log-core.js';
+/**
+ * Non-enumerable marker added to every `wrapMutating()` output.
+ * Used by `isWrappedHandler` to assert "this handler is NOT what
+ * you want in a prod replay target."
+ */
+export const WRAPPED_MARKER = Symbol.for('@inbrowser/agent/wrapMutating');
+/**
+ * Returns true when `handler` was produced by `wrapMutating()`.
+ * Use this in your replay target's setup to assert that no handler
+ * is wrapped — wrapped handlers in a replay target spawn runaway
+ * plan/commit cascades. See `wrapMutating`'s header.
+ */
+export function isWrappedHandler(handler) {
+    return handler[WRAPPED_MARKER] === true;
+}
+export function wrapMutating(handler, opts) {
+    const agent = opts.agent ?? HOST_AGENT_ID;
+    const wrapped = {
+        name: handler.name,
+        description: handler.description,
+        parameters: handler.parameters,
+        ...(handler.available ? { available: handler.available } : {}),
+        async execute(args, ctx) {
+            const target = opts.target(args, ctx);
+            const before = opts.snapshot ? await opts.snapshot(args, ctx) : undefined;
+            const planEvent = opts.log.append({
+                agent,
+                sessionId: opts.sessionId,
+                tool: handler.name,
+                args,
+                phase: 'plan',
+                target,
+                ...(before !== undefined ? { before } : {}),
+                reversible: opts.reversibleByDefault ?? !!opts.reverseOp,
+                ...(opts.irreversibleReason ? { irreversibleReason: opts.irreversibleReason } : {}),
+                ...(opts.metadata ? { metadata: opts.metadata } : {}),
+            });
+            void planEvent;
+            let result;
+            try {
+                result = await handler.execute(args, ctx);
+            }
+            catch (err) {
+                opts.log.append(buildRollbackEvent({
+                    original: planEvent,
+                    reason: 'failure',
+                    agent,
+                    sessionId: opts.sessionId,
+                }));
+                throw err;
+            }
+            const reverseOp = opts.reverseOp ? opts.reverseOp(args, result, ctx, before) : null;
+            opts.log.append({
+                agent,
+                sessionId: opts.sessionId,
+                tool: handler.name,
+                args,
+                phase: 'commit',
+                target,
+                ...(before !== undefined ? { before } : {}),
+                after: result.data,
+                reversible: !!reverseOp,
+                ...(reverseOp ? { reverseOp } : {}),
+                ...(reverseOp
+                    ? {}
+                    : opts.irreversibleReason
+                        ? { irreversibleReason: opts.irreversibleReason }
+                        : {}),
+                metadata: {
+                    ...(opts.metadata ?? {}),
+                    planEventId: planEvent.id,
+                    ok: result.ok,
+                    ...(result.summary ? { summary: result.summary } : {}),
+                },
+            });
+            return result;
+        },
+    };
+    // Stamp the wrapped marker as a non-enumerable property so it
+    // doesn't leak into JSON serialization (e.g. inside tool decls).
+    Object.defineProperty(wrapped, WRAPPED_MARKER, {
+        value: true,
+        enumerable: false,
+        writable: false,
+        configurable: false,
+    });
+    return wrapped;
+}
+//# sourceMappingURL=wrap.js.map

package/dist/events/wrap.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,73 @@
+/**
+ * `@inbrowser/agent` — agent runtime + agent-friendly CLI.
+ *
+ * The library surface (this module) exports the primitives the
+ * playground UI consumes: `AgentSession`, `AgentStrategy`, `ToolRegistry`,
+ * `LlmClient`, `MetricsCollector`, `SandboxObserver`, plus the default
+ * `createReactLoopStrategy()` and `createAgentSession()`.
+ *
+ * The CLI surface lives under `@inbrowser/agent/cli` and the `agent` binary
+ * — see `src/cli/main.ts` and the package's `AGENTS.md` for invariants.
+ *
+ * No React, no DOM, no localStorage, no fetch. All I/O is via injected
+ * interfaces.
+ */
+export type { Workspace, StitchContext } from './types/workspace.js';
+export { EMPTY_WORKSPACE } from './types/workspace.js';
+export type { ProjectContext } from './types/project-context.js';
+export type { RuntimeState, TerminalSection, TerminalEntry, RunSummary, DeployState, DeployMessage, ParseError, UiError, } from './types/runtime.js';
+export { EMPTY_RUNTIME } from './types/runtime.js';
+export type { ChatMessage, ChatRole, ToolCall as ChatToolCall, TurnMetrics, TurnDetails, NormalizedMessage, } from './types/chat.js';
+export type { LlmClient, LlmClientFactory, LlmConfig, ChatRequest, ChatEvent, ToolDeclaration, JsonSchema, RawUsage, } from './types/llm.js';
+export { legacyProviderAsLlmClient } from './llm-adapter.js';
+export type { LegacyProvider, LegacyChatTurnResult, LegacyChatCallbacks, LegacyChatMessage, LegacyToolDecl, LegacyProviderUsage, LegacyTurnDetails, } from './llm-adapter.js';
+export type { ToolHandler, ToolContext, ToolResult, ToolCall, ToolRegistry, ToolDispatch, SandboxHandle, LintFn, LintWarning, StitchClient, } from './types/tools.js';
+export { createToolRegistry, createDispatch, isParallelSafe, isPure } from './tools.js';
+export type { MemoKeyComponent, MemoOptions, MemoStats, MemoizedDispatch, } from './dispatch-memoization.js';
+export { createMemoizedDispatch } from './dispatch-memoization.js';
+export type { Capabilities } from './types/capabilities.js';
+export { DEFAULT_CAPABILITIES } from './types/capabilities.js';
+export type { AgentSession, AgentSessionConfig, SessionEvent, } from './types/session.js';
+export { createAgentSession } from './session.js';
+export type { AgentStrategy, ReflexionConfig, StrategyRunInput, StrategyEvent, } from './types/strategy.js';
+export { createReactLoopStrategy } from './strategy.js';
+export type { PlanStep, SkillCatalog, SkillCatalogEntry } from './skill-catalog.js';
+export { SKILL_CATALOG, getSkillEntry, listSkillNames } from './skill-catalog.js';
+export type { RouterDecision, RouterMatch, RouterOptions } from './skill-router.js';
+export { routeSkill } from './skill-router.js';
+export type { PlannerExecutorOptions, SkillRouter, SkillRouterDecision, SkillRouterMatch, } from './planner-executor.js';
+export { createPlannerExecutorStrategy, defaultKeywordRouter } from './planner-executor.js';
+export type { Tracer, TraceEvent, LlmRequestTrace, LlmResponseTrace, TurnDispatchCompleteTrace, ToolDeclarationView, } from './types/trace.js';
+export type { TurnTimingRow } from './diagnostics/timing.js';
+export { turnTimingTable } from './diagnostics/timing.js';
+export type { TruthfulnessFlag, TruthfulnessFlagCategory, TruthfulnessReport, } from './diagnostics/index.js';
+export { analyzeTruthfulness } from './diagnostics/index.js';
+export type { PartialWorkspace, RunSnapshot, SkillName, SpecFn, SpecRegistry, SpecResult, SuccessSpecReference, TaskFixture, ValidationError, ValidationResult, } from './eval/index.js';
+export { CUSTOM_SPEC_NAMES, SKILL_NAMES, SPEC_FINAL_RULES_EXCLUDES_LITERAL, SPEC_FINAL_RULES_INCLUDES_LITERAL, SPEC_FINAL_RUNTIME_RUN_SUMMARY_OK, SPEC_GAME_RULES_SIMULATOR_ACCEPTS_POSITIVE_AND_REJECTS_CHEAT, SPEC_PYRIC_AGENTS_LINT_CLEAN_AND_RULE_REJECTS_CHEAT, SPEC_REPORT_MENTIONS_ALL_OF, SPEC_REPORT_MENTIONS_AT_LEAST_ONE_OF, SPEC_TRACE_CONTAINS_TOOL_CALL_BY_NAME, STARTER_SPEC_NAMES, applyWorkspaceOverrides, createSpecRegistry, evaluateSpec, finalRulesExcludesLiteral, finalRulesIncludesLiteral, finalRuntimeRunSummaryOk, gameRulesSimulatorAcceptsPositiveAndRejectsCheat, parseFixture, pyricAgentsLintCleanAndRuleRejectsCheat, registerAllSpecs, registerCustomSpecs, registerStarterSpecs, reportMentionsAllOf, reportMentionsAtLeastOneOf, traceContainsToolCallByName, validateFixture, } from './eval/index.js';
+export type { RunRecord as EvalRunRecord } from './eval/run-record.js';
+export type { RunFixtureInput, RunFixturesDeps, RunFixturesOptions, } from './eval/runner.js';
+export { defaultSystemPromptBuilder, runFixture, runFixtures } from './eval/runner.js';
+export type { AggregateStat, AggregatedMetrics, CollectMetricsInput, MetricsTable, TrialMetrics, } from './eval/metric-collector.js';
+export { aggregateTrials, collectMetrics, extractTrialMetrics, } from './eval/metric-collector.js';
+export type { CompareMetricsInput, ComparisonFixture, ComparisonLabel, ComparisonMetricName, ComparisonReport, ComparisonRow, Polarity, } from './eval/comparison-report.js';
+export { POLARITY, compareMetrics, renderJson, renderMarkdown, } from './eval/comparison-report.js';
+export type { MetricsCollector, RecordTurnInput, SessionTotals, } from './types/metrics.js';
+export { computeTurnMetrics, createMetricsCollector, findPricing, } from './metrics.js';
+export type { Storage } from './types/storage.js';
+export { noopStorage, createMemoryStorage } from './types/storage.js';
+export { createLocalStorageAdapter } from './storage.js';
+export type { ObserverEvent, SandboxObserver, } from './types/observer.js';
+export { combineObservers, noopObserver } from './types/observer.js';
+export type { AgentDefinition, AgentTool, AgentContext, AgentToolResult, } from './types/agent.js';
+export type { ServeAgentsOptions, ServeAgentsHandle } from './mcp/serve.js';
+export type { RunRecord, RunRecordFilter, RunLog, OpenRunLogOptions, } from './metrics/runs.js';
+export type { MutationEvent, MutationEventFilter, MutationPhase, MutationTarget, ReverseOp, TargetKind, } from './types/events.js';
+export { wrapMutating, isWrappedHandler, WRAPPED_MARKER } from './events/wrap.js';
+export type { WrapMutatingOptions } from './events/wrap.js';
+export { replayEvents, ReplayInvariantError } from './events/replay.js';
+export type { ReplayOptions, ReplayProgress } from './events/replay.js';
+export { defaultEventValueCodec, identityCodec, composeCodecs, walkValue, ENVELOPE_KEY, } from './events/codec.js';
+export type { EventValueCodec } from './events/codec.js';
+export type { EventLog, AppendDraft } from './events/log-core.js';
+export type { EventLogIO, OpenEventLogOptions } from './events/log.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

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

package/dist/index.js

@@ -0,0 +1,47 @@
+/**
+ * `@inbrowser/agent` — agent runtime + agent-friendly CLI.
+ *
+ * The library surface (this module) exports the primitives the
+ * playground UI consumes: `AgentSession`, `AgentStrategy`, `ToolRegistry`,
+ * `LlmClient`, `MetricsCollector`, `SandboxObserver`, plus the default
+ * `createReactLoopStrategy()` and `createAgentSession()`.
+ *
+ * The CLI surface lives under `@inbrowser/agent/cli` and the `agent` binary
+ * — see `src/cli/main.ts` and the package's `AGENTS.md` for invariants.
+ *
+ * No React, no DOM, no localStorage, no fetch. All I/O is via injected
+ * interfaces.
+ */
+export { EMPTY_WORKSPACE } from './types/workspace.js';
+export { EMPTY_RUNTIME } from './types/runtime.js';
+export { legacyProviderAsLlmClient } from './llm-adapter.js';
+export { createToolRegistry, createDispatch, isParallelSafe, isPure } from './tools.js';
+export { createMemoizedDispatch } from './dispatch-memoization.js';
+export { DEFAULT_CAPABILITIES } from './types/capabilities.js';
+export { createAgentSession } from './session.js';
+export { createReactLoopStrategy } from './strategy.js';
+export { SKILL_CATALOG, getSkillEntry, listSkillNames } from './skill-catalog.js';
+export { routeSkill } from './skill-router.js';
+export { createPlannerExecutorStrategy, defaultKeywordRouter } from './planner-executor.js';
+export { turnTimingTable } from './diagnostics/timing.js';
+export { analyzeTruthfulness } from './diagnostics/index.js';
+export { CUSTOM_SPEC_NAMES, SKILL_NAMES, SPEC_FINAL_RULES_EXCLUDES_LITERAL, SPEC_FINAL_RULES_INCLUDES_LITERAL, SPEC_FINAL_RUNTIME_RUN_SUMMARY_OK, SPEC_GAME_RULES_SIMULATOR_ACCEPTS_POSITIVE_AND_REJECTS_CHEAT, SPEC_PYRIC_AGENTS_LINT_CLEAN_AND_RULE_REJECTS_CHEAT, SPEC_REPORT_MENTIONS_ALL_OF, SPEC_REPORT_MENTIONS_AT_LEAST_ONE_OF, SPEC_TRACE_CONTAINS_TOOL_CALL_BY_NAME, STARTER_SPEC_NAMES, applyWorkspaceOverrides, createSpecRegistry, evaluateSpec, finalRulesExcludesLiteral, finalRulesIncludesLiteral, finalRuntimeRunSummaryOk, gameRulesSimulatorAcceptsPositiveAndRejectsCheat, parseFixture, pyricAgentsLintCleanAndRuleRejectsCheat, registerAllSpecs, registerCustomSpecs, registerStarterSpecs, reportMentionsAllOf, reportMentionsAtLeastOneOf, traceContainsToolCallByName, validateFixture, } from './eval/index.js';
+export { defaultSystemPromptBuilder, runFixture, runFixtures } from './eval/runner.js';
+export { aggregateTrials, collectMetrics, extractTrialMetrics, } from './eval/metric-collector.js';
+export { POLARITY, compareMetrics, renderJson, renderMarkdown, } from './eval/comparison-report.js';
+export { computeTurnMetrics, createMetricsCollector, findPricing, } from './metrics.js';
+export { noopStorage, createMemoryStorage } from './types/storage.js';
+export { createLocalStorageAdapter } from './storage.js';
+export { combineObservers, noopObserver } from './types/observer.js';
+// Browser-safe events utilities — wrap, replay, codec. These live
+// in files that don't import `node:fs` / `node:os`, so they're safe
+// on the universal entry. Import them DIRECTLY (not via
+// `./events/index.js`) because that barrel re-exports `./events/log.js`,
+// which DOES pull in Node builtins.
+//
+// Node-only event log values (openEventLog, defaultProjectLogDir,
+// HOST_AGENT_ID, etc.) live on `@inbrowser/agent/node` — see src/node.ts.
+export { wrapMutating, isWrappedHandler, WRAPPED_MARKER } from './events/wrap.js';
+export { replayEvents, ReplayInvariantError } from './events/replay.js';
+export { defaultEventValueCodec, identityCodec, composeCodecs, walkValue, ENVELOPE_KEY, } from './events/codec.js';
+//# sourceMappingURL=index.js.map