@ixo/openhands-sdk 0.0.0-stage → 0.1.0

package/dist/cjs/data/oracles.js

@@ -0,0 +1,115 @@
+"use strict";
+/** Server-side reads of the oracles on chain. Never imported by client code. */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadOracles = loadOracles;
+exports.loadCheckers = loadCheckers;
+exports.oracleByAddress = oracleByAddress;
+/* Relative rather than the `@ixo/openhands-sdk/rubric` alias so this module also runs
+   under plain Node type-stripping — the probe script and any future agent-side
+   caller resolve it without Next's path mapping. */
+const card_ts_1 = require("../rubric/card.js");
+const outbound_ts_1 = require("./outbound.js");
+const gql_ts_1 = require("./gql.js");
+const CARD_TIMEOUT_MS = 8000;
+/*
+ * A card is a stranger's document at a stranger's address.
+ *
+ * Both halves matter. The address is published on chain by whoever minted the
+ * oracle entity, so fetching it is our server going where somebody else chose —
+ * the same shape as the Profile URL, and bounded by the same rule. And the
+ * strings inside it are rendered in the checker picker on /ask and on an
+ * agent's record, so they are cut to a length a page can hold.
+ *
+ * The service list is capped too. A card claiming ten thousand services is not
+ * an offer, and the picker would try to draw all of them.
+ */
+const NAME_MAX = 60;
+const DESCRIPTION_MAX = 200;
+const SERVICES_MAX = 20;
+async function fetchCard(url) {
+    const card = (0, card_ts_1.parseAgentCard)(await (0, outbound_ts_1.fetchPublicJson)(url, { timeoutMs: CARD_TIMEOUT_MS, revalidate: 300 }));
+    if (!card)
+        return null;
+    const subject = card.credentialSubject;
+    return {
+        ...card,
+        credentialSubject: {
+            ...subject,
+            name: (0, outbound_ts_1.clampText)(subject.name, NAME_MAX) ?? "",
+            description: (0, outbound_ts_1.clampText)(subject.description, DESCRIPTION_MAX) ?? "",
+            services: (subject.services ?? []).slice(0, SERVICES_MAX).map((service) => ({
+                ...service,
+                name: (0, outbound_ts_1.clampText)(service.name, NAME_MAX) ?? "",
+                description: (0, outbound_ts_1.clampText)(service.description, DESCRIPTION_MAX) ?? ""
+            }))
+        }
+    };
+}
+/**
+ * Every oracle on the network that publishes a card.
+ *
+ * An oracle without a card is not an error and not hidden — it simply has not
+ * said what it offers, so there is nothing honest to render for it. A card that
+ * will not load is the same case: the entity is still on chain, and the next
+ * read may well get it.
+ */
+async function loadOracles(limit = 200) {
+    /*
+     * Every active oracle, not a page of them. Blocksync sorts ids lexically, so
+     * a `first: 30` returns the alphabetically-first thirty rather than the most
+     * relevant thirty — the same trap that once made ten asks on the board render
+     * as "Ask #id". There are 66 oracles on testnet and 2 publish a card, so the
+     * honest read is: take them all, then fetch only the cards that exist.
+     */
+    const data = await (0, gql_ts_1.gql)(`query { entities(filter: {type: {equalTo: "oracle"}, status: {equalTo: 0}}, first: ${limit}) { nodes { id type status owner } } }`, 60).catch(() => null);
+    const entities = data?.entities?.nodes ?? [];
+    if (entities.length === 0)
+        return [];
+    const ids = entities.map((entity) => JSON.stringify(entity.id)).join(",");
+    const iidData = await (0, gql_ts_1.gql)(`query { iids(filter: {id: {in: [${ids}]}}, first: ${limit}) { nodes { id linkedResource } } }`, 60).catch(() => null);
+    const resources = new Map((iidData?.iids?.nodes ?? []).map((node) => [node.id, node.linkedResource ?? []]));
+    const owners = new Map(entities.map((entity) => [entity.id, entity.owner ?? ""]));
+    /* Only entities that actually anchor a card cost an HTTP fetch. */
+    const carded = entities.filter((entity) => (resources.get(entity.id) ?? []).some((resource) => resource.id.endsWith("#acard") || resource.type === "agentCard"));
+    const cards = await Promise.all(carded.map(async (entity) => {
+        const acard = (resources.get(entity.id) ?? []).find((resource) => resource.id.endsWith("#acard") || resource.type === "agentCard");
+        if (!acard?.serviceEndpoint)
+            return null;
+        const card = await fetchCard(acard.serviceEndpoint);
+        if (!card)
+            return null;
+        const services = card.credentialSubject.services ?? [];
+        const prices = services.map((service) => service.price?.amount).filter((amount) => typeof amount === "number" && amount > 0);
+        const serves = new Set();
+        for (const service of services)
+            for (const kind of service.serves ?? ["measure"])
+                serves.add(kind);
+        return {
+            did: entity.id,
+            address: owners.get(entity.id) ?? "",
+            name: card.credentialSubject.name,
+            description: card.credentialSubject.description,
+            services,
+            priceUixo: prices.length ? Math.min(...prices) : null,
+            serves: [...serves]
+        };
+    }));
+    return cards.filter((oracle) => Boolean(oracle) && Boolean(oracle?.address));
+}
+/**
+ * The oracles that will rule on work. A checker must be able to settle machine-
+ * checked criteria at minimum — an agent that can only judge prose cannot be
+ * trusted with an ask whose terms include a measurement.
+ */
+async function loadCheckers(limit = 200) {
+    const oracles = await loadOracles(limit);
+    return oracles.filter((oracle) => oracle.serves.includes("measure") && oracle.services.some((service) => service.id.startsWith("check")));
+}
+/** One oracle by the address that signs for it. */
+async function oracleByAddress(address) {
+    if (!address)
+        return null;
+    const oracles = await loadOracles(200).catch(() => []);
+    return oracles.find((oracle) => oracle.address === address) ?? null;
+}
+//# sourceMappingURL=oracles.js.map

