@inbrowser/agent 0.0.0-placeholder → 0.1.0

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"}

package/dist/types/llm.js

@@ -0,0 +1,12 @@
+/**
+ * `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.
+ */
+export {};
+//# sourceMappingURL=llm.js.map

package/dist/types/llm.js.map

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

package/dist/types/metrics.d.ts

@@ -0,0 +1,34 @@
+/**
+ * `MetricsCollector` — translates raw provider usage into typed
+ * turn metrics + session totals.
+ *
+ * Pure functions. Receives provider id + raw usage and returns a
+ * cost breakdown. Pricing tables live here, not inside provider
+ * implementations.
+ */
+import type { RawUsage, TurnMetrics } from './llm.js';
+export interface MetricsCollector {
+    /** Stamp a turn-completion event. Returns the typed metrics shape. */
+    recordTurn(input: RecordTurnInput): TurnMetrics;
+    /** Aggregate across all recorded turns in this collector's lifetime. */
+    totals(): SessionTotals;
+    /** Reset the collector — call on session reset / clear. */
+    reset(): void;
+}
+export interface RecordTurnInput {
+    llmId: string;
+    rawUsage: RawUsage;
+    model: string;
+    durationMs: number;
+    isByok?: boolean;
+}
+export interface SessionTotals {
+    tokensTotal: number;
+    tokensIn: number;
+    tokensOut: number;
+    tokensCached: number;
+    tokensReasoning: number;
+    costUsdTotal: number;
+    turnCount: number;
+}
+//# sourceMappingURL=metrics.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.d.ts","sourceRoot":"","sources":["../../src/types/metrics.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAEtD,MAAM,WAAW,gBAAgB;IAC/B,sEAAsE;IACtE,UAAU,CAAC,KAAK,EAAE,eAAe,GAAG,WAAW,CAAC;IAChD,wEAAwE;IACxE,MAAM,IAAI,aAAa,CAAC;IACxB,2DAA2D;IAC3D,KAAK,IAAI,IAAI,CAAC;CACf;AAED,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,QAAQ,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,aAAa;IAC5B,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,eAAe,EAAE,MAAM,CAAC;IACxB,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;CACnB"}

package/dist/types/metrics.js

@@ -0,0 +1,10 @@
+/**
+ * `MetricsCollector` — translates raw provider usage into typed
+ * turn metrics + session totals.
+ *
+ * Pure functions. Receives provider id + raw usage and returns a
+ * cost breakdown. Pricing tables live here, not inside provider
+ * implementations.
+ */
+export {};
+//# sourceMappingURL=metrics.js.map

package/dist/types/metrics.js.map

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

package/dist/types/observer.d.ts

@@ -0,0 +1,41 @@
+/**
+ * `SandboxObserver` — centralized error sink for simulated services.
+ *
+ * Every site inside `@pyric/sandbox`, `@pyric/admin`,
+ * `@pyric/firestore` (sandbox target), `@pyric/storage` (sandbox
+ * target) that throws / errors / surfaces denials calls
+ * `observer.onEvent({...})` *before* the throw or callback. The
+ * structured error returns the SDK already provides are unchanged.
+ *
+ * Append-only from the sandbox's perspective — emitting an event
+ * must never throw, never block, never affect the operation's
+ * return value. Pure side-channel.
+ *
+ * NOTE: this is the agent-layer *host-observer* event — a coarse
+ * error-sink shape. It is distinct from `@pyric/sandbox`'s
+ * `SandboxEvent` (the substrate-level discriminated union of every
+ * evaluated op). The two were briefly name-colliding; this one is
+ * `ObserverEvent` to keep them unambiguous. See issue #307.
+ */
+export interface ObserverEvent {
+    kind: 'denial' | 'snapshot_error' | 'transaction_conflict' | 'runtime_error' | 'lint_warning';
+    timestamp: number;
+    /** Stable identifier for the originating operation. */
+    operationId?: string;
+    /** Path the operation touched. */
+    path?: string;
+    /** Identity context at the time of the event. */
+    auth?: {
+        uid: string | null;
+    };
+    /** Structured detail — denial reason, error code, message. */
+    detail: unknown;
+}
+export interface SandboxObserver {
+    onEvent(event: ObserverEvent): void;
+}
+/** Compose multiple observers into one. */
+export declare function combineObservers(...observers: SandboxObserver[]): SandboxObserver;
+/** No-op observer — the default when no host subscribes. */
+export declare const noopObserver: SandboxObserver;
+//# sourceMappingURL=observer.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"observer.d.ts","sourceRoot":"","sources":["../../src/types/observer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,QAAQ,GAAG,gBAAgB,GAAG,sBAAsB,GAAG,eAAe,GAAG,cAAc,CAAC;IAC9F,SAAS,EAAE,MAAM,CAAC;IAClB,uDAAuD;IACvD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,kCAAkC;IAClC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,iDAAiD;IACjD,IAAI,CAAC,EAAE;QAAE,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC;IAC9B,8DAA8D;IAC9D,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,CAAC,KAAK,EAAE,aAAa,GAAG,IAAI,CAAC;CACrC;AAED,2CAA2C;AAC3C,wBAAgB,gBAAgB,CAAC,GAAG,SAAS,EAAE,eAAe,EAAE,GAAG,eAAe,CAYjF;AAED,4DAA4D;AAC5D,eAAO,MAAM,YAAY,EAAE,eAIzB,CAAC"}

