@inbrowser/agent 0.0.0-placeholder → 0.2.0

package/dist/tools.js

@@ -0,0 +1,147 @@
+/**
+ * `ToolRegistry` + `ToolDispatch` runtime implementations.
+ *
+ * The interfaces ship in slice 1 (`./types/tools.ts`). This module
+ * provides:
+ *
+ *   - `createToolRegistry()` — the basic in-memory registry.
+ *   - `createDispatch(registry)` — stateless executor that looks up
+ *     by name and invokes the handler with the supplied `ToolContext`.
+ *
+ * Both are pure-TS — no React, no stores, no localStorage.
+ */
+export function createToolRegistry() {
+    const handlers = new Map();
+    function clone() {
+        return new Map(handlers);
+    }
+    function makeFromMap(map) {
+        return {
+            register(handler) {
+                const existing = map.get(handler.name);
+                if (existing) {
+                    // Include both descriptions when available so the
+                    // composer can spot which two factories shipped the
+                    // same tool name without spelunking through stack
+                    // traces.
+                    const existingDesc = truncate(existing.description ?? '', 80);
+                    const newDesc = truncate(handler.description ?? '', 80);
+                    throw new Error(`ToolRegistry: tool '${handler.name}' is already registered.\n` +
+                        `  Previously registered: ${existingDesc || '(no description)'}\n` +
+                        `  New registration:      ${newDesc || '(no description)'}\n` +
+                        `  Use \`registry.replace(handler)\` if this overlay is intentional.`);
+                }
+                map.set(handler.name, handler);
+            },
+            replace(handler) {
+                map.set(handler.name, handler);
+            },
+            unregister(name) {
+                return map.delete(name);
+            },
+            list(opts) {
+                // No capability filter → return every registered handler.
+                // With a capability filter → drop handlers whose `available`
+                // hook returns false. Handlers without an `available` hook
+                // always pass.
+                const out = [];
+                if (opts?.capabilities === undefined) {
+                    for (const h of map.values())
+                        out.push(h);
+                    return out;
+                }
+                const caps = opts.capabilities;
+                for (const h of map.values()) {
+                    if (h.available && !h.available(caps))
+                        continue;
+                    out.push(h);
+                }
+                return out;
+            },
+            has(name) {
+                return map.has(name);
+            },
+            fork() {
+                // Fresh map cloning the current snapshot; later registrations
+                // on the forked registry don't affect the parent.
+                return makeFromMap(new Map(map));
+            },
+        };
+    }
+    return makeFromMap(handlers);
+}
+/**
+ * Create a stateless dispatcher over a registry. The dispatcher
+ * holds a reference to the registry — list/register/unregister calls
+ * on the registry are seen by the dispatcher on the next `execute`.
+ *
+ * Error shape: handlers that throw turn into `{ ok: false, summary:
+ * <message> }` results so the caller's `for await` loop doesn't have
+ * to wrap every tool invocation in a try/catch. The thrown value is
+ * stringified into the summary.
+ */
+export function createDispatch(registry) {
+    return {
+        async execute(call, ctx) {
+            // We look up via the underlying `list` to avoid exposing a
+            // public `get(name)` on the registry — `list()` already enforces
+            // capability filtering, but for `execute` we should run any
+            // registered handler the caller has on file regardless of
+            // capability (the caller's job to gate before calling).
+            const candidate = findByName(registry, call.name);
+            if (!candidate) {
+                return {
+                    ok: false,
+                    summary: `Unknown tool: ${call.name}`,
+                };
+            }
+            try {
+                const args = call.args;
+                return await candidate.execute(args, ctx);
+            }
+            catch (e) {
+                return {
+                    ok: false,
+                    summary: `Tool ${call.name} threw: ${e instanceof Error ? e.message : String(e)}`,
+                };
+            }
+        },
+    };
+}
+/**
+ * Find a handler by name without exposing a `get` method on the
+ * registry interface. Public consumers always go through `list()`;
+ * the dispatcher (a friend of the registry) uses this internal
+ * lookup.
+ */
+function findByName(registry, name) {
+    if (!registry.has(name))
+        return undefined;
+    // The registry doesn't expose a `get`; list() with no capability
+    // filter returns every handler — find by name from there.
+    const all = registry.list();
+    return all.find((h) => h.name === name);
+}
+/**
+ * Read `handler.parallelSafe` with the conservative default. The default
+ * when the field is absent or `false` is `false` — callers must opt in
+ * explicitly. Centralised so parallel-dispatch and any future scheduler
+ * apply the same rule.
+ */
+export function isParallelSafe(handler) {
+    return handler.parallelSafe === true;
+}
+/**
+ * Read `handler.pure` with the conservative default. The default when
+ * the field is absent or `false` is `false` — callers must opt in. The
+ * memoization layer reads this through here so a future change to the
+ * default (not in this branch) lands in a single spot.
+ */
+export function isPure(handler) {
+    return handler.pure === true;
+}
+/** Trim a string to `max` chars with an ellipsis marker. */
+function truncate(s, max) {
+    return s.length <= max ? s : `${s.slice(0, max)}…`;
+}
+//# sourceMappingURL=tools.js.map

