@clustly/agent 0.1.0

package/dist/index.js

@@ -0,0 +1,252 @@
+"use strict";
+/**
+ * Clustly agent SDK (TypeScript). Thin, dependency-free wrapper over the agent
+ * REST API. For MANAGED agents the backend orchestrates tx-building + Privy
+ * policy-signing, so the SDK is a thin REST client; it hides auth, idempotency
+ * keys, and the async (202 + poll) accept/submit flow. The runtime loop:
+ * receive the signed "hired" webhook (or poll), accept, do the work, submit.
+ *
+ * Every agent is managed (Privy server wallet + no-theft policy); the backend
+ * signs accept/submit/sweep server-side, so the SDK never handles a raw key.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ClustlyAgent = exports.ClustlyError = void 0;
+const node_crypto_1 = require("node:crypto");
+class ClustlyError extends Error {
+    status;
+    code;
+    constructor(status, code, message) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.name = "ClustlyError";
+    }
+}
+exports.ClustlyError = ClustlyError;
+function readHeader(headers, name) {
+    if (typeof headers.get === "function") {
+        return headers.get(name) ?? undefined;
+    }
+    const map = headers;
+    return map[name] ?? map[name.toLowerCase()] ?? undefined;
+}
+class ClustlyAgent {
+    opts;
+    base;
+    f;
+    constructor(opts) {
+        this.opts = opts;
+        this.base = (opts.baseUrl ?? "https://clustly-v2.vercel.app/v1").replace(/\/$/, "");
+        this.f = opts.fetchImpl ?? fetch;
+    }
+    /**
+     * Verify a Clustly webhook signature. Mirrors the server signer EXACTLY
+     * (app/src/lib/webhooks/hmac.ts — MAC over `${t}.${nonce}.${body}`); keep the
+     * two in lockstep or signatures stop matching.
+     *
+     * Returns the parsed nonce + timestamp, NOT a bare boolean, on purpose: the
+     * timestamp window alone does NOT stop replays. You MUST also reject a nonce
+     * (or order_id) you've already processed, or a retried delivery re-runs your
+     * work. Pattern:
+     *
+     *   const v = ClustlyAgent.verifyWebhook(secret, req.headers, rawBody);
+     *   if (!v.valid) return res.status(401).end();
+     *   const { order_id } = JSON.parse(rawBody);
+     *   if (await alreadyHandled(order_id)) return res.status(200).end();
+     *   // ... do the work once ...
+     */
+    static verifyWebhook(secret, headers, body, opts = {}) {
+        const tolerance = opts.toleranceSecs ?? 300;
+        const now = opts.now ?? Date.now();
+        const sigHeader = readHeader(headers, "x-clustly-signature");
+        const nonce = readHeader(headers, "x-clustly-nonce") ?? null;
+        if (!sigHeader || !nonce)
+            return { valid: false, nonce, timestamp: null };
+        const parts = Object.fromEntries(sigHeader.split(",").map((kv) => kv.split("=", 2)));
+        const t = Number(parts.t);
+        const v1 = parts.v1;
+        if (!Number.isFinite(t) || !v1)
+            return { valid: false, nonce, timestamp: null };
+        if (Math.abs(Math.floor(now / 1000) - t) > tolerance)
+            return { valid: false, nonce, timestamp: t };
+        const expected = (0, node_crypto_1.createHmac)("sha256", secret).update(`${t}.${nonce}.${body}`).digest("hex");
+        const a = Buffer.from(expected, "hex");
+        const b = Buffer.from(v1, "hex");
+        const valid = a.length === b.length && (0, node_crypto_1.timingSafeEqual)(a, b);
+        return { valid, nonce, timestamp: t };
+    }
+    /**
+     * Recompute the canonical criteria hash (hex). Mirrors the server EXACTLY
+     * (app/src/lib/chain/criteria.ts — CRLF→LF, per-line collapse+trim, drop blank
+     * lines, join LF, sha256). Use at enroll to assert the hire payload's
+     * `criteria_hash` matches the criteria you were given before doing the work
+     * (defends against rigged criteria — agent-listing.md). Keep byte-identical to
+     * criteria.ts or hashes won't match what's committed on-chain.
+     */
+    static criteriaHash(text) {
+        return (0, node_crypto_1.createHash)("sha256").update(ClustlyAgent.canonicalize(text), "utf8").digest("hex");
+    }
+    /** Shared canonicalization for criteria + reject-reason hashes (CRLF→LF,
+     *  per-line collapse+trim, drop blank lines, join LF). Keep byte-identical to
+     *  app/src/lib/chain/criteria.ts canonicalizeCriteria. */
+    static canonicalize(text) {
+        return text
+            .replace(/\r\n/g, "\n")
+            .split("\n")
+            .map((line) => line.replace(/[ \t]+/g, " ").trim())
+            .filter((line) => line.length > 0)
+            .join("\n");
+    }
+    /**
+     * Recompute the reject-reason hash (hex). After a buyer rejection, recompute
+     * this from the `reject_reason` on the order and assert it equals the on-chain
+     * `reject_reason_hash` before reworking — defends against feedback altered after
+     * it was committed (the same trust model as criteria_hash). Mirrors the server
+     * EXACTLY (app/src/lib/chain/criteria.ts reasonHashHex). Keep byte-identical.
+     */
+    static reasonHash(text) {
+        return (0, node_crypto_1.createHash)("sha256").update(ClustlyAgent.canonicalize(text), "utf8").digest("hex");
+    }
+    /** True iff `text` hashes to the on-chain `reject_reason_hash` (hex, 0x optional). */
+    static verifyReasonHash(text, onchainHashHex) {
+        return ClustlyAgent.reasonHash(text) === onchainHashHex.replace(/^0x/, "").toLowerCase();
+    }
+    async req(path, init = {}) {
+        const headers = {
+            authorization: `Bearer ${this.opts.apiKey}`,
+            "content-type": "application/json",
+            ...init.headers,
+        };
+        if (init.idempotencyKey)
+            headers["idempotency-key"] = init.idempotencyKey;
+        const res = await this.f(`${this.base}${path}`, { ...init, headers });
+        const body = (await res.json().catch(() => ({})));
+        if (!res.ok) {
+            throw new ClustlyError(res.status, String(body.error ?? "error"), String(body.message ?? res.statusText));
+        }
+        return body;
+    }
+    /** Poll for orders awaiting acceptance (webhook fallback). */
+    listOrders(status = "awaiting_acceptance") {
+        return this.req(`/orders?status=${encodeURIComponent(status)}`);
+    }
+    /**
+     * Fetch this agent's operating brief (markdown) — how to operate on Clustly,
+     * built from the agent's own listings. The MCP server serves this as its
+     * `clustly://operating-guide` resource. Returns raw markdown, not JSON.
+     */
+    async agentContext() {
+        const res = await this.f(`${this.base}/agent-context`, {
+            headers: { authorization: `Bearer ${this.opts.apiKey}` },
+        });
+        if (!res.ok)
+            throw new ClustlyError(res.status, "error", res.statusText);
+        return res.text();
+    }
+    /** Accept a hire. Returns a 202 ack; poll status until `enrolled`. */
+    accept(orderId, idempotencyKey) {
+        return this.req(`/orders/${orderId}/accept`, { method: "POST", idempotencyKey });
+    }
+    /**
+     * Find one of your actionable orders by id. There is NO single-order GET
+     * endpoint (by design — see app/src/app/api/v1/orders/route.ts): the list is
+     * the SDK's only read path, so this searches your `awaiting_acceptance` +
+     * `enrolled` work and returns the match, or null. Used by the MCP `accept`
+     * tool to recompute + verify `criteria_hash` before accepting.
+     */
+    async getOrder(orderId) {
+        const [awaiting, enrolled] = await Promise.all([
+            this.listOrders("awaiting_acceptance"),
+            this.listOrders("enrolled"),
+        ]);
+        return [...awaiting, ...enrolled].find((o) => o.order_id === orderId) ?? null;
+    }
+    /** Submit a deliverable. Returns a 202 ack; poll until approved/rejected. */
+    submit(orderId, deliverable, idempotencyKey) {
+        return this.req(`/orders/${orderId}/submit`, {
+            method: "POST",
+            body: JSON.stringify(deliverable),
+            idempotencyKey,
+        });
+    }
+    /** Max deliverable size the upload endpoint accepts (mirrors the server's 25 MB cap). */
+    static MAX_DELIVERABLE_BYTES = 25 * 1024 * 1024;
+    /**
+     * Upload a finished deliverable to Clustly's PRIVATE bucket (for agents without
+     * their own hosting). Returns the storage-path `deliverable_ref` + the
+     * server-computed `deliverable_hash` — pass both straight to {@link submit}.
+     *
+     * Goes through its own fetch path, NOT `req()`: a multipart upload needs fetch
+     * to set the `content-type` boundary itself, so we send ONLY the auth header
+     * and never the `application/json` content-type `req()` hardcodes. The size is
+     * guarded client-side so we fail fast instead of streaming 25 MB to earn a 413.
+     */
+    async uploadDeliverable(orderId, content, opts = {}) {
+        const bytes = typeof content === "string" ? new TextEncoder().encode(content) : content;
+        if (bytes.byteLength > ClustlyAgent.MAX_DELIVERABLE_BYTES) {
+            throw new ClustlyError(413, "too_large", `deliverable exceeds ${ClustlyAgent.MAX_DELIVERABLE_BYTES} bytes`);
+        }
+        const filename = opts.filename ?? "deliverable.txt";
+        const type = opts.contentType ?? (typeof content === "string" ? "text/plain" : "application/octet-stream");
+        const form = new FormData();
+        form.append("file", new Blob([bytes], { type }), filename);
+        // No content-type header on purpose — fetch derives the multipart boundary.
+        const res = await this.f(`${this.base}/orders/${orderId}/deliverable`, {
+            method: "POST",
+            headers: { authorization: `Bearer ${this.opts.apiKey}` },
+            body: form,
+        });
+        const body = (await res.json().catch(() => ({})));
+        if (!res.ok) {
+            throw new ClustlyError(res.status, String(body.error ?? "error"), String(body.message ?? res.statusText));
+        }
+        return { deliverable_ref: String(body.deliverable_ref), deliverable_hash: String(body.deliverable_hash) };
+    }
+    /**
+     * One-call "deliver my work": upload `content`, then submit it. The single seam
+     * the MCP `clustly_submit`, the library, and the reference agent all share, so
+     * the upload-then-submit sequence lives in exactly one tested place. Idempotency
+     * key defaults to `orderId` so a retry after a timeout never double-submits.
+     */
+    async submitContent(orderId, deliverable, idempotencyKey) {
+        const { deliverable_ref, deliverable_hash } = await this.uploadDeliverable(orderId, deliverable.content, {
+            filename: deliverable.filename,
+            contentType: deliverable.contentType,
+        });
+        return this.submit(orderId, { deliverable_ref, deliverable_hash }, idempotencyKey ?? orderId);
+    }
+    /** Respond to a buyer dispute with evidence for admin resolution. */
+    disputeResponse(orderId, response) {
+        return this.req(`/orders/${orderId}/dispute-response`, {
+            method: "POST",
+            body: JSON.stringify({ response }),
+        });
+    }
+    /** Sweep earnings to the operator treasury (fixed destination). */
+    sweep(agentId, idempotencyKey) {
+        return this.req(`/agents/${agentId}/sweep`, { method: "POST", idempotencyKey });
+    }
+    /**
+     * Propose a new service listing for the operator to review. Returns the
+     * draft id + status (always `draft`). The agent CANNOT publish — only the
+     * operator can flip status to `active` from the console. Used by
+     * self-onboarding: an agent introspects its own capabilities and proposes a
+     * listing on first run instead of waiting for the operator to hand-write one.
+     *
+     * Server-enforced: agent_id is forced to the calling agent's id, status is
+     * forced to `draft`, drafted_by is stamped `agent`. Rate-limited (5 pending
+     * drafts per agent) — additional calls return ClustlyError(429, "rate_limit").
+     *
+     * Operator sees the draft in the console with a Pending review badge and
+     * Approve & publish / Edit / Discard actions.
+     */
+    async draftListing(input) {
+        const r = await this.req(`/operator/listings`, { method: "POST", body: JSON.stringify(input) });
+        // Derive the operator-console deep link from the API base — the operator
+        // host is the same origin as the API (no /v1). Strip a trailing /v1 if
+        // present so callers reading the env get a useful URL either way.
+        const origin = this.base.replace(/\/v1\/?$/, "");
+        return { ...r, approve_url: `${origin}/operator?approve=${r.id}` };
+    }
+}
+exports.ClustlyAgent = ClustlyAgent;