package/dist/types/observer.js

@@ -0,0 +1,41 @@
+/**
+ * `SandboxObserver` — centralized error sink for simulated services.
+ *
+ * Every site inside `@pyric/sandbox`, `@pyric/admin`,
+ * `@pyric/firestore` (sandbox target), `@pyric/storage` (sandbox
+ * target) that throws / errors / surfaces denials calls
+ * `observer.onEvent({...})` *before* the throw or callback. The
+ * structured error returns the SDK already provides are unchanged.
+ *
+ * Append-only from the sandbox's perspective — emitting an event
+ * must never throw, never block, never affect the operation's
+ * return value. Pure side-channel.
+ *
+ * NOTE: this is the agent-layer *host-observer* event — a coarse
+ * error-sink shape. It is distinct from `@pyric/sandbox`'s
+ * `SandboxEvent` (the substrate-level discriminated union of every
+ * evaluated op). The two were briefly name-colliding; this one is
+ * `ObserverEvent` to keep them unambiguous. See issue #307.
+ */
+/** Compose multiple observers into one. */
+export function combineObservers(...observers) {
+    return {
+        onEvent: (event) => {
+            for (const o of observers) {
+                try {
+                    o.onEvent(event);
+                }
+                catch {
+                    // Side-channel; never let one observer's bug crash another.
+                }
+            }
+        },
+    };
+}
+/** No-op observer — the default when no host subscribes. */
+export const noopObserver = Object.freeze({
+    onEvent: () => {
+        /* intentionally empty */
+    },
+});
+//# sourceMappingURL=observer.js.map

package/dist/types/observer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"observer.js","sourceRoot":"","sources":["../../src/types/observer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAmBH,2CAA2C;AAC3C,MAAM,UAAU,gBAAgB,CAAC,GAAG,SAA4B;IAC9D,OAAO;QACL,OAAO,EAAE,CAAC,KAAK,EAAE,EAAE;YACjB,KAAK,MAAM,CAAC,IAAI,SAAS,EAAE,CAAC;gBAC1B,IAAI,CAAC;oBACH,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;gBACnB,CAAC;gBAAC,MAAM,CAAC;oBACP,4DAA4D;gBAC9D,CAAC;YACH,CAAC;QACH,CAAC;KACF,CAAC;AACJ,CAAC;AAED,4DAA4D;AAC5D,MAAM,CAAC,MAAM,YAAY,GAAoB,MAAM,CAAC,MAAM,CAAC;IACzD,OAAO,EAAE,GAAG,EAAE;QACZ,yBAAyB;IAC3B,CAAC;CACF,CAAC,CAAC"}

package/dist/types/project-context.d.ts

@@ -0,0 +1,18 @@
+/**
+ * `ProjectContext` — credential bundle Firebase-aware agents (rules
+ * audits, scripted deploys, hosted-app tooling) need to talk to a
+ * live project. The agent runtime stays Firebase-agnostic at the
+ * type level: `getFirestore()` is typed as `unknown` so the agent
+ * package has no `firebase-admin` dependency. Host packages that
+ * supply a ProjectContext narrow the return type at the call site
+ * via a cast (`ctx.getFirestore() as Firestore`).
+ */
+export interface ProjectContext {
+    readonly projectId: string;
+    resolveToken(): Promise<string>;
+    /** Returns the host's `firebase-admin/firestore` Firestore (or
+     *  equivalent). Typed `unknown` to keep agent runtime free of a
+     *  firebase-admin dep; callers cast at the use site. */
+    getFirestore(): unknown;
+}
+//# sourceMappingURL=project-context.d.ts.map

package/dist/types/project-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"project-context.d.ts","sourceRoot":"","sources":["../../src/types/project-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,YAAY,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IAChC;;4DAEwD;IACxD,YAAY,IAAI,OAAO,CAAC;CACzB"}

package/dist/types/project-context.js

