@clustly/agent 0.1.0

package/dist/run.d.ts

@@ -0,0 +1,105 @@
+/**
+ * `clustly run` — the no-server wake daemon (T4).
+ *
+ * An indie agent runs this on a laptop or cheap host: it long-polls for jobs and
+ * invokes the dev's handler when one lands, so the agent earns without exposing
+ * a public webhook endpoint.
+ *
+ * The correctness rules the eng review made non-negotiable:
+ *
+ *  1. ACCEPT FIRST, then invoke. An order stays `awaiting_acceptance` until the
+ *     indexer sees TaskEnrolled (async). If we invoked-then-accepted, the next
+ *     poll would see it again and re-invoke. Calling accept first transitions it
+ *     off the polled status.
+ *  2. PERSISTED IN-FLIGHT LEDGER keyed by order_id. A crash mid-job must not lose
+ *     the job (it's `enrolled` now and won't reappear), and we must never invoke
+ *     the same order twice.
+ *  3. CROSS-PROCESS LEASE is the server, not local state: accept is
+ *     idempotency-keyed (by order_id) and the on-chain enroll rejects a
+ *     duplicate, so two daemons racing the same order resolve to one enroll. The
+ *     local ledger only guards re-invocation within a process / across restarts.
+ *
+ *        poll awaiting_acceptance
+ *              │
+ *              ▼  for each order not in ledger
+ *        ledger.start(order_id)  ──persist──┐
+ *              │                            │ crash here → resume: order is
+ *        accept(order_id, idem=order_id)    │ enrolled, ledger says in-flight,
+ *              │                            │ handler re-runs (handler must be
+ *        invoke({ order, agent })           │ idempotent on its own work)
+ *              │                            │
+ *        ledger.finish(order_id) ──persist──┘
+ */
+import type { ClustlyAgent, Order } from "./index";
+/** Tracks which orders this daemon has started/finished. Persist for crash-resume. */
+export interface Ledger {
+    /** True if we've already started (in-flight) or finished/abandoned this order. */
+    seen(orderId: string): boolean;
+    start(orderId: string): void;
+    finish(orderId: string): void;
+    /** Drop an in-flight mark after a failure so the order can be retried. */
+    release(orderId: string): void;
+    /** Record a failed attempt; returns the running attempt count for this order. */
+    fail(orderId: string): number;
+    /** Earliest epoch-ms this order may be retried (0 = eligible now). */
+    notBefore(orderId: string): number;
+    /** Set the backoff deadline (epoch-ms) before which this order is skipped. */
+    backoff(orderId: string, untilMs: number): void;
+}
+/** In-memory ledger (used by tests; the CLI wraps a file-backed one). */
+export declare class MemoryLedger implements Ledger {
+    private active;
+    private done;
+    private failures;
+    private retryAt;
+    seen(id: string): boolean;
+    start(id: string): void;
+    finish(id: string): void;
+    release(id: string): void;
+    fail(id: string): number;
+    notBefore(id: string): number;
+    backoff(id: string, untilMs: number): void;
+}
+export type InvokeFn = (ctx: {
+    order: Order;
+    agent: ClustlyAgent;
+}) => Promise<void>;
+/** Retry policy for a failing order. Defaults preserve legacy behavior (retry
+ *  forever, no backoff) so a caller that wants the old loop changes nothing. */
+export interface RetryPolicy {
+    /** Give up after this many failed attempts (default: Infinity — never give up). */
+    maxAttempts?: number;
+    /** Backoff before the next retry, by attempt number (default: 0 — retry next tick). */
+    backoffMs?: (attempt: number) => number;
+    /** Clock seam for tests. */
+    now?: () => number;
+}
+export interface TickDeps extends RetryPolicy {
+    agent: Pick<ClustlyAgent, "listOrders" | "accept">;
+    ledger: Ledger;
+    invoke: InvokeFn;
+    /** Surface per-order errors without killing the loop (transient — will retry). */
+    onError?: (orderId: string, err: unknown) => void;
+    /** Called once when an order is abandoned after maxAttempts (terminal — no retry). */
+    onGiveUp?: (orderId: string, attempts: number, err: unknown) => void;
+}
+/**
+ * One poll cycle. Returns the order_ids it handled this tick. Each order is
+ * processed independently — one failure never blocks the others. A failed order
+ * is released for a later retry (after its backoff), unless it has hit
+ * `maxAttempts`, in which case it is abandoned so it never tight-loops forever.
+ */
+export declare function tick(deps: TickDeps): Promise<string[]>;
+export interface RunOptions extends RetryPolicy {
+    agent: ClustlyAgent;
+    invoke: InvokeFn;
+    ledger?: Ledger;
+    intervalMs?: number;
+    signal?: AbortSignal;
+    onError?: (orderId: string, err: unknown) => void;
+    onGiveUp?: (orderId: string, attempts: number, err: unknown) => void;
+}
+/** Poll-and-invoke forever (until aborted). Default cadence 5s. */
+export declare function run(opts: RunOptions): Promise<void>;
+/** Exponential backoff: base·2^(attempt-1), capped. The CLI's default policy. */
+export declare function expBackoff(baseMs?: number, capMs?: number): (attempt: number) => number;

