@ixo/decision-oracle 0.2.5 → 0.2.7

package/dist/lib/openhands/options.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"options.d.ts","sourceRoot":"","sources":["../../../src/lib/openhands/options.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,EAAa,KAAK,gBAAgB,EAAE,KAAK,cAAc,EAAE,MAAM,cAAc,CAAC;AACrF,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAExC,mFAAmF;AACnF,wBAAgB,gBAAgB,IAAI,OAAO,CAE1C;AAED,wBAAgB,gBAAgB,IAAI,gBAAgB,CAEnD;AAED,wGAAwG;AACxG,wBAAsB,WAAW,CAC/B,GAAG,EAAE,SAAS,EACd,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,cAAc,GACpB,OAAO,CAAC,IAAI,CAAC,CAWf"}

package/dist/lib/openhands/options.js

@@ -0,0 +1,28 @@
+/**
+ * The provider's `openhands` options (oracle.ts `OpenhandsOptions`), read through the registry like
+ * every other part of the config — and the one fail-soft way their `onQuota` hook is called.
+ */
+import { getOracle } from "../../oracle.js";
+/** Is this oracle an OpenHands checker (`openhands` present in `defineOracle`)? */
+export function openhandsEnabled() {
+    return getOracle().config.openhands !== undefined;
+}
+export function openhandsOptions() {
+    return getOracle().config.openhands ?? {};
+}
+/** Tell the provider's `onQuota` what was just read. A throw there never fails the hire or the pass. */
+export async function reportQuota(env, logger, quota) {
+    const hook = openhandsOptions().onQuota;
+    if (!hook)
+        return;
+    try {
+        await hook(quota, env);
+    }
+    catch (err) {
+        logger.warn("openhands.on-quota.failed", {
+            collectionId: quota.collectionId,
+            detail: err instanceof Error ? err.message : String(err),
+        });
+    }
+}
+//# sourceMappingURL=options.js.map

package/dist/lib/openhands/options.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"options.js","sourceRoot":"","sources":["../../../src/lib/openhands/options.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,SAAS,EAA8C,MAAM,cAAc,CAAC;AAGrF,mFAAmF;AACnF,MAAM,UAAU,gBAAgB;IAC9B,OAAO,SAAS,EAAE,CAAC,MAAM,CAAC,SAAS,KAAK,SAAS,CAAC;AACpD,CAAC;AAED,MAAM,UAAU,gBAAgB;IAC9B,OAAO,SAAS,EAAE,CAAC,MAAM,CAAC,SAAS,IAAI,EAAE,CAAC;AAC5C,CAAC;AAED,wGAAwG;AACxG,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,GAAc,EACd,MAAc,EACd,KAAqB;IAErB,MAAM,IAAI,GAAG,gBAAgB,EAAE,CAAC,OAAO,CAAC;IACxC,IAAI,CAAC,IAAI;QAAE,OAAO;IAClB,IAAI,CAAC;QACH,MAAM,IAAI,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;IACzB,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,CAAC,IAAI,CAAC,2BAA2B,EAAE;YACvC,YAAY,EAAE,KAAK,CAAC,YAAY;YAChC,MAAM,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC;SACzD,CAAC,CAAC;IACL,CAAC;AACH,CAAC"}

package/dist/lib/openhands/routes.d.ts

