@agrentingai/paperclip-adapter 0.2.2 → 0.4.0

package/dist/server/index.d.cts

@@ -1,5 +1,21 @@
+import * as _paperclipai_adapter_utils from '@paperclipai/adapter-utils';
+import { AdapterExecutionContext, AdapterExecutionResult, AdapterEnvironmentTestContext, AdapterEnvironmentTestResult, AdapterConfigSchema, AdapterSessionCodec } from '@paperclipai/adapter-utils';
 import { IncomingHttpHeaders } from 'http';
 
+declare const type = "agrenting";
+declare const label = "Agrenting";
+declare const agentConfigurationDoc = "# agrenting agent configuration\n\nAdapter: agrenting\n\nUse when:\n- A Paperclip agent should delegate each heartbeat to a remote agent hired from Agrenting.\n- The operator has an Agrenting user API token and sufficient ledger balance.\n\nCore fields:\n- agrentingUrl (required): Agrenting base URL, normally https://agrenting.com\n- apiKey (required, secret): Agrenting user API token (ap_...)\n- agentDid (required): DID of the marketplace agent to hire\n- capabilityRequested (optional): defaults to the first capability on the agent profile\n- price (optional): defaults to the agent's current base price\n- timeoutSec (optional): maximum time to poll a hiring, default 600\n- pollIntervalMs (optional): hiring status poll interval, default 2000\n- deliveryMode (optional): output by default; push requires repository access\n- repoUrl (optional): repository URL used only when deliveryMode is push\n\nRecommended API-key scopes:\n- agents:discover, agents:read, hire:create, hirings:read, hirings:cancel\n- add balance:read and artifacts:read when sharing the key with Apps/Claude\n- deposits:create and account:read/account:write are optional elevated scopes\n- set max_price_per_hire on the key to cap paid actions\n\nExecution:\n- Each Paperclip run creates one canonical Agrenting hiring.\n- The Paperclip run id is sent as client_idempotency_key so safe retries deduplicate.\n- Paperclip polls the hiring until it completes, fails, is cancelled, or times out.\n- Push delivery can use a repository URL from Paperclip and an Agrenting-stored\n  GitHub token. The adapter never stores a repository token in agent config.\n";
+/** Canonical Paperclip ServerAdapterModule execution entry point. */
+declare function executePaperclip(ctx: AdapterExecutionContext): Promise<AdapterExecutionResult>;
+/** Canonical structured environment test used by Paperclip. */
+declare function testPaperclipEnvironment(ctx: AdapterEnvironmentTestContext): Promise<AdapterEnvironmentTestResult>;
+declare function getPaperclipConfigSchema(): AdapterConfigSchema;
+type CompatibilitySessionCodec = AdapterSessionCodec & {
+    encode(state: unknown): string;
+    decode(blob: string | null | undefined): unknown;
+};
+declare const paperclipSessionCodec: CompatibilitySessionCodec;
+
 /**
  * Agrenting adapter configuration schema.
  * These fields are rendered in the Paperclip UI when configuring an Agrenting agent.
@@ -19,6 +35,16 @@ interface AgrentingAdapterConfig {
     pricingModel?: "fixed" | "per-token" | "subscription";
     /** Task timeout in seconds (default: 600) */
     timeoutSec?: number;
+    /** Default capability used by the canonical Paperclip hiring adapter. */
+    capabilityRequested?: string;
+    /** Price offered for each hiring. Defaults to the selected agent's base price. */
+    price?: string;
+    /** Poll interval for the hiring lifecycle in milliseconds (default: 2000). */
+    pollIntervalMs?: number;
+    /** Agrenting delivery mode for canonical Paperclip runs. */
+    deliveryMode?: "output" | "push";
+    /** Repository URL used for push delivery. */
+    repoUrl?: string;
     /** How instructions are handled: "managed" (uploaded to Agrenting) or "inline" (passed in task context) */
     instructionsBundleMode?: "managed" | "inline";
 }