package/dist/cjs/data/oracles.js.map

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

package/dist/cjs/data/outbound.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Where this server is willing to go, and how much it will believe when it
+ * gets there.
+ *
+ * Openhands reads the whole network. Most of what it renders was written by
+ * somebody else: an entity's name, an agent's card, the URLs both of those
+ * point at. That is the product working — a stranger's oracle should be
+ * hireable without asking us — and it means our server routinely makes requests
+ * an untrusted party chose the address of, and renders strings an untrusted
+ * party wrote.
+ *
+ * Neither of those is a bug. Doing them unbounded is. This is the one place
+ * that says what the bounds are, so a third caller does not invent a third
+ * answer.
+ */
+/**
+ * `https` only. Not prudishness — plain http is how you reach the addresses
+ * above without TLS complaining, and there is no public document that needs it.
+ *
+ * What this does **not** stop is DNS rebinding: a hostname that answers with a
+ * public address when checked and a private one when fetched. Closing that
+ * needs resolution-time pinning, which is a bigger machine than the risk here
+ * justifies — every response below is parsed as JSON and a handful of known
+ * fields are read out of it.
+ */
+export declare const reachable: (url: string) => boolean;
+/**
+ * Fetch a small public JSON document, or nothing.
+ *
+ * Nothing is the answer to every failure — refused address, bad status, a
+ * redirect that lands somewhere the address check would have refused, a body
+ * too big to be the document it claims to be, malformed JSON. None of these are
+ * errors worth propagating: a name or a card is decoration on a page whose
+ * subject is money, and the page has to render without it.
+ */
+export declare function fetchPublicJson(url: string, options?: {
+    timeoutMs?: number;
+    maxBytes?: number;
+    revalidate?: number;
+}): Promise<unknown | null>;
+/**
+ * A string somebody else wrote, made safe to put on a page.
+ *
+ * Control characters out — that is how a name becomes two lines, or borrows the
+ * shape of a label the page uses for something it verified — and a ceiling,
+ * because past a certain length it is not a name, it is a way of ruining a page
+ * that does not belong to whoever wrote it.
+ */
+export declare const clampText: (raw: unknown, max: number) => string | null;
+//# sourceMappingURL=outbound.d.ts.map