@@ -0,0 +1,73 @@
+/**
+ * The two webhooks the OpenHands app calls, in front of the package's own app (define-oracle.ts):
+ *
+ *   POST /openhands/hire/:collectionId   — the ask just granted this oracle; start its hire
+ *   POST /openhands/scan/:collectionId   — a claim just landed; scan now, don't wait for the tick
+ *
+ * UNAUTHENTICATED on purpose: they only ask this oracle to look at the chain, so there is no secret
+ * on them and every caller is a stranger. What bounds a stranger is all here:
+ *
+ *   - `OPENHANDS_RATE_LIMITER`, spent per caller address (an IPv6 caller by its /64) and per
+ *     collection, failing CLOSED (503) where it is not bound outside development;
+ *   - a collection id shaped like one (no leading zeros: one collection, one key, one instance id);
+ *   - before any instance is created or restarted, a cheap check that the collection exists and its
+ *     admin granted this oracle a live meta-grant — refused 404 / 409, only the 409 cached;
+ *   - a healthy hire's answer cached for a minute, so replays cost one KV read;
+ *   - an existing hire restarted ONLY when the chain says it must (unwatched, a stale ceiling, low
+ *     quota) and only from the webhook's OWN restart budget — never the backstop's;
+ *   - `/scan` at most once a minute per collection; a coalesced call marks the collection, and the
+ *     minute tick scans it (`runDirtyScans`).
+ *
+ * What a stranger cannot do: make this oracle MINT where the chain does not say so (the hire signs
+ * nothing until it read a live meta-grant from the collection's own admin), un-pause a collection,
+ * or evaluate a claim it was not authorized for.
+ */
+import type { OracleEnv } from "../../env.js";
+import { type HireDeps, type WatchedRestart } from "./backstop.js";
+import { type MetaGrant } from "./chain.js";
+/** The paths `GET /v1/info` advertises (`openhands`) — the app calls these and nothing else. */
+export declare const HIRE_PATH = "/openhands/hire/:collectionId";
+export declare const SCAN_PATH = "/openhands/scan/:collectionId";
+/** Twelve digits is a trillion collections; no leading zero, so `007` and `7` are not two keys. */
+export declare const COLLECTION_ID_RE: RegExp;
+/** How long a refused (409) hire is answered from `CACHE_KV` — the backstop's own period. */
+export declare const HIRE_REFUSED_TTL_SEC = 600;
+export declare const hireRefusedKey: (collectionId: string) => string;
+/** How long a healthy hire is answered from `CACHE_KV` — the shortest TTL KV accepts. */
+export declare const HIRE_HEALTHY_TTL_SEC = 60;
+export declare const hireHealthyKey: (collectionId: string) => string;
+/** One scan per collection per minute. */
+export declare const SCAN_COALESCE_TTL_SEC = 60;
+export declare const scanMarkerKey: (collectionId: string) => string;
+/** Coalesced collections the minute tick re-scans. */
+export declare const SCAN_DIRTY_PER_TICK = 20;
+/**
+ * The rate-limit key for the caller: `cf-connecting-ip`, an IPv6 address cut to its /64 (one
+ * subscriber is handed a whole /64), an IPv4-mapped IPv6 address as its IPv4.
+ */
+export declare function callerKey(request: Request): string;
+/**
+ * What the hire lane reads before it creates or restarts anything — injected by tests. Every
+ * method THROWS when its source cannot answer; a throw is a 503, never a refusal, never cached.
+ */
+export interface HireChain {
+    /** The collection's admin — Blocksync first, the chain when the index has not caught up. */
+    admin(collectionId: string): Promise<string | null>;
+    meta(admin: string, collectionId: string): Promise<MetaGrant | null>;
+    /** Why an ENDED hire must run again, or null when it need not. */
+    restartReason(collectionId: string, admin: string, meta: MetaGrant): Promise<WatchedRestart | "unwatched">;
+}
+export declare function liveHireChain(deps: HireDeps): HireChain;
+export declare function hireDeps(env: OracleEnv): HireDeps;
+/**
+ * Handle an OpenHands webhook, or `null` when the request is not one — the caller then falls
+ * through to the package's app. `chain` is injected by tests.
+ */
+export declare function handleOpenhandsRoute(request: Request, env: OracleEnv, chain?: HireChain): Promise<Response | null>;
+/**
+ * The minute half of `/scan` coalescing: scan the collections whose call was coalesced, then drop
+ * each marker if it still holds the value read (a call coalesced DURING the scan is scanned next
+ * minute). Every outcome drops it — a failed scan is the regular rotation's to find.
+ */
+export declare function runDirtyScans(env: OracleEnv): Promise<number>;
+//# sourceMappingURL=routes.d.ts.map