package/dist/tools.js.map

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

package/dist/types/agent.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Inverse-mode types — see `plans/inverse-mode-architecture.md`.
+ *
+ * In inference mode, an agent owns its LlmClient + conversation and the
+ * strategy drives a turn-by-turn loop calling `ToolHandler`s. In inverse
+ * mode, an external LLM host (Claude Code, Claude Desktop) drives the
+ * conversation and calls *behavior-named* `AgentTool`s one-shot.
+ *
+ * AgentTool is intentionally distinct from ToolHandler:
+ *   - `ToolHandler` carries session-coupled context (workspace, runtime,
+ *     sandbox, lint) that the inference loop maintains across turns.
+ *   - `AgentTool` is a pure(-ish) function over input + minimal context.
+ *     No conversation state. Plan/commit chaining is per-tool, enforced
+ *     via planHash, not framework-level.
+ */
+import type { EventLog } from '../events/log-core.js';
+import type { JsonSchema } from './llm.js';
+import type { ProjectContext } from './project-context.js';
+import type { SandboxHandle } from './tools.js';
+/**
+ * A bundle of behavior-named tools that share a domain + (where
+ * applicable) a planHash chain.
+ *
+ * `name` is the developer-facing id (`'hello-firestore'`,
+ * `'firestore-data-modeling'`). It surfaces in `agent describe` and
+ * `--agent` flags. It is NOT what the host LLM sees — each tool's own
+ * `name` is.
+ */
+export interface AgentDefinition {
+    name: string;
+    description: string;
+    tools: AgentTool[];
+}
+/**
+ * One MCP-exposable behavior. The `name` and `description` are what the
+ * host LLM matches against user intent — phrase them as verbs the user
+ * would utter ("design_firestore_schema", not "data_modeling__plan").
+ */
+export interface AgentTool<I = unknown, O = unknown> {
+    name: string;
+    description: string;
+    inputSchema: JsonSchema;
+    execute(input: I, ctx: AgentContext): Promise<AgentToolResult<O>>;
+}
+/**
+ * Per-call context. Distinct from `ToolContext` (the inference-mode
+ * shape): no workspace, no runtime, no lint — those concepts live in
+ * the conversation owner. AgentTools are one-shot from the host's POV.
+ */
+export interface AgentContext {
+    /** Unique per call; correlates the run record + any events emitted. */
+    runId: string;
+    /** Firebase project id — routes the event log + runs log. */
+    projectId: string;
+    /** Append-only mutation log; same one `wrapMutating` writes to. */
+    events: EventLog;
+    /** Cancellation signal. Host typically supplies one per RPC. */
+    signal: AbortSignal;
+    /** Optional sandbox handle for tools that need it. Absent for pure
+     *  computation (e.g. schema design). */
+    sandbox?: SandboxHandle;
+    /** Injectable clock for deterministic tests. */
+    now?: () => number;
+    /**
+     * Initialized `ProjectContext` for tools that need live project
+     * access (admin Firestore reads, REST API rules fetch). Present
+     * when `agent serve` was launched with FIREBASE_SA_BASE64 in env;
+     * absent otherwise. Tools should fail with a clear "needs SA"
+     * message when this is required and missing, not silently no-op.
+     *
+     * Field name preserved (vs. `projectContext`) so the public
+     * AgentContext shape doesn't break external tools that destructure
+     * `ctx.agentApp`; the *type* migrated from `AgentApp` to
+     * `ProjectContext` in Phase C step 13 of the legacy-SDK migration.
+     */
+    agentApp?: ProjectContext;
+}
+export interface AgentToolResult<O = unknown> {
+    ok: boolean;
+    /** One-line summary the host LLM can quote back to the user. */
+    summary: string;
+    /** Structured payload. Host LLM may reference it in follow-up tool calls. */
+    data?: O;
+    /**
+     * Set by preview/plan tools; consumed by the corresponding commit
+     * tool to enforce that the user-approved plan is what gets executed.
+     * Hash content is at the tool author's discretion (typically a SHA
+     * of the canonical JSON of `data`).
+     */
+    planHash?: string;
+    /** Event log ids produced this call. Surfaces to the run record. */
+    eventIds?: string[];
+}
+//# sourceMappingURL=agent.d.ts.map

