@inbrowser/agent 0.0.0-placeholder → 0.1.0

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":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AAIH,OAAO,EAAiB,aAAa,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAuCjF;;;;GAIG;AACH,MAAM,CAAC,MAAM,cAAc,GAAkB,MAAM,CAAC,GAAG,CAAC,+BAA+B,CAAC,CAAC;AAEzF;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAAC,OAAoB;IACnD,OAAQ,OAA8C,CAAC,cAAc,CAAC,KAAK,IAAI,CAAC;AAClF,CAAC;AAED,MAAM,UAAU,YAAY,CAC1B,OAA0B,EAC1B,IAA+B;IAE/B,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,IAAI,aAAa,CAAC;IAE1C,MAAM,OAAO,GAAsB;QACjC,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,WAAW,EAAE,OAAO,CAAC,WAAW;QAChC,UAAU,EAAE,OAAO,CAAC,UAAU;QAC9B,GAAG,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,OAAO,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC9D,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG;YACrB,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;YACtC,MAAM,MAAM,GAAG,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;YAE1E,MAAM,SAAS,GAAkB,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC;gBAC/C,KAAK;gBACL,SAAS,EAAE,IAAI,CAAC,SAAS;gBACzB,IAAI,EAAE,OAAO,CAAC,IAAI;gBAClB,IAAI;gBACJ,KAAK,EAAE,MAAM;gBACb,MAAM;gBACN,GAAG,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBAC3C,UAAU,EAAE,IAAI,CAAC,mBAAmB,IAAI,CAAC,CAAC,IAAI,CAAC,SAAS;gBACxD,GAAG,CAAC,IAAI,CAAC,kBAAkB,CAAC,CAAC,CAAC,EAAE,kBAAkB,EAAE,IAAI,CAAC,kBAAkB,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBACnF,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aACtD,CAAC,CAAC;YACH,KAAK,SAAS,CAAC;YAEf,IAAI,MAAqB,CAAC;YAC1B,IAAI,CAAC;gBACH,MAAM,GAAG,MAAM,OAAO,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;YAC5C,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,IAAI,CAAC,GAAG,CAAC,MAAM,CACb,kBAAkB,CAAC;oBACjB,QAAQ,EAAE,SAAS;oBACnB,MAAM,EAAE,SAAS;oBACjB,KAAK;oBACL,SAAS,EAAE,IAAI,CAAC,SAAS;iBAC1B,CAAC,CACH,CAAC;gBACF,MAAM,GAAG,CAAC;YACZ,CAAC;YAED,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;YAEpF,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC;gBACd,KAAK;gBACL,SAAS,EAAE,IAAI,CAAC,SAAS;gBACzB,IAAI,EAAE,OAAO,CAAC,IAAI;gBAClB,IAAI;gBACJ,KAAK,EAAE,QAAQ;gBACf,MAAM;gBACN,GAAG,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBAC3C,KAAK,EAAE,MAAM,CAAC,IAAI;gBAClB,UAAU,EAAE,CAAC,CAAC,SAAS;gBACvB,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBACnC,GAAG,CAAC,SAAS;oBACX,CAAC,CAAC,EAAE;oBACJ,CAAC,CAAC,IAAI,CAAC,kBAAkB;wBACvB,CAAC,CAAC,EAAE,kBAAkB,EAAE,IAAI,CAAC,kBAAkB,EAAE;wBACjD,CAAC,CAAC,EAAE,CAAC;gBACT,QAAQ,EAAE;oBACR,GAAG,CAAC,IAAI,CAAC,QAAQ,IAAI,EAAE,CAAC;oBACxB,WAAW,EAAE,SAAS,CAAC,EAAE;oBACzB,EAAE,EAAE,MAAM,CAAC,EAAE;oBACb,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;iBACvD;aACF,CAAC,CAAC;YAEH,OAAO,MAAM,CAAC;QAChB,CAAC;KACF,CAAC;IACF,8DAA8D;IAC9D,iEAAiE;IACjE,MAAM,CAAC,cAAc,CAAC,OAAO,EAAE,cAAc,EAAE;QAC7C,KAAK,EAAE,IAAI;QACX,UAAU,EAAE,KAAK;QACjB,QAAQ,EAAE,KAAK;QACf,YAAY,EAAE,KAAK;KACpB,CAAC,CAAC;IACH,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,52 @@
+/**
+ * `@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 } from './tools.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, StrategyRunInput, StrategyEvent, } from './types/strategy.js';
+export { createReactLoopStrategy } from './strategy.js';
+export type { Tracer, TraceEvent, LlmRequestTrace, LlmResponseTrace, ToolDeclarationView, } from './types/trace.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,37 @@
+/**
+ * `@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 } from './tools.js';
+export { DEFAULT_CAPABILITIES } from './types/capabilities.js';
+export { createAgentSession } from './session.js';
+export { createReactLoopStrategy } from './strategy.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

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAcvD,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAqBnD,OAAO,EAAE,yBAAyB,EAAE,MAAM,kBAAkB,CAAC;AAuB7D,OAAO,EAAE,kBAAkB,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAGhE,OAAO,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AAO/D,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAOlD,OAAO,EAAE,uBAAuB,EAAE,MAAM,eAAe,CAAC;AAexD,OAAO,EACL,kBAAkB,EAClB,sBAAsB,EACtB,WAAW,GACZ,MAAM,cAAc,CAAC;AAGtB,OAAO,EAAE,WAAW,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AACtE,OAAO,EAAE,yBAAyB,EAAE,MAAM,cAAc,CAAC;AAMzD,OAAO,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AA+BrE,kEAAkE;AAClE,oEAAoE;AACpE,wDAAwD;AACxD,yEAAyE;AACzE,oCAAoC;AACpC,EAAE;AACF,kEAAkE;AAClE,0EAA0E;AAC1E,OAAO,EAAE,YAAY,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAElF,OAAO,EAAE,YAAY,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAExE,OAAO,EACL,sBAAsB,EACtB,aAAa,EACb,aAAa,EACb,SAAS,EACT,YAAY,GACb,MAAM,mBAAmB,CAAC"}

package/dist/llm-adapter.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Adapter from the playground's existing `LlmProvider` shape to the
+ * core `LlmClient` interface. Lets new core code (AgentSession,
+ * AgentStrategy) consume providers via the narrow event-stream
+ * surface without each provider needing a refactor.
+ *
+ * The existing `LlmProvider` is callback-based (`onText`,
+ * `onToolCall`, etc.) and lives in the React host alongside its
+ * BYOK forms + localStorage wiring. This file flips it into the
+ * `AsyncIterable<ChatEvent>` shape the core wants.
+ *
+ * Each provider can later migrate to natively implement `LlmClient`
+ * to drop this adapter. The plan calls this "slice 4 — one
+ * provider at a time"; the adapter exists so slice 4 doesn't have
+ * to land atomically.
+ */
+import type { LlmClient } from './types/llm.js';
+/**
+ * Minimal external surface the adapter expects. Matches the shape
+ * `examples/admin-compat-browser/src/llm.ts` exports. We re-declare
+ * it here so `@inbrowser/agent` doesn't import from the playground.
+ */
+export interface LegacyProviderUsage {
+    promptTokens?: number;
+    outputTokens?: number;
+    totalTokens?: number;
+    costUsd?: number;
+    costEstimated?: boolean;
+    cachedTokens?: number;
+    reasoningTokens?: number;
+    isByok?: boolean;
+}
+export interface LegacyTurnDetails {
+    generationId?: string;
+    servedModel?: string;
+    requestedModel?: string;
+    fingerprint?: string;
+    routing?: Record<string, unknown>;
+}
+export interface LegacyChatTurnResult {
+    text?: string;
+    thinking?: string;
+    finishReason?: 'stop' | 'tool' | 'abort' | 'error';
+    usage?: LegacyProviderUsage;
+    details?: LegacyTurnDetails;
+}
+export interface LegacyChatCallbacks {
+    onText(chunk: string): void;
+    onThinking?(chunk: string): void;
+    onToolCall(call: {
+        callId: string;
+        name: string;
+        args: unknown;
+        signature?: string;
+    }): void;
+    signal?: AbortSignal;
+}
+export interface LegacyToolDecl {
+    name: string;
+    description: string;
+    parameters: unknown;
+}
+export interface LegacyChatMessage {
+    role: 'system' | 'user' | 'assistant' | 'tool';
+    text?: string;
+    toolCalls?: {
+        callId: string;
+        name: string;
+        args: unknown;
+        signature?: string;
+    }[];
+    callId?: string;
+    name?: string;
+    resultJson?: string;
+}
+export interface LegacyProvider {
+    readonly label: string;
+    readonly supportsTools?: boolean;
+    chatWithTools?(messages: LegacyChatMessage[], tools: LegacyToolDecl[], callbacks: LegacyChatCallbacks): Promise<LegacyChatTurnResult>;
+    ask(prompt: string, onChunk: (chunk: string) => void, options?: {
+        signal?: AbortSignal;
+    }): Promise<LegacyChatTurnResult>;
+}
+/**
+ * Wrap a legacy `LlmProvider` instance in the `LlmClient` shape.
+ * The adapter:
+ *
+ *   - Translates `ChatRequest` → legacy `chatWithTools` / `ask`
+ *     call.
+ *   - Buffers callback events into an async queue and replays them
+ *     as a `ChatEvent` `AsyncIterable`.
+ *   - Forwards the final usage + details as a `turn_complete`
+ *     event before closing the stream.
+ */
+export declare function legacyProviderAsLlmClient(legacy: LegacyProvider, id: string): LlmClient;
+//# sourceMappingURL=llm-adapter.d.ts.map

package/dist/llm-adapter.d.ts.map

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