package/dist/lib/openhands/routes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"routes.d.ts","sourceRoot":"","sources":["../../../src/lib/openhands/routes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAIH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAI3C,OAAO,EAEL,KAAK,QAAQ,EAGb,KAAK,cAAc,EAEpB,MAAM,YAAY,CAAC;AACpB,OAAO,EAGL,KAAK,SAAS,EAGf,MAAM,SAAS,CAAC;AAYjB,gGAAgG;AAChG,eAAO,MAAM,SAAS,kCAAkC,CAAC;AACzD,eAAO,MAAM,SAAS,kCAAkC,CAAC;AAGzD,mGAAmG;AACnG,eAAO,MAAM,gBAAgB,QAAuB,CAAC;AAErD,6FAA6F;AAC7F,eAAO,MAAM,oBAAoB,MAAM,CAAC;AACxC,eAAO,MAAM,cAAc,iBAAkB,MAAM,WAA6C,CAAC;AACjG,yFAAyF;AACzF,eAAO,MAAM,oBAAoB,KAAK,CAAC;AACvC,eAAO,MAAM,cAAc,iBAAkB,MAAM,WAA6C,CAAC;AACjG,0CAA0C;AAC1C,eAAO,MAAM,qBAAqB,KAAK,CAAC;AACxC,eAAO,MAAM,aAAa,iBAAkB,MAAM,WAAqC,CAAC;AACxF,sDAAsD;AACtD,eAAO,MAAM,mBAAmB,KAAK,CAAC;AAUtC;;;GAGG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAKlD;AA+CD;;;GAGG;AACH,MAAM,WAAW,SAAS;IACxB,4FAA4F;IAC5F,KAAK,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACpD,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,CAAC;IACrE,kEAAkE;IAClE,aAAa,CACX,YAAY,EAAE,MAAM,EACpB,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,SAAS,GACd,OAAO,CAAC,cAAc,GAAG,WAAW,CAAC,CAAC;CAC1C;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,QAAQ,GAAG,SAAS,CAkCvD;AAED,wBAAgB,QAAQ,CAAC,GAAG,EAAE,SAAS,GAAG,QAAQ,CAGjD;AAED;;;GAGG;AACH,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,OAAO,EAChB,GAAG,EAAE,SAAS,EACd,KAAK,CAAC,EAAE,SAAS,GAChB,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CA2B1B;AAgJD;;;;GAIG;AACH,wBAAsB,aAAa,CAAC,GAAG,EAAE,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC,CAiBnE"}

package/dist/lib/openhands/routes.js