@@ -0,0 +1,11 @@
+/**
+ * `ProjectContext` — credential bundle Firebase-aware agents (rules
+ * audits, scripted deploys, hosted-app tooling) need to talk to a
+ * live project. The agent runtime stays Firebase-agnostic at the
+ * type level: `getFirestore()` is typed as `unknown` so the agent
+ * package has no `firebase-admin` dependency. Host packages that
+ * supply a ProjectContext narrow the return type at the call site
+ * via a cast (`ctx.getFirestore() as Firestore`).
+ */
+export {};
+//# sourceMappingURL=project-context.js.map

package/dist/types/project-context.js.map

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

package/dist/types/runtime.d.ts

@@ -0,0 +1,71 @@
+/**
+ * `RuntimeState` — what the agent's tools have produced this session.
+ *
+ * Per-session. Owned by `AgentSession`, mutated by tool handlers via
+ * the patch returned from `ToolResult.runtimePatch`. The host reads
+ * this through `runtime_changed` session events; it does not write
+ * directly.
+ *
+ * Ephemeral by design — not persisted across reloads. The user's
+ * authored content lives in `Workspace`; this is the volatile
+ * runtime view.
+ */
+export interface RuntimeState {
+    terminal: TerminalSection[];
+    runSummary: RunSummary | null;
+    deploy: DeployState | null;
+    parseError: ParseError | null;
+    uiErrors: UiError[];
+    /** Bumped on reseed / preset switch / sandbox reset; consumers watch to remount. */
+    sandboxVersion: number;
+}
+export interface TerminalSection {
+    id: string;
+    kind: 'run' | 'deploy' | 'system';
+    title: string;
+    timestamp: number;
+    entries: TerminalEntry[];
+}
+export interface TerminalEntry {
+    level: 'info' | 'warn' | 'error' | 'denial';
+    message: string;
+    path?: string;
+    detail?: unknown;
+}
+export interface RunSummary {
+    ok: boolean;
+    durationMs: number;
+    docsTouched: number;
+    errors: number;
+    message?: string;
+}
+export interface DeployState {
+    ok: boolean;
+    messages: DeployMessage[];
+    timestamp: number;
+}
+export interface DeployMessage {
+    severity: 'info' | 'warn' | 'error';
+    text: string;
+    line?: number;
+    column?: number;
+}
+export interface ParseError {
+    message: string;
+    line: number;
+    column: number;
+    expected?: string;
+}
+export interface UiError {
+    source: 'compile' | 'runtime' | 'render';
+    message: string;
+    /** Filled when the error came from rule denial — request/resource context. */
+    denialContext?: Record<string, unknown>;
+    /** Compile errors carry source location. */
+    line?: number;
+    column?: number;
+    /** Runtime errors carry an error code (e.g. `permission-denied`). */
+    code?: string;
+}
+export declare const EMPTY_RUNTIME: RuntimeState;
+//# sourceMappingURL=runtime.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../../src/types/runtime.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,eAAe,EAAE,CAAC;IAC5B,UAAU,EAAE,UAAU,GAAG,IAAI,CAAC;IAC9B,MAAM,EAAE,WAAW,GAAG,IAAI,CAAC;IAC3B,UAAU,EAAE,UAAU,GAAG,IAAI,CAAC;IAC9B,QAAQ,EAAE,OAAO,EAAE,CAAC;IACpB,oFAAoF;IACpF,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,KAAK,GAAG,QAAQ,GAAG,QAAQ,CAAC;IAClC,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,aAAa,EAAE,CAAC;CAC1B;AAED,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,CAAC;IAC5C,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,OAAO,CAAC;IACZ,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,OAAO,CAAC;IACZ,QAAQ,EAAE,aAAa,EAAE,CAAC;IAC1B,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,OAAO;IACtB,MAAM,EAAE,SAAS,GAAG,SAAS,GAAG,QAAQ,CAAC;IACzC,OAAO,EAAE,MAAM,CAAC;IAChB,8EAA8E;IAC9E,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACxC,4CAA4C;IAC5C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,qEAAqE;IACrE,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,eAAO,MAAM,aAAa,EAAE,YAOV,CAAC"}

package/dist/types/runtime.js

@@ -0,0 +1,21 @@
+/**
+ * `RuntimeState` — what the agent's tools have produced this session.
+ *
+ * Per-session. Owned by `AgentSession`, mutated by tool handlers via
+ * the patch returned from `ToolResult.runtimePatch`. The host reads
+ * this through `runtime_changed` session events; it does not write
+ * directly.
+ *
+ * Ephemeral by design — not persisted across reloads. The user's
+ * authored content lives in `Workspace`; this is the volatile
+ * runtime view.
+ */
+export const EMPTY_RUNTIME = Object.freeze({
+    terminal: Object.freeze([]),
+    runSummary: null,
+    deploy: null,
+    parseError: null,
+    uiErrors: Object.freeze([]),
+    sandboxVersion: 0,
+});
+//# sourceMappingURL=runtime.js.map