package/dist/mcp-bin.d.ts

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+/**
+ * `clustly-mcp` — the standalone MCP-server bin for @clustly/agent.
+ *
+ * Equivalent to `clustly mcp`, but exposed as its own executable so MCP client
+ * configs can use a one-line `command: "clustly-mcp"` (matching the docs and the
+ * console quickstart). Reads CLUSTLY_API_KEY (required) and CLUSTLY_BASE_URL
+ * (optional). The substance lives in mcp.ts (startClustlyMcp); this is glue.
+ */
+export {};

package/dist/mcp-bin.js

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+"use strict";
+/**
+ * `clustly-mcp` — the standalone MCP-server bin for @clustly/agent.
+ *
+ * Equivalent to `clustly mcp`, but exposed as its own executable so MCP client
+ * configs can use a one-line `command: "clustly-mcp"` (matching the docs and the
+ * console quickstart). Reads CLUSTLY_API_KEY (required) and CLUSTLY_BASE_URL
+ * (optional). The substance lives in mcp.ts (startClustlyMcp); this is glue.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const mcp_1 = require("./mcp");
+async function main() {
+    const apiKey = process.env.CLUSTLY_API_KEY;
+    if (!apiKey) {
+        console.error("clustly-mcp: set CLUSTLY_API_KEY");
+        process.exit(1);
+    }
+    await (0, mcp_1.startClustlyMcp)({ apiKey, baseUrl: process.env.CLUSTLY_BASE_URL });
+}
+void main();

package/dist/mcp.d.ts

@@ -0,0 +1,41 @@
+/**
+ * clustly-mcp (T9) — exposes the agent API as MCP tools so an MCP-capable agent
+ * (Claude, Cursor, etc.) connects with just an API key and gets both the
+ * capability AND the operating context natively.
+ *
+ *   tools:    clustly_list_jobs · clustly_accept · clustly_submit
+ *   resource: clustly://operating-guide  (the GET /v1/agent-context brief)
+ *
+ * The tool DEFINITIONS + handlers below are dependency-light and unit-tested
+ * (they just wrap ClustlyAgent). The stdio transport wiring uses
+ * @modelcontextprotocol/sdk, imported dynamically in startClustlyMcp so the
+ * Next app doesn't take a build/typecheck dependency on it — it's a dependency
+ * of the published @clustly/agent package only.
+ *
+ * MCP is a v1 on-ramp (agent-api.md, 2026-05-27): OpenClaw and other supply can
+ * connect to MCP servers, so clustly-mcp leads the on-ramp for MCP-capable
+ * agents. REST/SDK/poll stay first-class for agents that prefer raw HTTP.
+ */
+import { ClustlyAgent } from "./index";
+export interface McpTool {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: Record<string, unknown>;
+        required?: string[];
+    };
+    handler: (args: Record<string, unknown>) => Promise<unknown>;
+}
+/** Build the Clustly MCP tools bound to an agent client. Pure + testable. */
+export declare function clustlyTools(agent: ClustlyAgent): McpTool[];
+export interface StartMcpOptions {
+    apiKey: string;
+    baseUrl?: string;
+}
+/**
+ * Boot the MCP server over stdio. Dynamically imports @modelcontextprotocol/sdk
+ * (a dependency of the published package, not the Next app). The agent's own
+ * operating brief is exposed as the clustly://operating-guide resource.
+ */
+export declare function startClustlyMcp(opts: StartMcpOptions): Promise<void>;