@@ -113,7 +139,7 @@ interface AgentProfile {
     name: string;
     description?: string;
     capabilities: string[];
-    pricing_tiers: Array<{
+    pricing_tiers?: Array<{
         model: string;
         price_per_task?: string;
         price_per_token?: string;
@@ -125,39 +151,87 @@ interface AgentProfile {
         average_rating: number;
         total_reviews: number;
     };
-    reputation_score?: number;
+    reputation_score?: number | string;
     total_earnings?: string;
     verified?: boolean;
     response_time_avg?: number;
-    availability_status: "available" | "busy" | "offline";
+    availability_status?: "available" | "busy" | "offline";
+    availability?: string;
+    status?: string;
     success_rate?: number;
     total_tasks_completed?: number;
     metadata?: Record<string, unknown>;
     avatar_url?: string;
-    created_at: string;
+    created_at?: string;
 }
 /** Result of hiring an agent via POST /api/v1/agents/:did/hire */
 interface HireAgentResult {
-    agent_did: string;
-    adapter_config: {
-        agrentingUrl: string;
+    hiring: Hiring;
+    config: {
         agentDid: string;
         pricingModel: string;
-        webhookSecret?: string;
+        basePrice: string;
+        capabilities: string[];
+        hiringId: string;
+        metadata?: Record<string, unknown>;
     };
-    status: "hired" | "pending_approval";
-    hired_at: string;
 }
-/** Hiring record returned by POST /api/v1/agents/:did/hire */
+/** Canonical payload required by POST /api/v1/agents/:did/hire. */
+interface HireAgentOptions {
+    taskDescription: string;
+    capabilityRequested: string;
+    price: string | number;
+    repoUrl?: string;
+    repoAccessToken?: string;
+    deliveryMode?: "output" | "push";
+    clientIdempotencyKey?: string;
+    taskInput?: Record<string, unknown>;
+    clientMessage?: string;
+}
+type HiringStatus = "pending_payment" | "paid" | "queued" | "in_progress" | "completed" | "failed" | "cancelled" | "disputed" | "refunded" | (string & {});
+/** Hiring record returned by the canonical Agrenting hiring REST API. */
 interface Hiring {
     id: string;
-    agent_id: string;
-    agent_did: string;
-    client_agent_id: string;
-    status: string;
+    status: HiringStatus;
+    final?: boolean;
+    agent_id?: string;
+    agent_did?: string;
+    client_agent_id?: string;
+    agent?: {
+        id: string;
+        did: string;
+        name: string;
+        category?: string;
+        capabilities?: string[];
+        base_price?: string;
+        reputation_score?: string;
+        status?: string;
+    } | null;
+    price?: string | null;
+    capability_requested?: string;
+    task_description?: string;
+    delivery_mode?: "output" | "push" | string;
     pricing_model?: string;
-    created_at: string;
-    updated_at: string;
+    task_input?: Record<string, unknown>;
+    task_output?: Record<string, unknown> | string | null;
+    failed_reason?: string | null;
+    repo_url?: string | null;
+    messages?: HiringMessage[];
+    artifacts?: Array<Record<string, unknown>>;
+    started_at?: string | null;
+    completed_at?: string | null;
+    failed_at?: string | null;
+    deadline_at?: string | null;
+    created_at?: string;
+    updated_at?: string;
+}
+/** Paginated response returned by GET /api/v1/hirings. */
+interface HiringListResult {
+    hirings: Hiring[];
+    total: number;
+    page: number;
+    per_page: number;
+    total_pages: number;
 }
 /** Options for sending a message to a task */
 interface SendMessageOptions {
@@ -193,10 +267,12 @@ interface ReassignTaskResult {
 /** Hiring message for communication with hired agent */
 interface HiringMessage {
     id: string;
-    hiring_id: string;
-    sender_agent_id: string;
+    hiring_id?: string;
+    sender_agent_id?: string;
+    sender_type?: string;
     content: string;
-    created_at: string;
+    created_at?: string;
+    inserted_at?: string;
     sender_name?: string;
 }
 /** Capability returned by GET /api/v1/capabilities */
@@ -210,6 +286,7 @@ interface Capability {
 /** Options for auto-selecting an agent */
 interface AutoSelectOptions {
     capability: string;
+    taskDescription: string;
     maxPrice?: string;
     minReputation?: number;
     sortBy?: "reputation_score" | "base_price" | "availability";
@@ -349,7 +426,7 @@ declare function cancelTask(config: AgrentingAdapterConfig, taskId: string): Pro
  * Hire an agent by DID. Returns hiring record and adapter config for auto-provisioning.
  * This is the primary entry point for the "browse marketplace, click Hire" flow.
  */
-declare function hireAgent(config: AgrentingAdapterConfig, agentDid: string): Promise<HireAgentResult>;
+declare function hireAgent(config: AgrentingAdapterConfig, agentDid: string, options: HireAgentOptions): Promise<HireAgentResult>;
 /**
  * Get full agent profile by DID.
  * Returns description, capabilities, pricing, reputation, and availability.
@@ -400,6 +477,8 @@ declare function listHirings(config: AgrentingAdapterConfig, options?: {
     limit?: number;
     offset?: number;
 }): Promise<Hiring[]>;
+/** Cancel an active hiring and release its escrow according to Agrenting policy. */
+declare function cancelHiring(config: AgrentingAdapterConfig, hiringId: string): Promise<Hiring>;
 /**
  * Auto-select mode: given a capability requirement, discover the best agent,
  * hire them, and return the adapter config for immediate use.
@@ -438,15 +517,76 @@ declare function forwardCommentToAgrenting$1(config: AgrentingAdapterConfig, tas
  * Called by the webhook handler when it receives task messages.
  */
 declare function processIncomingMessage$1(message: TaskMessage): string;
+/** Paperclip skill shape (subset of the canonical Paperclip Skill). */
+interface PaperclipSkill {
+    id: string;
+    name: string;
+    description?: string;
+}
+/**
+ * Detect a sensible default model/provider for the configured Agrenting agent.
+ * Paperclip calls this to pre-populate the adapter UI when an agent is
+ * created. Returns null if no info is available.
+ */
+declare function detectModel(config: Pick<AgrentingAdapterConfig, "agrentingUrl" | "apiKey" | "agentDid">): Promise<{
+    provider: string;
+    model: string;
+} | null>;
+/**
+ * Enumerate the configured Agrenting agent's capabilities and map them to
+ * Paperclip's Skill shape.
+ */
+declare function listSkills(config: AgrentingAdapterConfig): Promise<PaperclipSkill[]>;
+/**
+ * Reconcile the agent's current capabilities against Paperclip's local skill
+ * registry. Returns sets to add and remove.
+ */
+declare function syncSkills(config: AgrentingAdapterConfig, existing: PaperclipSkill[]): Promise<{
+    added: PaperclipSkill[];
+    removed: PaperclipSkill[];
+}>;
+/**
+ * Session codec — Paperclip uses this to serialise session state across
+ * heartbeats. Hirings carry no rich session state, so we pass JSON through.
+ */
+declare const sessionCodec: _paperclipai_adapter_utils.AdapterSessionCodec & {
+    encode(state: unknown): string;
+    decode(blob: string | null | undefined): unknown;
+};
+/**
+ * Legacy `AgentAdapter.invoke`. Forwards to {@link execute}.
+ */
+declare function invoke(config: AgrentingAdapterConfig, params: {
+    input: string;
+    capability: string;
+    instructions?: string;
+    maxPrice?: string;
+    paymentType?: string;
+}): Promise<AgrentingExecutionResult>;
+/**
+ * Legacy `AgentAdapter.status`. Returns the current run status.
+ */
+declare function status(config: AgrentingAdapterConfig, taskId: string): Promise<{
+    status: AgrentingTaskStatus;
+    progressPercent: number;
+    progressMessage?: string;
+}>;
+/**
+ * Legacy `AgentAdapter.cancel`. Cancels a running task; throws on failure
+ * so Paperclip can treat the call as a void Promise.
+ */
+declare function cancel(config: AgrentingAdapterConfig, taskId: string): Promise<void>;
 /**
  * Create the server-side adapter module.
- * This is the entry point for Paperclip's server adapter registry.
+ * Paperclip plugin loaders call this factory from the package root. The
+ * current ServerAdapterModule members are combined with explicitly named
+ * compatibility helpers for pre-0.4 consumers.
  */
 declare function createServerAdapter(): {
     name: "agrenting";
-    execute: typeof execute;
-    testEnvironment: typeof testEnvironment;
-    getConfigSchema: typeof getConfigSchema;
+    legacyExecute: typeof execute;
+    legacyTestEnvironment: typeof testEnvironment;
+    getLegacyConfigSchema: typeof getConfigSchema;
     startWebhookListener: typeof startWebhookListener;
     stopWebhookListener: typeof stopWebhookListener;
     registerWebhook: typeof registerWebhook;
@@ -464,6 +604,7 @@ declare function createServerAdapter(): {
     sendMessageToHiring: typeof sendMessageToHiring;
     getHiringMessages: typeof getHiringMessages;
     retryHiring: typeof retryHiring;
+    cancelHiring: typeof cancelHiring;
     getHiring: typeof getHiring;
     listHirings: typeof listHirings;
     autoSelectAgent: typeof autoSelectAgent;
@@ -474,6 +615,21 @@ declare function createServerAdapter(): {
     getTransactions: typeof getTransactions;
     deposit: typeof deposit;
     withdraw: typeof withdraw;
+    invoke: typeof invoke;
+    status: typeof status;
+    cancel: typeof cancel;
+    legacyDetectModel: typeof detectModel;
+    legacyListSkills: typeof listSkills;
+    legacySyncSkills: typeof syncSkills;
+    type: string;
+    execute: typeof executePaperclip;
+    testEnvironment: typeof testPaperclipEnvironment;
+    sessionCodec: _paperclipai_adapter_utils.AdapterSessionCodec & {
+        encode(state: unknown): string;
+        decode(blob: string | null | undefined): unknown;
+    };
+    getConfigSchema: typeof getPaperclipConfigSchema;
+    agentConfigurationDoc: string;
 };
 
 /**
@@ -631,12 +787,10 @@ declare class AgrentingClient {
      * Returns capabilities, pricing tiers, reviews, and availability.
      */
     getAgentProfile(agentDid: string): Promise<AgentProfile>;
-    /** Hire/bind an agent to your account.
-     * Returns adapter config so Paperclip can auto-provision the agent.
+    /** Create a paid hiring for an agent.
+     * Agrenting requires a concrete task, capability, and offered price.
      */
-    hireAgent(agentDid: string, options?: {
-        pricingModel?: string;
-    }): Promise<HireAgentResult>;
+    hireAgent(agentDid: string, options: HireAgentOptions): Promise<HireAgentResult>;
     /** Send a message to a running task (mid-task instructions, feedback, or questions).
      * Enables bidirectional communication between the Paperclip user and the remote agent.
      */
@@ -658,7 +812,7 @@ declare class AgrentingClient {
      */
     sendMessageToHiring(hiringId: string, content: string): Promise<HiringMessage>;
     /** Get messages for a hiring.
-     * GET /api/v1/hirings/:id/messages
+     * The canonical API includes recent messages in GET /api/v1/hirings/:id.
      */
     getHiringMessages(hiringId: string): Promise<HiringMessage[]>;
     /** Retry a failed hiring.
@@ -669,6 +823,10 @@ declare class AgrentingClient {
      * GET /api/v1/hirings/:id
      */
     getHiring(hiringId: string): Promise<Hiring>;
+    /** Cancel an active hiring.
+     * POST /api/v1/hirings/:id/cancel
+     */
+    cancelHiring(hiringId: string): Promise<Hiring>;
     /** List hirings for the authenticated agent.
      * GET /api/v1/hirings
      */
@@ -892,4 +1050,31 @@ declare function formatInsufficientBalanceComment(balanceInfo: BalanceInfo): str
  */
 declare function verifyWebhookSignature(rawBody: string, signature: string, secret: string): Promise<boolean>;
 
-export { type AgentInfo, type AgentProfile, type AgrentingAdapterConfig, AgrentingClient, type AgrentingExecutionResult, type AgrentingTask, type AgrentingTaskStatus, type AgrentingWebhookPayload, type AutoSelectOptions, type BalanceCheckOptions, type BalanceInfo, type Capability, type CreateTaskPaymentOptions, type DiscoverAgentsOptions, type HireAgentResult, type Hiring, type HiringMessage, MAX_POLLS, POLL_INTERVALS_MS, type PaperclipApiClient, type PaymentInfo, type PollOptions, type PollResult, type ReassignTaskResult, type RetryHiringOptions, type SendMessageOptions, type SendMessageResult, type TaskMessage, type TransactionInfo, type WebhookHandlerOptions, autoSelectAgent, canSubmitTask, checkBalance, createServerAdapter, createWebhookHandler, deregisterWebhook, executeWithRetry, formatAgentResponse, formatInsufficientBalanceComment, formatLowBalanceComment, forwardCommentToAgrenting, getActiveTaskMappings, getAgentProfile, getBackoffMs, getHiring, getHiringMessages, getTaskMessages, getWebhookGracePeriodMs, hireAgent, listCapabilities, listHirings, pollTaskUntilDone, processIncomingMessage, reassignTask, registerTaskMapping, registerWebhook, retryHiring, sendMessageToHiring, sendMessageToTask, unregisterTaskMapping, verifyWebhookSignature };
+declare const agrentingAppGalleryEntry: {
+    key: string;
+    name: string;
+    logoUrl: string;
+    tagline: string;
+    description: string;
+    authKind: "api_key";
+    transportTemplate: {
+        transport: "remote_http";
+        url: string;
+    };
+    credentialFields: {
+        label: string;
+        configPath: string;
+        helpUrl: string;
+        required: true;
+        placement: "header";
+        key: string;
+        prefix: string;
+    }[];
+    recommendedDefaults: {
+        access: string;
+        askFirstRiskLevels: string[];
+    };
+    urlPatterns: string[];
+};
+
+export { type AgentInfo, type AgentProfile, type AgrentingAdapterConfig, AgrentingClient, type AgrentingExecutionResult, type AgrentingTask, type AgrentingTaskStatus, type AgrentingWebhookPayload, type AutoSelectOptions, type BalanceCheckOptions, type BalanceInfo, type Capability, type CreateTaskPaymentOptions, type DiscoverAgentsOptions, type HireAgentOptions, type HireAgentResult, type Hiring, type HiringListResult, type HiringMessage, type HiringStatus, MAX_POLLS, POLL_INTERVALS_MS, type PaperclipApiClient, type PaperclipSkill, type PaymentInfo, type PollOptions, type PollResult, type ReassignTaskResult, type RetryHiringOptions, type SendMessageOptions, type SendMessageResult, type TaskMessage, type TransactionInfo, type WebhookHandlerOptions, agentConfigurationDoc, agrentingAppGalleryEntry, autoSelectAgent, canSubmitTask, cancel, cancelHiring, cancelTask, checkBalance, createServerAdapter, createWebhookHandler, deregisterWebhook, detectModel, execute, executePaperclip, executeWithRetry, formatAgentResponse, formatInsufficientBalanceComment, formatLowBalanceComment, forwardCommentToAgrenting, getActiveTaskMappings, getAgentProfile, getBackoffMs, getConfigSchema, getHiring, getHiringMessages, getPaperclipConfigSchema, getTaskMessages, getTaskProgress, getWebhookGracePeriodMs, hireAgent, invoke, label, listCapabilities, listHirings, listSkills, paperclipSessionCodec, pollTaskUntilDone, processIncomingMessage, reassignTask, registerTaskMapping, registerWebhook, retryHiring, sendMessageToHiring, sendMessageToTask, sessionCodec, status, syncSkills, testEnvironment, testPaperclipEnvironment, type, unregisterTaskMapping, verifyWebhookSignature };