package/dist/cjs/data/outbound.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"outbound.d.ts","sourceRoot":"","sources":["../../../src/data/outbound.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAYH;;;;;;;;;GASG;AACH,eAAO,MAAM,SAAS,GAAI,KAAK,MAAM,KAAG,OAQvC,CAAC;AAEF;;;;;;;;GAQG;AACH,wBAAsB,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,GAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAqBxJ;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,SAAS,GAAI,KAAK,OAAO,EAAE,KAAK,MAAM,KAAG,MAAM,GAAG,IAM9D,CAAC"}

package/dist/cjs/data/outbound.js

@@ -0,0 +1,102 @@
+"use strict";
+/**
+ * Where this server is willing to go, and how much it will believe when it
+ * gets there.
+ *
+ * Openhands reads the whole network. Most of what it renders was written by
+ * somebody else: an entity's name, an agent's card, the URLs both of those
+ * point at. That is the product working — a stranger's oracle should be
+ * hireable without asking us — and it means our server routinely makes requests
+ * an untrusted party chose the address of, and renders strings an untrusted
+ * party wrote.
+ *
+ * Neither of those is a bug. Doing them unbounded is. This is the one place
+ * that says what the bounds are, so a third caller does not invent a third
+ * answer.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.clampText = exports.reachable = void 0;
+exports.fetchPublicJson = fetchPublicJson;
+/**
+ * Hosts that are ours rather than the internet's.
+ *
+ * Reaching one of these on a stranger's instruction is the shape of an SSRF:
+ * cloud metadata at `169.254.169.254`, a database on `10.x`, a homeserver on
+ * localhost. None of them can be a legitimate profile or agent card.
+ */
+const PRIVATE_HOST = /^(localhost|0\.0\.0\.0|\[?::1\]?|10\.\d+\.\d+\.\d+|127\.\d+\.\d+\.\d+|169\.254\.\d+\.\d+|192\.168\.\d+\.\d+|172\.(1[6-9]|2\d|3[01])\.\d+\.\d+|\[?f[cd][0-9a-f]{2}:|\[?fe80:)/i;
+/**
+ * `https` only. Not prudishness — plain http is how you reach the addresses
+ * above without TLS complaining, and there is no public document that needs it.
+ *
+ * What this does **not** stop is DNS rebinding: a hostname that answers with a
+ * public address when checked and a private one when fetched. Closing that
+ * needs resolution-time pinning, which is a bigger machine than the risk here
+ * justifies — every response below is parsed as JSON and a handful of known
+ * fields are read out of it.
+ */
+const reachable = (url) => {
+    try {
+        const parsed = new URL(url);
+        if (parsed.protocol !== "https:")
+            return false;
+        return !PRIVATE_HOST.test(parsed.hostname);
+    }
+    catch {
+        return false;
+    }
+};
+exports.reachable = reachable;
+/**
+ * Fetch a small public JSON document, or nothing.
+ *
+ * Nothing is the answer to every failure — refused address, bad status, a
+ * redirect that lands somewhere the address check would have refused, a body
+ * too big to be the document it claims to be, malformed JSON. None of these are
+ * errors worth propagating: a name or a card is decoration on a page whose
+ * subject is money, and the page has to render without it.
+ */
+async function fetchPublicJson(url, options = {}) {
+    const { timeoutMs = 8000, maxBytes = 64 * 1024, revalidate = 300 } = options;
+    if (!(0, exports.reachable)(url))
+        return null;
+    try {
+        /* `next` is Next's own addition to RequestInit and is absent from the plain
+           Node lib these files are also typechecked against. */
+        const response = await fetch(url, { signal: AbortSignal.timeout(timeoutMs), redirect: "follow", next: { revalidate } });
+        if (!response.ok)
+            return null;
+        /* A redirect can land somewhere the first check would have refused, so the
+           address actually reached is checked too. */
+        if (response.url && !(0, exports.reachable)(response.url))
+            return null;
+        if (Number(response.headers.get("content-length") ?? 0) > maxBytes)
+            return null;
+        const text = await response.text();
+        if (text.length > maxBytes)
+            return null;
+        return JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * A string somebody else wrote, made safe to put on a page.
+ *
+ * Control characters out — that is how a name becomes two lines, or borrows the
+ * shape of a label the page uses for something it verified — and a ceiling,
+ * because past a certain length it is not a name, it is a way of ruining a page
+ * that does not belong to whoever wrote it.
+ */
+const clampText = (raw, max) => {
+    if (typeof raw !== "string")
+        return null;
+    // eslint-disable-next-line no-control-regex -- stripping them is the point
+    const text = raw.replace(/[\u0000-\u001f\u007f\u2028\u2029]/g, " ").replace(/\s+/g, " ").trim();
+    if (!text)
+        return null;
+    return text.length <= max ? text : `${text.slice(0, max)}…`;
+};
+exports.clampText = clampText;
+//# sourceMappingURL=outbound.js.map

package/dist/cjs/data/outbound.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"outbound.js","sourceRoot":"","sources":["../../../src/data/outbound.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;GAcG;;;AAyCH,0CAqBC;AA5DD;;;;;;GAMG;AACH,MAAM,YAAY,GAChB,+KAA+K,CAAC;AAElL;;;;;;;;;GASG;AACI,MAAM,SAAS,GAAG,CAAC,GAAW,EAAW,EAAE;IAChD,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;QAC5B,IAAI,MAAM,CAAC,QAAQ,KAAK,QAAQ;YAAE,OAAO,KAAK,CAAC;QAC/C,OAAO,CAAC,YAAY,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IAC7C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC,CAAC;AARW,QAAA,SAAS,aAQpB;AAEF;;;;;;;;GAQG;AACI,KAAK,UAAU,eAAe,CAAC,GAAW,EAAE,UAA0E,EAAE;IAC7H,MAAM,EAAE,SAAS,GAAG,IAAI,EAAE,QAAQ,GAAG,EAAE,GAAG,IAAI,EAAE,UAAU,GAAG,GAAG,EAAE,GAAG,OAAO,CAAC;IAC7E,IAAI,CAAC,IAAA,iBAAS,EAAC,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IAEjC,IAAI,CAAC;QACH;gEACwD;QACxD,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE,EAAE,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE,EAAE,UAAU,EAAE,EAAiB,CAAC,CAAC;QACvI,IAAI,CAAC,QAAQ,CAAC,EAAE;YAAE,OAAO,IAAI,CAAC;QAE9B;sDAC8C;QAC9C,IAAI,QAAQ,CAAC,GAAG,IAAI,CAAC,IAAA,iBAAS,EAAC,QAAQ,CAAC,GAAG,CAAC;YAAE,OAAO,IAAI,CAAC;QAC1D,IAAI,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC,IAAI,CAAC,CAAC,GAAG,QAAQ;YAAE,OAAO,IAAI,CAAC;QAEhF,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC;QACnC,IAAI,IAAI,CAAC,MAAM,GAAG,QAAQ;YAAE,OAAO,IAAI,CAAC;QACxC,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAY,CAAC;IACrC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED;;;;;;;GAOG;AACI,MAAM,SAAS,GAAG,CAAC,GAAY,EAAE,GAAW,EAAiB,EAAE;IACpE,IAAI,OAAO,GAAG,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IACzC,2EAA2E;IAC3E,MAAM,IAAI,GAAG,GAAG,CAAC,OAAO,CAAC,oCAAoC,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;IAChG,IAAI,CAAC,IAAI;QAAE,OAAO,IAAI,CAAC;IACvB,OAAO,IAAI,CAAC,MAAM,IAAI,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,GAAG,CAAC;AAC9D,CAAC,CAAC;AANW,QAAA,SAAS,aAMpB"}

package/dist/cjs/data/paged.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Every page of a Cosmos REST list, or an error — never the first page
+ * passed off as the whole list.
+ *
+ * The chain's list endpoints answer one page and a `pagination.next_key` for
+ * the rest. Three readers here asked for one page of 200 or 500 and stopped,
+ * so past a few hundred grants the lobby, `/me`'s queue and an agent's
+ * delegations simply lost the tail, and nothing anywhere said so (scale
+ * review A11). This follows `next_key` until the chain says there is no more.
+ *
+ * **It has a ceiling, and the ceiling throws.** An address can be handed
+ * grants by anybody, so "read until done" with no bound is a loop a stranger
+ * can lengthen for free. A list longer than `maxPages × limit` is an error
+ * the caller sees, not a partial list it trusts — the same rule the GraphQL
+ * reader keeps: "we could not read it all" must never look like "that is
+ * all there is".
+ *
+ * No chain SDK: this sits under pages as well as workers.
+ */
+/** The node answered with something other than a page. */
+export declare class RestError extends Error {
+    readonly status: number;
+    readonly url: string;
+    constructor(url: string, status: number);
+}
+/** A list longer than the reader is allowed to follow. Thrown instead of a partial answer. */
+export declare class TruncatedRead extends Error {
+    readonly what: string;
+    readonly read: number;
+    constructor(what: string, read: number, detail: string);
+}
+export interface PagedRestOptions {
+    /** The array field the endpoint lists under — `grants`, `balances`, … */
+    key: string;
+    /** Rows per page. The node may cap it lower; `next_key` still says whether more remain. */
+    limit?: number;
+    /** Pages followed before giving up loudly. */
+    maxPages?: number;
+    /** Per page, not for the whole read. */
+    timeoutMs?: number;
+    /** Extra init for every page (Next's `next`, `cache`). Its `signal` is replaced per page. */
+    init?: RequestInit;
+    fetchImpl?: typeof fetch;
+}
+export declare const PAGE_LIMIT = 200;
+export declare const MAX_PAGES = 100;
+export declare function pagedRest<T>(url: string, options: PagedRestOptions): Promise<T[]>;
+//# sourceMappingURL=paged.d.ts.map

package/dist/cjs/data/paged.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paged.d.ts","sourceRoot":"","sources":["../../../src/data/paged.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,0DAA0D;AAC1D,qBAAa,SAAU,SAAQ,KAAK;IAClC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;gBACT,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;CAMxC;AAED,8FAA8F;AAC9F,qBAAa,aAAc,SAAQ,KAAK;IACtC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBACV,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;CAMvD;AAED,MAAM,WAAW,gBAAgB;IAC/B,yEAAyE;IACzE,GAAG,EAAE,MAAM,CAAC;IACZ,2FAA2F;IAC3F,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,8CAA8C;IAC9C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,wCAAwC;IACxC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,6FAA6F;IAC7F,IAAI,CAAC,EAAE,WAAW,CAAC;IACnB,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B;AAED,eAAO,MAAM,UAAU,MAAM,CAAC;AAC9B,eAAO,MAAM,SAAS,MAAM,CAAC;AAE7B,wBAAsB,SAAS,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC,CA4BvF"}

package/dist/cjs/data/paged.js

@@ -0,0 +1,81 @@
+"use strict";
+/**
+ * Every page of a Cosmos REST list, or an error — never the first page
+ * passed off as the whole list.
+ *
+ * The chain's list endpoints answer one page and a `pagination.next_key` for
+ * the rest. Three readers here asked for one page of 200 or 500 and stopped,
+ * so past a few hundred grants the lobby, `/me`'s queue and an agent's
+ * delegations simply lost the tail, and nothing anywhere said so (scale
+ * review A11). This follows `next_key` until the chain says there is no more.
+ *
+ * **It has a ceiling, and the ceiling throws.** An address can be handed
+ * grants by anybody, so "read until done" with no bound is a loop a stranger
+ * can lengthen for free. A list longer than `maxPages × limit` is an error
+ * the caller sees, not a partial list it trusts — the same rule the GraphQL
+ * reader keeps: "we could not read it all" must never look like "that is
+ * all there is".
+ *
+ * No chain SDK: this sits under pages as well as workers.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_PAGES = exports.PAGE_LIMIT = exports.TruncatedRead = exports.RestError = void 0;
+exports.pagedRest = pagedRest;
+/** The node answered with something other than a page. */
+class RestError extends Error {
+    status;
+    url;
+    constructor(url, status) {
+        super(`REST ${status} for ${url.replace(/\?.*$/, "")}`);
+        this.name = "RestError";
+        this.status = status;
+        this.url = url;
+    }
+}
+exports.RestError = RestError;
+/** A list longer than the reader is allowed to follow. Thrown instead of a partial answer. */
+class TruncatedRead extends Error {
+    what;
+    read;
+    constructor(what, read, detail) {
+        super(`${what}: ${detail} after ${read} rows; refusing to answer with a partial list`);
+        this.name = "TruncatedRead";
+        this.what = what;
+        this.read = read;
+    }
+}
+exports.TruncatedRead = TruncatedRead;
+exports.PAGE_LIMIT = 200;
+exports.MAX_PAGES = 100;
+async function pagedRest(url, options) {
+    const { key, limit = exports.PAGE_LIMIT, maxPages = exports.MAX_PAGES, timeoutMs = 15_000, init = {}, fetchImpl = fetch } = options;
+    const rows = [];
+    const seen = new Set();
+    let nextKey = null;
+    for (let page = 0; page < maxPages; page += 1) {
+        const target = new URL(url);
+        target.searchParams.set("pagination.limit", String(limit));
+        if (nextKey)
+            target.searchParams.set("pagination.key", nextKey);
+        else
+            target.searchParams.delete("pagination.key");
+        const response = await fetchImpl(target.toString(), { ...init, signal: AbortSignal.timeout(timeoutMs) });
+        if (!response.ok)
+            throw new RestError(target.toString(), response.status);
+        const body = (await response.json());
+        const list = body[key];
+        if (list !== undefined && list !== null && !Array.isArray(list))
+            throw new TypeError(`REST ${key} is not a list for ${url.replace(/\?.*$/, "")}`);
+        rows.push(...(list ?? []));
+        nextKey = body.pagination?.next_key || null;
+        if (!nextKey)
+            return rows;
+        /* A node that hands back a key it already gave would loop to the cap;
+           say what happened instead of blaming the list's length. */
+        if (seen.has(nextKey))
+            throw new TruncatedRead(key, rows.length, "the node repeated a page key");
+        seen.add(nextKey);
+    }
+    throw new TruncatedRead(key, rows.length, `more than ${maxPages} pages of ${limit}`);
+}
+//# sourceMappingURL=paged.js.map

package/dist/cjs/data/paged.js.map

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

package/dist/cjs/data/profiles.d.ts

@@ -0,0 +1,3 @@
+export declare const cleanEntityName: (raw: unknown) => string | null;
+export declare function entityNames(ids: (string | null | undefined)[]): Promise<Map<string, string>>;
+//# sourceMappingURL=profiles.d.ts.map

package/dist/cjs/data/profiles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"profiles.d.ts","sourceRoot":"","sources":["../../../src/data/profiles.ts"],"names":[],"mappings":"AA2BA,eAAO,MAAM,eAAe,GAAI,KAAK,OAAO,KAAG,MAAM,GAAG,IAAgC,CAAC;AAqCzF,wBAAsB,WAAW,CAAC,GAAG,EAAE,CAAC,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,EAAE,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAqBlG"}

package/dist/cjs/data/profiles.js

@@ -0,0 +1,71 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.cleanEntityName = void 0;
+exports.entityNames = entityNames;
+const gql_ts_1 = require("./gql.js");
+const outbound_ts_1 = require("./outbound.js");
+const clean = (value) => value.trim().replace(/[\r\n]+$/, "");
+/**
+ * The board reads **every** claim collection on the network, so the entity
+ * behind a row is usually a stranger's — and its Profile setting is a URL that
+ * stranger chose. Fetching it is the feature; the bounds on doing so live in
+ * `outbound.ts`, which the agent-card reader uses for the same reason.
+ */
+const NAME_MAX = 120;
+const cleanEntityName = (raw) => (0, outbound_ts_1.clampText)(raw, NAME_MAX);
+exports.cleanEntityName = cleanEntityName;
+function profileUrl(entity) {
+    let endpoint = entity.settings?.["Profile"]?.serviceEndpoint ?? null;
+    if (!endpoint)
+        return null;
+    endpoint = clean(endpoint);
+    if (endpoint.includes("ipfs.w3s.link") || endpoint.includes("ipfs.dweb.link")) {
+        endpoint = endpoint.split(".")[0]?.replace("https://", "") ?? "";
+    }
+    if (endpoint.startsWith("matrix:"))
+        return null;
+    if (endpoint.startsWith("http://") || endpoint.startsWith("https://"))
+        return (0, outbound_ts_1.reachable)(endpoint) ? endpoint : null;
+    const colon = endpoint.indexOf(":");
+    if (colon === -1) {
+        return /^[a-z0-9]{40,}$/i.test(endpoint) ? `https://${endpoint}.ipfs.w3s.link` : null;
+    }
+    const serviceId = endpoint.slice(0, colon);
+    const path = endpoint.slice(colon + 1);
+    if (serviceId === "ipfs")
+        return `https://${path.replace(/^\/+/, "")}.ipfs.w3s.link`;
+    const service = entity.service?.find((candidate) => candidate.id.slice(candidate.id.indexOf("#") + 1) === serviceId);
+    const base = service?.serviceEndpoint ? clean(service.serviceEndpoint) : "";
+    if (!base)
+        return null;
+    /* The service endpoint is the entity's too, so it is checked like the rest. */
+    const built = `${base.replace(/\/+$/, "")}/${path.replace(/^\/+/, "")}`;
+    return (0, outbound_ts_1.reachable)(built) ? built : null;
+}
+async function fetchName(entity) {
+    const url = profileUrl(entity);
+    if (!url)
+        return null;
+    const profile = (await (0, outbound_ts_1.fetchPublicJson)(url, { timeoutMs: 4000, revalidate: 3600 }));
+    return (0, exports.cleanEntityName)(profile?.name);
+}
+async function entityNames(ids) {
+    const names = new Map();
+    const unique = [...new Set(ids.filter((id) => Boolean(id)))];
+    if (unique.length === 0)
+        return names;
+    try {
+        const data = await (0, gql_ts_1.gql)(`query { entities(filter: {id: {in: [${unique.map((id) => JSON.stringify(id)).join(", ")}]}}) { nodes { id alsoKnownAs settings service } } }`, 300);
+        await Promise.all(data.entities.nodes.map(async (entity) => {
+            /* `alsoKnownAs` is on chain and just as much a stranger's string. */
+            const name = (await fetchName(entity)) ?? (entity.alsoKnownAs && !entity.alsoKnownAs.startsWith("did:") ? (0, exports.cleanEntityName)(entity.alsoKnownAs) : null);
+            if (name)
+                names.set(entity.id, name);
+        }));
+    }
+    catch {
+        // Names are decoration; the data stands without them.
+    }
+    return names;
+}
+//# sourceMappingURL=profiles.js.map

package/dist/cjs/data/profiles.js.map

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

package/dist/cjs/data/proof.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Reading a `verificationProof`, whatever shape it arrived in.
+ *
+ * This field has meant four different things on this chain, and every one of
+ * them is still out there on claims nobody is going to re-evaluate: a bare
+ * content address of a document in the estate's own stores (the early
+ * receipts), a `sha256:<hex>` digest (the standard's own digest form), a URL
+ * to a signed determination, and — since the oracle migration — a bare
+ * content address that is not a stored document at all: the decision
+ * engine's receipt, served by the engine at `/v1/receipts/<cid>`. A reader
+ * that assumes one of them silently shows nothing for the others, which is
+ * how a page ends up quietly claiming a checked claim was never checked.
+ *
+ * So: no assumptions, one classifier, and callers branch on `kind` rather
+ * than on a string test they invented at the call site. The classifier is
+ * synchronous and reads the string alone, so a bare CID comes out as `cid`
+ * — a stored document's address and the engine's are the same shape —
+ * and `engine` is what `receiptBehind` says once it has asked the engine (see
+ * `engine.ts`).
+ */
+import type { EngineDecision } from "./engine.ts";
+export type ProofKind = "udid-url" | "cid" | "engine" | "digest" | "unknown";
+export interface ProofRef {
+    kind: ProofKind;
+    /** The content address, when one can be recovered. */
+    cid?: string;
+    /** Where the document can be fetched, when the proof says. */
+    url?: string;
+    /** The raw value, always, so a surface can show what it could not read. */
+    raw: string;
+}
+export declare function proofRef(proof?: string | null): ProofRef;
+/**
+ * The check receipt behind a proof.
+ *
+ * A determination is not the receipt — it *points at* the receipt, in
+ * `res.trace.cid`. Pages that show the checker's words need that address, and
+ * this is the one place that knows how to get from either proof shape to it,
+ * so the join lives here rather than in four components.
+ */
+export declare function receiptCidOf(proof: ProofRef, fetchJson: (url: string) => Promise<unknown>, fetchCid?: (cid: string) => Promise<unknown>): Promise<string | null>;
+export interface ReceiptBehindOptions {
+    /**
+     * Whether to ask the decision engine about a bare CID, and where it is.
+     * Defaults to `NEXT_PUBLIC_DECISION_ENGINE_URL`; `false` never asks (a
+     * caller that knows it holds a pre-migration proof). `reasons` joins gate
+     * codes to the rubric's sentences — see `gateReasonsFor`.
+     */
+    engine?: false | {
+        baseUrl?: string;
+        reasons?: Record<string, string>;
+    };
+}
+/**
+ * The check receipt behind whatever the chain recorded, in one call.
+ *
+ * Three surfaces do this dance — the MCP's answer envelope, the check API,
+ * and the words a thread renders — and each of them had its own idea of what
+ * a proof looks like. Two of the three were wrong for at least one of the
+ * three shapes. This is the dance, once: classify, follow a determination's
+ * trace when there is one, fetch the receipt, hand it back.
+ *
+ * **A bare CID asks the engine first, then the document stores.** Both
+ * address spaces have the same shape, so shape cannot tell them apart, and
+ * the order is chosen to make the common case one round trip: since the
+ * oracle migration every new verdict is an engine receipt, and the engine
+ * answers a miss with an indexed 404 in milliseconds (a primary-key lookup),
+ * while a miss in the stores can be a walk of the public network. The only
+ * rows that pay the extra 404 are the earliest bare-CID Openhands receipts
+ * — the oldest and rarest shape on the chain. Both answers are
+ * content-addressed and immutable, so a caller with a cache pays either
+ * order exactly once. With no engine wired the engine step costs nothing and
+ * the stores are read as before. A determination URL or a digest never
+ * touches the engine at all.
+ *
+ * Two readers, because a stored document can live on either store:
+ * `fetchJson` follows an allowlisted URL, `fetchCid` finds a bare content
+ * address on whichever store holds it (`readDocJson` is the one to pass).
+ *
+ * `kind: "engine"` comes back with the normalised decision in `engine` and
+ * `receipt: null` — there is no Openhands verdict document to hand over.
+ * Otherwise `null` in `receipt` means the receipt could not be reached, which
+ * is different from there being none — a caller should say "not available",
+ * never "none".
+ */
+export declare function receiptBehind<T>(proof: string | null | undefined, fetchJson: (url: string) => Promise<unknown>, fetchCid: (cid: string) => Promise<unknown>, options?: ReceiptBehindOptions): Promise<{
+    receipt: T | null;
+    receiptCid: string | null;
+    kind: ProofKind;
+    ref: ProofRef;
+    engine?: EngineDecision;
+}>;
+//# sourceMappingURL=proof.d.ts.map

package/dist/cjs/data/proof.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"proof.d.ts","sourceRoot":"","sources":["../../../src/data/proof.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AASlD,MAAM,MAAM,SAAS,GAAG,UAAU,GAAG,KAAK,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,CAAC;AAE7E,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,SAAS,CAAC;IAChB,sDAAsD;IACtD,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,8DAA8D;IAC9D,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,2EAA2E;IAC3E,GAAG,EAAE,MAAM,CAAC;CACb;AAED,wBAAgB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,QAAQ,CAexD;AAED;;;;;;;GAOG;AACH,wBAAsB,YAAY,CAChC,KAAK,EAAE,QAAQ,EACf,SAAS,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,EAC5C,QAAQ,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,GAC3C,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAyBxB;AAED,MAAM,WAAW,oBAAoB;IACnC;;;;;OAKG;IACH,MAAM,CAAC,EAAE,KAAK,GAAG;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;KAAE,CAAC;CACzE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAsB,aAAa,CAAC,CAAC,EACnC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAChC,SAAS,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,EAC5C,QAAQ,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,EAC3C,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC;IAAE,OAAO,EAAE,CAAC,GAAG,IAAI,CAAC;IAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,IAAI,EAAE,SAAS,CAAC;IAAC,GAAG,EAAE,QAAQ,CAAC;IAAC,MAAM,CAAC,EAAE,cAAc,CAAA;CAAE,CAAC,CAapH"}