package/dist/types/agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../src/types/agent.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AACtD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAC3C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD;;;;;;;;GAQG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,SAAS,EAAE,CAAC;CACpB;AAED;;;;GAIG;AACH,MAAM,WAAW,SAAS,CAAC,CAAC,GAAG,OAAO,EAAE,CAAC,GAAG,OAAO;IACjD,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,UAAU,CAAC;IACxB,OAAO,CAAC,KAAK,EAAE,CAAC,EAAE,GAAG,EAAE,YAAY,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,CAAC;CACnE;AAED;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,uEAAuE;IACvE,KAAK,EAAE,MAAM,CAAC;IACd,6DAA6D;IAC7D,SAAS,EAAE,MAAM,CAAC;IAClB,mEAAmE;IACnE,MAAM,EAAE,QAAQ,CAAC;IACjB,gEAAgE;IAChE,MAAM,EAAE,WAAW,CAAC;IACpB;4CACwC;IACxC,OAAO,CAAC,EAAE,aAAa,CAAC;IACxB,gDAAgD;IAChD,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,EAAE,cAAc,CAAC;CAC3B;AAED,MAAM,WAAW,eAAe,CAAC,CAAC,GAAG,OAAO;IAC1C,EAAE,EAAE,OAAO,CAAC;IACZ,gEAAgE;IAChE,OAAO,EAAE,MAAM,CAAC;IAChB,6EAA6E;IAC7E,IAAI,CAAC,EAAE,CAAC,CAAC;IACT;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,oEAAoE;IACpE,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;CACrB"}

package/dist/types/agent.js

@@ -0,0 +1,17 @@
+/**
+ * Inverse-mode types — see `plans/inverse-mode-architecture.md`.
+ *
+ * In inference mode, an agent owns its LlmClient + conversation and the
+ * strategy drives a turn-by-turn loop calling `ToolHandler`s. In inverse
+ * mode, an external LLM host (Claude Code, Claude Desktop) drives the
+ * conversation and calls *behavior-named* `AgentTool`s one-shot.
+ *
+ * AgentTool is intentionally distinct from ToolHandler:
+ *   - `ToolHandler` carries session-coupled context (workspace, runtime,
+ *     sandbox, lint) that the inference loop maintains across turns.
+ *   - `AgentTool` is a pure(-ish) function over input + minimal context.
+ *     No conversation state. Plan/commit chaining is per-tool, enforced
+ *     via planHash, not framework-level.
+ */
+export {};
+//# sourceMappingURL=agent.js.map

package/dist/types/agent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.js","sourceRoot":"","sources":["../../src/types/agent.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG"}

package/dist/types/capabilities.d.ts

@@ -0,0 +1,17 @@
+/**
+ * `Capabilities` — what the current session can do.
+ *
+ * Computed once per session at start, refreshed at start of each
+ * turn. Drives which tools the agent is told about and which
+ * behaviors the system prompt mentions.
+ */
+export interface Capabilities {
+    /** The active LLM provider advertises tool-use support. */
+    llmSupportsTools: boolean;
+    /** Stitch design tools are available (BYOK present + feature-flag on). */
+    stitchAvailable: boolean;
+    /** Sandbox is initialized and ready to receive tool calls. */
+    sandboxReady: boolean;
+}
+export declare const DEFAULT_CAPABILITIES: Capabilities;
+//# sourceMappingURL=capabilities.d.ts.map

