@x12i/sdk 0.4.0 → 1.1.0

package/dist/client.js

@@ -1,728 +1,220 @@
-import { fetchUrl, launchBrowser, retrieve, retrieveBatch, retrieveWithCache, checkChanges, InMemoryFetchCache, InMemorySnapshotStore, } from "@x12i/fetcher";
-import { ingestRepository } from "@x12i/ingest";
-import { createSerperProvider, loadSearchConfig, search as runSearch, } from "@x12i/search";
-import { crawl } from "@x12i/crawl";
-import { research } from "@x12i/research";
-import { extract, } from "@x12i/extract";
-import { InMemoryRunStore, } from "@x12i/runs";
-import { InMemoryFunctionCheckpointStore, analyzeWebChanges, analyzeWebSource, answerFromWeb, auditWebResearch, compareWebSubjects, createExecutorFromPolicy, evaluateCandidate, listBindings, listWebAIProfiles, loadBindingsFromPath, loadHostPolicyFromEnv, planQueries, previewWebAIProfile, rankEvidenceBlocks, validateBindingCompatibility, } from "@x12i/web-functions";
-import { createHash } from "node:crypto";
-import { createDefaultRegistry } from "./registry.js";
-function requestHash(value) {
-    return createHash("sha256").update(JSON.stringify(value)).digest("hex").slice(0, 24);
-}
-/**
- * Per-site fetch defaults so client-rendered pages actually populate before
- * we snapshot HTML. Caller-supplied options still win (spread after this).
- */
-function siteFetchDefaults(url) {
-    try {
-        const parsed = new URL(url);
-        const host = parsed.hostname;
-        const path = parsed.pathname;
-        if ((host === "openrouter.ai" || host.endsWith(".openrouter.ai")) &&
-            (path === "/rankings" || path.startsWith("/rankings/"))) {
-            return {
-                waitForSelector: "div.grid.grid-cols-12.items-center",
-                settleMs: 500,
-            };
-        }
-        if ((host === "linkedin.com" || host === "www.linkedin.com" || host.endsWith(".linkedin.com")) &&
-            path.startsWith("/company/")) {
-            return { waitForSelector: "h1", settleMs: 1000 };
-        }
-        if (host === "medium.com" ||
-            host.endsWith(".medium.com") ||
-            host === "towardsdatascience.com") {
-            return { waitForSelector: "article h1, h1", settleMs: 800 };
-        }
-        if (host === "g2.com" || host === "www.g2.com" || host.endsWith(".g2.com")) {
-            return { settleMs: 1500 };
-        }
+import { createRequire } from "node:module";
+import { getReadme, searchPackages } from "@x12i/npm-core";
+import { loadOrCreateIdentity, saveIdentity, defaultIdentityPath } from "./identity.js";
+import { rankPackages } from "./rank.js";
+import { canonicalRequest, randomNonce, reviewRating, sign, solveWork, usageFields, } from "./protocol.js";
+const require = createRequire(import.meta.url);
+export const SDK_VERSION = require("../package.json").version;
+/** Catalog service. Override with X12I_SDK_URL. */
+export const DEFAULT_SERVICE_URL = "https://x12i-sdk.x12i.com";
+export class SdkError extends Error {
+    status;
+    code;
+    constructor(message, status = 0, code = "REQUEST_FAILED") {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.name = "SdkError";
     }
-    catch {
-        // ignore unparseable URLs
-    }
-    return {};
 }
-/**
- * Canonical programmatic surface: fetch/retrieve/research/crawl/extract/runs.
- * CLI, REST, and MCP are thin adapters around this client.
- */
-export class WebAgentClient {
-    registry;
-    defaultFetchOptions;
-    reuseBrowser;
-    searchProvider;
-    browserPromise;
-    fetchCache;
-    snapshotStore;
-    runStore;
-    extractionAdapter;
-    ownsCache;
-    ownsSnapshots;
-    ownsRuns;
-    funcxExecutor;
-    ownsFuncxExecutor;
-    webFunctionBindings;
-    hostPolicy;
-    aiProfilesSource;
-    functionCheckpoints = new InMemoryFunctionCheckpointStore();
-    activeRunEventSink;
+export class X12iClient {
+    baseUrl;
+    identityPath;
+    fetchImpl;
     constructor(options = {}) {
-        this.registry = options.registry ?? createDefaultRegistry();
-        this.defaultFetchOptions = options.fetchOptions ?? {};
-        this.reuseBrowser = options.reuseBrowser ?? false;
-        this.searchProvider = resolveSearchProvider(options.search);
-        this.ownsCache = !options.fetchCache;
-        this.ownsSnapshots = !options.snapshotStore;
-        this.ownsRuns = !options.runStore;
-        this.fetchCache = options.fetchCache ?? new InMemoryFetchCache();
-        this.snapshotStore = options.snapshotStore ?? new InMemorySnapshotStore();
-        this.runStore = options.runStore ?? new InMemoryRunStore();
-        this.extractionAdapter = options.extractionAdapter;
-        this.hostPolicy = loadHostPolicyFromEnv();
-        if (options.aiProfiles?.source)
-            this.hostPolicy.aiProfilesSource = options.aiProfiles.source;
-        this.aiProfilesSource = options.aiProfiles?.source ?? this.hostPolicy.aiProfilesSource ?? "auto";
-        this.ownsFuncxExecutor = options.ownsFuncxExecutor ?? !options.funcxExecutor;
-        this.funcxExecutor = options.funcxExecutor ?? createExecutorFromPolicy(this.hostPolicy);
-        this.webFunctionBindings = options.webFunctionBindings ?? [];
-        void this.loadBindingsFromEnv();
+        this.baseUrl = (options.baseUrl ?? process.env.X12I_SDK_URL ?? DEFAULT_SERVICE_URL).replace(/\/$/, "");
+        this.identityPath = options.identityPath ?? defaultIdentityPath();
+        this.fetchImpl = options.fetch ?? fetch;
     }
-    async loadBindingsFromEnv() {
-        const path = process.env.WEB_AGENTIC_FUNCTION_BINDINGS;
-        if (!path || this.webFunctionBindings.length)
-            return;
+    async search(task) {
+        try {
+            const body = await this.send("POST", "/v1/recommend", JSON.stringify({ task }), { "content-type": "application/json" });
+            const parsed = body;
+            return { source: "service", ranked: parsed.ranked === true, task, results: parsed.results ?? [] };
+        }
+        catch (error) {
+            if (error instanceof SdkError && error.status >= 400 && error.status < 500)
+                throw error;
+            const found = await searchPackages(task, { scope: "@x12i/", size: 20, fetch: this.fetchImpl });
+            const results = rankPackages(task, found.map((pkg) => ({ name: pkg.name, description: pkg.description, keywords: pkg.keywords })));
+            return { source: "registry", ranked: results.some((item) => item.confidence === "high"), task, results };
+        }
+    }
+    catalog(cursor, limit = 50) {
+        const query = new URLSearchParams();
+        if (cursor)
+            query.set("cursor", cursor);
+        query.set("limit", String(limit));
+        return this.send("GET", `/v1/catalog?${query}`);
+    }
+    package(name) {
+        return this.readThrough(packagePath(name), name);
+    }
+    readme(name) {
+        return this.readThrough(`${packagePath(name)}/readme`, name);
+    }
+    reviews(name) {
+        return this.send("GET", `${packagePath(name)}/reviews`);
+    }
+    async report(input) {
+        const fields = usageFields(input);
+        const identity = await this.ensureEnrolled();
+        return this.signedPost("/v1/reports", { ...fields, sdkVersion: SDK_VERSION }, identity);
+    }
+    async review(input) {
+        const fields = usageFields(input);
+        const rating = reviewRating(input.rating);
+        const identity = await this.ensureEnrolled();
+        return this.signedPost("/v1/reviews", { ...fields, rating, sdkVersion: SDK_VERSION }, identity);
+    }
+    async status() {
+        let identity;
         try {
-            this.webFunctionBindings = await loadBindingsFromPath(path);
+            identity = await loadOrCreateIdentity(this.identityPath);
         }
         catch {
-            // Bindings file is optional; function routes report not configured / incompatible.
-        }
-    }
-    webFunctionsDeps() {
-        return {
-            bindings: this.webFunctionBindings,
-            executor: this.funcxExecutor,
-            hostPolicy: this.hostPolicy,
-            checkpoints: this.functionCheckpoints,
-            onEvent: (type, data) => {
-                this.activeRunEventSink?.(type, data);
-            },
-            resolvePacket: async (runId) => {
-                for (const kind of ["research_packet", "packet", "grounded_answer"]) {
-                    const items = await this.runStore.listItems(runId, { kind, limit: 1 });
-                    const data = items.items[0]?.data;
-                    if (kind === "grounded_answer")
-                        continue;
-                    if (data)
-                        return data;
-                }
-                // Prefer packet item explicitly
-                const packetItems = await this.runStore.listItems(runId, { limit: 20 });
-                const packet = packetItems.items.find((i) => i.kind === "packet" || i.kind === "research_packet");
-                return packet?.data;
-            },
-            resolveRunSource: async (runId, sourceId) => {
-                const packet = await this.webFunctionsDeps().resolvePacket?.(runId);
-                return packet?.sources.find((s) => s.sourceId === sourceId);
-            },
-            retrieveUrl: async (url, opts) => {
-                const fetch = await this.retrieve(url, { strategy: "auto", signal: opts?.signal });
-                return {
-                    sourceId: `src_${createHash("sha256").update(url).digest("hex").slice(0, 10)}`,
-                    title: fetch.title,
-                    fetch,
-                };
-            },
-            research: (req, opts) => this.research(req, opts),
-            checkChanges: async ({ url, againstSnapshotId, signal }) => {
-                void signal;
-                const previousSnapshot = await this.snapshotStore.get(againstSnapshotId);
-                return this.checkChanges({ url, previousSnapshot });
-            },
-        };
-    }
-    buildResearchFunctionHooks(request) {
-        if (!request.functions || this.funcxExecutor.mode === "disabled")
-            return undefined;
-        const fn = request.functions;
-        const deps = this.webFunctionsDeps();
-        return {
-            planQueries: fn.queryPlanBindingId
-                ? async (input) => planQueries(deps, {
-                    bindingId: fn.queryPlanBindingId,
-                    question: input.question,
-                    constraints: input.constraints,
-                    profileAlternativeId: input.profileAlternativeId ?? fn.profileAlternativeId,
-                    signal: input.signal,
-                })
-                : undefined,
-            evaluateCandidate: fn.candidateEvaluateBindingId
-                ? async (input) => evaluateCandidate(deps, {
-                    bindingId: fn.candidateEvaluateBindingId,
-                    candidate: input.candidate,
-                    profileAlternativeId: input.profileAlternativeId ?? fn.profileAlternativeId,
-                    signal: input.signal,
-                })
-                : undefined,
-            analyzeSource: fn.sourceAnalyzeBindingId
-                ? async (input) => {
-                    const result = await analyzeWebSource(deps, {
-                        bindingId: fn.sourceAnalyzeBindingId,
-                        profileAlternativeId: input.profileAlternativeId ?? fn.profileAlternativeId,
-                        source: { researchSource: input.source },
-                        includeOriginal: false,
-                    }, { signal: input.signal });
-                    return {
-                        analysis: result.analysis,
-                        warnings: result.warnings,
-                        errors: result.errors,
-                    };
-                }
-                : undefined,
-            enrichRecord: fn.recordEnrichBindingId
-                ? async (input) => {
-                    const result = await analyzeWebSource(deps, {
-                        bindingId: fn.recordEnrichBindingId,
-                        profileAlternativeId: input.profileAlternativeId ?? fn.profileAlternativeId,
-                        source: { researchSource: input.source },
-                        enrichBindingId: fn.recordEnrichBindingId,
-                        includeOriginal: true,
-                    }, { signal: input.signal });
-                    return {
-                        original: result.original,
-                        enriched: result.enriched,
-                        conflicts: result.conflicts,
-                        warnings: result.warnings,
-                        errors: result.errors,
-                    };
-                }
-                : undefined,
-            rankEvidence: fn.evidenceRankBindingId
-                ? async (input) => rankEvidenceBlocks(deps, {
-                    bindingId: fn.evidenceRankBindingId,
-                    blocks: input.blocks,
-                    question: input.question,
-                    profileAlternativeId: input.profileAlternativeId ?? fn.profileAlternativeId,
-                    signal: input.signal,
-                })
-                : undefined,
-        };
-    }
-    use(parser) {
-        this.registry.register(parser);
-        return this;
-    }
-    /** Download a URL via Playwright (compatibility default: browser strategy). */
-    async fetch(url, options = {}) {
-        const browser = this.reuseBrowser ? await this.getBrowser() : undefined;
-        return fetchUrl(url, {
-            ...this.defaultFetchOptions,
-            ...siteFetchDefaults(url),
-            ...options,
-            browser: browser ?? options.browser,
-        });
-    }
-    /** Strategy-aware multi-format retrieval (default strategy: auto). */
-    async retrieve(url, options = {}) {
-        const browser = this.reuseBrowser ? await this.getBrowser() : undefined;
-        return retrieve(url, {
-            ...this.defaultFetchOptions,
-            ...siteFetchDefaults(url),
-            strategy: "auto",
-            ...options,
-            browser: browser ?? options.browser,
-        });
-    }
-    async fetchBatch(request) {
-        const browser = this.reuseBrowser ? await this.getBrowser() : undefined;
-        return retrieveBatch({
-            ...request,
-            retrieveOptions: {
-                ...this.defaultFetchOptions,
-                strategy: "auto",
-                ...request.retrieveOptions,
-                browser: browser ?? request.retrieveOptions?.browser,
-            },
-        });
-    }
-    async retrieveCached(url, options = {}) {
-        const browser = this.reuseBrowser ? await this.getBrowser() : undefined;
-        return retrieveWithCache(url, {
-            ...this.defaultFetchOptions,
-            ...siteFetchDefaults(url),
-            strategy: "auto",
-            cache: this.fetchCache,
-            ...options,
-            browser: browser ?? options.browser,
-        });
-    }
-    async classify(url, options = {}) {
-        const fetched = await this.fetch(url, options);
-        return this.registry.classify(fetched);
-    }
-    async parse(url, options = {}) {
-        const fetched = await this.fetch(url, options);
-        return this.registry.parse(fetched);
-    }
-    async parseAs(type, url, options = {}) {
-        const fetched = await this.fetch(url, options);
-        return this.registry.parseAs(type, fetched);
-    }
-    listParsers() {
-        return this.registry.list();
-    }
-    ingest(rootUrl, options = {}) {
-        return ingestRepository(rootUrl, options);
-    }
-    search(request, options = {}) {
-        return runSearch(request, {
-            provider: this.searchProvider ?? null,
-            signal: options.signal,
-        });
-    }
-    searchConfigured() {
-        return this.searchProvider !== undefined;
-    }
-    async fetchSearchResults(searchResult, options = {}) {
-        const targets = resolveFetchTargets(searchResult, options);
-        const concurrency = Math.max(1, options.concurrency ?? 2);
-        const continueOnError = options.continueOnError !== false;
-        const pages = [];
-        for (let i = 0; i < targets.length; i += concurrency) {
-            if (options.signal?.aborted)
-                break;
-            const batch = targets.slice(i, i + concurrency);
-            const settled = await Promise.all(batch.map(async (t) => {
-                try {
-                    const fetched = await this.fetch(t.url, {
-                        ...options.fetchOptions,
-                    });
-                    return {
-                        position: t.position,
-                        url: t.url,
-                        title: fetched.title ?? t.title,
-                        fetch: fetched,
-                    };
-                }
-                catch (err) {
-                    const error = err instanceof Error ? err.message : String(err);
-                    if (!continueOnError)
-                        throw err;
-                    return { position: t.position, url: t.url, title: t.title, error };
-                }
-            }));
-            pages.push(...settled);
+            identity = undefined;
         }
-        return pages;
-    }
-    async searchAndFetch(request) {
-        const { top, positions, urls, concurrency, continueOnError, fetchOptions, signal, ...searchRequest } = request;
-        const searchResult = await this.search(searchRequest, { signal });
-        const pages = await this.fetchSearchResults(searchResult, {
-            positions: positions ?? (urls ? undefined : range(1, top ?? 3)),
-            urls,
-            concurrency,
-            continueOnError,
-            fetchOptions,
-            signal,
-        });
-        return { search: searchResult, pages };
-    }
-    async research(request, options = {}) {
-        await this.loadBindingsFromEnv();
-        const browser = this.reuseBrowser ? await this.getBrowser() : undefined;
-        const deps = {
-            searchFn: (req, opts) => this.search(req, opts),
-            retrieveFn: (url, ropts) => retrieve(url, {
-                ...this.defaultFetchOptions,
-                strategy: "auto",
-                ...ropts,
-                browser,
-            }),
-            registry: this.registry,
-            signal: options.signal,
-            functionHooks: this.buildResearchFunctionHooks(request),
-        };
-        return research(request, deps);
-    }
-    async startResearch(request, opts) {
-        const run = await this.runStore.create({
-            type: "research",
-            request,
-            requestHash: requestHash(request),
-            idempotencyKey: opts?.idempotencyKey,
-        });
-        void this.runResearchJob(run.id, request);
-        return run;
-    }
-    async runResearchJob(runId, request) {
-        await this.runStore.update(runId, { status: "planning" });
-        await this.runStore.update(runId, { status: "running", phase: "research" });
+        let service;
         try {
-            const packet = await this.research(request);
-            const status = packet.status === "completed"
-                ? "completed"
-                : packet.status === "failed"
-                    ? "failed"
-                    : packet.status === "cancelled"
-                        ? "cancelled"
-                        : packet.status === "partial"
-                            ? "partial"
-                            : "completed_with_errors";
-            await this.runStore.update(runId, { status });
-            await this.runStore.appendItem?.(runId, {
-                kind: "packet",
-                data: packet,
-            });
+            service = await this.send("GET", "/v1/status");
         }
-        catch (err) {
-            await this.runStore.update(runId, {
-                status: "failed",
-                errors: [
-                    {
-                        code: "PARSER_FAILED",
-                        message: err instanceof Error ? err.message : String(err),
-                        phase: "export",
-                        retryable: false,
-                    },
-                ],
-            });
+        catch (error) {
+            service = { ok: false, error: error instanceof Error ? error.message : String(error) };
         }
-    }
-    async crawl(request, options = {}) {
-        const browser = this.reuseBrowser ? await this.getBrowser() : undefined;
-        return crawl(request, {
-            retrieve: (url, ropts) => retrieve(url, {
-                ...this.defaultFetchOptions,
-                strategy: "auto",
-                includeLinks: true,
-                ...ropts,
-                browser,
-            }),
-            signal: options.signal,
-        });
-    }
-    async startCrawl(request, opts) {
-        const run = await this.runStore.create({
-            type: "crawl",
-            request,
-            requestHash: requestHash(request),
-            idempotencyKey: opts?.idempotencyKey,
-        });
-        void this.runCrawlJob(run.id, request);
-        return run;
-    }
-    async runCrawlJob(runId, request) {
-        await this.runStore.update(runId, { status: "running", phase: "crawl" });
-        try {
-            const result = await this.crawl(request);
-            await this.runStore.update(runId, {
-                status: result.terminationReason === "cancelled" ? "cancelled" : "completed",
-                usage: {
-                    pagesFetched: result.usage.pagesFetched,
-                    bytesFetched: result.usage.bytesFetched,
-                },
-            });
-            await this.runStore.appendItem?.(runId, {
-                kind: "crawl_result",
-                data: result,
-            });
-        }
-        catch (err) {
-            await this.runStore.update(runId, {
-                status: "failed",
-                errors: [
-                    {
-                        code: "PARSER_FAILED",
-                        message: err instanceof Error ? err.message : String(err),
-                        phase: "crawl",
-                        retryable: false,
-                    },
-                ],
-            });
-        }
-    }
-    async extract(request) {
-        const browser = this.reuseBrowser ? await this.getBrowser() : undefined;
-        return extract(request, {
-            registry: this.registry,
-            adapter: this.extractionAdapter,
-            retrieveFn: (url, opts) => retrieve(url, {
-                ...this.defaultFetchOptions,
-                strategy: "auto",
-                ...opts,
-                browser,
-            }),
-        });
-    }
-    async checkChanges(request) {
-        let current = request.current;
-        if (!current && request.url) {
-            current = await this.retrieve(request.url, { strategy: "auto" });
-            if (current.canonicalUrl) {
-                await this.snapshotStore.put({
-                    canonicalUrl: current.canonicalUrl,
-                    markdown: current.markdown,
-                    rawContentHash: current.rawContentHash,
-                    normalizedContentHash: current.normalizedContentHash,
-                });
-            }
-        }
-        let previousSnapshot = request.previousSnapshot;
-        if (!previousSnapshot && !request.previous && current?.canonicalUrl) {
-            previousSnapshot = await this.snapshotStore.latestForUrl(current.canonicalUrl);
-        }
-        return checkChanges({ ...request, current, previousSnapshot });
-    }
-    async analyze(request, opts) {
-        await this.loadBindingsFromEnv();
-        return analyzeWebSource(this.webFunctionsDeps(), request, opts);
-    }
-    async answer(request, opts) {
-        await this.loadBindingsFromEnv();
-        return answerFromWeb(this.webFunctionsDeps(), request, opts);
-    }
-    async compare(request, opts) {
-        await this.loadBindingsFromEnv();
-        return compareWebSubjects(this.webFunctionsDeps(), request, opts);
-    }
-    async analyzeChanges(request, opts) {
-        await this.loadBindingsFromEnv();
-        return analyzeWebChanges(this.webFunctionsDeps(), request, opts);
-    }
-    async auditResearch(request, opts) {
-        await this.loadBindingsFromEnv();
-        return auditWebResearch(this.webFunctionsDeps(), request, opts);
-    }
-    async listWebFunctions(options) {
-        await this.loadBindingsFromEnv();
-        const listed = listBindings(this.webFunctionBindings, { role: options?.role });
-        const statuses = await Promise.all(listed.map(async (binding) => {
-            const compat = await validateBindingCompatibility(binding, this.funcxExecutor, this.hostPolicy);
-            return { binding, ...compat };
-        }));
         return {
-            mode: this.funcxExecutor.mode,
-            bindings: statuses,
+            sdkVersion: SDK_VERSION,
+            serviceUrl: this.baseUrl,
+            identity: identity ? { fingerprint: identity.fingerprint, enrolled: identity.enrolledService === this.baseUrl } : null,
+            service,
         };
     }
-    async listWebAIProfiles(options) {
-        return listWebAIProfiles({
-            role: options?.role,
-            source: this.aiProfilesSource,
-            catalogLane: "text",
-        });
-    }
-    async previewWebAIProfile(request) {
-        return previewWebAIProfile({
-            profileChoice: request.profileChoice,
-            bindingId: request.bindingId,
-            source: this.aiProfilesSource,
-            hostPolicy: this.hostPolicy,
-        });
-    }
-    async startAnswer(request, opts) {
-        const run = await this.runStore.create({
-            type: "answer",
-            request,
-            requestHash: requestHash(request),
-            idempotencyKey: opts?.idempotencyKey,
-        });
-        void this.runAnswerJob(run.id, request);
-        return run;
-    }
-    async runAnswerJob(runId, request) {
-        await this.runStore.update(runId, { status: "running", phase: "function" });
-        this.activeRunEventSink = (type, data) => {
-            void this.runStore.appendEvent(runId, { type: type, data });
-        };
-        await this.runStore.appendEvent(runId, { type: "function_started", data: { bindingId: request.synthesisBindingId } });
+    async ensureEnrolled() {
+        const identity = await loadOrCreateIdentity(this.identityPath);
+        if (identity.enrolledService === this.baseUrl)
+            return identity;
+        const challenge = await this.send("POST", "/v1/enrollment/challenges", JSON.stringify({ publicKey: identity.publicKey }), {
+            "content-type": "application/json",
+        });
+        const work = await solveWork(challenge.challenge, challenge.workBits ?? 0);
+        await this.signedPost("/v1/installs/enroll", { challenge: challenge.challenge, work }, identity);
+        identity.enrolledService = this.baseUrl;
+        await saveIdentity(this.identityPath, identity);
+        return identity;
+    }
+    async signedPost(path, payload, identity) {
+        const body = JSON.stringify(payload);
+        const timestamp = String(Date.now());
+        const nonce = randomNonce();
+        const message = await canonicalRequest("POST", path, timestamp, nonce, body);
+        const signature = await sign(identity.privateKey, message);
+        return this.send("POST", path, body, {
+            "content-type": "application/json",
+            "x-x12i-key": identity.publicKey,
+            "x-x12i-timestamp": timestamp,
+            "x-x12i-nonce": nonce,
+            "x-x12i-signature": signature,
+        });
+    }
+    async readThrough(path, name) {
+        let cachedBody;
         try {
-            // Resume reuse: if a completed grounded_answer already exists, return it.
-            const existing = await this.runStore.listItems(runId, { kind: "grounded_answer", limit: 1 });
-            if (existing.items[0]?.data) {
-                const result = existing.items[0].data;
-                await this.runStore.update(runId, {
-                    status: result.status === "failed"
-                        ? "failed"
-                        : result.status === "completed_with_errors"
-                            ? "completed_with_errors"
-                            : "completed",
-                });
-                return;
-            }
-            const result = await this.answer(request);
-            await this.runStore.appendItem?.(runId, { kind: "grounded_answer", data: result });
-            await this.runStore.appendEvent(runId, {
-                type: result.audit ? "audit_completed" : "function_completed",
-                data: { status: result.status },
-            });
-            await this.runStore.update(runId, {
-                status: result.status === "failed" ? "failed" : result.status === "completed_with_errors" ? "completed_with_errors" : "completed",
-            });
+            cachedBody = await this.send("GET", path);
         }
-        catch (err) {
-            await this.runStore.update(runId, {
-                status: "failed",
-                errors: [
-                    {
-                        code: "FUNCTION_INVOCATION_FAILED",
-                        message: err instanceof Error ? err.message : String(err),
-                        phase: "function",
-                        retryable: false,
-                    },
-                ],
-            });
+        catch (error) {
+            if (error instanceof SdkError && error.status >= 400 && error.status < 500)
+                throw error;
+            return this.readmeFromRegistry(name);
         }
-        finally {
-            this.activeRunEventSink = undefined;
-        }
-    }
-    async startCompare(request, opts) {
-        const run = await this.runStore.create({
-            type: "compare",
-            request,
-            requestHash: requestHash(request),
-            idempotencyKey: opts?.idempotencyKey,
-        });
-        void this.runCompareJob(run.id, request);
-        return run;
-    }
-    async runCompareJob(runId, request) {
-        await this.runStore.update(runId, { status: "running", phase: "function" });
-        this.activeRunEventSink = (type, data) => {
-            void this.runStore.appendEvent(runId, { type: type, data });
-        };
-        await this.runStore.appendEvent(runId, {
-            type: "function_started",
-            data: { bindingId: request.comparisonBindingId },
-        });
+        const cached = snapshotPackage(cachedBody);
+        if (cached.readmeStatus === "fresh")
+            return packageView(cachedBody, cached, false, "service");
         try {
-            const existing = await this.runStore.listItems(runId, { kind: "web_comparison", limit: 1 });
-            if (existing.items[0]?.data) {
-                const result = existing.items[0].data;
-                await this.runStore.update(runId, {
-                    status: result.status === "failed"
-                        ? "failed"
-                        : result.status === "completed_with_errors"
-                            ? "completed_with_errors"
-                            : "completed",
-                });
-                return;
-            }
-            const result = await this.compare(request);
-            await this.runStore.appendItem?.(runId, { kind: "web_comparison", data: result });
-            await this.runStore.appendEvent(runId, {
-                type: result.audit ? "audit_completed" : "function_completed",
-                data: { status: result.status },
-            });
-            await this.runStore.update(runId, {
-                status: result.status === "failed"
-                    ? "failed"
-                    : result.status === "completed_with_errors"
-                        ? "completed_with_errors"
-                        : "completed",
-            });
-        }
-        catch (err) {
-            await this.runStore.update(runId, {
-                status: "failed",
-                errors: [
-                    {
-                        code: "FUNCTION_INVOCATION_FAILED",
-                        message: err instanceof Error ? err.message : String(err),
-                        phase: "function",
-                        retryable: false,
-                    },
-                ],
-            });
+            const freshBody = await this.send("GET", `${path}?update=1`);
+            const fresh = snapshotPackage(freshBody);
+            const updated = fresh.readme !== cached.readme || fresh.version !== cached.version || fresh.description !== cached.description;
+            return packageView(freshBody, cached, updated, "service");
         }
-        finally {
-            this.activeRunEventSink = undefined;
+        catch (error) {
+            return { ...packageView(cachedBody, cached, false, "service"), refreshError: error instanceof Error ? error.message : String(error) };
         }
     }
-    getRun(runId) {
-        return this.runStore.get(runId);
-    }
-    listRunItems(runId, options) {
-        return this.runStore.listItems(runId, options);
-    }
-    cancelRun(runId) {
-        return this.runStore.requestCancel(runId);
+    async readmeFromRegistry(name) {
+        const info = await getReadme(name, { fetch: this.fetchImpl });
+        const cached = { readme: "", readmeStatus: "missing", version: null, description: "", modifiedAt: null, refreshedAt: null };
+        return {
+            name: info.name,
+            readme: info.readme,
+            readmeStatus: "fresh",
+            version: info.version,
+            description: info.description,
+            modifiedAt: info.modifiedAt,
+            refreshedAt: null,
+            updated: Boolean(info.readme),
+            source: "registry",
+            cached,
+            detail: { ...info },
+        };
     }
-    async resumeRun(runId) {
-        const run = await this.runStore.get(runId);
-        if (!run)
-            throw new Error("RUN_NOT_FOUND");
-        if (!["partial", "cancelled", "failed"].includes(run.status)) {
-            throw new Error("RUN_NOT_RESUMABLE");
-        }
-        await this.runStore.update(runId, { status: "queued", cancellationRequested: false });
-        if (run.type === "research") {
-            void this.runResearchJob(runId, run.request);
-        }
-        else if (run.type === "crawl") {
-            void this.runCrawlJob(runId, run.request);
-        }
-        else if (run.type === "answer") {
-            void this.runAnswerJob(runId, run.request);
+    async send(method, path, body, headers = {}) {
+        let response;
+        try {
+            response = await this.fetchImpl(`${this.baseUrl}${path}`, { method, headers, body });
         }
-        else if (run.type === "compare") {
-            void this.runCompareJob(runId, run.request);
+        catch (error) {
+            throw new SdkError(error instanceof Error ? error.message : "Service unreachable");
         }
-        return (await this.runStore.get(runId));
-    }
-    async getBrowser() {
-        this.browserPromise ??= launchBrowser(this.defaultFetchOptions.executablePath);
-        return this.browserPromise;
-    }
-    async close() {
-        if (this.browserPromise) {
-            const browser = await this.browserPromise;
-            await browser.close();
-            this.browserPromise = undefined;
+        const text = await response.text();
+        const parsed = text ? safeJson(text) : {};
+        if (!response.ok) {
+            const record = parsed;
+            throw new SdkError(record.error?.message ?? `Service returned ${response.status}`, response.status, record.error?.code ?? "HTTP");
         }
-        void this.ownsCache;
-        void this.ownsSnapshots;
-        void this.ownsRuns;
+        return parsed;
     }
 }
-function resolveSearchProvider(search) {
-    if (search === null)
-        return undefined;
-    if (!search) {
-        return createSerperProvider(loadSearchConfig());
-    }
-    if ("search" in search && typeof search.search === "function") {
-        return search;
+function snapshotPackage(body) {
+    const status = body.readmeStatus;
+    return {
+        readme: typeof body.readme === "string" ? body.readme : "",
+        readmeStatus: status === "fresh" || status === "stale" || status === "missing" ? status : "missing",
+        version: typeof body.version === "string" ? body.version : null,
+        description: typeof body.description === "string" ? body.description : "",
+        modifiedAt: typeof body.modifiedAt === "string" ? body.modifiedAt : null,
+        refreshedAt: typeof body.refreshedAt === "string" ? body.refreshedAt : null,
+    };
+}
+function packageView(body, cached, updated, source) {
+    const current = updated || cached.readmeStatus !== "fresh" ? snapshotPackage(body) : cached;
+    const name = typeof body.name === "string" ? body.name : "";
+    return {
+        name,
+        readme: current.readme,
+        readmeStatus: current.readmeStatus,
+        version: current.version,
+        description: current.description,
+        modifiedAt: current.modifiedAt,
+        refreshedAt: current.refreshedAt,
+        updated,
+        source,
+        cached,
+        detail: body,
+    };
+}
+function packagePath(name) {
+    if (name.startsWith("@")) {
+        const slash = name.indexOf("/");
+        if (slash > 1)
+            return `/v1/packages/${encodeURIComponent(name.slice(0, slash))}/${encodeURIComponent(name.slice(slash + 1))}`;
     }
-    return createSerperProvider(search);
+    return `/v1/packages/${encodeURIComponent(name)}`;
 }
-function resolveFetchTargets(searchResult, options) {
-    if (options.urls?.length) {
-        return options.urls.map((url) => {
-            const match = searchResult.organic.find((o) => o.url === url);
-            return { url, position: match?.position, title: match?.title };
-        });
+function safeJson(text) {
+    try {
+        return JSON.parse(text);
     }
-    const positions = options.positions?.length
-        ? options.positions
-        : searchResult.organic.map((o) => o.position);
-    const out = [];
-    for (const pos of positions) {
-        const hit = searchResult.organic.find((o) => o.position === pos);
-        if (hit)
-            out.push({ url: hit.url, position: hit.position, title: hit.title });
+    catch {
+        return { text };
     }
-    return out;
-}
-function range(start, endInclusive) {
-    const out = [];
-    for (let i = start; i <= endInclusive; i++)
-        out.push(i);
-    return out;
 }
 //# sourceMappingURL=client.js.map