@@ -0,0 +1,355 @@
+/**
+ * The two webhooks the OpenHands app calls, in front of the package's own app (define-oracle.ts):
+ *
+ *   POST /openhands/hire/:collectionId   — the ask just granted this oracle; start its hire
+ *   POST /openhands/scan/:collectionId   — a claim just landed; scan now, don't wait for the tick
+ *
+ * UNAUTHENTICATED on purpose: they only ask this oracle to look at the chain, so there is no secret
+ * on them and every caller is a stranger. What bounds a stranger is all here:
+ *
+ *   - `OPENHANDS_RATE_LIMITER`, spent per caller address (an IPv6 caller by its /64) and per
+ *     collection, failing CLOSED (503) where it is not bound outside development;
+ *   - a collection id shaped like one (no leading zeros: one collection, one key, one instance id);
+ *   - before any instance is created or restarted, a cheap check that the collection exists and its
+ *     admin granted this oracle a live meta-grant — refused 404 / 409, only the 409 cached;
+ *   - a healthy hire's answer cached for a minute, so replays cost one KV read;
+ *   - an existing hire restarted ONLY when the chain says it must (unwatched, a stale ceiling, low
+ *     quota) and only from the webhook's OWN restart budget — never the backstop's;
+ *   - `/scan` at most once a minute per collection; a coalesced call marks the collection, and the
+ *     minute tick scans it (`runDirtyScans`).
+ *
+ * What a stranger cannot do: make this oracle MINT where the chain does not say so (the hire signs
+ * nothing until it read a live meta-grant from the collection's own admin), un-pause a collection,
+ * or evaluate a claim it was not authorized for.
+ */
+import { loadConfig } from "../../config.js";
+import { cronContext } from "../../cron/scan.js";
+import { scanCollection } from "../../runtime.js";
+import { AppError } from "../errors.js";
+import { getCollection } from "../ixo/blocksync/index.js";
+import { ENDED, hireWorkflow, isAlreadyExists, watchedRestartReason, } from "./backstop.js";
+import { approvalDenomOf, collectionAdminOnChain, metaGrantFor, readGrantsFrom, } from "./chain.js";
+import { openhandsOptions } from "./options.js";
+import { claimRestart, deleteStateIf, dirtyScans, SCAN_DIRTY_PREFIX, scanDirtyName, webhookBudgetName, writeState, } from "./store.js";
+/** The paths `GET /v1/info` advertises (`openhands`) — the app calls these and nothing else. */
+export const HIRE_PATH = "/openhands/hire/:collectionId";
+export const SCAN_PATH = "/openhands/scan/:collectionId";
+const ROUTE = /^\/openhands\/(hire|scan)\/([^/]*)\/?$/;
+/** Twelve digits is a trillion collections; no leading zero, so `007` and `7` are not two keys. */
+export const COLLECTION_ID_RE = /^[1-9][0-9]{0,11}$/;
+/** How long a refused (409) hire is answered from `CACHE_KV` — the backstop's own period. */
+export const HIRE_REFUSED_TTL_SEC = 600;
+export const hireRefusedKey = (collectionId) => `openhands:hire-refused:${collectionId}`;
+/** How long a healthy hire is answered from `CACHE_KV` — the shortest TTL KV accepts. */
+export const HIRE_HEALTHY_TTL_SEC = 60;
+export const hireHealthyKey = (collectionId) => `openhands:hire-healthy:${collectionId}`;
+/** One scan per collection per minute. */
+export const SCAN_COALESCE_TTL_SEC = 60;
+export const scanMarkerKey = (collectionId) => `openhands:scan:${collectionId}`;
+/** Coalesced collections the minute tick re-scans. */
+export const SCAN_DIRTY_PER_TICK = 20;
+const asMessage = (err) => (err instanceof Error ? err.message : String(err));
+const json = (status, body, headers = {}) => new Response(JSON.stringify(body), {
+    status,
+    headers: { "content-type": "application/json", ...headers },
+});
+/**
+ * The rate-limit key for the caller: `cf-connecting-ip`, an IPv6 address cut to its /64 (one
+ * subscriber is handed a whole /64), an IPv4-mapped IPv6 address as its IPv4.
+ */
+export function callerKey(request) {
+    const raw = request.headers.get("cf-connecting-ip")?.trim() ?? "";
+    if (!raw)
+        return "unknown";
+    if (!raw.includes(":"))
+        return raw;
+    return ipv6Slash64(raw) ?? `unparsed:${raw.slice(0, 64)}`;
+}
+function ipv6Slash64(address) {
+    let a = address.toLowerCase();
+    const zone = a.indexOf("%");
+    if (zone >= 0)
+        a = a.slice(0, zone);
+    const mapped = /^::ffff:(\d{1,3}(?:\.\d{1,3}){3})$/.exec(a);
+    if (mapped?.[1])
+        return mapped[1];
+    const halves = a.split("::");
+    if (halves.length > 2)
+        return null;
+    const groupsOf = (part) => (part ? part.split(":") : []);
+    const head = groupsOf(halves[0]);
+    const tail = groupsOf(halves[1]);
+    const last = tail.length > 0 ? tail[tail.length - 1] : head[head.length - 1];
+    const tailWidth = last?.includes(".") ? 1 : 0;
+    const explicit = head.length + tail.length + tailWidth;
+    const groups = halves.length === 2
+        ? explicit <= 7
+            ? [...head, ...Array(8 - explicit).fill("0"), ...tail]
+            : null
+        : explicit === 8
+            ? head
+            : null;
+    if (!groups)
+        return null;
+    const prefix = groups.slice(0, 4);
+    if (!prefix.every((g) => /^[0-9a-f]{1,4}$/.test(g)))
+        return null;
+    return `${prefix.map((g) => Number.parseInt(g, 16).toString(16)).join(":")}::/64`;
+}
+async function spendLimit(env, key) {
+    const limiter = env.OPENHANDS_RATE_LIMITER;
+    if (!limiter) {
+        if (loadConfig(env).ENVIRONMENT === "development")
+            return "ok";
+        console.error("[openhands] OPENHANDS_RATE_LIMITER is not bound — refusing");
+        return "unavailable";
+    }
+    try {
+        return (await limiter.limit({ key })).success ? "ok" : "limited";
+    }
+    catch (err) {
+        console.error(`[openhands] rate limiter failed, refusing: ${asMessage(err)}`);
+        return "unavailable";
+    }
+}
+export function liveHireChain(deps) {
+    const { config, blocksync, db } = deps;
+    return {
+        admin: async (collectionId) => {
+            try {
+                const indexed = (await getCollection(blocksync, collectionId))?.admin;
+                if (indexed)
+                    return indexed;
+            }
+            catch (err) {
+                // The chain is the authority the index copies; an index outage is no reason to refuse.
+                deps.logger.warn("openhands.hire.index-unreadable", {
+                    collectionId,
+                    detail: asMessage(err),
+                });
+            }
+            return collectionAdminOnChain(config, collectionId);
+        },
+        meta: (admin, collectionId) => metaGrantFor(config, admin, collectionId),
+        restartReason: async (collectionId, admin) => {
+            const watched = await db.query.watchedCollections.findFirst({
+                columns: { collectionId: true },
+                where: (t, { eq }) => eq(t.collectionId, collectionId),
+            });
+            if (!watched)
+                return "unwatched";
+            const [chain, collection] = await Promise.all([
+                readGrantsFrom(config, admin),
+                getCollection(blocksync, collectionId),
+            ]);
+            return watchedRestartReason(chain, { collectionId, admin, approvalDenom: approvalDenomOf(collection?.payments) }, openhandsOptions().maxCustomAmount);
+        },
+    };
+}
+export function hireDeps(env) {
+    const ctx = cronContext(env);
+    return { env, config: loadConfig(env), db: ctx.db, logger: ctx.logger, blocksync: ctx.deps };
+}
+/**
+ * Handle an OpenHands webhook, or `null` when the request is not one — the caller then falls
+ * through to the package's app. `chain` is injected by tests.
+ */
+export async function handleOpenhandsRoute(request, env, chain) {
+    const match = ROUTE.exec(new URL(request.url).pathname);
+    if (!match)
+        return null;
+    const [, lane, rawId = ""] = match;
+    if (request.method !== "POST") {
+        return json(405, { error: "Use POST on this endpoint" }, { allow: "POST" });
+    }
+    if (!COLLECTION_ID_RE.test(rawId)) {
+        return json(400, {
+            error: `collectionId must be a decimal collection id without leading zeros, got ${rawId.slice(0, 32) || "''"}`,
+        });
+    }
+    // The address first: a caller over its own budget must not also spend the collection's.
+    let spent = await spendLimit(env, `ip:${callerKey(request)}`);
+    if (spent === "ok")
+        spent = await spendLimit(env, `${lane}:${rawId}`);
+    if (spent === "limited") {
+        return json(429, { error: "Too many requests — retry in a minute" }, { "retry-after": "60" });
+    }
+    if (spent === "unavailable") {
+        return json(503, { error: "rate limiter unavailable — retry later" }, { "retry-after": "60" });
+    }
+    if (lane === "hire" && !env.HIRE_WORKFLOW) {
+        console.error("[openhands] the HIRE_WORKFLOW binding is missing (wrangler.jsonc)");
+        return json(503, { error: "this oracle's hire workflow is not bound — retry later" });
+    }
+    const deps = hireDeps(env);
+    return lane === "hire" ? hire(deps, rawId, chain ?? liveHireChain(deps)) : scan(deps, rawId);
+}
+/**
+ * Start the one hire instance for this collection — or rerun the one holding its id, when and only
+ * when the chain says a rerun is needed. A poster calls again precisely when something changed (a
+ * raised ceiling, a re-grant); the chain read tells that apart from a stranger replaying it.
+ */
+async function hire(deps, collectionId, chain) {
+    const { env, logger } = deps;
+    if (await kvHas(env, hireHealthyKey(collectionId))) {
+        return json(200, { started: false, existing: true, cached: true });
+    }
+    const workflow = hireWorkflow(env);
+    let instance = null;
+    try {
+        instance = await workflow.get(collectionId);
+    }
+    catch {
+        instance = null;
+    }
+    // A run in flight reaches the same place on its own: nothing to read, nothing to spend.
+    if (instance && !ENDED.has((await instance.status()).status)) {
+        return json(200, { started: false, existing: true });
+    }
+    const cached = await cachedRefusal(env, collectionId);
+    if (cached)
+        return json(409, { error: cached, cached: true });
+    let admin;
+    let meta;
+    try {
+        admin = await chain.admin(collectionId);
+        meta = admin ? await chain.meta(admin, collectionId) : null;
+    }
+    catch (err) {
+        logger.error("openhands.hire.precheck-unavailable", { collectionId, detail: asMessage(err) });
+        return json(503, { error: "could not read the collection or its grant — retry" });
+    }
+    // NOT cached: an ask posted seconds ago may not be on the index or the chain yet.
+    if (!admin)
+        return json(404, { error: `no collection #${collectionId}` });
+    if (!meta) {
+        const error = `collection #${collectionId}'s admin has granted this oracle no live meta-grant`;
+        await env.CACHE_KV.put(hireRefusedKey(collectionId), error, {
+            expirationTtl: HIRE_REFUSED_TTL_SEC,
+        }).catch(() => undefined);
+        logger.info("openhands.hire.no-grant", { collectionId });
+        return json(409, { error });
+    }
+    if (!instance) {
+        try {
+            await workflow.create({ id: collectionId, params: { collectionId } });
+            return json(202, { started: true });
+        }
+        catch (err) {
+            // Lost the race with the backstop or another webhook — the backstop owns what happens next.
+            if (isAlreadyExists(err))
+                return json(200, { started: false, existing: true });
+            logger.error("openhands.hire.unstartable", { collectionId, detail: asMessage(err) });
+            return json(503, { error: asMessage(err) });
+        }
+    }
+    let reason;
+    try {
+        reason = await chain.restartReason(collectionId, admin, meta);
+    }
+    catch (err) {
+        logger.error("openhands.hire.restart-check-unavailable", {
+            collectionId,
+            detail: asMessage(err),
+        });
+        return json(503, { error: "could not read whether this hire needs a rerun — retry" });
+    }
+    if (reason === null) {
+        await env.CACHE_KV.put(hireHealthyKey(collectionId), "1", {
+            expirationTtl: HIRE_HEALTHY_TTL_SEC,
+        }).catch(() => undefined);
+        return json(200, { started: false, existing: true });
+    }
+    // The webhook's OWN budget: anonymous POSTs never spend the restarts the backstop needs.
+    let won;
+    try {
+        won = !("denied" in (await claimRestart(deps.db, webhookBudgetName(collectionId), new Date())));
+    }
+    catch (err) {
+        logger.error("openhands.hire.budget-unreadable", { collectionId, detail: asMessage(err) });
+        return json(503, { error: `hire #${collectionId} could not be restarted` });
+    }
+    if (!won)
+        return json(200, { started: false, existing: true, throttled: true });
+    try {
+        await instance.restart();
+    }
+    catch (err) {
+        logger.error("openhands.hire.unrestartable", { collectionId, detail: asMessage(err) });
+        return json(503, { error: `hire #${collectionId} could not be restarted` });
+    }
+    logger.info("openhands.hire.restarted", { collectionId, by: "webhook", reason });
+    return json(200, { started: false, restarted: true, reason });
+}
+async function kvHas(env, key) {
+    try {
+        return (await env.CACHE_KV.get(key)) !== null;
+    }
+    catch {
+        return false;
+    }
+}
+async function cachedRefusal(env, collectionId) {
+    try {
+        return await env.CACHE_KV.get(hireRefusedKey(collectionId));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Run the per-collection discovery pass now — at most once a minute per collection. 202 = coalesced
+ * (the minute tick scans it); 404 = not watched, 409 = paused. KV is eventually consistent, so this
+ * is a cost brake, not an exact once.
+ */
+async function scan(deps, collectionId) {
+    const { env, db, logger } = deps;
+    const marker = scanMarkerKey(collectionId);
+    try {
+        if (await env.CACHE_KV.get(marker)) {
+            await writeState(db, scanDirtyName(collectionId), new Date().toISOString()).catch((err) => logger.warn("openhands.scan.unmarked", { collectionId, detail: asMessage(err) }));
+            return json(202, { started: false, coalesced: true });
+        }
+        await env.CACHE_KV.put(marker, new Date().toISOString(), {
+            expirationTtl: SCAN_COALESCE_TTL_SEC,
+        });
+    }
+    catch (err) {
+        logger.warn("openhands.scan.uncoalesced", { collectionId, detail: asMessage(err) });
+    }
+    try {
+        return json(200, { started: await scanCollection(env, collectionId) });
+    }
+    catch (err) {
+        if (err instanceof AppError && (err.status === 404 || err.status === 409)) {
+            return json(err.status, { error: err.message });
+        }
+        logger.error("openhands.scan.failed", { collectionId, detail: asMessage(err) });
+        return json(503, { error: asMessage(err) });
+    }
+}
+/**
+ * The minute half of `/scan` coalescing: scan the collections whose call was coalesced, then drop
+ * each marker if it still holds the value read (a call coalesced DURING the scan is scanned next
+ * minute). Every outcome drops it — a failed scan is the regular rotation's to find.
+ */
+export async function runDirtyScans(env) {
+    const { db, logger } = hireDeps(env);
+    const marked = await dirtyScans(db, SCAN_DIRTY_PER_TICK);
+    let scanned = 0;
+    for (const { name, value } of marked) {
+        const collectionId = name.slice(SCAN_DIRTY_PREFIX.length);
+        try {
+            await scanCollection(env, collectionId);
+            scanned += 1;
+        }
+        catch (err) {
+            if (!(err instanceof AppError && (err.status === 404 || err.status === 409))) {
+                logger.warn("openhands.scan.dirty-failed", { collectionId, detail: asMessage(err) });
+            }
+        }
+        await deleteStateIf(db, name, value);
+    }
+    return scanned;
+}
+//# sourceMappingURL=routes.js.map

package/dist/lib/openhands/routes.js.map

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

package/dist/lib/openhands/store.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Every statement the OpenHands add-on runs against its two tables (db/schema.ts `openhandsState`,
+ * `openhandsHires`) — each one statement, so two passes or a pass and a webhook never interleave a
+ * read and a write that matter.
+ */
+import type { Database } from "../../db/client.js";
+/** The rows the backstop resumes its rotating lanes from. */
+export declare const WINDOW_CURSOR = "window";
+export declare const PAUSED_CURSOR = "paused";
+export declare const GRANTS_CURSOR = "grants";
+/** One collection's restart budget — the backstop's and the webhook's, counted apart. */
+export declare const restartBudgetName: (collectionId: string) => string;
+export declare const webhookBudgetName: (collectionId: string) => string;
+/** A collection whose `/openhands/scan` was coalesced, waiting for the minute tick. */
+export declare const SCAN_DIRTY_PREFIX = "scan-dirty:";
+export declare const scanDirtyName: (collectionId: string) => string;
+export declare function readState(db: Database, name: string): Promise<string | null>;
+export declare function writeState(db: Database, name: string, value: string): Promise<void>;
+/** Delete a row only if it still holds `value` — a marker re-set meanwhile survives. */
+export declare function deleteStateIf(db: Database, name: string, value: string): Promise<void>;
+/** Restarts allowed per collection per window, per budget (backstop, webhook). */
+export declare const MAX_RESTARTS = 3;
+/** The window the count is kept over — it starts at the first restart, not at midnight. */
+export declare const RESTART_WINDOW_MS = 86400000;
+export interface RestartBudget {
+    allowed: boolean;
+    /** `<count>|<windowStartIso>`, or null when over budget. */
+    value: string | null;
+}
+/**
+ * The budget as a pure function of the stored row and the clock. A row that cannot be read opens a
+ * fresh window rather than blocking forever: a brake on a loop, not a ledger.
+ */
+export declare function spendRestart(stored: string | null, now: Date): RestartBudget;
+export type RestartClaim = {
+    slot: string;
+} | {
+    denied: "exhausted" | "raced";
+};
+/**
+ * Spend one restart from budget `name`, BEFORE the restart (one that then fails still counts —
+ * a restart that keeps failing is what the budget is for). A compare-and-swap on the value read:
+ * two overlapping passes spend ONE slot between them, and the loser hears `raced`.
+ */
+export declare function claimRestart(db: Database, name: string, now: Date): Promise<RestartClaim>;
+/** The coalesced scans waiting, oldest first, at most `limit`. */
+export declare function dirtyScans(db: Database, limit: number): Promise<{
+    name: string;
+    value: string;
+}[]>;
+/**
+ * Delete restart budgets whose window ended more than a day ago — written for every collection ever
+ * restarted, and `spendRestart` opens a fresh window for such a row anyway. ISO-8601 in UTC
+ * compares as text; a value that does not parse is left for a human.
+ */
+export declare function pruneBudgets(db: Database, now: Date): Promise<number>;
+/** What the backstop reads of one collection's `openhands_hires` row before it refreshes it. */
+export interface HireState {
+    checkedAt: string;
+    endsAt: string | null;
+}
+/**
+ * Write what the chain says about one collection's quota. `endsAt` undefined leaves the stored
+ * value alone: the mint step does not read the end date the way the window does.
+ */
+export declare function refreshHire(db: Database, row: {
+    collectionId: string;
+    remaining: number;
+    mintQuota: number;
+    now: Date;
+    endsAt?: string | null;
+}): Promise<void>;
+export declare function hireStates(db: Database, ids: readonly string[]): Promise<Map<string, HireState>>;
+//# sourceMappingURL=store.d.ts.map

package/dist/lib/openhands/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../../src/lib/openhands/store.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAKhD,6DAA6D;AAC7D,eAAO,MAAM,aAAa,WAAW,CAAC;AACtC,eAAO,MAAM,aAAa,WAAW,CAAC;AACtC,eAAO,MAAM,aAAa,WAAW,CAAC;AAEtC,yFAAyF;AACzF,eAAO,MAAM,iBAAiB,iBAAkB,MAAM,WAA+B,CAAC;AACtF,eAAO,MAAM,iBAAiB,iBAAkB,MAAM,WAAuC,CAAC;AAE9F,uFAAuF;AACvF,eAAO,MAAM,iBAAiB,gBAAgB,CAAC;AAC/C,eAAO,MAAM,aAAa,iBAAkB,MAAM,WAA0C,CAAC;AAE7F,wBAAsB,SAAS,CAAC,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAMlF;AAED,wBAAsB,UAAU,CAAC,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAKzF;AAED,wFAAwF;AACxF,wBAAsB,aAAa,CAAC,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAI5F;AAED,kFAAkF;AAClF,eAAO,MAAM,YAAY,IAAI,CAAC;AAC9B,2FAA2F;AAC3F,eAAO,MAAM,iBAAiB,WAAS,CAAC;AAExC,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,OAAO,CAAC;IACjB,4DAA4D;IAC5D,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,EAAE,GAAG,EAAE,IAAI,GAAG,aAAa,CAW5E;AAED,MAAM,MAAM,YAAY,GAAG;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAA;CAAE,CAAC;AAEhF;;;;GAIG;AACH,wBAAsB,YAAY,CAAC,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,GAAG,OAAO,CAAC,YAAY,CAAC,CAc/F;AAED,kEAAkE;AAClE,wBAAsB,UAAU,CAC9B,EAAE,EAAE,QAAQ,EACZ,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,EAAE,CAAC,CAO5C;AAKD;;;;GAIG;AACH,wBAAsB,YAAY,CAAC,EAAE,EAAE,QAAQ,EAAE,GAAG,EAAE,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC,CAU3E;AAED,gGAAgG;AAChG,MAAM,WAAW,SAAS;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB;AAED;;;GAGG;AACH,wBAAsB,WAAW,CAC/B,EAAE,EAAE,QAAQ,EACZ,GAAG,EAAE;IACH,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,GAAG,EAAE,IAAI,CAAC;IACV,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB,GACA,OAAO,CAAC,IAAI,CAAC,CAgBf;AAKD,wBAAsB,UAAU,CAC9B,EAAE,EAAE,QAAQ,EACZ,GAAG,EAAE,SAAS,MAAM,EAAE,GACrB,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC,CAgBjC"}