@inbrowser/agent 0.0.0-placeholder → 0.2.0

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

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

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

package/dist/types/session.js

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

package/dist/types/session.js.map

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

package/dist/types/storage.d.ts

@@ -0,0 +1,20 @@
+/**
+ * `Storage` — the platform-level key/value abstraction over
+ * `localStorage` / fs / in-memory. Used for BYOK keys, layout
+ * prefs, last-used project id, recent-sessions cache.
+ *
+ * Distinct from `@pyric/storage` (Firebase Storage adapter for
+ * user-owned cloud data). They live at different layers.
+ */
+export interface Storage {
+    get(key: string): string | null;
+    set(key: string, value: string): void;
+    remove(key: string): void;
+    /** Optionally list keys with a prefix. Implementations may degrade to []. */
+    keys(prefix?: string): string[];
+}
+/** No-op storage. Useful for tests + the headless CLI's default. */
+export declare const noopStorage: Storage;
+/** In-memory storage. Thread-safe within one event loop. */
+export declare function createMemoryStorage(seed?: Record<string, string>): Storage;
+//# sourceMappingURL=storage.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../../src/types/storage.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,MAAM,WAAW,OAAO;IACtB,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IAChC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACtC,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,6EAA6E;IAC7E,IAAI,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;CACjC;AAED,oEAAoE;AACpE,eAAO,MAAM,WAAW,EAAE,OASxB,CAAC;AAEH,4DAA4D;AAC5D,wBAAgB,mBAAmB,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,OAAO,CAkB1E"}

package/dist/types/storage.js

@@ -0,0 +1,41 @@
+/**
+ * `Storage` — the platform-level key/value abstraction over
+ * `localStorage` / fs / in-memory. Used for BYOK keys, layout
+ * prefs, last-used project id, recent-sessions cache.
+ *
+ * Distinct from `@pyric/storage` (Firebase Storage adapter for
+ * user-owned cloud data). They live at different layers.
+ */
+/** No-op storage. Useful for tests + the headless CLI's default. */
+export const noopStorage = Object.freeze({
+    get: () => null,
+    set: () => {
+        /* ignored */
+    },
+    remove: () => {
+        /* ignored */
+    },
+    keys: () => [],
+});
+/** In-memory storage. Thread-safe within one event loop. */
+export function createMemoryStorage(seed) {
+    const map = new Map(seed ? Object.entries(seed) : []);
+    return {
+        get: (k) => map.get(k) ?? null,
+        set: (k, v) => {
+            map.set(k, v);
+        },
+        remove: (k) => {
+            map.delete(k);
+        },
+        keys: (prefix) => {
+            const out = [];
+            for (const k of map.keys()) {
+                if (prefix === undefined || k.startsWith(prefix))
+                    out.push(k);
+            }
+            return out;
+        },
+    };
+}
+//# sourceMappingURL=storage.js.map

package/dist/types/storage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.js","sourceRoot":"","sources":["../../src/types/storage.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAUH,oEAAoE;AACpE,MAAM,CAAC,MAAM,WAAW,GAAY,MAAM,CAAC,MAAM,CAAC;IAChD,GAAG,EAAE,GAAG,EAAE,CAAC,IAAI;IACf,GAAG,EAAE,GAAG,EAAE;QACR,aAAa;IACf,CAAC;IACD,MAAM,EAAE,GAAG,EAAE;QACX,aAAa;IACf,CAAC;IACD,IAAI,EAAE,GAAG,EAAE,CAAC,EAAE;CACf,CAAC,CAAC;AAEH,4DAA4D;AAC5D,MAAM,UAAU,mBAAmB,CAAC,IAA6B;IAC/D,MAAM,GAAG,GAAG,IAAI,GAAG,CAAiB,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IACtE,OAAO;QACL,GAAG,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,IAAI;QAC9B,GAAG,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE;YACZ,GAAG,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;QAChB,CAAC;QACD,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE;YACZ,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;QAChB,CAAC;QACD,IAAI,EAAE,CAAC,MAAM,EAAE,EAAE;YACf,MAAM,GAAG,GAAa,EAAE,CAAC;YACzB,KAAK,MAAM,CAAC,IAAI,GAAG,CAAC,IAAI,EAAE,EAAE,CAAC;gBAC3B,IAAI,MAAM,KAAK,SAAS,IAAI,CAAC,CAAC,UAAU,CAAC,MAAM,CAAC;oBAAE,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;YAChE,CAAC;YACD,OAAO,GAAG,CAAC;QACb,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/types/strategy.d.ts

