pyric-tools 0.1.0-alpha.7

package/dist/discover/session.d.ts

@@ -0,0 +1,116 @@
+export declare const DEFAULT_MAX_SESSIONS = 8;
+export declare const DEFAULT_MAX_SESSION_BYTES: number;
+export declare const DEFAULT_TTL_MS: number;
+export type SessionErrorCode = 'SESSION_EXPIRED' | 'SESSION_EVICTED' | 'SESSION_PAYLOAD_TOO_LARGE' | 'SESSION_MALFORMED_TOKEN';
+export interface SessionError {
+    code: SessionErrorCode;
+    message: string;
+    recoveryHint: string;
+}
+/**
+ * A live session record. `state` is opaque to the store — Item 4.2 will
+ * instantiate `SessionStore` with the concrete crawler-state type.
+ */
+export interface SessionRecord<TState> {
+    /** Raw ULID — internal id; not the token surfaced to agents. */
+    readonly id: string;
+    /** Opaque continuation handle: `disc_<base64url-ulid>`. */
+    readonly token: string;
+    readonly createdAt: number;
+    /** Last get/update; drives both LRU eviction and TTL. */
+    lastAccessedAt: number;
+    /** Caller-reported payload size for byte-cap enforcement. */
+    bytes: number;
+    state: TState;
+}
+export interface SessionStoreOptions {
+    maxSessions?: number;
+    maxSessionBytes?: number;
+    ttlMs?: number;
+    /** Test seam — defaults to `Date.now`. */
+    now?: () => number;
+    /** Test seam — defaults to `crypto.randomBytes`. */
+    randomBytes?: (n: number) => Uint8Array;
+    evictionLogSize?: number;
+}
+/** Discriminated-union result so callers don't have to try/catch. */
+export type SessionResult<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    error: SessionError;
+};
+/**
+ * Encode a 16-byte ULID into a `disc_<base64url>` token. Internal — used
+ * by `SessionStore.create`.
+ */
+export declare function encodeToken(ulidBytes: Uint8Array): string;
+/**
+ * Decode a `disc_<base64url>` token. Returns `null` on any malformation
+ * — caller maps null to `SESSION_MALFORMED_TOKEN`.
+ */
+export declare function decodeToken(token: string): {
+    id: string;
+} | null;
+/**
+ * In-process LRU session store with TTL sweep and per-session byte cap.
+ *
+ * Eviction policy:
+ *   1. On every `create`/`get`/`update`, sweep TTL-expired sessions first.
+ *      Their tokens land in the eviction log as `SESSION_EXPIRED`.
+ *   2. If `create` would exceed `maxSessions`, evict the LRU
+ *      (oldest-by-`lastAccessedAt`). Its token lands in the eviction log
+ *      as `SESSION_EVICTED` so the displaced agent gets a meaningful
+ *      error on its next call.
+ *   3. `update` rejects with `SESSION_PAYLOAD_TOO_LARGE` if the new
+ *      `bytes` exceeds `maxSessionBytes` (per-session cap, not aggregate).
+ *
+ * The eviction log is a bounded ring buffer; once it overflows, evicted
+ * tokens degrade silently to `SESSION_EXPIRED` (still actionable — the
+ * recoveryHint is the same: re-issue without continuation).
+ */
+export declare class SessionStore<TState> {
+    private readonly maxSessions;
+    private readonly maxSessionBytes;
+    private readonly ttlMs;
+    private readonly evictionLogSize;
+    private readonly now;
+    private readonly rand;
+    private readonly sessions;
+    /** id → eviction reason. Bounded — see `recordEviction`. */
+    private readonly evictionLog;
+    constructor(opts?: SessionStoreOptions);
+    /** Live session count. */
+    get size(): number;
+    /**
+     * Create a new session. Always succeeds unless `bytes` exceeds the
+     * per-session byte cap. On cap-hit, evicts the LRU session — the
+     * displaced token will report `SESSION_EVICTED` on its next access.
+     */
+    create(state: TState, bytes: number): SessionResult<SessionRecord<TState>>;
+    /**
+     * Look up a session by token. Touches `lastAccessedAt` on success so
+     * subsequent reads keep the session warm. On expired/malformed/evicted
+     * tokens returns the appropriate structured error.
+     */
+    get(token: string): SessionResult<SessionRecord<TState>>;
+    /**
+     * Replace the state of an existing session. Same lookup/error model
+     * as `get`, plus per-session-bytes enforcement on the new payload.
+     */
+    update(token: string, state: TState, bytes: number): SessionResult<SessionRecord<TState>>;
+    /** Best-effort delete; returns true if a session was removed. */
+    delete(token: string): boolean;
+    /**
+     * Drop sessions whose `lastAccessedAt + ttlMs` is in the past.
+     * Returns the number of sessions evicted. Public for tests +
+     * future scheduled-sweep usage; `create`/`get`/`update` all call it
+     * lazily so callers don't normally need to.
+     */
+    sweepExpired(now?: number): number;
+    private evictLru;
+    private recordEviction;
+    private lookupEvicted;
+}
+//# sourceMappingURL=session.d.ts.map

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

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

