@escro/plugin-eliza 0.0.0-stage → 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,478 @@
+import { Escro, EscrowAccount, PredicateCheck, Delivery, PredicateContext, Acceptance, CreateEscrowParams, WorkerCandidate, ServedWalletReputation } from '@escro/sdk';
+export { ServedWalletReputation, WorkerCandidate } from '@escro/sdk';
+import { Keypair } from '@solana/web3.js';
+import { z } from 'zod';
+
+/**
+ * Minimal vendored type surface for `@elizaos/core`.
+ *
+ * `@elizaos/core` (v1.7.x) is provided by the host elizaOS runtime at load time;
+ * this plugin imports ZERO runtime values from it. It is intentionally NOT declared
+ * as a dependency or peerDependency here: this monorepo runs pnpm with
+ * auto-install-peers enabled (a root-level setting this package cannot scope), so a
+ * declared peer is materialized into the workspace - dragging core's heavy runtime
+ * tree (langchain, pdfjs-dist, handlebars, and a zod v4 that clashes with this
+ * repo's zod v3) in for types that are erased at build time. Instead we vendor the
+ * narrow subset of core's public interfaces that `commission_task` implements
+ * against. Ideal end state (owner: root workspace, not this lane): re-add the
+ * peerDependency once `pnpm.peerDependencyRules.ignoreMissing` lists it.
+ *
+ * Every interface below is a faithful, structurally-typed SUBSET copied from the
+ * published declarations of:
+ *
+ *   @elizaos/core@1.7.2  dist/types/{primitives,components,plugin,runtime}.d.ts
+ *   (fetched from the npm registry 2026-08-10)
+ *
+ * These are CONSUME-only views (the plugin receives an `IAgentRuntime`/`Memory`
+ * from the host; it never constructs or fully implements them). A view of a value the
+ * host passes in carries an index signature only where core's declaration does
+ * (`Content`, `State`): a core interface without one does not assign to a view that
+ * has one. The only intentional narrowing is
+ * `Handler`'s return type (`Promise<ActionResult>` - this plugin always returns a
+ * result), which stays assignable to core's wider `Promise<ActionResult | void |
+ * undefined>`. If a future `@elizaos/core` major changes these shapes, re-verify
+ * against the published `.d.ts` and update this file.
+ */
+/** @elizaos/core dist/types/primitives.d.ts - `UUID`. */
+type UUID = `${string}-${string}-${string}-${string}-${string}`;
+/** @elizaos/core dist/types/primitives.d.ts - `Content` (subset). */
+interface Content {
+    /** The agent's internal thought process. */
+    thought?: string;
+    /** The main text content visible to users. */
+    text?: string;
+    /** Actions to be performed. */
+    actions?: string[];
+    /** Source/origin of the content. */
+    source?: string;
+    /** Additional dynamic properties (core's own extension point). */
+    [key: string]: unknown;
+}
+/**
+ * @elizaos/core dist/types/memory.d.ts - `Memory` (subset). The plugin reads `id` and `content`;
+ * `entityId` is typed for an operator's `authorizeChatInput` and read by the plugin nowhere.
+ */
+interface Memory {
+    id?: UUID;
+    entityId?: UUID;
+    content: Content;
+}
+/** @elizaos/core dist/types/state.d.ts - `State` (subset). */
+interface State {
+    values: Record<string, unknown>;
+    data: Record<string, unknown>;
+    text: string;
+    [key: string]: unknown;
+}
+/** @elizaos/core dist/types/components.d.ts - `ActionResult` (subset). */
+interface ActionResult {
+    /** Whether the action succeeded. */
+    success: boolean;
+    /** Human-readable description of the result. */
+    text?: string;
+    /** Values to merge into the runtime state. */
+    values?: Record<string, unknown>;
+    /** Action-specific result payload. */
+    data?: Record<string, unknown>;
+    /** Error information if the action failed. */
+    error?: string | Error;
+}
+/** @elizaos/core dist/types/components.d.ts - `ActionExample`. */
+interface ActionExample {
+    /** Name of the participant (user or agent). */
+    name: string;
+    /** Message content. */
+    content: Content;
+}
+/** @elizaos/core dist/types/components.d.ts - `HandlerCallback`. */
+type HandlerCallback = (response: Content) => Promise<Memory[]>;
+/**
+ * @elizaos/core dist/types/components.d.ts - `HandlerOptions` (subset).
+ * The plugin does not read multi-step plan context, so this is left opaque.
+ */
+type HandlerOptions = Record<string, unknown>;
+/**
+ * Minimal logger surface exposed by `IAgentRuntime.logger`
+ * (@elizaos/core dist/logger - Logger). The plugin uses only these levels.
+ * Method signatures, not function-typed properties: core's `LogFn` takes a narrower first
+ * parameter, and only a method is compared bivariantly under `strictFunctionTypes`, so a
+ * plugin typed against this view still assigns to core's `Plugin`.
+ */
+interface ElizaLogger {
+    info(...args: unknown[]): void;
+    warn(...args: unknown[]): void;
+    error(...args: unknown[]): void;
+    debug(...args: unknown[]): void;
+}
+/**
+ * @elizaos/core dist/types/runtime.d.ts - `IAgentRuntime` (consume-only subset).
+ * The real interface extends `IDatabaseAdapter` and is large; this plugin reads
+ * ONLY `getSetting` (and optionally `logger`). No index signature: core declares
+ * none, so a real runtime is assignable to this view only without one.
+ */
+interface IAgentRuntime {
+    /** Wider than the core declaration: a runtime may answer `undefined` for an unset key. */
+    getSetting(key: string): string | boolean | number | null | undefined;
+    logger?: ElizaLogger;
+    agentId?: UUID;
+}
+/** @elizaos/core dist/types/components.d.ts - `Validator`. */
+type Validator = (runtime: IAgentRuntime, message: Memory, state?: State) => Promise<boolean>;
+/**
+ * @elizaos/core dist/types/components.d.ts - `Handler`.
+ * Return narrowed to `Promise<ActionResult>` (this plugin always returns a
+ * result); assignable to core's `Promise<ActionResult | void | undefined>`.
+ */
+type Handler = (runtime: IAgentRuntime, message: Memory, state?: State, options?: HandlerOptions, callback?: HandlerCallback, responses?: Memory[]) => Promise<ActionResult>;
+/** @elizaos/core dist/types/components.d.ts - `Action` (subset). */
+interface Action {
+    name: string;
+    description: string;
+    similes?: string[];
+    examples?: ActionExample[][];
+    validate: Validator;
+    handler: Handler;
+    [key: string]: unknown;
+}
+/** @elizaos/core dist/types/plugin.d.ts - `Plugin` (subset). */
+interface Plugin {
+    name: string;
+    description: string;
+    actions?: Action[];
+    [key: string]: unknown;
+}
+
+type SolanaCluster = "devnet" | "mainnet";
+
+/**
+ * The SDK methods the plugin uses, all as the buyer: it commissions, funds a 402 on the escrow
+ * rail, reads the directory, EscroRep and an escrow, and settles only through the operator's own
+ * predicate. It never judges a deliverable.
+ */
+type EscroClient = Pick<Escro, "createEscrow" | "pay" | "getEscrow" | "releaseWithPredicate" | "raiseDispute" | "findWorkers" | "listReputations">;
+/** Resolved connection settings for the Escro SDK client. */
+interface EscroClientConfig {
+    cluster: SolanaCluster;
+    rpcUrl: string;
+    apiUrl: string;
+}
+declare function resolveClientConfig(runtime: IAgentRuntime): EscroClientConfig;
+declare function loadWalletFromRuntime(runtime: IAgentRuntime): Keypair;
+declare function createEscroClientFromRuntime(runtime: IAgentRuntime): EscroClient;
+
+/** Action name exposed to the elizaOS runtime. */
+declare const REVIEW_DELIVERY = "REVIEW_DELIVERY";
+/**
+ * The operator's decision input for one delivery: the expectation and the bytes are its own. The
+ * record's job is the action's to bind (the reviewed escrow on the runtime's cluster), never the hook's.
+ */
+interface PredicateReview {
+    check: Omit<PredicateCheck, "job">;
+    delivery: Delivery;
+    context?: PredicateContext;
+    onFail?: "hold" | "dispute";
+}
+/** Answers null to make no decision: nothing is released and the escrow stays held. */
+type ReviewHook = (escrow: EscrowAccount) => Promise<PredicateReview | null>;
+interface ReviewDeliveryDeps {
+    createClient: (runtime: IAgentRuntime) => EscroClient;
+    review?: ReviewHook;
+}
+/**
+ * Build the `REVIEW_DELIVERY` action. The buyer is the judge: the check and the delivered bytes come
+ * only from the operator's hook, and a chat message can name nothing but the escrow, which is why a
+ * fenced block needs no consent here.
+ */
+declare function makeReviewDeliveryAction(deps?: Partial<ReviewDeliveryDeps>): Action;
+/** The default `REVIEW_DELIVERY` action: no hook, so it refuses every delivery. */
+declare const reviewDeliveryAction: Action;
+
+/** Decides whether a chat message may supply fund-moving input as text. */
+type ChatInputAuthorizer = (message: Memory) => boolean | Promise<boolean>;
+declare const CHAT_INPUT_SETTING = "ESCRO_CHAT_INPUT_CONSENT";
+declare const CHAT_INPUT_RISK_ACKNOWLEDGED = "anyone who can message this agent can spend its wallet";
+
+/** What only the operator may decide; a chat message can set none of these. */
+interface EscroPluginOptions {
+    review?: ReviewHook;
+    admitAcceptance?: (acceptance: Acceptance) => boolean;
+    authorizeChatInput?: ChatInputAuthorizer;
+}
+/**
+ * The plugin with the operator's decisions wired in. Without a `review` hook `REVIEW_DELIVERY`
+ * refuses, so settlement exists only for an operator who registers this form.
+ */
+declare function createEscroPlugin(options?: EscroPluginOptions): Plugin;
+/**
+ * The plugin a character loads by name: it commissions and funds 402s once an operator admits chat
+ * input, and has no review hook, so it can never release. The agent's operator remains the judge.
+ */
+declare const escroPlugin: Plugin;
+
+/** Injectable dependencies for the commission action (mockable in tests). */
+interface CommissionTaskDeps {
+    /** Build the Escro client for a given runtime. Defaults to the settings-based factory. */
+    createClient: (runtime: IAgentRuntime) => EscroClient;
+    /** Decides whether a commission read from chat text may spend; see `chatInputGate`. */
+    authorizeChatInput?: ChatInputAuthorizer;
+}
+/** Action name exposed to the elizaOS runtime. */
+declare const COMMISSION_TASK = "COMMISSION_TASK";
+/**
+ * Build the `commission_task` action, wrapping the Escro SDK's `createEscrow`.
+ * The client factory is injectable so tests never touch Solana.
+ *
+ * This action is a thin wrapper: it locks funds against an assigned worker and
+ * reports the escrow. It makes NO judgment about deliverable quality - the agent
+ * (Buyer) reviews and releases, and Escro defaults to refund if nothing arrives.
+ */
+declare function makeCommissionTaskAction(deps?: Partial<CommissionTaskDeps>): Action;
+/** The default `commission_task` action using the settings-based client factory. */
+declare const commissionTaskAction: Action;
+
+/** Action name exposed to the elizaOS runtime. */
+declare const PAY_402 = "PAY_402";
+/** Injectable dependencies for the 402 action. */
+interface Pay402Deps {
+    /**
+     * The client that pays. The action cannot read an injected client's cluster, so with
+     * `ESCRO_CLUSTER` unset it holds an injected client to mainnet's host rule and pays only mainnet
+     * entries; set `ESCRO_CLUSTER=devnet` for devnet's.
+     */
+    createClient: (runtime: IAgentRuntime) => EscroClient;
+    /** The operator's decision on an `acceptance` a 402 carries; only ever from plugin options. */
+    admitAcceptance?: (acceptance: Acceptance) => boolean;
+    authorizeChatInput?: ChatInputAuthorizer;
+    now?: () => number;
+}
+/** Build the `PAY_402` action: funds a worker's 402 on the escrow rail through the SDK's `pay`. */
+declare function makePay402Action(deps?: Partial<Pay402Deps>): Action;
+/** The default `PAY_402` action: no `admitAcceptance`, so an acceptance-bearing 402 is refused. */
+declare const pay402Action: Action;
+
+/** Default relative deadline (seconds) when the caller supplies no deadline. */
+declare const DEFAULT_DEADLINE_SECONDS = 3600;
+/**
+ * Structured input for the `commission_task` action. This is the shape the
+ * agent/runtime supplies; it maps 1:1 onto the SDK's `CreateEscrowParams`.
+ *
+ * `amountUsdc` is micro-USDC (1 USDC = 1_000_000), matching the SDK field
+ * exactly - the plugin performs no unit conversion (it is a thin SDK wrapper).
+ */
+declare const commissionInputSchema: z.ZodObject<{
+    /** Base-58 public key of the worker being commissioned. */
+    worker: z.ZodString;
+    /** Worker's net payment in micro-USDC. Minimum enforced from shared config. */
+    amountUsdc: z.ZodNumber;
+    /** Absolute Unix deadline (seconds). Takes precedence over `deadlineSeconds`. */
+    deadlineUnix: z.ZodOptional<z.ZodNumber>;
+    /** Relative deadline in seconds from now. Used when `deadlineUnix` is absent. */
+    deadlineSeconds: z.ZodOptional<z.ZodNumber>;
+    task: z.ZodObject<{
+        description: z.ZodString;
+        taskType: z.ZodOptional<z.ZodEnum<["code_generation", "code_review", "data_analysis", "content_writing", "translation", "summarization", "question_answering", "image_generation", "audio_transcription", "custom"]>>;
+        acceptanceCriteria: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            description: z.ZodString;
+            weight: z.ZodOptional<z.ZodNumber>;
+            required: z.ZodOptional<z.ZodBoolean>;
+        }, "strict", z.ZodTypeAny, {
+            description: string;
+            id: string;
+            weight?: number | undefined;
+            required?: boolean | undefined;
+        }, {
+            description: string;
+            id: string;
+            weight?: number | undefined;
+            required?: boolean | undefined;
+        }>, "many">;
+        deliverableFormat: z.ZodOptional<z.ZodObject<{
+            type: z.ZodEnum<["text", "json", "file", "url", "code"]>;
+            schema: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+            mimeType: z.ZodOptional<z.ZodString>;
+            maxSizeBytes: z.ZodOptional<z.ZodNumber>;
+            language: z.ZodOptional<z.ZodString>;
+        }, "strict", z.ZodTypeAny, {
+            type: "code" | "text" | "json" | "file" | "url";
+            schema?: Record<string, unknown> | undefined;
+            mimeType?: string | undefined;
+            maxSizeBytes?: number | undefined;
+            language?: string | undefined;
+        }, {
+            type: "code" | "text" | "json" | "file" | "url";
+            schema?: Record<string, unknown> | undefined;
+            mimeType?: string | undefined;
+            maxSizeBytes?: number | undefined;
+            language?: string | undefined;
+        }>>;
+        version: z.ZodOptional<z.ZodString>;
+        metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, "strict", z.ZodTypeAny, {
+        description: string;
+        acceptanceCriteria: {
+            description: string;
+            id: string;
+            weight?: number | undefined;
+            required?: boolean | undefined;
+        }[];
+        taskType?: "code_generation" | "code_review" | "data_analysis" | "content_writing" | "translation" | "summarization" | "question_answering" | "image_generation" | "audio_transcription" | "custom" | undefined;
+        deliverableFormat?: {
+            type: "code" | "text" | "json" | "file" | "url";
+            schema?: Record<string, unknown> | undefined;
+            mimeType?: string | undefined;
+            maxSizeBytes?: number | undefined;
+            language?: string | undefined;
+        } | undefined;
+        version?: string | undefined;
+        metadata?: Record<string, unknown> | undefined;
+    }, {
+        description: string;
+        acceptanceCriteria: {
+            description: string;
+            id: string;
+            weight?: number | undefined;
+            required?: boolean | undefined;
+        }[];
+        taskType?: "code_generation" | "code_review" | "data_analysis" | "content_writing" | "translation" | "summarization" | "question_answering" | "image_generation" | "audio_transcription" | "custom" | undefined;
+        deliverableFormat?: {
+            type: "code" | "text" | "json" | "file" | "url";
+            schema?: Record<string, unknown> | undefined;
+            mimeType?: string | undefined;
+            maxSizeBytes?: number | undefined;
+            language?: string | undefined;
+        } | undefined;
+        version?: string | undefined;
+        metadata?: Record<string, unknown> | undefined;
+    }>;
+    /** `false` sends the create and returns without waiting for its confirmation. */
+    wait: z.ZodOptional<z.ZodBoolean>;
+}, "strict", z.ZodTypeAny, {
+    worker: string;
+    amountUsdc: number;
+    task: {
+        description: string;
+        acceptanceCriteria: {
+            description: string;
+            id: string;
+            weight?: number | undefined;
+            required?: boolean | undefined;
+        }[];
+        taskType?: "code_generation" | "code_review" | "data_analysis" | "content_writing" | "translation" | "summarization" | "question_answering" | "image_generation" | "audio_transcription" | "custom" | undefined;
+        deliverableFormat?: {
+            type: "code" | "text" | "json" | "file" | "url";
+            schema?: Record<string, unknown> | undefined;
+            mimeType?: string | undefined;
+            maxSizeBytes?: number | undefined;
+            language?: string | undefined;
+        } | undefined;
+        version?: string | undefined;
+        metadata?: Record<string, unknown> | undefined;
+    };
+    deadlineUnix?: number | undefined;
+    deadlineSeconds?: number | undefined;
+    wait?: boolean | undefined;
+}, {
+    worker: string;
+    amountUsdc: number;
+    task: {
+        description: string;
+        acceptanceCriteria: {
+            description: string;
+            id: string;
+            weight?: number | undefined;
+            required?: boolean | undefined;
+        }[];
+        taskType?: "code_generation" | "code_review" | "data_analysis" | "content_writing" | "translation" | "summarization" | "question_answering" | "image_generation" | "audio_transcription" | "custom" | undefined;
+        deliverableFormat?: {
+            type: "code" | "text" | "json" | "file" | "url";
+            schema?: Record<string, unknown> | undefined;
+            mimeType?: string | undefined;
+            maxSizeBytes?: number | undefined;
+            language?: string | undefined;
+        } | undefined;
+        version?: string | undefined;
+        metadata?: Record<string, unknown> | undefined;
+    };
+    deadlineUnix?: number | undefined;
+    deadlineSeconds?: number | undefined;
+    wait?: boolean | undefined;
+}>;
+type CommissionInput = z.infer<typeof commissionInputSchema>;
+/**
+ * Validate and parse raw commission parameters into a {@link CommissionInput}.
+ * Throws {@link CommissionInputError} with a readable message on failure.
+ */
+declare function parseCommissionInput(raw: unknown): CommissionInput;
+/**
+ * Map a validated {@link CommissionInput} to the SDK's `CreateEscrowParams`,
+ * resolving the deadline against `nowUnix`. Throws {@link CommissionInputError}
+ * if the resolved deadline is not in the future.
+ */
+declare function buildCreateEscrowParams(input: CommissionInput, nowUnix?: number): CreateEscrowParams;
+
+/**
+ * A directory candidate joined to its EscroRep RAW components. The
+ * `descriptor`/`signatureValid` pair is unchanged from {@link WorkerCandidate}
+ * (a self-reported CLAIM plus an authorship check); `reputation` is that wallet's
+ * verified on-chain history, or `null` when the wallet has no Escro history yet.
+ * The claim and the verified history are kept as separate fields, never merged
+ * into one score.
+ */
+interface WorkerWithReputation extends WorkerCandidate {
+    /** The wallet's raw EscroRep components, or `null` when it has no on-chain Escro history. */
+    reputation: ServedWalletReputation | null;
+}
+/**
+ * A CALLER-SUPPLIED weighting over a candidate's raw components. Escro ships no
+ * default weight (Escro-shipped code never ranks) - the
+ * caller's own bot owns the policy. A higher number wins.
+ */
+type WorkerWeight = (worker: WorkerWithReputation) => number;
+/**
+ * List directory workers and join each to its EscroRep raw components. The
+ * reputation join uses ONE bulk export fetch (`Escro.listReputations`) regardless
+ * of candidate count - the per-wallet endpoint shares a 10/min public-metrics
+ * budget, so a per-candidate fan-out would rate-limit itself. Registry order is
+ * preserved; no ranking or reordering happens here. Weighting/selection is the
+ * caller's ({@link selectWorker}).
+ */
+declare function findWorkersWithReputation(client: EscroClient, params?: {
+    capability?: string;
+}): Promise<WorkerWithReputation[]>;
+/**
+ * Select the highest-weighted worker under the caller's `weight`. Ties preserve
+ * input (registry) order - the strict `>` never lets a later, equal candidate
+ * displace an earlier one, so Escro imposes no tie-break opinion of its own. The
+ * raw components are handed to `weight` untransformed (no normalization or
+ * pre-scoring). Returns `undefined` only for an empty candidate set.
+ */
+declare function selectWorker(workers: WorkerWithReputation[], weight: WorkerWeight): WorkerWithReputation | undefined;
+
+/** Base error for all @escro/plugin-eliza failures. */
+declare class EscroPluginError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * Thrown when the commission parameters supplied by the agent/runtime are
+ * missing or malformed (fails validation before any transaction is built).
+ */
+declare class CommissionInputError extends EscroPluginError {
+}
+/**
+ * Thrown when the plugin's runtime settings are missing or invalid
+ * (e.g. no wallet secret). Never carries secret material in its message.
+ */
+declare class EscroConfigError extends EscroPluginError {
+}
+/** Thrown when an action's input is refused before it is validated against the action's schema. */
+declare class ActionInputError extends EscroPluginError {
+}
+/** Thrown when text in a chat message supplies fund-moving input the operator has not admitted. */
+declare class ChatInputRefusedError extends EscroPluginError {
+}
+
+export { ActionInputError, CHAT_INPUT_RISK_ACKNOWLEDGED, CHAT_INPUT_SETTING, COMMISSION_TASK, ChatInputRefusedError, CommissionInputError, DEFAULT_DEADLINE_SECONDS, EscroConfigError, EscroPluginError, PAY_402, REVIEW_DELIVERY, buildCreateEscrowParams, commissionInputSchema, commissionTaskAction, createEscroClientFromRuntime, createEscroPlugin, escroPlugin as default, escroPlugin, findWorkersWithReputation, loadWalletFromRuntime, makeCommissionTaskAction, makePay402Action, makeReviewDeliveryAction, parseCommissionInput, pay402Action, resolveClientConfig, reviewDeliveryAction, selectWorker };
+export type { Action, ActionResult, ChatInputAuthorizer, CommissionInput, CommissionTaskDeps, Content, EscroClient, EscroClientConfig, EscroPluginOptions, HandlerCallback, IAgentRuntime, Memory, Pay402Deps, Plugin, PredicateReview, ReviewDeliveryDeps, ReviewHook, WorkerWeight, WorkerWithReputation };