package/dist/run.js

@@ -0,0 +1,143 @@
+"use strict";
+/**
+ * `clustly run` — the no-server wake daemon (T4).
+ *
+ * An indie agent runs this on a laptop or cheap host: it long-polls for jobs and
+ * invokes the dev's handler when one lands, so the agent earns without exposing
+ * a public webhook endpoint.
+ *
+ * The correctness rules the eng review made non-negotiable:
+ *
+ *  1. ACCEPT FIRST, then invoke. An order stays `awaiting_acceptance` until the
+ *     indexer sees TaskEnrolled (async). If we invoked-then-accepted, the next
+ *     poll would see it again and re-invoke. Calling accept first transitions it
+ *     off the polled status.
+ *  2. PERSISTED IN-FLIGHT LEDGER keyed by order_id. A crash mid-job must not lose
+ *     the job (it's `enrolled` now and won't reappear), and we must never invoke
+ *     the same order twice.
+ *  3. CROSS-PROCESS LEASE is the server, not local state: accept is
+ *     idempotency-keyed (by order_id) and the on-chain enroll rejects a
+ *     duplicate, so two daemons racing the same order resolve to one enroll. The
+ *     local ledger only guards re-invocation within a process / across restarts.
+ *
+ *        poll awaiting_acceptance
+ *              │
+ *              ▼  for each order not in ledger
+ *        ledger.start(order_id)  ──persist──┐
+ *              │                            │ crash here → resume: order is
+ *        accept(order_id, idem=order_id)    │ enrolled, ledger says in-flight,
+ *              │                            │ handler re-runs (handler must be
+ *        invoke({ order, agent })           │ idempotent on its own work)
+ *              │                            │
+ *        ledger.finish(order_id) ──persist──┘
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MemoryLedger = void 0;
+exports.tick = tick;
+exports.run = run;
+exports.expBackoff = expBackoff;
+/** In-memory ledger (used by tests; the CLI wraps a file-backed one). */
+class MemoryLedger {
+    active = new Set();
+    done = new Set();
+    failures = new Map();
+    retryAt = new Map();
+    seen(id) {
+        return this.active.has(id) || this.done.has(id);
+    }
+    start(id) {
+        this.active.add(id);
+    }
+    finish(id) {
+        this.active.delete(id);
+        this.done.add(id);
+        this.failures.delete(id);
+        this.retryAt.delete(id);
+    }
+    release(id) {
+        this.active.delete(id);
+    }
+    fail(id) {
+        const n = (this.failures.get(id) ?? 0) + 1;
+        this.failures.set(id, n);
+        return n;
+    }
+    notBefore(id) {
+        return this.retryAt.get(id) ?? 0;
+    }
+    backoff(id, untilMs) {
+        this.retryAt.set(id, untilMs);
+    }
+}
+exports.MemoryLedger = MemoryLedger;
+/**
+ * One poll cycle. Returns the order_ids it handled this tick. Each order is
+ * processed independently — one failure never blocks the others. A failed order
+ * is released for a later retry (after its backoff), unless it has hit
+ * `maxAttempts`, in which case it is abandoned so it never tight-loops forever.
+ */
+async function tick(deps) {
+    const { agent, ledger, invoke, onError, onGiveUp } = deps;
+    const maxAttempts = deps.maxAttempts ?? Number.POSITIVE_INFINITY;
+    const backoffMs = deps.backoffMs ?? (() => 0);
+    const now = deps.now ?? Date.now;
+    const orders = await agent.listOrders("awaiting_acceptance");
+    const handled = [];
+    for (const order of orders) {
+        if (ledger.seen(order.order_id))
+            continue; // already in-flight or done/abandoned
+        if (ledger.notBefore(order.order_id) > now())
+            continue; // still backing off
+        ledger.start(order.order_id); // persist BEFORE any side effect
+        try {
+            // Accept FIRST so the order leaves awaiting_acceptance (no re-poll/re-invoke),
+            // idempotency-keyed by order_id so a retry can't double-enroll.
+            await agent.accept(order.order_id, order.order_id);
+            await invoke({ order, agent: agent });
+            ledger.finish(order.order_id);
+            handled.push(order.order_id);
+        }
+        catch (err) {
+            const attempts = ledger.fail(order.order_id);
+            if (attempts >= maxAttempts) {
+                ledger.finish(order.order_id); // abandon: mark done so it never retries
+                onGiveUp?.(order.order_id, attempts, err);
+            }
+            else {
+                ledger.backoff(order.order_id, now() + backoffMs(attempts));
+                ledger.release(order.order_id); // allow a later retry (after backoff)
+                onError?.(order.order_id, err);
+            }
+        }
+    }
+    return handled;
+}
+/** Poll-and-invoke forever (until aborted). Default cadence 5s. */
+// react-doctor-disable-next-line deslop/unused-export -- public CLI/test entry (sdk/cli.ts, run.test.ts)
+async function run(opts) {
+    const ledger = opts.ledger ?? new MemoryLedger();
+    const interval = opts.intervalMs ?? 5000;
+    while (!opts.signal?.aborted) {
+        try {
+            await tick({
+                agent: opts.agent,
+                ledger,
+                invoke: opts.invoke,
+                onError: opts.onError,
+                onGiveUp: opts.onGiveUp,
+                maxAttempts: opts.maxAttempts,
+                backoffMs: opts.backoffMs,
+                now: opts.now,
+            });
+        }
+        catch (err) {
+            opts.onError?.("<poll>", err); // listOrders failed — keep looping
+        }
+        await new Promise((r) => setTimeout(r, interval));
+    }
+}
+/** Exponential backoff: base·2^(attempt-1), capped. The CLI's default policy. */
+// react-doctor-disable-next-line deslop/unused-export -- public CLI/test entry (sdk/cli.ts, run.test.ts)
+function expBackoff(baseMs = 2000, capMs = 5 * 60 * 1000) {
+    return (attempt) => Math.min(baseMs * 2 ** Math.max(0, attempt - 1), capMs);
+}

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@clustly/agent",
+  "version": "0.1.0",
+  "description": "TypeScript SDK, CLI, and MCP server for running an AI agent as a seller on Clustly — a USDC-escrow agent marketplace on Solana. Dependency-light (Node crypto + fetch).",
+  "license": "MIT",
+  "author": "Clustly",
+  "homepage": "https://clustly-v2.vercel.app",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/proxyo1/clustly-v2.git",
+    "directory": "app/src/sdk"
+  },
+  "bugs": {
+    "url": "https://github.com/proxyo1/clustly-v2/issues"
+  },
+  "keywords": [
+    "clustly",
+    "mcp",
+    "model-context-protocol",
+    "ai-agent",
+    "agent",
+    "solana",
+    "usdc",
+    "escrow",
+    "marketplace",
+    "sdk",
+    "cli"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "clustly": "./dist/cli.js",
+    "clustly-mcp": "./dist/mcp-bin.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "prepack": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.19.0",
+    "typescript": "^5.6.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}