@@ -0,0 +1,124 @@
+/**
+ * `AgentStrategy` — the pluggable inference algorithm.
+ *
+ * The current ReAct-style single-loop behavior is one strategy;
+ * future planner / graph / parallel-branch strategies are new files
+ * implementing this same interface. The session's external event
+ * surface stays stable; only the internals change.
+ */
+import type { ChatMessage, TurnDetails } from './chat.js';
+import type { LlmClient, RawUsage } from './llm.js';
+import type { RuntimeState } from './runtime.js';
+import type { ToolContext, ToolDispatch, ToolHandler, ToolResult } from './tools.js';
+import type { Tracer } from './trace.js';
+import type { Workspace } from './workspace.js';
+export interface AgentStrategy {
+    readonly id: string;
+    /**
+     * Execute one user prompt to completion. Returns the strategy's
+     * event stream — the session translates it into `SessionEvent`s.
+     */
+    run(input: StrategyRunInput, signal: AbortSignal): AsyncIterable<StrategyEvent>;
+}
+export interface StrategyRunInput {
+    prompt: string;
+    history: ChatMessage[];
+    workspace: Workspace;
+    runtime: RuntimeState;
+    llm: LlmClient;
+    tools: ToolDispatch;
+    /** Already filtered by the active capabilities. */
+    toolList: ToolHandler[];
+    /** Factory — call per tool exec so the latest workspace/runtime flows in. */
+    toolContext(): ToolContext;
+    /** Pre-built by the session from `Workspace` + `RuntimeState`. */
+    systemPrompt: string;
+    /** Optional trace sink — emitted at well-defined moments in the
+     *  loop (request about to dispatch; response complete). The
+     *  strategy never inspects the impl. Absent = zero-cost no-op. */
+    tracer?: Tracer;
+    /** Optional session-scoped id used by the strategy when generating
+     *  per-iteration `requestId`s. The session is what owns the turn
+     *  identity; the strategy receives it for trace labeling only. */
+    turnId?: string;
+}
+export type StrategyEvent = {
+    kind: 'text';
+    chunk: string;
+} | {
+    kind: 'thinking';
+    chunk: string;
+} | {
+    kind: 'tool_call';
+    id: string;
+    name: string;
+    args: unknown;
+    signature?: string;
+} | {
+    kind: 'tool_result';
+    id: string;
+    result: ToolResult;
+} | {
+    kind: 'turn_complete';
+    usage: RawUsage;
+    details: TurnDetails;
+} | {
+    kind: 'error';
+    message: string;
+}
+/** Custom milestone — name + arbitrary payload, surfaced as
+ *  `SessionEvent.kind === 'strategy_event'` to the host. */
+ | {
+    kind: 'custom';
+    name: string;
+    data?: unknown;
+};
+/**
+ * Opt-in critique-and-retry pass after a candidate final-answer turn.
+ *
+ * When `enabled === true`, the ReAct loop runs as usual, but instead of
+ * returning immediately on a turn that produced no tool calls the
+ * strategy issues a second chat call asking the model to evaluate its
+ * own last response against the prior tool results visible in the
+ * conversation. The evaluation returns a JSON verdict of the shape
+ * `{ "ok": boolean, "feedback"?: string }`. When the verdict is `ok`
+ * the original answer stands. When the verdict flags problems and the
+ * retry budget has not been exhausted, the strategy injects the
+ * feedback as a synthetic user message and loops back into the next
+ * ReAct iteration. When the retry budget is exhausted the strategy
+ * returns the most recent final-answer turn as-is — reflexion never
+ * blocks completion.
+ *
+ * A malformed verdict (non-JSON critique text, or JSON missing the
+ * `ok` field) is treated as `{ ok: true }`: fail-open, never block on a
+ * critique the strategy could not parse.
+ *
+ * The critique runs through the same `LlmClient` as the main loop; the
+ * trace emits an additional `llm_request` for the critique call with a
+ * `requestId` suffixed `#critique`, so trace consumers can distinguish
+ * critique requests from main-loop requests. The strategy emits a
+ * `custom` `StrategyEvent` named `'reflexion_critique'` with a
+ * `{ verdict, text, feedback? }` payload at every critique decision.
+ *
+ * Defaults: `maxRetries: 1`. When `enabled === false` (or the option
+ * is absent) the strategy's behavior is byte-for-byte identical to the
+ * pre-reflexion loop.
+ */
+export interface ReflexionConfig {
+    /** Opt-in switch. */
+    enabled: boolean;
+    /**
+     * Maximum retries after the critique flags problems. Defaults to 1.
+     * Setting to 0 disables retries entirely (the critique runs and its
+     * verdict is emitted, but no retry is attempted on `ok: false`).
+     */
+    maxRetries?: number;
+    /**
+     * System prompt used for the critique call. Defaults to a neutral
+     * prompt that asks the model to evaluate consistency with prior
+     * tool results and reply with `{"ok": boolean, "feedback"?: string}`
+     * JSON. Override when a skill needs a tighter verifier rubric.
+     */
+    critiqueSystemPrompt?: string;
+}
+//# sourceMappingURL=strategy.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"strategy.d.ts","sourceRoot":"","sources":["../../src/types/strategy.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAC1D,OAAO,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AACpD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACrF,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AACzC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAEhD,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,GAAG,CAAC,KAAK,EAAE,gBAAgB,EAAE,MAAM,EAAE,WAAW,GAAG,aAAa,CAAC,aAAa,CAAC,CAAC;CACjF;AAED,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,WAAW,EAAE,CAAC;IACvB,SAAS,EAAE,SAAS,CAAC;IACrB,OAAO,EAAE,YAAY,CAAC;IACtB,GAAG,EAAE,SAAS,CAAC;IACf,KAAK,EAAE,YAAY,CAAC;IACpB,mDAAmD;IACnD,QAAQ,EAAE,WAAW,EAAE,CAAC;IACxB,6EAA6E;IAC7E,WAAW,IAAI,WAAW,CAAC;IAC3B,kEAAkE;IAClE,YAAY,EAAE,MAAM,CAAC;IACrB;;sEAEkE;IAClE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;sEAEkE;IAClE,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,MAAM,aAAa,GACrB;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,aAAa,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,UAAU,CAAA;CAAE,GACvD;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;AACpC;4DAC4D;GAC1D;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,OAAO,CAAA;CAAE,CAAC;AAErD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,WAAW,eAAe;IAC9B,qBAAqB;IACrB,OAAO,EAAE,OAAO,CAAC;IACjB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;;OAKG;IACH,oBAAoB,CAAC,EAAE,MAAM,CAAC;CAC/B"}

package/dist/types/strategy.js

@@ -0,0 +1,10 @@
+/**
+ * `AgentStrategy` — the pluggable inference algorithm.
+ *
+ * The current ReAct-style single-loop behavior is one strategy;
+ * future planner / graph / parallel-branch strategies are new files
+ * implementing this same interface. The session's external event
+ * surface stays stable; only the internals change.
+ */
+export {};
+//# sourceMappingURL=strategy.js.map

package/dist/types/strategy.js.map

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