package/dist/types/capabilities.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capabilities.d.ts","sourceRoot":"","sources":["../../src/types/capabilities.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,WAAW,YAAY;IAC3B,2DAA2D;IAC3D,gBAAgB,EAAE,OAAO,CAAC;IAC1B,0EAA0E;IAC1E,eAAe,EAAE,OAAO,CAAC;IACzB,8DAA8D;IAC9D,YAAY,EAAE,OAAO,CAAC;CACvB;AAED,eAAO,MAAM,oBAAoB,EAAE,YAIjB,CAAC"}

package/dist/types/capabilities.js

@@ -0,0 +1,13 @@
+/**
+ * `Capabilities` — what the current session can do.
+ *
+ * Computed once per session at start, refreshed at start of each
+ * turn. Drives which tools the agent is told about and which
+ * behaviors the system prompt mentions.
+ */
+export const DEFAULT_CAPABILITIES = Object.freeze({
+    llmSupportsTools: true,
+    stitchAvailable: false,
+    sandboxReady: false,
+});
+//# sourceMappingURL=capabilities.js.map

package/dist/types/capabilities.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capabilities.js","sourceRoot":"","sources":["../../src/types/capabilities.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAWH,MAAM,CAAC,MAAM,oBAAoB,GAAiB,MAAM,CAAC,MAAM,CAAC;IAC9D,gBAAgB,EAAE,IAAI;IACtB,eAAe,EAAE,KAAK;IACtB,YAAY,EAAE,KAAK;CACpB,CAAiB,CAAC"}

package/dist/types/chat.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Chat message shape — the cross-session transcript surface.
+ *
+ * Matches the playground's existing `ChatMessage` shape closely so
+ * the React host can drop in `@inbrowser/agent` types without
+ * rewriting render code. The neutral shape lets non-React hosts
+ * (CLI, eval harness) consume the same transcripts.
+ */
+export type ChatRole = 'system' | 'user' | 'assistant' | 'tool';
+export interface ChatMessage {
+    id: string;
+    role: ChatRole;
+    text: string;
+    /** Streaming flag — true while the LLM is still emitting chunks. */
+    streaming?: boolean;
+    /** Hidden reasoning ("thinking") text — surface only when the host opts in. */
+    thinking?: string;
+    toolCalls?: ToolCall[];
+    /** Turn-scoped usage + cost — stamped on the assistant message at turn end. */
+    metrics?: TurnMetrics;
+    /** Per-turn detail block (servedModel, requestedModel, fingerprint, …). */
+    details?: TurnDetails;
+    /** Wall-clock milliseconds the turn took. */
+    timestamp?: number;
+}
+export interface ToolCall {
+    id: string;
+    name: string;
+    argsJson: string;
+    /** Stringified result; absent while the call is in flight. */
+    resultJson?: string;
+    ok?: boolean;
+    /** Optional human-readable one-liner the model can quote on the next turn. */
+    summary?: string;
+    /** Provider-specific signature carried through round-trips (Gemini thoughtSignature). */
+    signature?: string;
+}
+export interface TurnMetrics {
+    tokensIn: number;
+    tokensOut: number;
+    tokensCached: number;
+    tokensReasoning: number;
+    costUsd: number;
+    /** True when cost is computed client-side from a pricing table vs returned by the provider. */
+    costEstimated?: boolean;
+    /** True when the user supplied their own key — affects billing display. */
+    isByok?: boolean;
+}
+export interface TurnDetails {
+    /** The model name the host requested. */
+    requestedModel: string;
+    /** The model name the provider actually served (e.g. an OpenRouter routing fallback). */
+    servedModel?: string;
+    /** Provider-stable fingerprint when offered (Gemini systemFingerprint, OpenAI fingerprint). */
+    fingerprint?: string;
+    /** Free-form provider routing info (OpenRouter "provider" field, etc.). */
+    routing?: Record<string, unknown>;
+}
+/** A normalized message shape providers consume — drops React-specific fields like `streaming`. */
+export interface NormalizedMessage {
+    role: ChatRole;
+    text: string;
+    toolCalls?: {
+        callId: string;
+        name: string;
+        args: unknown;
+        signature?: string;
+    }[];
+    /** For `role: 'tool'` only — the result of a previous tool call. */
+    callId?: string;
+    name?: string;
+    resultJson?: string;
+}
+//# sourceMappingURL=chat.d.ts.map

