@singularity-layer/grid 0.7.0 → 0.9.0

package/README.md

@@ -132,3 +132,37 @@ try {
 ## License
 
 MIT
+
+## Processors
+
+Processors are served by `processors.x402compute.cc`, not the grid, so they have their own client.
+
+```ts
+import { ProcessorsClient } from "@singularity-layer/grid";
+
+const p = new ProcessorsClient({ apiKey: process.env.SGL_API_KEY });
+
+await p.catalogue();                       // public, no credential
+await p.list();                            // yours          (processors:read)
+await p.deploy({ manifest, code });        // returns the invoke token ONCE
+await p.update("my-processor", { code });
+await p.setListing("my-processor", true);
+await p.run("my-processor", { name: "world" }, invokeToken);
+```
+
+> **`processors:write` is full control** of processors owned by that key's wallet — delete and
+> secrets included, the same as a Cloudflare API token. Mint `processors:read` if you want a
+> credential that cannot change anything. Note that compute keys do not expire, there is no audit
+> log, and **delete is permanent**: the code is wiped and the slug is burned forever.
+
+`run()` takes the **invoke token** from `deploy()`, not the API key — the run route is the only one
+with both a money path and an anonymous buyer lane, so it does not read a key as an ownership
+claim. Buyers use `runWithPayment()` with an x402 header instead.
+
+### Upgrading from 0.8.x
+
+The six processor methods on `GridClient` (`deployProcessor`, `invokeProcessor`,
+`listProcessors`, `getProcessor`, `deleteProcessor`, `getProcessorLogs`) are **removed**. They
+pointed at `/grid/processors`, which has never existed — every call returned 404 — and their types
+described an older design that was never shipped. Use `ProcessorsClient`. Nothing else changed:
+chat, embeddings, jobs, models, capacity, pricing, reserve and the vault are untouched.

package/dist/index.d.mts

@@ -178,87 +178,6 @@ interface ReserveResponse {
     attestation_verified?: boolean;
     expires_in_ms: number;
 }
-interface DeployProcessorOptions {
-    name: string;
-    code: string;
-    runtime?: "deno" | "wasm";
-    memory_mb?: number;
-    timeout_seconds?: number;
-    tee_type_required?: string;
-    metadata?: Record<string, unknown>;
-}
-interface ProcessorInfo {
-    id: string;
-    name: string;
-    owner_wallet: string;
-    owner_chain: string;
-    runtime: string;
-    memory_mb: number;
-    timeout_seconds: number;
-    tee_type_required?: string;
-    invocation_count: number;
-    last_invoked_at?: string;
-    status: string;
-    code_hash?: string;
-    deployment_stake_sgl: number;
-    invoke_url: string;
-    created_at: string;
-    updated_at?: string;
-    metadata?: Record<string, unknown>;
-}
-interface ProcessorDeployResult {
-    id: string;
-    name: string;
-    runtime: string;
-    memory_mb: number;
-    timeout_seconds: number;
-    status: string;
-    code_hash: string;
-    invoke_url: string;
-    tier: string;
-    sgl_staked: number;
-    created_at: string;
-}
-interface ProcessorInvokeResult {
-    job_id: string;
-    processor: string;
-    status: string;
-    output?: unknown;
-    duration_ms?: number;
-    payment?: {
-        amount_usd: string;
-        token: string;
-        discount_pct: number;
-    };
-    tee?: {
-        node_id: string;
-        tee_type: string;
-        attestation_verified: boolean;
-    };
-    message?: string;
-}
-interface ProcessorListResponse {
-    processors: ProcessorInfo[];
-    total: number;
-    page: number;
-    limit: number;
-}
-interface ProcessorLogEntry {
-    id: string;
-    processor_id: string;
-    job_id: string;
-    node_id: string;
-    duration_ms?: number;
-    status: string;
-    error_message?: string;
-    created_at: string;
-}
-interface ProcessorLogsResponse {
-    logs: ProcessorLogEntry[];
-    total: number;
-    page: number;
-    limit: number;
-}
 interface WalletAuth {
     address: string;
     chain?: string;
@@ -321,27 +240,86 @@ declare class GridClient {
      * streaming (toggle off), the whole reply is yielded as a single chunk.
      */
     chatCompletionStream(request: ChatCompletionRequest): AsyncGenerator<string, void, unknown>;
-    private requestWithWalletAuth;
-    private requestWithPayment;
-    deployProcessor(wallet: WalletAuth, options: DeployProcessorOptions): Promise<ProcessorDeployResult>;
-    invokeProcessor(processorName: string, input: Record<string, unknown>, options?: {
-        paymentHeader?: string;
-        paymentToken?: "USDC" | "SGL";
-    }): Promise<ProcessorInvokeResult>;
-    listProcessors(options?: {
-        owner?: string;
-        page?: number;
-        limit?: number;
-    }): Promise<ProcessorListResponse>;
-    getProcessor(processorId: string): Promise<ProcessorInfo>;
-    deleteProcessor(processorId: string, wallet: WalletAuth): Promise<{
-        deleted: boolean;
-        id: string;
+}
+
+/**
+ * Agent Vault — zero-knowledge encrypted agent backup/restore.
+ *
+ * Pure-JS envelope (noble scrypt + AES-256-GCM), byte-compatible with the
+ * agentvault CLI, the pod runner, and the Python SDK:
+ * `[4-byte BE header length][JSON header][GCM body, tag appended]`, with the
+ * snapshot identity bound into the GCM AAD. Runs in Node AND browsers.
+ *
+ * Scope: this module encrypts/decrypts BYTES and drives the API. Packing a
+ * directory into a tarball is filesystem work — use the `agentvault` CLI or
+ * the Python SDK for that, or bring your own archive bytes.
+ *
+ * Auth: a Singularity compute API key (X-API-Key). Passphrases and plaintext
+ * never leave this process.
+ */
+declare const VAULT_URL = "https://compute.x402layer.cc";
+interface VaultAad {
+    userId: string;
+    agentId: string;
+    backupId: string;
+    formatVersion: 1;
+}
+/** Envelope-encrypt arbitrary bytes under a passphrase (scrypt + AES-256-GCM). */
+declare function encryptEnvelope(plaintext: Uint8Array, passphrase: string, aad: VaultAad): Uint8Array;
+/** Reverse of encryptEnvelope. Throws on wrong passphrase or AAD mismatch. */
+declare function decryptEnvelope(blob: Uint8Array, passphrase: string, aad: VaultAad): Uint8Array;
+declare function parseAadFromKey(r2Key: string): VaultAad;
+interface VaultAgent {
+    id: string;
+    name: string;
+    framework: string;
+    source: "local" | "pod";
+    pod_order_id: string | null;
+}
+interface VaultSnapshot {
+    id: string;
+    agent_id: string;
+    size_bytes: number;
+    sha256: string | null;
+    created_at: string;
+}
+interface VaultUsage {
+    plan: "free" | "pro";
+    planRenewsAt: string | null;
+    bytesUsed: number;
+    bytesReserved: number;
+    maxBytes: number;
+    proPriceUsd: number;
+}
+interface VaultClientOptions {
+    apiKey: string;
+    baseUrl?: string;
+    fetchImpl?: typeof fetch;
+}
+declare class VaultClient {
+    private readonly base;
+    private readonly apiKey;
+    private readonly fetchImpl;
+    constructor(options: VaultClientOptions);
+    private static id;
+    private call;
+    agents(): Promise<VaultAgent[]>;
+    createAgent(name: string, framework: string): Promise<VaultAgent>;
+    snapshots(agentId?: string): Promise<VaultSnapshot[]>;
+    usage(): Promise<VaultUsage>;
+    /** Activate Vault Pro ($3/mo from credits). */
+    subscribePro(): Promise<{
+        ok: boolean;
+        already?: boolean;
     }>;
-    getProcessorLogs(processorId: string, wallet: WalletAuth, options?: {
-        page?: number;
-        limit?: number;
-    }): Promise<ProcessorLogsResponse>;
+    deleteSnapshot(id: string): Promise<void>;
+    /**
+     * Encrypt + upload arbitrary payload bytes (e.g. a tarball you packed) as a
+     * snapshot of `agentId`. Returns the snapshot id.
+     */
+    backupBytes(agentId: string, payload: Uint8Array, passphrase: string): Promise<string>;
+    /** Download + decrypt a snapshot's payload bytes. */
+    restoreBytes(snapshotId: string, passphrase: string): Promise<Uint8Array>;
 }
 
 declare class SGLError extends Error {
@@ -362,4 +340,264 @@ declare class SGLConnectionError extends SGLError {
     constructor(message: string);
 }
 
-export { type Attestation, type AttestationProof, type CapacityResponse, type ChatChoice, type ChatCompletionRequest, type ChatCompletionResponse, type ChatContentPart, type ChatMessage, DEFAULT_BASE_URL, type DeployProcessorOptions, type EmbeddingDatum, type EmbeddingRequest, type EmbeddingResponse, GridClient, type GridClientOptions, type JobResponse, type JobResult, type JobSubmission, type ModelInfo, type ModelPricing, type PricingInfo, type ProcessorDeployResult, type ProcessorInfo, type ProcessorInvokeResult, type ProcessorListResponse, type ProcessorLogEntry, type ProcessorLogsResponse, type ReserveResponse, SGLAPIError, SGLAuthError, SGLConnectionError, SGLError, SGLNotFoundError, type TeeCapacity, type WalletAuth };
+/**
+ * Singularity Processors.
+ *
+ * A processor is a function we host: deploy one and you get a paid HTTP endpoint, an OpenAPI
+ * document and an MCP server. Buyers pay the PUBLISHER directly in USDC over x402 — the platform
+ * never holds it and takes no cut. The publisher pays for compute instead.
+ *
+ * ─── WHY THIS IS A SEPARATE CLIENT ──────────────────────────────────────────
+ * Processors live on their own worker at `https://processors.x402compute.cc`, not on the grid.
+ * Until 0.9.0 these methods hung off `GridClient` and pointed at `/grid/processors`, which has
+ * never existed — every call 404'd. Fixing that by teaching `GridClient` a second base URL would
+ * have meant a per-call host override inside the shared request path that chat, embeddings and
+ * jobs all use, which is a real risk to working features for no benefit. A separate client with
+ * its own base URL touches none of that.
+ *
+ * ─── AUTH ───────────────────────────────────────────────────────────────────
+ * A compute API key (`x402c_…`) with the `processors:write` scope, sent as `X-API-Key`.
+ *
+ * `processors:write` is FULL CONTROL of processors owned by that key's wallet, delete and secrets
+ * included — the same shape as a Cloudflare API token. If you want a credential that cannot change
+ * anything, mint `processors:read`. Three things to know before relying on it: compute keys do not
+ * expire, there is no audit log of what a key did, and delete is permanent — the code is wiped and
+ * the slug is burned forever, so a leaked key can destroy a name you can never reclaim.
+ *
+ * Two routes never accept a key: `suspend` (moderation) and `auth-session`. Both need a wallet
+ * signature, and neither is a publisher action.
+ *
+ * ─── RUNNING A PROCESSOR IS NOT DONE WITH THE API KEY ────────────────────────
+ * `run()` takes the INVOKE TOKEN that `deploy()` returns, because the run route is the only one
+ * with both a money path and an anonymous buyer lane and deliberately does not read an API key as
+ * an ownership claim. Anonymous buyers pay with x402 instead; see `runWithPayment`.
+ */
+declare const PROCESSORS_BASE_URL = "https://processors.x402compute.cc";
+interface ProcessorsClientOptions {
+    /** Compute API key (`x402c_…`) holding `processors:read` or `processors:write`. */
+    apiKey?: string;
+    /** Override the base URL. Defaults to https://processors.x402compute.cc */
+    baseUrl?: string;
+    /**
+     * Send the API key to a `baseUrl` that is neither the official host nor loopback.
+     *
+     * Off by default on purpose: see `keyAllowedOnHost`. Set it only when you genuinely run your
+     * own processors host and mean to hand it your credential.
+     */
+    allowKeyOnCustomHost?: boolean;
+    timeoutMs?: number;
+}
+/** Limits are declared, not discovered: the runtime hold before each run derives from `timeout_ms`. */
+interface ProcessorLimits {
+    timeout_ms: number;
+    cpu_ms: number;
+    /** Must be >= 1. */
+    subrequests: number;
+}
+interface ProcessorSecretDeclaration {
+    name: string;
+    /** Hosts this secret may be injected at. Every one must also appear in `egress.allow`. */
+    hosts?: string[];
+    /** Header injection. `format` must contain the literal `{value}` placeholder. */
+    inject?: {
+        header: string;
+        format: string;
+    };
+    /** `env` makes the value readable by your own code — a deliberate downgrade, opt in per secret. */
+    mode?: "env";
+}
+/** One `price_usd` is the price on EVERY chain: all three assets are 6-decimal stablecoins. */
+interface ProcessorPayout {
+    /** base58 wallet. Defaults to the deploying wallet. */
+    solana?: string;
+    /** 0x… — USDC on Base. */
+    base?: string;
+    /** 0x… — USDG on Robinhood Chain. */
+    robinhood?: string;
+}
+interface ProcessorManifest {
+    manifest_version: 1;
+    /** Lowercase, permanent, and NEVER reusable — `pause` exists so nobody burns one to stop traffic. */
+    slug: string;
+    name: string;
+    description: string;
+    lane?: "managed" | "self_hosted" | "pod";
+    price_usd?: string;
+    methods?: Array<"GET" | "POST">;
+    input_schema: Record<string, unknown>;
+    output_schema: Record<string, unknown>;
+    limits: ProcessorLimits;
+    egress?: {
+        allow: string[];
+    };
+    secrets?: ProcessorSecretDeclaration[];
+    payout?: ProcessorPayout;
+    pricing?: Record<string, unknown>;
+    inference?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+interface DeployProcessorInput {
+    manifest: ProcessorManifest;
+    /** A single ES module. Use `bundle` instead if you need imports or npm packages. */
+    code?: string;
+    /** esbuild output, bundled on YOUR machine. We never run `npm install` for you. */
+    bundle?: string;
+    files?: Record<string, string>;
+}
+interface ProcessorDeployResult {
+    id: string;
+    slug: string;
+    /** Shown EXACTLY ONCE. Store it — there is no way to read it back, only to rotate it. */
+    invoke_token: string;
+    listing_state: string;
+    note?: string;
+}
+interface ProcessorSummary {
+    id: string;
+    slug: string;
+    lane: string;
+    price_micro: number;
+    status: string;
+    listed?: boolean;
+    listing_state?: string;
+    run_count?: number;
+    last_run_at?: string | null;
+    created_at: string;
+    config_rev?: number;
+    code_hash?: string | null;
+    manifest?: ProcessorManifest | null;
+    paused_at?: string | null;
+}
+interface ProcessorListResponse {
+    processors: ProcessorSummary[];
+    /** Present on the owner-scoped list; the wallet the credential resolved to. */
+    owner?: string;
+}
+interface ProcessorRun {
+    id: string;
+    status: string;
+    error: string | null;
+    run_ms: number | null;
+    cpu_ms: number | null;
+    attempt_count?: number;
+    created_at: string;
+    finished_at?: string | null;
+    output?: unknown;
+}
+interface ProcessorRunsResponse {
+    runs: ProcessorRun[];
+    /** Publisher-caused failures only. Platform faults are excluded, so it measures YOUR code. */
+    failure_rate_30d?: number;
+    runs_30d?: number;
+}
+interface ProcessorEarnings {
+    sales?: unknown;
+    runtime?: unknown;
+    [key: string]: unknown;
+}
+interface ProcessorWebhookRegistration {
+    url: string;
+    /** Returned EXACTLY ONCE on registration. There is no way to read it back. */
+    secret?: string;
+    active?: boolean;
+    [key: string]: unknown;
+}
+declare class ProcessorsClient {
+    private readonly baseUrl;
+    private readonly headers;
+    private readonly timeout;
+    constructor(options?: ProcessorsClientOptions);
+    private request;
+    /**
+     * The public catalogue.
+     *
+     * Sends NO credential, even when the client holds one. `GET /processors` is owner-scoped when a
+     * key is presented and public otherwise, so passing the key here would silently return your own
+     * processors instead of the catalogue — the opposite of what the name promises. Use `list()`
+     * when you want yours.
+     */
+    catalogue(): Promise<ProcessorListResponse>;
+    /** Processors owned by this key's wallet. Needs `processors:read`. */
+    list(): Promise<ProcessorListResponse>;
+    /** Owner projection when the key owns it, public projection otherwise. */
+    get(slug: string): Promise<ProcessorSummary>;
+    /**
+     * Deploy. The wallet behind the key becomes `owner_wallet`, which is also the x402 `payTo` and
+     * the runtime-billing account — so the key must be minted on a SOLANA wallet or this returns
+     * `400 solana_wallet_required`.
+     *
+     * The `invoke_token` in the response is shown once and never again.
+     */
+    deploy(input: DeployProcessorInput): Promise<ProcessorDeployResult>;
+    /** Push new code, a new manifest, or both. Omitting `manifest` keeps the stored one. */
+    update(slug: string, input: {
+        manifest?: ProcessorManifest;
+        code?: string;
+        bundle?: string;
+        files?: Record<string, string>;
+    }): Promise<{
+        slug: string;
+        config_rev: number;
+        config_changed: boolean;
+    }>;
+    /**
+     * Delete. **Irreversible, and the slug is burned forever** — it can never be reused, by you or
+     * anyone. In-flight runs finish first; the code is wiped when they drain.
+     */
+    delete(slug: string): Promise<{
+        slug: string;
+        status: string;
+        note?: string;
+    }>;
+    /** Stop or restart traffic WITHOUT losing the slug. This is the switch, not `delete`. */
+    setPaused(slug: string, paused: boolean): Promise<unknown>;
+    /**
+     * List or unlist publicly. Instant, no review step.
+     *
+     * Unlisting is NOT stopping: an unlisted processor keeps answering anyone holding the URL or an
+     * invoke token, earning nothing while still drawing compute from your balance. Use `setPaused`.
+     */
+    setListing(slug: string, listed: boolean): Promise<unknown>;
+    /** Set secret VALUES. Each name must already be declared in `manifest.secrets`. */
+    setSecrets(slug: string, values: Record<string, string>): Promise<unknown>;
+    /** Mint a new invoke token. The old one stops working immediately. */
+    rotateToken(slug: string): Promise<{
+        invoke_token: string;
+    }>;
+    runs(slug: string): Promise<ProcessorRunsResponse>;
+    run_(slug: string, runId: string): Promise<ProcessorRun>;
+    /** Sales (paid straight to your wallet, with the on-chain tx per row) and runtime spend. */
+    earnings(slug: string): Promise<ProcessorEarnings>;
+    /** The processor's own key/value state. Read-only from out here, by design. */
+    kv(slug: string): Promise<unknown>;
+    getWebhook(slug: string): Promise<ProcessorWebhookRegistration>;
+    /**
+     * Register or replace. We immediately POST a signed verification to the URL: it must answer 2xx
+     * or the webhook stays registered-but-inactive and delivers nothing. The signing secret comes
+     * back EXACTLY ONCE.
+     */
+    setWebhook(slug: string, url: string): Promise<ProcessorWebhookRegistration>;
+    deleteWebhook(slug: string): Promise<unknown>;
+    testWebhook(slug: string): Promise<unknown>;
+    /**
+     * Run YOUR OWN processor with the invoke token from `deploy()`.
+     *
+     * Not the API key: the run route deliberately does not read a key as an ownership claim, because
+     * it is the only route with both a money path and an anonymous buyer lane. You pay for the
+     * compute; nobody pays at call time.
+     */
+    run(slug: string, input: Record<string, unknown>, invokeToken: string): Promise<unknown>;
+    /**
+     * Run someone else's processor as a buyer, with an x402 payment header.
+     *
+     * Call once WITHOUT `paymentHeader` to get the 402 and its `accepts` array — one entry per chain
+     * that publisher takes. Match on `network`, pay that entry, and retry with the header.
+     *
+     * Re-sending the SAME header returns the run that payment already bought and does NOT charge
+     * again. That is the recovery path for every failure mode, because **there are no refunds**: the
+     * money went straight to the publisher and the platform never held it.
+     */
+    runWithPayment(slug: string, input: Record<string, unknown>, paymentHeader?: string, acceptNetworks?: Array<"solana" | "base" | "robinhood">): Promise<unknown>;
+}
+
+export { type Attestation, type AttestationProof, type CapacityResponse, type ChatChoice, type ChatCompletionRequest, type ChatCompletionResponse, type ChatContentPart, type ChatMessage, DEFAULT_BASE_URL, type DeployProcessorInput, type EmbeddingDatum, type EmbeddingRequest, type EmbeddingResponse, GridClient, type GridClientOptions, type JobResponse, type JobResult, type JobSubmission, type ModelInfo, type ModelPricing, PROCESSORS_BASE_URL, type PricingInfo, type ProcessorDeployResult, type ProcessorEarnings, type ProcessorLimits, type ProcessorListResponse, type ProcessorManifest, type ProcessorPayout, type ProcessorRun, type ProcessorRunsResponse, type ProcessorSecretDeclaration, type ProcessorSummary, type ProcessorWebhookRegistration, ProcessorsClient, type ProcessorsClientOptions, type ReserveResponse, SGLAPIError, SGLAuthError, SGLConnectionError, SGLError, SGLNotFoundError, type TeeCapacity, VAULT_URL, type VaultAad, type VaultAgent, VaultClient, type VaultClientOptions, type VaultSnapshot, type VaultUsage, type WalletAuth, decryptEnvelope, encryptEnvelope, parseAadFromKey };