@ixo/openhands-sdk 0.0.0-stage → 0.2.0

package/dist/esm/data/docs.js

@@ -0,0 +1,177 @@
+/**
+ * Where a public document lives, and how to fetch one by its address.
+ *
+ * Two stores, one address space. A document is named by its content — a
+ * CIDv1 over the exact bytes — and lives in one of two places:
+ *
+ * - **The IXO Virtual Filesystem**, when a signed-in person put it there.
+ *   Their own namespace, published, served to anyone at `/public/cid/<cid>`
+ *   without a token (the bytes stay encrypted at rest; the CID is computed
+ *   over the plaintext, with the same encoder the network's IPFS pins use).
+ * - **IPFS, through the ixo gateway**, for everything else: uploads by a
+ *   phone that is not signed in, by the worker's own keys, and every
+ *   document written before 2026-09-17 — those lived on a store that is gone
+ *   from this code, and `scripts/migrate-docs.ts` copies them to the gateway
+ *   under the same addresses (both encode bytes the same way).
+ *
+ * A reader does not know which, and does not need to: `fetchDoc` asks both
+ * stores at once and takes the first that has the bytes — a miss on the
+ * filesystem is one index lookup, a miss on the gateway is a walk of the
+ * public network that can take half a minute, so waiting for either in turn
+ * would be the wrong speed for half the documents — and remembers which
+ * store answered so the next read of the same address asks only there.
+ * Nothing here imports anything, so a browser, a route, a cron and a test
+ * all read the same way.
+ */
+import { docUrls, isCid } from "./docUrls.js";
+export * from "./docUrls.js";
+/*
+ * Which store answered for an address, remembered for this process. An
+ * address never moves between stores, so a hit is good for as long as the
+ * isolate lives; a miss is not remembered, because a document that is not
+ * there yet may be there in a minute.
+ */
+const WHERE_MAX = 5000;
+const where = new Map();
+export function rememberDocStore(cid, store) {
+    if (where.size >= WHERE_MAX)
+        where.delete(where.keys().next().value);
+    where.set(cid, store);
+}
+/** For tests: forget every remembered store. */
+export const forgetDocStores = () => void where.clear();
+const missing = () => new Response(null, { status: 404, statusText: "not found in any store" });
+/**
+ * One request to one store, bounded by its own clock and by the race it is
+ * part of: when another store has already answered, this one is let go.
+ */
+async function attempt(fetchImpl, url, init, timeoutMs, race) {
+    const controller = new AbortController();
+    const clock = setTimeout(() => controller.abort(), timeoutMs);
+    const relay = () => controller.abort();
+    race.addEventListener("abort", relay, { once: true });
+    try {
+        return await fetchImpl(url, { ...init, signal: controller.signal });
+    }
+    finally {
+        clearTimeout(clock);
+        race.removeEventListener("abort", relay);
+    }
+}
+/**
+ * Every store at once; the first `ok` wins and the rest are abandoned.
+ *
+ * A store that answers "not here" is not the answer — the other may still
+ * be on its way — so the promise settles on the first success, or on the
+ * last refusal when there is none (a 5xx from the gateway is kept over a
+ * 404 from the filesystem, so a caller can tell an outage from an absence).
+ */
+function firstStore(candidates, init, timeoutMs, fetchImpl, outer) {
+    const races = candidates.map(() => new AbortController());
+    const letGo = () => races.forEach((one) => one.abort());
+    outer?.addEventListener("abort", letGo, { once: true });
+    return new Promise((resolve) => {
+        let pending = candidates.length;
+        let done = false;
+        let last = null;
+        const settle = (answer) => {
+            if (done)
+                return;
+            done = true;
+            outer?.removeEventListener("abort", letGo);
+            resolve(answer);
+        };
+        if (!pending)
+            settle(null);
+        candidates.forEach(({ store, url }, i) => {
+            attempt(fetchImpl, url, init, timeoutMs, races[i].signal)
+                .then(async (response) => {
+                if (response.ok && !done) {
+                    races.forEach((one, j) => j !== i && one.abort());
+                    settle({ response, url, store });
+                    return;
+                }
+                /* Nothing to read here, or somebody else won; a body may still be
+                   open on a keep-alive socket, and dropping it is what lets the
+                   next request reuse it. */
+                await response.body?.cancel().catch(() => undefined);
+                if (!response.ok && (!last || response.status >= 500))
+                    last = { response, url, store };
+            })
+                .catch(() => undefined)
+                .finally(() => {
+                if (--pending === 0)
+                    settle(last);
+            });
+        });
+    });
+}
+/** The known store alone when there is one; both otherwise. */
+function order(cid, only) {
+    const all = docUrls(cid);
+    return only ? all.filter((one) => one.store === only) : all;
+}
+/**
+ * Fetch a document by its address, wherever it is.
+ *
+ * Always answers with a `Response`, never throws: `ok` means the bytes are
+ * there, anything else means they are not, from whichever store answered
+ * last — so a caller written against `fetch(url)` reads the same. The
+ * response's `url` is the store's own, which is how a caller finds the
+ * documents stored beside this one (`docUrlBeside`).
+ */
+export async function fetchDoc(cid, init = {}) {
+    if (!isCid(cid))
+        return missing();
+    const { timeoutMs = 12_000, fetchImpl = fetch, signal, ...rest } = init;
+    const known = where.get(cid);
+    if (known) {
+        const found = await firstStore(order(cid, known), rest, timeoutMs, fetchImpl, signal);
+        if (found?.response.ok)
+            return found.response;
+        /* Moved, or a store having a bad minute: ask everybody again. */
+        where.delete(cid);
+    }
+    const found = await firstStore(order(cid), rest, timeoutMs, fetchImpl, signal);
+    if (found?.response.ok)
+        rememberDocStore(cid, found.store);
+    return found?.response ?? missing();
+}
+/** The document as JSON, or null — for the many readers that want nothing else. */
+export async function readDocJson(cid, init = {}) {
+    try {
+        const response = await fetchDoc(cid, init);
+        return response.ok ? (await response.json()) : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The one URL a document is actually at — for a place that has to write an
+ * address down (a credential, a signed determination, a share card's image)
+ * rather than fetch it now. A HEAD to every store at once, remembered like a
+ * read; null when none has it, which a caller must treat as "not yet" rather
+ * than invent a location for.
+ */
+export async function resolveDocUrl(cid, init = {}) {
+    if (!isCid(cid))
+        return null;
+    const { timeoutMs = 8_000, fetchImpl = fetch, signal, ...rest } = init;
+    const head = { ...rest, method: "HEAD" };
+    const known = where.get(cid);
+    if (known) {
+        const found = await firstStore(order(cid, known), head, timeoutMs, fetchImpl, signal);
+        await found?.response.body?.cancel().catch(() => undefined);
+        if (found?.response.ok)
+            return found.url;
+        where.delete(cid);
+    }
+    const found = await firstStore(order(cid), head, timeoutMs, fetchImpl, signal);
+    await found?.response.body?.cancel().catch(() => undefined);
+    if (!found?.response.ok)
+        return null;
+    rememberDocStore(cid, found.store);
+    return found.url;
+}
+//# sourceMappingURL=docs.js.map

package/dist/esm/data/docs.js.map

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

package/dist/esm/data/engine.d.ts

@@ -0,0 +1,193 @@
+/**
+ * Reading a decision-engine receipt.
+ *
+ * Since the oracle migration a verdict's `verificationProof` on chain is a
+ * bare CID that lives in neither document store: it is the content address of
+ * a receipt the decision engine minted, served at
+ * `<ENGINE_URL>/v1/receipts/<cid>` (the exact bytes — a compact JWS) and, with
+ * `?format=json`, rendered beside its own verification. This module is the
+ * one place that knows that document's shape and turns it into the shape the
+ * pages already render — a verdict word, a gate list, when it was decided,
+ * what governed it.
+ *
+ * **What a receipt carries, and what it never does.** The engine's rule is
+ * codes, scores and identifiers only: every gate the rubric declared and its
+ * outcome (`code` + `passed`/`failed`/…), the decision's `reasonCodes`, the
+ * rubric id, the oracle that acted. It carries no `explanation` and no gate
+ * `reason` — those are erasable prose, and a signed immutable artefact must
+ * be able to outlive them. So the gate *reason* a page shows is joined from
+ * the rubric the ask published (`{id}#rub`, the same document the engine
+ * decided against, whose gates carry `reason` per code), and falls back to
+ * the words inside the code itself (`OH-101-NAMES-SITE` → "names site").
+ * `explanation` is `null` on every receipt; the field exists so a reader
+ * that one day gets one renders it without a change here.
+ *
+ * Field names below are the engine's own (`src/lib/receipt/schema.ts`): the
+ * v3 credential puts everything under `credentialSubject.{decision,
+ * evaluation}`; the legacy v2 payload, minted before 2026-09-14 and never
+ * re-minted, puts the same facts under `ixo` with `iss`/`sub`/`aud`/`iat` on
+ * top. Both are read, because both are on chain forever.
+ *
+ * Plain TypeScript with no Next imports, on purpose: the MCP, the worker and
+ * the pages all read receipts, and they share this.
+ */
+export { engineUrl, engineConfigured, engineReceiptUrl, engineIssuerKeysUrl } from "./engineUrl.ts";
+export type EngineVerdict = "approve" | "partial" | "reject" | "review";
+export type EngineGateOutcome = "passed" | "failed" | "skipped" | "unevaluated" | "not_reached";
+export interface EngineGate {
+    /** `OH-<100+index>-<LABEL>` — the bridge's grammar, off the ask's terms. */
+    code: string;
+    outcome: EngineGateOutcome;
+    /** The rubric's own sentence for this gate when the join found it, else
+     *  the label inside the code, said as words. Never empty. */
+    reason: string;
+    /** False when `reason` came from the code alone — a page may say so. */
+    joined: boolean;
+}
+export interface EngineCheck {
+    name: string;
+    kind: "ai" | "ext" | "unique" | "frequency";
+    status: "ok" | "error";
+    verdict: string | null;
+    model: string | null;
+    /** An AI check's score out of 100, when it gave one. */
+    score: number | null;
+}
+export interface EngineDecision {
+    kind: "engine";
+    /** The receipt's address — what the chain's `verificationProof` names. */
+    cid: string | null;
+    /** `vc+jwt` is the v3 credential; `jws` the legacy v2 payload. */
+    format: "vc+jwt" | "jws" | null;
+    /** The signed bytes, when the document carried them. The only artefact. */
+    jws: string | null;
+    /** The engine's `did:web`. */
+    issuer: string | null;
+    verdict: EngineVerdict;
+    verdictClass: string | null;
+    action: string | null;
+    status: "decided" | "unusable";
+    /** x/claims EvaluationStatus the engine cast: 1 approve · 2 reject · 5 review. */
+    outcome: 1 | 2 | 5 | null;
+    totalBps: number | null;
+    gates: EngineGate[];
+    /** The gates that turned it — `outcome === "failed"`, in rubric order. */
+    failed: EngineGate[];
+    reasonCodes: string[];
+    checks: EngineCheck[];
+    /** Never on a receipt (see the header). Null until a reader gets one elsewhere. */
+    explanation: string | null;
+    /** When the engine decided (`decision.evaluatedAt` / `ixo.decidedAt`). */
+    decidedAt: string | null;
+    /** When the receipt was minted (`validFrom` / `iat`). */
+    issuedAt: string | null;
+    /** When the oracle froze the facts it ran over. */
+    frozenAt: string | null;
+    /** The rubric's id — the hex sha256 the ask's `#rub` resource carries as `proof`. */
+    rubricId: string | null;
+    rubricResolution: "ok" | "unresolved" | null;
+    protocolDid: string | null;
+    collectionId: string | null;
+    claimId: string | null;
+    network: string | null;
+    oracle: {
+        did: string;
+        address: string;
+    } | null;
+    /** The authorization the oracle acted under (`act.cap`). */
+    cap: string | null;
+    /** The hash of the facts the oracle froze before the engine decided. */
+    factsDigest: string | null;
+    /**
+     * The engine's own trace of the decision (`res.trace`): where it lives and
+     * the hash that pins it. The URI is not public today (UCAN-gated), so a
+     * page can show the pin but not yet the trace.
+     */
+    trace: {
+        uri: string | null;
+        digest: string;
+    } | null;
+    reviewFolded: boolean;
+    /** The engine's own verification of the bytes it served, when it said. */
+    verified: boolean | null;
+    failures: string[];
+    verify: {
+        kid: string | null;
+        issuerKeys: string | null;
+    };
+}
+/** The reasons per gate code, out of the rubric the ask published. */
+export type GateReasons = Record<string, string>;
+/**
+ * The words inside a gate code, when nothing better is known.
+ *
+ * `OH-101-NAMES-SITE` says "names site"; `OH-104-FILE-TYPE` says "file type".
+ * A code that does not follow the grammar is returned as it is — still a
+ * true thing to show, and never blank.
+ */
+export declare function gateReasonFromCode(code: string): string;
+/**
+ * Code → reason, off an engine rubric document — the `{id}#rub` resource the
+ * bridge publishes (`packages/openhands-sdk/src/rubric/bridge.ts` `EngineRubric`).
+ * Tolerant of the bare `rubric` block as well as the envelope around it.
+ */
+export declare function gateReasonsOf(rubric: unknown): GateReasons;
+/**
+ * One receipt document, whatever the engine served, as the shape a page renders.
+ *
+ * Takes the `?format=json` rendering (`{cid, jws, issuedAt, format, payload,
+ * verify}`), or a bare claimset (a v3 credential or a v2 payload) for a reader
+ * that already holds one. `null` for anything that is not a receipt at all —
+ * an Openhands verdict document out of the stores, say, which has no
+ * `credentialSubject` and no `ixo` block — so a caller can try this first and
+ * fall through without misreading.
+ */
+export declare function normaliseEngineReceipt(doc: unknown, reasons?: GateReasons): EngineDecision | null;
+/** The verdict, in the chain's own numbering — what `verdictSays` reads. */
+export declare const engineStatusOf: (decision: EngineDecision) => number;
+export interface EngineReadOptions {
+    /** Where the engine is. Defaults to `NEXT_PUBLIC_DECISION_ENGINE_URL`. */
+    baseUrl?: string;
+    /** How to fetch JSON — a page passes one with its own caching; tests a fake. */
+    fetchJson?: (url: string) => Promise<unknown>;
+    /** Gate code → reason, when the caller already joined the rubric. */
+    reasons?: GateReasons;
+}
+/**
+ * The receipt at a content address, from the engine — or `null` when no
+ * engine is wired, the engine has no such receipt, or it could not be reached.
+ * `null` is "not an engine receipt as far as this reader can tell", which a
+ * caller may follow with a read of its own store.
+ */
+export declare function fetchEngineReceipt(cid: string, options?: EngineReadOptions): Promise<EngineDecision | null>;
+/**
+ * The engine's decision behind a chain proof, in one call — the reader the
+ * thread, the receipt page and the MCP share.
+ *
+ * Only a **bare CID** can be an engine receipt: a store URL points at one of
+ * our own signed determinations and a `sha256:` digest is neither, so those
+ * never cost a request here. A bare CID is ambiguous — the early Openhands
+ * receipts were bare CIDs too — and a stored document's address is
+ * indistinguishable by shape from the engine's, so this asks the engine and
+ * lets the caller fall through to the document stores on `null`.
+ */
+export declare function engineDecisionFor(proof: string | null | undefined, options?: EngineReadOptions): Promise<EngineDecision | null>;
+export declare function gateReasonsFor(entityDid: string | null | undefined, options?: {
+    fetchJson?: (url: string) => Promise<unknown>;
+}): Promise<GateReasons>;
+/**
+ * The words a thread row shows for an engine decision — the same
+ * `{ failed, allPassed }` the checker's verdict documents produce, so the
+ * timeline renders both without knowing which it has.
+ */
+export declare function engineVerdictLines(decision: EngineDecision): {
+    failed: {
+        id: string;
+        note: string;
+    }[];
+    allPassed: boolean;
+};
+/** The same decision with its gate reasons joined after the fact — for a
+ *  reader that learns which ask it was (`protocolDid`) only from the receipt. */
+export declare function withGateReasons(decision: EngineDecision, reasons: GateReasons): EngineDecision;
+//# sourceMappingURL=engine.d.ts.map

package/dist/esm/data/engine.d.ts.map

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