package/dist/types/chat.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chat.d.ts","sourceRoot":"","sources":["../../src/types/chat.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,MAAM,MAAM,QAAQ,GAAG,QAAQ,GAAG,MAAM,GAAG,WAAW,GAAG,MAAM,CAAC;AAEhE,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,QAAQ,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,oEAAoE;IACpE,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,+EAA+E;IAC/E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,QAAQ,EAAE,CAAC;IACvB,+EAA+E;IAC/E,OAAO,CAAC,EAAE,WAAW,CAAC;IACtB,2EAA2E;IAC3E,OAAO,CAAC,EAAE,WAAW,CAAC;IACtB,6CAA6C;IAC7C,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,8DAA8D;IAC9D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,EAAE,CAAC,EAAE,OAAO,CAAC;IACb,8EAA8E;IAC9E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,yFAAyF;IACzF,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,eAAe,EAAE,MAAM,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,+FAA+F;IAC/F,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,2EAA2E;IAC3E,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,WAAW;IAC1B,yCAAyC;IACzC,cAAc,EAAE,MAAM,CAAC;IACvB,yFAAyF;IACzF,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,+FAA+F;IAC/F,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,2EAA2E;IAC3E,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED,mGAAmG;AACnG,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,QAAQ,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,OAAO,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAClF,oEAAoE;IACpE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB"}

package/dist/types/chat.js

@@ -0,0 +1,10 @@
+/**
+ * Chat message shape — the cross-session transcript surface.
+ *
+ * Matches the playground's existing `ChatMessage` shape closely so
+ * the React host can drop in `@inbrowser/agent` types without
+ * rewriting render code. The neutral shape lets non-React hosts
+ * (CLI, eval harness) consume the same transcripts.
+ */
+export {};
+//# sourceMappingURL=chat.js.map

package/dist/types/chat.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chat.js","sourceRoot":"","sources":["../../src/types/chat.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG"}

package/dist/types/events.d.ts