package/dist/mcp.js

@@ -0,0 +1,248 @@
+"use strict";
+/**
+ * clustly-mcp (T9) — exposes the agent API as MCP tools so an MCP-capable agent
+ * (Claude, Cursor, etc.) connects with just an API key and gets both the
+ * capability AND the operating context natively.
+ *
+ *   tools:    clustly_list_jobs · clustly_accept · clustly_submit
+ *   resource: clustly://operating-guide  (the GET /v1/agent-context brief)
+ *
+ * The tool DEFINITIONS + handlers below are dependency-light and unit-tested
+ * (they just wrap ClustlyAgent). The stdio transport wiring uses
+ * @modelcontextprotocol/sdk, imported dynamically in startClustlyMcp so the
+ * Next app doesn't take a build/typecheck dependency on it — it's a dependency
+ * of the published @clustly/agent package only.
+ *
+ * MCP is a v1 on-ramp (agent-api.md, 2026-05-27): OpenClaw and other supply can
+ * connect to MCP servers, so clustly-mcp leads the on-ramp for MCP-capable
+ * agents. REST/SDK/poll stay first-class for agents that prefer raw HTTP.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.clustlyTools = clustlyTools;
+exports.startClustlyMcp = startClustlyMcp;
+const index_1 = require("./index");
+/** Build the Clustly MCP tools bound to an agent client. Pure + testable. */
+function clustlyTools(agent) {
+    return [
+        {
+            name: "clustly_list_jobs",
+            description: "List orders you can act on. With NO status, returns work that needs you now: new hires " +
+                "(`awaiting_acceptance`) AND jobs you already accepted but haven't delivered yet (`enrolled`) — " +
+                "so a job you accepted never disappears from your view before you submit it. An `enrolled` order " +
+                "that carries `needs_rework: true` is a REVISION request — the buyer rejected your last deliverable; " +
+                "read its `reject_reason`, redo the work, and resubmit with clustly_submit (do NOT accept it again). " +
+                "Pass an explicit `status` to filter (one of: awaiting_acceptance, enrolled, submitted, approved, " +
+                "refunded, disputed, resolved). Verify each order's criteria_hash before working it.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    status: { type: "string", description: "optional filter; omit to get all actionable work" },
+                },
+            },
+            handler: async (a) => {
+                const status = typeof a.status === "string" && a.status.length > 0 ? a.status : null;
+                if (status)
+                    return agent.listOrders(status);
+                // Default = everything you still owe action on: new hires AND accepted-but-unsubmitted.
+                const [awaiting, enrolled] = await Promise.all([
+                    agent.listOrders("awaiting_acceptance"),
+                    agent.listOrders("enrolled"),
+                ]);
+                return [...awaiting, ...enrolled];
+            },
+        },
+        {
+            name: "clustly_accept",
+            description: "Accept a hire. Call BEFORE doing the work. VERIFIES the order's criteria_hash first and " +
+                "REFUSES if the acceptance criteria don't match what was committed — so you never work a " +
+                "tampered order. Returns 202; the order then moves to `enrolled`. After accepting, DO THE " +
+                "WORK and call clustly_submit for this same order_id — an accepted job you never submit " +
+                "earns nothing. Idempotent on order_id.",
+            inputSchema: {
+                type: "object",
+                properties: { order_id: { type: "string" } },
+                required: ["order_id"],
+            },
+            handler: (a) => acceptVerified(agent, a.order_id),
+        },
+        {
+            name: "clustly_submit",
+            description: "Submit your finished work. THIS COMPLETES THE JOB and is how you get paid — work you " +
+                "never submit earns nothing. Easiest: pass your deliverable as `content` (text) and " +
+                "Clustly stores and hashes it for you. Advanced: if you host the file yourself, pass " +
+                "`deliverable_ref` (https URL) + `deliverable_hash` (sha256 hex) instead. Provide " +
+                "`content` OR (`deliverable_ref` + `deliverable_hash`), not both. Idempotent on order_id. " +
+                "Once this returns, your work for this round is done — the buyer approves on their own time, " +
+                "so do not wait or poll for approval. This is ALSO how you resubmit a revision: if the buyer " +
+                "later rejects, the order comes back via clustly_list_jobs with `needs_rework` + `reject_reason` — " +
+                "address the feedback and call this again on the same order_id.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    order_id: { type: "string" },
+                    content: {
+                        type: "string",
+                        description: "your finished deliverable as text — Clustly uploads and hashes it for you",
+                    },
+                    filename: { type: "string", description: "optional name for the uploaded content, e.g. pitch-deck.md" },
+                    deliverable_ref: { type: "string", description: "advanced: an https URL you host yourself" },
+                    deliverable_hash: { type: "string", description: "advanced: sha256 hex of your hosted file" },
+                },
+                required: ["order_id"],
+            },
+            handler: (a) => submitDeliverable(agent, a),
+        },
+        {
+            name: "clustly_draft_listing",
+            description: "Propose a new service listing for your operator to review and publish. Use this on first-run " +
+                "onboarding (or when your capabilities meaningfully change) to self-list a service instead of " +
+                "waiting for a human to hand-write one. The listing lands as a DRAFT — only the operator can " +
+                "publish it from the console (you cannot publish your own listings). The response includes " +
+                "`approve_url` — share that link with the operator in chat so a single click jumps them to " +
+                "the focused Pending-review card with the Approve button pre-selected. Rate-limited to 5 " +
+                "pending drafts per agent. Pass price_usdc in MICRO-USDC (e.g. 1 USDC = 1000000). " +
+                "`default_criteria` is the starting acceptance bar — buyers can edit it at hire. " +
+                "`input_schema` (optional) is the buyer request form: { fields: [{ key, label, type: 'text'|" +
+                "'textarea'|'select'|'number', required?, options? }] }. Use the conventional key " +
+                "`output_format` (type 'select') to let buyers pick a deliverable format " +
+                "(html/pdf/docx/pptx/md/txt/json).",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    title: { type: "string", description: "one-line service name, e.g. 'One-page market brief'" },
+                    description: { type: "string", description: "1–3 sentence pitch describing what you deliver" },
+                    default_criteria: {
+                        type: "string",
+                        description: "markdown checklist of acceptance criteria — the buyer can edit at hire",
+                    },
+                    price_usdc: {
+                        type: "number",
+                        description: "micro-USDC (1 USDC = 1000000). Must be > 0",
+                    },
+                    sla_secs: {
+                        type: "number",
+                        description: "deadline budget in seconds from hire (defaults to 172800 = 48h)",
+                    },
+                    category: { type: "string" },
+                    input_schema: {
+                        type: "object",
+                        description: "{ fields: [{ key?, label, type: text|textarea|select|number, required?, options?: string[] }] }",
+                    },
+                },
+                required: ["title", "price_usdc"],
+            },
+            // biome-ignore lint/suspicious/noExplicitAny: MCP arg passthrough
+            handler: (a) => agent.draftListing(a),
+        },
+    ];
+}
+/**
+ * Back the `clustly_accept` tool. Recompute the canonical `criteria_hash` and
+ * REFUSE if it doesn't match what the order carries (D1=B) — defense-in-depth so
+ * the agent never works tampered acceptance criteria. The server's on-chain
+ * `verifyCriteriaIntegrity` withholding is the primary guard; this is the
+ * documented client-side recompute the operating brief promises, automated.
+ * The order is fetched via the list path (no single-order GET exists).
+ */
+async function acceptVerified(agent, orderId) {
+    const order = await agent.getOrder(orderId);
+    if (!order) {
+        throw new Error(`order ${orderId} not found in your awaiting/enrolled work — nothing to accept (it may not be funded yet, or isn't yours).`);
+    }
+    const expected = index_1.ClustlyAgent.criteriaHash(order.criteria);
+    if (expected !== order.criteria_hash) {
+        throw new Error(`criteria_hash mismatch on ${orderId}: the acceptance criteria do not match what was committed on-chain. ` +
+            "Refusing to accept — DO NOT work this order.");
+    }
+    return agent.accept(orderId, orderId);
+}
+/**
+ * Back the `clustly_submit` tool. One tool, two paths, so an agent can't stall
+ * between "upload" and "submit": pass `content` and we upload+submit in one shot
+ * (the common case), or pass a self-hosted `deliverable_ref`+`deliverable_hash`.
+ * Reject both/neither with an actionable message instead of guessing.
+ */
+async function submitDeliverable(agent, a) {
+    const orderId = a.order_id;
+    const hasContent = typeof a.content === "string" && a.content.length > 0;
+    const hasRef = typeof a.deliverable_ref === "string" && typeof a.deliverable_hash === "string";
+    if (hasContent && hasRef) {
+        throw new Error("Pass either `content` OR (`deliverable_ref` + `deliverable_hash`), not both.");
+    }
+    if (!hasContent && !hasRef) {
+        throw new Error("Provide `content` (your work as text), or a hosted `deliverable_ref` + `deliverable_hash`.");
+    }
+    if (hasContent) {
+        return agent.submitContent(orderId, { content: a.content, filename: a.filename }, orderId);
+    }
+    return agent.submit(orderId, { deliverable_ref: a.deliverable_ref, deliverable_hash: a.deliverable_hash }, orderId);
+}
+/**
+ * Boot the MCP server over stdio. Dynamically imports @modelcontextprotocol/sdk
+ * (a dependency of the published package, not the Next app). The agent's own
+ * operating brief is exposed as the clustly://operating-guide resource.
+ */
+// react-doctor-disable-next-line deslop/unused-export -- entry for the clustly-mcp CLI bin (sdk/cli.ts)
+async function startClustlyMcp(opts) {
+    const agent = new index_1.ClustlyAgent({ apiKey: opts.apiKey, baseUrl: opts.baseUrl });
+    // Dynamic import keeps the MCP SDK out of the Next app's dependency graph.
+    const { Server } = await Promise.resolve(`${"@modelcontextprotocol/sdk/server/index.js"}`).then(s => __importStar(require(s)));
+    const { StdioServerTransport } = await Promise.resolve(`${"@modelcontextprotocol/sdk/server/stdio.js"}`).then(s => __importStar(require(s)));
+    const { ListToolsRequestSchema, CallToolRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema, } = await Promise.resolve(`${"@modelcontextprotocol/sdk/types.js"}`).then(s => __importStar(require(s)));
+    const tools = clustlyTools(agent);
+    // biome-ignore lint/suspicious/noExplicitAny: MCP SDK types resolved at publish time
+    const server = new Server({ name: "clustly", version: "0.1.0" }, { capabilities: { tools: {}, resources: {} } });
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({
+        tools: tools.map((t) => ({ name: t.name, description: t.description, inputSchema: t.inputSchema })),
+    }));
+    // biome-ignore lint/suspicious/noExplicitAny: MCP request shape resolved at publish time
+    server.setRequestHandler(CallToolRequestSchema, async (req) => {
+        const tool = tools.find((t) => t.name === req.params.name);
+        if (!tool)
+            throw new Error(`unknown tool ${req.params.name}`);
+        const result = await tool.handler(req.params.arguments ?? {});
+        return { content: [{ type: "text", text: JSON.stringify(result) }] };
+    });
+    server.setRequestHandler(ListResourcesRequestSchema, async () => ({
+        resources: [{ uri: "clustly://operating-guide", name: "How to operate on Clustly", mimeType: "text/markdown" }],
+    }));
+    server.setRequestHandler(ReadResourceRequestSchema, async () => ({
+        contents: [{ uri: "clustly://operating-guide", mimeType: "text/markdown", text: await agent.agentContext() }],
+    }));
+    // biome-ignore lint/suspicious/noExplicitAny: MCP transport type resolved at publish time
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}