package/dist/discover/session.js

@@ -0,0 +1,331 @@
+/**
+ * In-process session store for `firestore_discover_paths` continuations.
+ *
+ * Phase 3.3 locked the session API: the agent receives an opaque
+ * `continuation` token between batches and the server holds the
+ * partial-schema state. This module owns the storage layer; Item 4.2
+ * wires it into the crawler.
+ *
+ * Hard caps (per prerequisite 0.G — bounded session memory):
+ *   - `maxSessions`        = 8       — total live sessions
+ *   - `maxSessionBytes`    = 32 MB   — per-session payload (well above
+ *                                      Phase 0.4's 11.64 MB worst case)
+ *   - `ttlMs`              = 30 min  — idle TTL (Phase 3.3 lock)
+ *
+ * Token format: `disc_` + base64url(16-byte ULID). ULID gives natural
+ * monotonic ordering (timestamp-prefixed) and avoids a runtime
+ * dependency on the `ulid` package.
+ *
+ * Error model — never throws on expected paths (per Item 4 acceptance
+ * criteria). Returns `{ ok: false, error: { code, message, recoveryHint } }`:
+ *   - `SESSION_EXPIRED`        — token unknown OR past TTL (per 0.C)
+ *   - `SESSION_EVICTED`        — token was capacity-evicted by an LRU
+ *                                bump from a concurrent agent (per 0.G)
+ *   - `SESSION_PAYLOAD_TOO_LARGE` — state would exceed `maxSessionBytes`
+ *   - `SESSION_MALFORMED_TOKEN`   — wrong prefix or undecodable b64
+ */
+'use strict';
+/**
+ * Default RNG — Web Crypto's `getRandomValues`. Works in modern
+ * browsers AND Node 19+ (webcrypto on globalThis) AND Bun, so this
+ * module evaluates cleanly in any environment without a top-level
+ * `node:crypto` import.
+ *
+ * Tests + Node consumers that want a deterministic seam can still
+ * override via `SessionStoreOptions.randomBytes`.
+ */
+function defaultRandomBytes(n) {
+    const buf = new Uint8Array(n);
+    globalThis.crypto.getRandomValues(buf);
+    return buf;
+}
+// ─── Defaults (per prerequisite 0.G + Phase 3.3) ──────────────────────────
+export const DEFAULT_MAX_SESSIONS = 8;
+export const DEFAULT_MAX_SESSION_BYTES = 32 * 1024 * 1024; // 32 MB
+export const DEFAULT_TTL_MS = 30 * 60 * 1000; // 30 min idle
+/**
+ * How many recently-evicted tokens to remember so a returning agent can
+ * be told *why* their session is gone (`SESSION_EVICTED`) rather than
+ * the generic `SESSION_EXPIRED`. Bounded ring buffer; older entries get
+ * overwritten and degrade silently to `SESSION_EXPIRED`.
+ */
+const DEFAULT_EVICTION_LOG_SIZE = 64;
+const TOKEN_PREFIX = 'disc_';
+// ─── ULID + token codec ───────────────────────────────────────────────────
+/**
+ * 16-byte ULID: 6 bytes big-endian ms timestamp, 10 bytes randomness.
+ * Sortable by creation time, collision-free at 80 bits randomness.
+ */
+function generateUlidBytes(now, rand) {
+    const bytes = new Uint8Array(16);
+    let ts = Math.max(0, Math.floor(now));
+    for (let i = 5; i >= 0; i--) {
+        bytes[i] = ts & 0xff;
+        ts = Math.floor(ts / 256);
+    }
+    const r = rand(10);
+    bytes.set(r, 6);
+    return bytes;
+}
+function bytesToBase64Url(bytes) {
+    let bin = '';
+    for (let i = 0; i < bytes.length; i++)
+        bin += String.fromCharCode(bytes[i]);
+    return btoa(bin).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+function base64UrlToBytes(s) {
+    if (!/^[A-Za-z0-9_-]*$/.test(s))
+        return null;
+    let b64 = s.replace(/-/g, '+').replace(/_/g, '/');
+    while (b64.length % 4)
+        b64 += '=';
+    try {
+        const bin = atob(b64);
+        const out = new Uint8Array(bin.length);
+        for (let i = 0; i < bin.length; i++)
+            out[i] = bin.charCodeAt(i);
+        return out;
+    }
+    catch {
+        return null;
+    }
+}
+function bytesToHex(bytes) {
+    let s = '';
+    for (let i = 0; i < bytes.length; i++) {
+        s += bytes[i].toString(16).padStart(2, '0');
+    }
+    return s;
+}
+/**
+ * Encode a 16-byte ULID into a `disc_<base64url>` token. Internal — used
+ * by `SessionStore.create`.
+ */
+export function encodeToken(ulidBytes) {
+    if (ulidBytes.length !== 16) {
+        throw new Error(`encodeToken: expected 16-byte ULID, got ${ulidBytes.length}`);
+    }
+    return TOKEN_PREFIX + bytesToBase64Url(ulidBytes);
+}
+/**
+ * Decode a `disc_<base64url>` token. Returns `null` on any malformation
+ * — caller maps null to `SESSION_MALFORMED_TOKEN`.
+ */
+export function decodeToken(token) {
+    if (typeof token !== 'string' || !token.startsWith(TOKEN_PREFIX))
+        return null;
+    const tail = token.slice(TOKEN_PREFIX.length);
+    if (tail.length === 0)
+        return null;
+    const bytes = base64UrlToBytes(tail);
+    if (bytes === null || bytes.length !== 16)
+        return null;
+    return { id: bytesToHex(bytes) };
+}
+// ─── Session store ────────────────────────────────────────────────────────
+/**
+ * In-process LRU session store with TTL sweep and per-session byte cap.
+ *
+ * Eviction policy:
+ *   1. On every `create`/`get`/`update`, sweep TTL-expired sessions first.
+ *      Their tokens land in the eviction log as `SESSION_EXPIRED`.
+ *   2. If `create` would exceed `maxSessions`, evict the LRU
+ *      (oldest-by-`lastAccessedAt`). Its token lands in the eviction log
+ *      as `SESSION_EVICTED` so the displaced agent gets a meaningful
+ *      error on its next call.
+ *   3. `update` rejects with `SESSION_PAYLOAD_TOO_LARGE` if the new
+ *      `bytes` exceeds `maxSessionBytes` (per-session cap, not aggregate).
+ *
+ * The eviction log is a bounded ring buffer; once it overflows, evicted
+ * tokens degrade silently to `SESSION_EXPIRED` (still actionable — the
+ * recoveryHint is the same: re-issue without continuation).
+ */
+export class SessionStore {
+    maxSessions;
+    maxSessionBytes;
+    ttlMs;
+    evictionLogSize;
+    now;
+    rand;
+    sessions = new Map();
+    /** id → eviction reason. Bounded — see `recordEviction`. */
+    evictionLog = new Map();
+    constructor(opts = {}) {
+        this.maxSessions = opts.maxSessions ?? DEFAULT_MAX_SESSIONS;
+        this.maxSessionBytes = opts.maxSessionBytes ?? DEFAULT_MAX_SESSION_BYTES;
+        this.ttlMs = opts.ttlMs ?? DEFAULT_TTL_MS;
+        this.evictionLogSize = opts.evictionLogSize ?? DEFAULT_EVICTION_LOG_SIZE;
+        this.now = opts.now ?? Date.now;
+        this.rand = opts.randomBytes ?? defaultRandomBytes;
+        if (!Number.isInteger(this.maxSessions) || this.maxSessions < 1) {
+            throw new RangeError(`SessionStore: maxSessions must be a positive integer, got ${this.maxSessions}`);
+        }
+        if (!Number.isInteger(this.maxSessionBytes) || this.maxSessionBytes < 1) {
+            throw new RangeError(`SessionStore: maxSessionBytes must be a positive integer, got ${this.maxSessionBytes}`);
+        }
+        if (!Number.isInteger(this.ttlMs) || this.ttlMs < 1) {
+            throw new RangeError(`SessionStore: ttlMs must be a positive integer, got ${this.ttlMs}`);
+        }
+    }
+    /** Live session count. */
+    get size() {
+        return this.sessions.size;
+    }
+    /**
+     * Create a new session. Always succeeds unless `bytes` exceeds the
+     * per-session byte cap. On cap-hit, evicts the LRU session — the
+     * displaced token will report `SESSION_EVICTED` on its next access.
+     */
+    create(state, bytes) {
+        if (bytes > this.maxSessionBytes) {
+            return {
+                ok: false,
+                error: {
+                    code: 'SESSION_PAYLOAD_TOO_LARGE',
+                    message: `Session payload (${bytes} bytes) exceeds cap (${this.maxSessionBytes} bytes)`,
+                    recoveryHint: 'Reduce per-batch result size (lower maxSamples or rootFilter to a smaller subtree)',
+                },
+            };
+        }
+        const now = this.now();
+        this.sweepExpired(now);
+        if (this.sessions.size >= this.maxSessions) {
+            this.evictLru();
+        }
+        const ulidBytes = generateUlidBytes(now, this.rand);
+        const id = bytesToHex(ulidBytes);
+        const token = encodeToken(ulidBytes);
+        const record = {
+            id,
+            token,
+            createdAt: now,
+            lastAccessedAt: now,
+            bytes,
+            state,
+        };
+        this.sessions.set(id, record);
+        return { ok: true, value: record };
+    }
+    /**
+     * Look up a session by token. Touches `lastAccessedAt` on success so
+     * subsequent reads keep the session warm. On expired/malformed/evicted
+     * tokens returns the appropriate structured error.
+     */
+    get(token) {
+        const decoded = decodeToken(token);
+        if (decoded === null) {
+            return {
+                ok: false,
+                error: {
+                    code: 'SESSION_MALFORMED_TOKEN',
+                    message: `Continuation token is malformed (expected ${TOKEN_PREFIX}<base64url>)`,
+                    recoveryHint: 'Re-issue without continuation to start fresh',
+                },
+            };
+        }
+        const now = this.now();
+        this.sweepExpired(now);
+        const record = this.sessions.get(decoded.id);
+        if (!record)
+            return this.lookupEvicted(decoded.id);
+        record.lastAccessedAt = now;
+        return { ok: true, value: record };
+    }
+    /**
+     * Replace the state of an existing session. Same lookup/error model
+     * as `get`, plus per-session-bytes enforcement on the new payload.
+     */
+    update(token, state, bytes) {
+        const lookup = this.get(token);
+        if (!lookup.ok)
+            return lookup;
+        if (bytes > this.maxSessionBytes) {
+            return {
+                ok: false,
+                error: {
+                    code: 'SESSION_PAYLOAD_TOO_LARGE',
+                    message: `Updated session payload (${bytes} bytes) exceeds cap (${this.maxSessionBytes} bytes)`,
+                    recoveryHint: 'Crawl produced more state than the per-session cap allows; surface partial result and stop',
+                },
+            };
+        }
+        const record = lookup.value;
+        record.state = state;
+        record.bytes = bytes;
+        // `get` already touched lastAccessedAt; no need to re-stamp.
+        return { ok: true, value: record };
+    }
+    /** Best-effort delete; returns true if a session was removed. */
+    delete(token) {
+        const decoded = decodeToken(token);
+        if (decoded === null)
+            return false;
+        return this.sessions.delete(decoded.id);
+    }
+    /**
+     * Drop sessions whose `lastAccessedAt + ttlMs` is in the past.
+     * Returns the number of sessions evicted. Public for tests +
+     * future scheduled-sweep usage; `create`/`get`/`update` all call it
+     * lazily so callers don't normally need to.
+     */
+    sweepExpired(now = this.now()) {
+        let count = 0;
+        const cutoff = now - this.ttlMs;
+        for (const [id, record] of this.sessions) {
+            if (record.lastAccessedAt < cutoff) {
+                this.sessions.delete(id);
+                this.recordEviction(id, 'SESSION_EXPIRED');
+                count++;
+            }
+        }
+        return count;
+    }
+    // ─── internals ───────────────────────────────────────────────────────
+    evictLru() {
+        let oldestId = null;
+        let oldestTs = Infinity;
+        for (const [id, record] of this.sessions) {
+            if (record.lastAccessedAt < oldestTs) {
+                oldestTs = record.lastAccessedAt;
+                oldestId = id;
+            }
+        }
+        if (oldestId !== null) {
+            this.sessions.delete(oldestId);
+            this.recordEviction(oldestId, 'SESSION_EVICTED');
+        }
+    }
+    recordEviction(id, reason) {
+        if (this.evictionLog.size >= this.evictionLogSize) {
+            // Drop the oldest entry — Map iteration is insertion-ordered.
+            const firstKey = this.evictionLog.keys().next().value;
+            if (firstKey !== undefined)
+                this.evictionLog.delete(firstKey);
+        }
+        this.evictionLog.set(id, reason);
+    }
+    lookupEvicted(id) {
+        const reason = this.evictionLog.get(id);
+        if (reason === 'SESSION_EVICTED') {
+            return {
+                ok: false,
+                error: {
+                    code: 'SESSION_EVICTED',
+                    message: 'Continuation was evicted because the session-store capacity is full (a concurrent agent bumped you).',
+                    recoveryHint: 'Retry the discover_paths call without the continuation; consider serializing concurrent crawls',
+                },
+            };
+        }
+        // SESSION_EXPIRED covers both TTL-expired and never-existed tokens.
+        // Both surface the same recovery action: re-issue without continuation.
+        return {
+            ok: false,
+            error: {
+                code: 'SESSION_EXPIRED',
+                message: 'Continuation is unknown or past the 30-minute TTL. The server has discarded the partial state.',
+                recoveryHint: 'Re-issue without continuation to start fresh',
+            },
+        };
+    }
+}
+//# sourceMappingURL=session.js.map

package/dist/discover/session.js.map

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

package/dist/discover/tools.d.ts

@@ -0,0 +1,59 @@
+/**
+ * `createFirestoreDiscoverTools({ resolveDb })` — `ToolHandler[]` for
+ * the discover-paths feature, browser-safe (no firebase-admin import).
+ *
+ * Two handlers:
+ *   - `firestore_discover_paths` — BFS sample every collection
+ *     reachable from the root, return per-templatePath schema +
+ *     cost counters. Supports `dryRun` cost preview and
+ *     `continuation` resume.
+ *   - `firestore_find_collection_group` — bounded
+ *     `collectionGroup(id).select().limit(N).get()` to answer "where
+ *     does collection ID X appear?".
+ *
+ * Session lifetime: per-factory-call. Each `createFirestoreDiscoverTools`
+ * invocation creates its own `SessionStore` for continuation tokens.
+ * Per the in-progress agents work, a single agent process should
+ * therefore reuse one factory instance for the duration of a session.
+ *
+ * Per F2 / F4: identity is a value (the resolver), lifecycle is
+ * per-dispatch. `resolveDb()` runs inside each tool execute so hosts
+ * can swap the underlying CrawlerFirestore (e.g. admin → sandbox)
+ * between calls without re-wiring.
+ *
+ * Output shape: `crawl()`'s native `finalizedSchemas: Map<...>` flattens
+ * to a `schemas: Record<templatePath, ...>` shape for JSON
+ * serialization across the tool boundary. `discovered` (raw refs) is
+ * dropped — agents consume the finalized schemas.
+ */
+import type { ToolHandler } from '@inbrowser/agent';
+import { type FullCrawlResult } from './crawler.js';
+import type { CrawlerFirestore } from './crawler.js';
+import type { CollectionSchema, DiscoverEvent } from './types.js';
+import type { CollectionGroupCapableFirestore } from './findCollectionGroup.js';
+export interface FirestoreDiscoverToolDeps {
+    /**
+     * Resolver returning the CrawlerFirestore to scan. Called per
+     * dispatch (F4). For `firestore_find_collection_group` the returned
+     * Firestore must also satisfy {@link CollectionGroupCapableFirestore}.
+     */
+    resolveDb(): CrawlerFirestore & CollectionGroupCapableFirestore;
+}
+/** JSON-serializable shape returned by `firestore_discover_paths`. */
+export interface DiscoverPathsToolResult {
+    /** Per-templatePath finalized schemas, keyed by templatePath. */
+    schemas: Record<string, CollectionSchema>;
+    events: DiscoverEvent[];
+    /** `listCollections` + `listDocuments` calls — cumulative across batches. */
+    listOps: number;
+    /** `.get()` calls during sampling — cumulative across batches. */
+    readOps: number;
+    /** Opaque resume handle iff the crawl paused at a payload boundary. */
+    continuation?: string;
+    /** True iff the crawl finished. Equivalent to `continuation === undefined`. */
+    complete: boolean;
+    /** Present iff this was a `dryRun: true` preview. */
+    dryRunCostEstimate?: FullCrawlResult['dryRunCostEstimate'];
+}
+export declare function createFirestoreDiscoverTools(deps: FirestoreDiscoverToolDeps): ToolHandler[];
+//# sourceMappingURL=tools.d.ts.map

package/dist/discover/tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../src/discover/tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAAS,KAAK,eAAe,EAAE,MAAM,cAAc,CAAC;AAG3D,OAAO,KAAK,EAAE,gBAAgB,EAAuB,MAAM,cAAc,CAAC;AAC1E,OAAO,KAAK,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAClE,OAAO,KAAK,EAAE,+BAA+B,EAAE,MAAM,0BAA0B,CAAC;AAEhF,MAAM,WAAW,yBAAyB;IACxC;;;;OAIG;IACH,SAAS,IAAI,gBAAgB,GAAG,+BAA+B,CAAC;CACjE;AAED,sEAAsE;AACtE,MAAM,WAAW,uBAAuB;IACtC,iEAAiE;IACjE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;IAC1C,MAAM,EAAE,aAAa,EAAE,CAAC;IACxB,6EAA6E;IAC7E,OAAO,EAAE,MAAM,CAAC;IAChB,kEAAkE;IAClE,OAAO,EAAE,MAAM,CAAC;IAChB,uEAAuE;IACvE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,+EAA+E;IAC/E,QAAQ,EAAE,OAAO,CAAC;IAClB,qDAAqD;IACrD,kBAAkB,CAAC,EAAE,eAAe,CAAC,oBAAoB,CAAC,CAAC;CAC5D;AAmBD,wBAAgB,4BAA4B,CAC1C,IAAI,EAAE,yBAAyB,GAC9B,WAAW,EAAE,CAoHf"}

package/dist/discover/tools.js

@@ -0,0 +1,115 @@
+import { crawl } from './crawler.js';
+import { findCollectionGroup } from './findCollectionGroup.js';
+import { SessionStore } from './session.js';
+export function createFirestoreDiscoverTools(deps) {
+    const { resolveDb } = deps;
+    // Per-factory session store — see header note on lifetime.
+    const sessions = new SessionStore();
+    return [
+        {
+            name: 'firestore_discover_paths',
+            description: 'Sample every collection reachable from the database root and return per-templatePath schemas (field types, presence, enums, examples) plus discovered subcollection paths. Use this to understand a Firestore database\'s shape before generating client code, security rules, or analytics queries. ' +
+                'Cost is bounded: structure walk is one listCollections/listDocuments per collection; sampling is min(maxSamples, available) per templatePath with adaptive early-exit. Cumulative cost is reported as listOps + readOps. ' +
+                'Set dryRun: true for an informational cost preview that issues exactly one root listCollections RPC and returns a heuristic projection — no documents are read. Large databases pause at payload boundaries and return a continuation token; pass it back as the next call\'s continuation to resume.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    maxDepth: { type: 'integer', minimum: 1, description: 'Max BFS depth from root collections. Default 10 — runaway guard.' },
+                    maxConcurrency: { type: 'integer', minimum: 1, description: 'In-flight RPC cap. Default 32.' },
+                    maxSamples: { type: 'integer', minimum: 1, description: 'Hard cap on docs sampled per templatePath. Default 50.' },
+                    stopOnStable: { type: 'integer', minimum: 1, description: 'Adaptive early-exit: stop sampling a templatePath after this many consecutive no-change merges. Default 8. Set higher than maxSamples to disable.' },
+                    maxBatchBytes: { type: 'integer', minimum: 1024, description: 'Pause when persisted state exceeds this many bytes. Default 1 MB. Only effective when continuations are in play.' },
+                    rootPrefix: { type: 'string', description: 'Restrict the crawl to root collections whose ID starts with this prefix.' },
+                    dryRun: { type: 'boolean', description: 'Cost-preview mode. Issues exactly one root listCollections RPC and returns a heuristic projection. No documents are read. Cannot be combined with a continuation token.' },
+                    dryRunSubtreeMultiplier: { type: 'integer', minimum: 1, description: 'Multiplier in the dryRun projection: roots × this = projected total collections. Default 3 (conservative).' },
+                    continuation: { type: 'string', description: 'Resume a paused crawl. Use the continuation token from a prior result. Pass nothing to start fresh.' },
+                },
+            },
+            async execute(args) {
+                const params = (args ?? {});
+                try {
+                    const db = resolveDb();
+                    const rootFilter = params.rootPrefix
+                        ? (id) => id.startsWith(params.rootPrefix)
+                        : undefined;
+                    const result = await crawl(db, {
+                        maxDepth: params.maxDepth,
+                        maxConcurrency: params.maxConcurrency,
+                        maxSamples: params.maxSamples,
+                        stopOnStable: params.stopOnStable,
+                        maxBatchBytes: params.maxBatchBytes,
+                        rootFilter,
+                        dryRun: params.dryRun,
+                        dryRunSubtreeMultiplier: params.dryRunSubtreeMultiplier,
+                        continuation: params.continuation,
+                    }, sessions);
+                    const schemas = {};
+                    for (const [templatePath, schema] of result.finalizedSchemas) {
+                        schemas[templatePath] = schema;
+                    }
+                    const data = {
+                        schemas,
+                        events: result.events,
+                        listOps: result.listOps,
+                        readOps: result.readOps,
+                        complete: result.complete,
+                        ...(result.continuation !== undefined && { continuation: result.continuation }),
+                        ...(result.dryRunCostEstimate !== undefined && {
+                            dryRunCostEstimate: result.dryRunCostEstimate,
+                        }),
+                    };
+                    return {
+                        ok: true,
+                        summary: `Discovered ${Object.keys(schemas).length} template path(s); ${result.readOps} read(s), ${result.listOps} list(s)${result.complete ? '' : ' — paused, resume with continuation'}`,
+                        data,
+                    };
+                }
+                catch (e) {
+                    const message = e instanceof Error ? e.message : String(e);
+                    return {
+                        ok: false,
+                        summary: `firestore_discover_paths failed: ${message}`,
+                        data: { success: false, error: { code: 'DISCOVER_FAILED', message, recoverable: false } },
+                    };
+                }
+            },
+        },
+        {
+            name: 'firestore_find_collection_group',
+            description: 'Find every collection-group host of a given collection ID. Answers "where does collection ID X appear in the database?" by issuing one collectionGroup(id).select().limit(N).get() — cost is exactly N reads (default 100). ' +
+                'Returns hosts in template-path form (e.g. users/{userId}/posts) with the per-host sampleDocCount from the N-doc draw. Coverage of all hosts is statistical: with K hosts, N=100 covers ~22 distinct hosts with high confidence (coupon-collector). The result\'s limitWasReached flag signals whether to raise the cap. ' +
+                'Use this as a cold-start alternative to firestore_discover_paths when you already know the collection ID and just need the parent paths.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    collectionId: { type: 'string', minLength: 1, description: 'The leaf collection ID to find (e.g. "posts", "moves").' },
+                    limit: { type: 'integer', minimum: 1, description: 'Max docs to fetch from the collection group. Default 100. Each doc costs one read; raise this if limitWasReached is true and you suspect more hosts.' },
+                },
+                required: ['collectionId'],
+            },
+            async execute(args) {
+                const params = args;
+                try {
+                    const db = resolveDb();
+                    const result = await findCollectionGroup(db, params.collectionId, {
+                        limit: params.limit,
+                    });
+                    return {
+                        ok: true,
+                        summary: `Found ${result.hosts.length} host(s) for '${params.collectionId}'${result.limitWasReached ? ' (limit reached — raise to find more)' : ''}`,
+                        data: result,
+                    };
+                }
+                catch (e) {
+                    const message = e instanceof Error ? e.message : String(e);
+                    return {
+                        ok: false,
+                        summary: `firestore_find_collection_group failed: ${message}`,
+                        data: { success: false, error: { code: 'FIND_COLLECTION_GROUP_FAILED', message, recoverable: false } },
+                    };
+                }
+            },
+        },
+    ];
+}
+//# sourceMappingURL=tools.js.map

package/dist/discover/tools.js.map

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