@@ -0,0 +1,115 @@
+/**
+ * `MutationEvent` — the canonical record a mutating tool emits to the
+ * project event log. Three phases:
+ *
+ *   - `plan` — emitted before the tool actually runs. Records intent +
+ *     captured "before" snapshot. Always present.
+ *   - `commit` — emitted after the tool returns successfully. Records
+ *     "after" snapshot + the `reverseOp` (when one exists) so `agent
+ *     undo` can roll it back.
+ *   - `rollback` — emitted when execution failed mid-flight, or when
+ *     `agent undo` reverses a previously-committed event. Helps the
+ *     auditor distinguish "started but never finished" from "finished
+ *     and later undone."
+ *
+ * The log is **append-only NDJSON** at
+ * `~/.pyric/projects/<projectId>/events.ndjson`. The whole point is
+ * that the file is replayable + diffable — never overwrite, never
+ * mutate previous lines.
+ *
+ * See `plans/specialized-firebase-agents.md` §7 for the design rationale.
+ */
+export type MutationPhase = 'plan' | 'commit' | 'rollback';
+export type TargetKind = 'doc' | 'collection' | 'rules' | 'index' | 'service' | 'bucket' | 'hosting' | 'functions' | 'workspace' | 'other';
+export interface MutationTarget {
+    kind: TargetKind;
+    /**
+     * Stable, fully-qualified identifier for the target. Examples:
+     *   - `users/alice`
+     *   - `projects/my-app/rulesets/active`
+     *   - `firebasestorage.googleapis.com`
+     *   - `my-app.firebasestorage.app`
+     *   - `workspace.rules`
+     */
+    path: string;
+    /** Optional friendly label. */
+    label?: string;
+}
+export interface ReverseOp {
+    /** Tool name to invoke to reverse the committed mutation. */
+    tool: string;
+    /** Arguments to pass. The tool MUST be registered in the same
+     *  ToolRegistry the caller used; otherwise undo cannot resolve it. */
+    args: unknown;
+    /** Free-form human-readable description of the reverse action. */
+    description?: string;
+}
+export interface MutationEvent {
+    /** Sortable, opaque event id (timestamp-prefixed). */
+    id: string;
+    /** ISO-8601 timestamp the event was emitted at. */
+    ts: string;
+    /** Agent that emitted it. `'host'` for direct CLI / library use. */
+    agent: string;
+    /** Session id from `AgentSession`. */
+    sessionId: string;
+    /** Tool that did (or planned) the mutation. */
+    tool: string;
+    /** Args the tool was invoked with. Stored verbatim so the event can
+     *  be **replayed** against a different `ToolDispatch` (e.g. a
+     *  production registry pointed at live Firestore). Optional for
+     *  back-compat with legacy event files written before this field
+     *  existed; legacy events can't be replayed without it. */
+    args?: unknown;
+    /** Lifecycle phase. */
+    phase: MutationPhase;
+    /** What was (or would be) mutated. */
+    target: MutationTarget;
+    /** Captured pre-image. Absent when the API doesn't expose one or the
+     *  caller opted out. */
+    before?: unknown;
+    /** Captured post-image. Always present for `commit` phase. */
+    after?: unknown;
+    /** Whether the API supports reversing this mutation. Hard-false for
+     *  irreversible ops (service enablement, hosting release rollbacks
+     *  past retention window, etc) — `agent undo` refuses with the
+     *  message in `irreversibleReason`. */
+    reversible: boolean;
+    /** When `reversible: false`, why. Surfaced to the user. */
+    irreversibleReason?: string;
+    /** When `reversible: true`, the tool+args to invoke to roll back.
+     *  Absent during `plan` phase (intent, not commitment); always
+     *  present on `commit` phase for reversible events. */
+    reverseOp?: ReverseOp;
+    /** Free-form metadata the host can stash on the event. The event log
+     *  treats this as opaque — readers can use it to correlate with their
+     *  own systems (Linear ticket id, deploy build number, etc). */
+    metadata?: Record<string, unknown>;
+}
+export interface MutationEventFilter {
+    /** Restrict to a single session. */
+    sessionId?: string;
+    /** Restrict to a single tool name. */
+    tool?: string;
+    /** Restrict to a single agent. */
+    agent?: string;
+    /** ISO-8601 lower bound (inclusive). */
+    since?: string;
+    /** ISO-8601 upper bound (exclusive). */
+    until?: string;
+    /** Restrict to a single phase. */
+    phase?: MutationPhase;
+    /** Restrict to a single target kind. */
+    targetKind?: TargetKind;
+    /** Restrict by event id (for undo). */
+    id?: string;
+}
+/**
+ * Identifier used in event records when the host didn't name an agent.
+ * Lives in the types module (zero side effects) so it's safe on the
+ * universal `@inbrowser/agent` entry — the value lives in `events/log.ts`
+ * too, but that file imports `node:fs` / `node:os` and can't ship to
+ * the browser.
+ */
+export declare const HOST_AGENT_ID = "host";
+//# sourceMappingURL=events.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../src/types/events.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,QAAQ,GAAG,UAAU,CAAC;AAE3D,MAAM,MAAM,UAAU,GAClB,KAAK,GACL,YAAY,GACZ,OAAO,GACP,OAAO,GACP,SAAS,GACT,QAAQ,GACR,SAAS,GACT,WAAW,GACX,WAAW,GACX,OAAO,CAAC;AAEZ,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,UAAU,CAAC;IACjB;;;;;;;OAOG;IACH,IAAI,EAAE,MAAM,CAAC;IACb,+BAA+B;IAC/B,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,SAAS;IACxB,6DAA6D;IAC7D,IAAI,EAAE,MAAM,CAAC;IACb;0EACsE;IACtE,IAAI,EAAE,OAAO,CAAC;IACd,kEAAkE;IAClE,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,aAAa;IAC5B,sDAAsD;IACtD,EAAE,EAAE,MAAM,CAAC;IACX,mDAAmD;IACnD,EAAE,EAAE,MAAM,CAAC;IACX,oEAAoE;IACpE,KAAK,EAAE,MAAM,CAAC;IACd,sCAAsC;IACtC,SAAS,EAAE,MAAM,CAAC;IAClB,+CAA+C;IAC/C,IAAI,EAAE,MAAM,CAAC;IACb;;;;+DAI2D;IAC3D,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,uBAAuB;IACvB,KAAK,EAAE,aAAa,CAAC;IACrB,sCAAsC;IACtC,MAAM,EAAE,cAAc,CAAC;IACvB;4BACwB;IACxB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,8DAA8D;IAC9D,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB;;;2CAGuC;IACvC,UAAU,EAAE,OAAO,CAAC;IACpB,2DAA2D;IAC3D,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B;;2DAEuD;IACvD,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB;;oEAEgE;IAChE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,MAAM,WAAW,mBAAmB;IAClC,oCAAoC;IACpC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,sCAAsC;IACtC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,kCAAkC;IAClC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,wCAAwC;IACxC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,wCAAwC;IACxC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,kCAAkC;IAClC,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB,wCAAwC;IACxC,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,uCAAuC;IACvC,EAAE,CAAC,EAAE,MAAM,CAAC;CACb;AAED;;;;;;GAMG;AACH,eAAO,MAAM,aAAa,SAAS,CAAC"}