package/dist/types/runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.js","sourceRoot":"","sources":["../../src/types/runtime.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAmEH,MAAM,CAAC,MAAM,aAAa,GAAiB,MAAM,CAAC,MAAM,CAAC;IACvD,QAAQ,EAAE,MAAM,CAAC,MAAM,CAAC,EAAuB,CAAiC;IAChF,UAAU,EAAE,IAAI;IAChB,MAAM,EAAE,IAAI;IACZ,UAAU,EAAE,IAAI;IAChB,QAAQ,EAAE,MAAM,CAAC,MAAM,CAAC,EAAe,CAAyB;IAChE,cAAc,EAAE,CAAC;CAClB,CAAiB,CAAC"}

package/dist/types/session.d.ts

@@ -0,0 +1,103 @@
+/**
+ * `AgentSession` + `SessionEvent` — host-facing surfaces for one
+ * in-flight agent run.
+ *
+ * The session is a generic container — it owns the id, the workspace
+ * + runtime references, the cancellation token, and the typed event
+ * stream. The actual inference algorithm lives in an `AgentStrategy`
+ * (`./strategy.ts`).
+ */
+import type { ChatMessage, TurnDetails, TurnMetrics } from './chat.js';
+import type { LlmClient } from './llm.js';
+import type { MetricsCollector } from './metrics.js';
+import type { RuntimeState } from './runtime.js';
+import type { AgentStrategy } from './strategy.js';
+import type { ToolContext, ToolDispatch, ToolHandler, ToolResult } from './tools.js';
+import type { Tracer } from './trace.js';
+import type { Workspace } from './workspace.js';
+export interface AgentSessionConfig {
+    /** Pluggable inference algorithm. See `./strategy.ts`. */
+    strategy: AgentStrategy;
+    llm: LlmClient;
+    tools: ToolDispatch;
+    /** Tool declarations the LLM should see this turn. Caller filters by
+     *  capabilities before construction. Empty list disables function
+     *  calling and the LLM is driven via plain-chat — typically a host
+     *  bug rather than an intended state. */
+    toolList: ToolHandler[];
+    /** Factory producing a fresh `ToolContext` for each tool exec — lets the
+     *  session thread its current workspace/runtime through without
+     *  closing over stale references. */
+    toolContext(): ToolContext;
+    /** Build the system prompt from live workspace + runtime. */
+    systemPromptBuilder(workspace: Workspace, runtime: RuntimeState): string;
+    metrics: MetricsCollector;
+    /** Empty for fresh sessions; loaded for resume. */
+    history: ChatMessage[];
+    /** Optional session id; one is generated when absent. */
+    id?: string;
+    /** Optional trace sink. Forwarded to the strategy alongside the
+     *  session-owned `turnId` so the host can correlate
+     *  `LlmRequestTrace.turnId` back to `SessionEvent`s. Absent =
+     *  zero-cost no-op. */
+    tracer?: Tracer;
+}
+export interface AgentSession {
+    readonly id: string;
+    readonly workspace: Workspace;
+    readonly runtime: RuntimeState;
+    /** Run one prompt to completion. The iterable closes when the run is done. */
+    submit(prompt: string, signal: AbortSignal): AsyncIterable<SessionEvent>;
+    /** Cancel any in-flight submit. Safe to call when idle. */
+    cancel(): void;
+}
+export type SessionEvent = {
+    kind: 'turn_started';
+    turnId: string;
+} | {
+    kind: 'text';
+    turnId: string;
+    chunk: string;
+} | {
+    kind: 'thinking';
+    turnId: string;
+    chunk: string;
+} | {
+    kind: 'tool_started';
+    turnId: string;
+    callId: string;
+    name: string;
+    args: unknown;
+    signature?: string;
+} | {
+    kind: 'tool_finished';
+    turnId: string;
+    callId: string;
+    result: ToolResult;
+} | {
+    kind: 'workspace_changed';
+    workspace: Workspace;
+} | {
+    kind: 'runtime_changed';
+    runtime: RuntimeState;
+} | {
+    kind: 'turn_completed';
+    turnId: string;
+    metrics: TurnMetrics;
+    details: TurnDetails;
+} | {
+    kind: 'error';
+    turnId?: string;
+    message: string;
+} | {
+    kind: 'completed';
+}
+/** Strategy-emitted milestones (planner phases, branch expansions, …)
+ *  — generic envelope so new strategies can surface custom events
+ *  without expanding the union. */
+ | {
+    kind: 'strategy_event';
+    name: string;
+    data?: unknown;
+};
+//# sourceMappingURL=session.d.ts.map