package/dist/types/events.js

@@ -0,0 +1,30 @@
+/**
+ * `MutationEvent` — the canonical record a mutating tool emits to the
+ * project event log. Three phases:
+ *
+ *   - `plan` — emitted before the tool actually runs. Records intent +
+ *     captured "before" snapshot. Always present.
+ *   - `commit` — emitted after the tool returns successfully. Records
+ *     "after" snapshot + the `reverseOp` (when one exists) so `agent
+ *     undo` can roll it back.
+ *   - `rollback` — emitted when execution failed mid-flight, or when
+ *     `agent undo` reverses a previously-committed event. Helps the
+ *     auditor distinguish "started but never finished" from "finished
+ *     and later undone."
+ *
+ * The log is **append-only NDJSON** at
+ * `~/.pyric/projects/<projectId>/events.ndjson`. The whole point is
+ * that the file is replayable + diffable — never overwrite, never
+ * mutate previous lines.
+ *
+ * See `plans/specialized-firebase-agents.md` §7 for the design rationale.
+ */
+/**
+ * Identifier used in event records when the host didn't name an agent.
+ * Lives in the types module (zero side effects) so it's safe on the
+ * universal `@inbrowser/agent` entry — the value lives in `events/log.ts`
+ * too, but that file imports `node:fs` / `node:os` and can't ship to
+ * the browser.
+ */
+export const HOST_AGENT_ID = 'host';
+//# sourceMappingURL=events.js.map

package/dist/types/events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../../src/types/events.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAuGH;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,MAAM,CAAC"}

package/dist/types/llm.d.ts

@@ -0,0 +1,89 @@
+/**
+ * `LlmClient` — narrow provider interface.
+ *
+ * Implementations live in adapter packages (one per provider). The
+ * client knows about model calls and streamed events; it knows
+ * **nothing** about BYOK forms, localStorage, model pickers, or
+ * pricing tables. Receives its config explicitly at construction
+ * time so concurrent sessions can use different keys/models against
+ * the same provider without contention.
+ */
+import type { NormalizedMessage } from './chat.js';
+import type { TurnDetails, TurnMetrics } from './chat.js';
+export interface LlmConfig {
+    apiKey?: string;
+    model: string;
+    /** Base URL override (e.g. for OpenAI-compatible proxies). */
+    baseUrl?: string;
+    /** Reasoning effort for providers that support it (OpenRouter). */
+    reasoningEffort?: 'low' | 'medium' | 'high';
+    /** Caller-side flag — affects metrics' `isByok`. */
+    isByok?: boolean;
+}
+export interface ChatRequest {
+    messages: NormalizedMessage[];
+    /** Tool declarations the model may invoke. Empty array → plain chat. */
+    tools: ToolDeclaration[];
+    /** Lighter than `tools.length === 0`; lets adapters skip tool-mode encoding entirely. */
+    toolUseEnabled: boolean;
+}
+export interface ToolDeclaration {
+    name: string;
+    description: string;
+    /** JSON Schema describing the tool's arguments. */
+    parameters: JsonSchema;
+}
+export type JsonSchema = {
+    type?: string;
+    description?: string;
+    properties?: Record<string, JsonSchema>;
+    required?: string[];
+    items?: JsonSchema | JsonSchema[];
+    enum?: unknown[];
+    [key: string]: unknown;
+};
+export interface LlmClient {
+    readonly id: string;
+    readonly supportsTools: boolean;
+    chat(req: ChatRequest, signal: AbortSignal): AsyncIterable<ChatEvent>;
+}
+export type ChatEvent = {
+    kind: 'text';
+    chunk: string;
+} | {
+    kind: 'thinking';
+    chunk: string;
+} | {
+    kind: 'tool_call';
+    id: string;
+    name: string;
+    args: unknown;
+    signature?: string;
+} | {
+    kind: 'turn_complete';
+    usage: RawUsage;
+    details: TurnDetails;
+} | {
+    kind: 'error';
+    message: string;
+};
+/**
+ * Raw token usage as the provider reports it — interpreted by
+ * `MetricsCollector` to derive `TurnMetrics` (cost, cached
+ * fraction, reasoning fraction). Different providers report
+ * different shapes; the collector handles them.
+ */
+export interface RawUsage {
+    promptTokens: number;
+    completionTokens: number;
+    cachedTokens?: number;
+    reasoningTokens?: number;
+    /** Provider-supplied cost (OpenRouter), when available — bypasses pricing tables. */
+    costUsd?: number;
+}
+export interface LlmClientFactory {
+    create(config: LlmConfig): LlmClient;
+}
+/** Re-export so consumers don't have to dig into `./chat.js`. */
+export type { TurnDetails, TurnMetrics };
+//# sourceMappingURL=llm.d.ts.map

package/dist/types/llm.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"llm.d.ts","sourceRoot":"","sources":["../../src/types/llm.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AACnD,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAE1D,MAAM,WAAW,SAAS;IACxB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,8DAA8D;IAC9D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,mEAAmE;IACnE,eAAe,CAAC,EAAE,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAC;IAC5C,oDAAoD;IACpD,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,iBAAiB,EAAE,CAAC;IAC9B,wEAAwE;IACxE,KAAK,EAAE,eAAe,EAAE,CAAC;IACzB,yFAAyF;IACzF,cAAc,EAAE,OAAO,CAAC;CACzB;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,mDAAmD;IACnD,UAAU,EAAE,UAAU,CAAC;CACxB;AAED,MAAM,MAAM,UAAU,GAAG;IACvB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IACxC,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,KAAK,CAAC,EAAE,UAAU,GAAG,UAAU,EAAE,CAAC;IAClC,IAAI,CAAC,EAAE,OAAO,EAAE,CAAC;IACjB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB,CAAC;AAEF,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;IAChC,IAAI,CAAC,GAAG,EAAE,WAAW,EAAE,MAAM,EAAE,WAAW,GAAG,aAAa,CAAC,SAAS,CAAC,CAAC;CACvE;AAED,MAAM,MAAM,SAAS,GACjB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAC/B;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACnC;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,OAAO,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,GAClF;IAAE,IAAI,EAAE,eAAe,CAAC;IAAC,KAAK,EAAE,QAAQ,CAAC;IAAC,OAAO,EAAE,WAAW,CAAA;CAAE,GAChE;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAEvC;;;;;GAKG;AACH,MAAM,WAAW,QAAQ;IACvB,YAAY,EAAE,MAAM,CAAC;IACrB,gBAAgB,EAAE,MAAM,CAAC;IACzB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,qFAAqF;IACrF,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,gBAAgB;IAC/B,MAAM,CAAC,MAAM,EAAE,SAAS,GAAG,SAAS,CAAC;CACtC;AAED,iEAAiE;AACjE,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,CAAC"}