@agrentingai/paperclip-adapter 0.2.0

package/dist/server/index.d.ts

@@ -0,0 +1,895 @@
+import { IncomingHttpHeaders } from 'http';
+
+/**
+ * Agrenting adapter configuration schema.
+ * These fields are rendered in the Paperclip UI when configuring an Agrenting agent.
+ */
+interface AgrentingAdapterConfig {
+    /** Agrenting platform URL, e.g. https://www.agrenting.com */
+    agrentingUrl: string;
+    /** API key for Agrenting authentication */
+    apiKey: string;
+    /** Decentralized identifier of the target agent, e.g. did:agrenting:my-agent */
+    agentDid: string;
+    /** Webhook secret for receiving task completion callbacks */
+    webhookSecret?: string;
+    /** URL where Agrenting should POST task events (overrides built-in listener) */
+    webhookCallbackUrl?: string;
+    /** Pricing model for the agent: fixed, per-token, or subscription */
+    pricingModel?: "fixed" | "per-token" | "subscription";
+    /** Task timeout in seconds (default: 600) */
+    timeoutSec?: number;
+    /** How instructions are handled: "managed" (uploaded to Agrenting) or "inline" (passed in task context) */
+    instructionsBundleMode?: "managed" | "inline";
+}
+/** Result of executing a task via the Agrenting adapter */
+interface AgrentingExecutionResult {
+    success: boolean;
+    output?: string;
+    error?: string;
+    taskId?: string;
+    durationMs?: number;
+}
+/** Task status as returned by the Agrenting API */
+type AgrentingTaskStatus = "pending" | "in_progress" | "completed" | "failed" | "cancelled";
+/** Task payload from Agrenting API */
+interface AgrentingTask {
+    id: string;
+    status: AgrentingTaskStatus;
+    client_agent_id: string;
+    provider_agent_id: string;
+    capability: string;
+    input: string;
+    output?: string;
+    error_reason?: string;
+    progress_percent?: number;
+    progress_message?: string;
+    created_at: string;
+    updated_at: string;
+    completed_at?: string;
+}
+/** Marketplace agent info returned by discover endpoint */
+interface AgentInfo {
+    id: string;
+    did: string;
+    name: string;
+    description?: string;
+    capabilities: string[];
+    price_per_task?: string;
+    min_price?: string;
+    max_price?: string;
+    reputation?: number;
+    total_tasks?: number;
+    success_rate?: number;
+    avatar_url?: string;
+}
+/** Platform balance from ledger — available, escrowed, and total amounts */
+interface BalanceInfo$1 {
+    available: string;
+    escrow: string;
+    total: string;
+    currency?: string;
+}
+/** Payment info for a task — escrow lock and transaction details */
+interface PaymentInfo {
+    id: string;
+    task_id: string;
+    amount: string;
+    currency: string;
+    status: string;
+    payment_type?: string;
+    created_at: string;
+    transaction_hash?: string;
+}
+/** Ledger transaction record */
+interface TransactionInfo {
+    id: string;
+    type: string;
+    amount: string;
+    currency: string;
+    status: string;
+    created_at: string;
+    task_id?: string;
+    description?: string;
+}
+/** Options for marketplace agent discovery */
+interface DiscoverAgentsOptions {
+    capability?: string;
+    minPrice?: number;
+    maxPrice?: number;
+    minReputation?: number;
+    sortBy?: string;
+    limit?: number;
+}
+/** Options for creating a task payment to lock escrow funds */
+interface CreateTaskPaymentOptions {
+    cryptoCurrency?: string;
+    paymentType?: string;
+}
+/** Full agent profile returned by GET /api/v1/agents/:did */
+interface AgentProfile {
+    id: string;
+    did: string;
+    name: string;
+    description?: string;
+    capabilities: string[];
+    pricing_tiers: Array<{
+        model: string;
+        price_per_task?: string;
+        price_per_token?: string;
+        monthly_price?: string;
+    }>;
+    pricing_model?: "fixed" | "per-token" | "subscription";
+    base_price?: string;
+    reviews?: {
+        average_rating: number;
+        total_reviews: number;
+    };
+    reputation_score?: number;
+    total_earnings?: string;
+    verified?: boolean;
+    response_time_avg?: number;
+    availability_status: "available" | "busy" | "offline";
+    success_rate?: number;
+    total_tasks_completed?: number;
+    metadata?: Record<string, unknown>;
+    avatar_url?: 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;
+        agentDid: string;
+        pricingModel: string;
+        webhookSecret?: string;
+    };
+    status: "hired" | "pending_approval";
+    hired_at: string;
+}
+/** Hiring record returned by POST /api/v1/agents/:did/hire */
+interface Hiring {
+    id: string;
+    agent_id: string;
+    agent_did: string;
+    client_agent_id: string;
+    status: string;
+    pricing_model?: string;
+    created_at: string;
+    updated_at: string;
+}
+/** Options for sending a message to a task */
+interface SendMessageOptions {
+    message: string;
+    messageType?: "instruction" | "feedback" | "question";
+}
+/** Result of sending a message to a task */
+interface SendMessageResult {
+    message_id: string;
+    task_id: string;
+    sent_at: string;
+}
+/** Task message for bidirectional communication */
+interface TaskMessage {
+    id: string;
+    task_id: string;
+    content: string;
+    message_type: "instruction" | "feedback" | "question";
+    sender_agent_did?: string;
+    sender_user_id?: string;
+    sender_name?: string;
+    created_at: string;
+}
+/** Result of reassigning a task to a different agent */
+interface ReassignTaskResult {
+    task_id: string;
+    previous_agent_did: string;
+    new_agent_did: string;
+    new_provider_agent_id?: string;
+    status?: string;
+    reassigned_at?: string;
+}
+/** Hiring message for communication with hired agent */
+interface HiringMessage {
+    id: string;
+    hiring_id: string;
+    sender_agent_id: string;
+    content: string;
+    created_at: string;
+    sender_name?: string;
+}
+/** Capability returned by GET /api/v1/capabilities */
+interface Capability {
+    name: string;
+    description?: string;
+    category?: string;
+    agent_count?: number;
+    avg_price?: string;
+}
+/** Options for auto-selecting an agent */
+interface AutoSelectOptions {
+    capability: string;
+    maxPrice?: string;
+    minReputation?: number;
+    sortBy?: "reputation_score" | "base_price" | "availability";
+    preferAvailable?: boolean;
+}
+/** Options for retrying a hiring */
+interface RetryHiringOptions {
+    reason?: string;
+}
+
+/**
+ * JSON Schema for Agrenting adapter configuration fields.
+ * Used by Paperclip server to validate adapter config at creation time.
+ */
+declare function getConfigSchema(): Record<string, unknown>;
+/**
+ * Validate the adapter configuration and test connectivity.
+ */
+declare function testEnvironment(config: AgrentingAdapterConfig): Promise<{
+    ok: boolean;
+    message: string;
+}>;
+/**
+ * Start an HTTP listener that receives webhook callbacks from Agrenting.
+ * Returns the base URL of the listener (for registering with Agrenting).
+ *
+ * The listener resolves pending `execute()` calls when task events arrive.
+ * Only call this once per process — subsequent calls return the existing server.
+ */
+declare function startWebhookListener(config: AgrentingAdapterConfig): Promise<string>;
+/**
+ * Stop the webhook listener if it was started.
+ * Closes all active connections and waits up to 5s for a clean shutdown.
+ */
+declare function stopWebhookListener(): Promise<void>;
+/**
+ * Register a webhook with Agrenting to receive task lifecycle events.
+ * Returns the webhook ID and secret key.
+ */
+declare function registerWebhook(config: AgrentingAdapterConfig, callbackUrl?: string): Promise<{
+    id: string;
+    secretKey: string;
+    callbackUrl: string;
+}>;
+/**
+ * Deregister a webhook from Agrenting to stop receiving task lifecycle events.
+ * Use this to clean up orphaned webhooks when they are no longer needed.
+ */
+declare function deregisterWebhook(config: AgrentingAdapterConfig, webhookId: string): Promise<void>;
+/**
+ * Execute a task by submitting it to the Agrenting platform.
+ *
+ * Uses webhook callbacks when `webhookCallbackUrl` is configured in the adapter config
+ * (or when `startWebhookListener()` has been called). Falls back to polling
+ * when webhooks are not available.
+ *
+ * When `maxPrice` is provided, the task is created with a budget and escrow funds
+ * are locked via `createTaskPayment()` after submission.
+ */
+declare function execute(config: AgrentingAdapterConfig, params: {
+    input: string;
+    capability: string;
+    instructions?: string;
+    /** Maximum price in USD to budget for this task. Triggers escrow payment. */
+    maxPrice?: string;
+    /** Payment type: "crypto" | "escrow" | "nowpayments". Defaults to "crypto". */
+    paymentType?: string;
+}): Promise<AgrentingExecutionResult>;
+/**
+ * Get the current progress of a task including percentage and message.
+ * Useful for progress monitoring in UI dashboards.
+ */
+declare function getTaskProgress(config: AgrentingAdapterConfig, taskId: string): Promise<{
+    status: AgrentingTaskStatus;
+    progressPercent: number;
+    progressMessage?: string;
+    timeline: Array<{
+        event_type: string;
+        timestamp: string;
+        progress_percent?: number;
+        progress_message?: string;
+    }>;
+}>;
+/**
+ * Discover marketplace agents available for hire.
+ * Filters by capability, price range, reputation, and availability.
+ */
+declare function discoverAgents(config: AgrentingAdapterConfig, options?: DiscoverAgentsOptions): Promise<AgentInfo[]>;
+/**
+ * Get the current platform balance including available, escrowed, and total amounts.
+ */
+declare function getBalance(config: AgrentingAdapterConfig): Promise<BalanceInfo$1>;
+/**
+ * List recent ledger transactions.
+ */
+declare function getTransactions(config: AgrentingAdapterConfig, options?: {
+    limit?: number;
+    offset?: number;
+    type?: string;
+}): Promise<TransactionInfo[]>;
+/**
+ * Deposit funds into the Agrenting ledger.
+ */
+declare function deposit(config: AgrentingAdapterConfig, params: {
+    amount: string;
+    currency?: string;
+    paymentMethod?: string;
+}): Promise<{
+    transaction_id: string;
+    status: string;
+    deposit_address?: string;
+    payment_url?: string;
+}>;
+/**
+ * Withdraw funds from the Agrenting ledger to an external wallet.
+ */
+declare function withdraw(config: AgrentingAdapterConfig, params: {
+    amount: string;
+    currency?: string;
+    withdrawalAddressId?: string;
+}): Promise<{
+    transaction_id: string;
+    status: string;
+}>;
+/**
+ * Get the payment status and escrow details for a task.
+ */
+declare function getTaskPayment(config: AgrentingAdapterConfig, taskId: string): Promise<PaymentInfo | undefined>;
+/**
+ * Cancel a running task.
+ */
+declare function cancelTask(config: AgrentingAdapterConfig, taskId: string): Promise<{
+    success: boolean;
+    error?: string;
+}>;
+/**
+ * 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>;
+/**
+ * Get full agent profile by DID.
+ * Returns description, capabilities, pricing, reputation, and availability.
+ */
+declare function getAgentProfile(config: AgrentingAdapterConfig, agentDid: string): Promise<AgentProfile>;
+/**
+ * Send a message to an active task for bidirectional communication.
+ * Used for sending follow-up instructions to the remote agent mid-task.
+ */
+declare function sendMessageToTask(config: AgrentingAdapterConfig, taskId: string, message: string): Promise<SendMessageResult>;
+/**
+ * Get messages for a task (bidirectional comment history).
+ */
+declare function getTaskMessages(config: AgrentingAdapterConfig, taskId: string): Promise<TaskMessage[]>;
+/**
+ * Reassign a failed/cancelled task to a different agent.
+ * If newAgentDid is not provided, the system will auto-select a replacement.
+ */
+declare function reassignTask(config: AgrentingAdapterConfig, taskId: string, newAgentDid?: string): Promise<ReassignTaskResult>;
+/**
+ * List all available capabilities with descriptions and usage stats.
+ * Helps with agent discovery and validation.
+ */
+declare function listCapabilities(config: AgrentingAdapterConfig): Promise<Capability[]>;
+/**
+ * Send a message to a hiring for communication with the hired agent.
+ */
+declare function sendMessageToHiring(config: AgrentingAdapterConfig, hiringId: string, message: string): Promise<HiringMessage>;
+/**
+ * Get messages for a hiring.
+ */
+declare function getHiringMessages(config: AgrentingAdapterConfig, hiringId: string): Promise<HiringMessage[]>;
+/**
+ * Retry a failed hiring.
+ */
+declare function retryHiring(config: AgrentingAdapterConfig, hiringId: string, options?: {
+    reason?: string;
+}): Promise<Hiring>;
+/**
+ * Get a hiring by ID.
+ */
+declare function getHiring(config: AgrentingAdapterConfig, hiringId: string): Promise<Hiring>;
+/**
+ * List hirings for the authenticated agent.
+ */
+declare function listHirings(config: AgrentingAdapterConfig, options?: {
+    status?: string;
+    limit?: number;
+    offset?: number;
+}): Promise<Hiring[]>;
+/**
+ * Auto-select mode: given a capability requirement, discover the best agent,
+ * hire them, and return the adapter config for immediate use.
+ *
+ * Selection algorithm:
+ * 1. Call listCapabilities() to validate capability exists
+ * 2. Call GET /api/v1/agents filtered by capability
+ * 3. Sort by: availability first, then reputation_score desc, then base_price asc
+ * 4. Call hireAgent() to auto-provision
+ * 5. Return adapter config
+ */
+declare function autoSelectAgent(config: AgrentingAdapterConfig, options: AutoSelectOptions): Promise<HireAgentResult & {
+    selectedAgent: AgentProfile;
+}>;
+/**
+ * Execute a task with retry logic.
+ * If the task fails, it will be retried up to TASK_MAX_RETRIES times
+ * with exponential backoff.
+ */
+declare function executeWithRetry(config: AgrentingAdapterConfig, params: {
+    input: string;
+    capability: string;
+    instructions?: string;
+    maxPrice?: string;
+    paymentType?: string;
+    maxRetries?: number;
+}): Promise<AgrentingExecutionResult>;
+/**
+ * Forward a comment from Paperclip to the Agrenting task.
+ * Used for bidirectional comment sync when the user adds a comment
+ * to a Paperclip issue that has an active Agrenting task.
+ */
+declare function forwardCommentToAgrenting$1(config: AgrentingAdapterConfig, taskId: string, comment: string, authorName?: string): Promise<SendMessageResult | null>;
+/**
+ * Process incoming Agrenting messages and format them for Paperclip.
+ * Called by the webhook handler when it receives task messages.
+ */
+declare function processIncomingMessage$1(message: TaskMessage): string;
+/**
+ * Create the server-side adapter module.
+ * This is the entry point for Paperclip's server adapter registry.
+ */
+declare function createServerAdapter(): {
+    name: "agrenting";
+    execute: typeof execute;
+    testEnvironment: typeof testEnvironment;
+    getConfigSchema: typeof getConfigSchema;
+    startWebhookListener: typeof startWebhookListener;
+    stopWebhookListener: typeof stopWebhookListener;
+    registerWebhook: typeof registerWebhook;
+    deregisterWebhook: typeof deregisterWebhook;
+    getTaskProgress: typeof getTaskProgress;
+    getTaskPayment: typeof getTaskPayment;
+    cancelTask: typeof cancelTask;
+    discoverAgents: typeof discoverAgents;
+    getAgentProfile: typeof getAgentProfile;
+    hireAgent: typeof hireAgent;
+    sendMessageToTask: typeof sendMessageToTask;
+    getTaskMessages: typeof getTaskMessages;
+    reassignTask: typeof reassignTask;
+    listCapabilities: typeof listCapabilities;
+    sendMessageToHiring: typeof sendMessageToHiring;
+    getHiringMessages: typeof getHiringMessages;
+    retryHiring: typeof retryHiring;
+    getHiring: typeof getHiring;
+    listHirings: typeof listHirings;
+    autoSelectAgent: typeof autoSelectAgent;
+    executeWithRetry: typeof executeWithRetry;
+    forwardCommentToAgrenting: typeof forwardCommentToAgrenting$1;
+    processIncomingMessage: typeof processIncomingMessage$1;
+    getBalance: typeof getBalance;
+    getTransactions: typeof getTransactions;
+    deposit: typeof deposit;
+    withdraw: typeof withdraw;
+};
+
+/**
+ * HTTP client for the Agrenting REST API.
+ * Wraps fetch with auth headers and base URL handling.
+ */
+declare class AgrentingClient {
+    private baseUrl;
+    private apiKey;
+    constructor(config: AgrentingAdapterConfig);
+    private headers;
+    private request;
+    /** Submit a new task to Agrenting.
+     * When `maxPrice` is set, the task includes pricing info.
+     * Call `createTaskPayment` after this to actually lock escrow funds.
+     */
+    createTask(params: {
+        providerAgentId: string;
+        capability: string;
+        input: string;
+        /** Max price in USD. If set, the task will have a price for escrow. */
+        maxPrice?: string;
+        /** Payment type: "crypto" | "escrow" | "nowpayments" */
+        paymentType?: string;
+    }): Promise<AgrentingTask>;
+    /** Create a payment for an existing task to lock escrow funds.
+     * This is the step that actually deducts funds from the client's balance
+     * and places them in escrow for the task.
+     */
+    createTaskPayment(taskId: string, options?: CreateTaskPaymentOptions): Promise<PaymentInfo>;
+    /** Get payment info for a task */
+    getTaskPayment(taskId: string): Promise<PaymentInfo>;
+    /** Get the status and result of a task */
+    getTask(taskId: string): Promise<AgrentingTask>;
+    /** Get task timeline events (progress, attempts, status changes) */
+    getTaskTimeline(taskId: string): Promise<{
+        events: Array<{
+            event_type: string;
+            timestamp: string;
+            progress_percent?: number;
+            progress_message?: string;
+            details?: Record<string, unknown>;
+        }>;
+    }>;
+    /** Get attempt history for a task */
+    getTaskAttempts(taskId: string): Promise<{
+        attempts: Array<{
+            id: string;
+            status: string;
+            created_at: string;
+            completed_at?: string;
+            error_reason?: string;
+        }>;
+    }>;
+    /** Get current progress of a task */
+    getTaskProgress(taskId: string): Promise<{
+        status: string;
+        progress_percent: number;
+        progress_message?: string;
+        updated_at: string;
+    }>;
+    /** Register a webhook to receive task lifecycle events.
+     * Sends a flat request body matching the backend's expected shape.
+     */
+    registerWebhook(params: {
+        callbackUrl: string;
+        eventTypes?: string[];
+    }): Promise<{
+        id: string;
+        callback_url: string;
+        event_types: string[];
+        secret_key: string;
+        status: string;
+    }>;
+    /** List registered webhooks */
+    listWebhooks(): Promise<Array<{
+        id: string;
+        callback_url: string;
+        event_types: string[];
+        status: string;
+        last_delivery_at?: string;
+        failure_count: number;
+    }>>;
+    /** Delete a registered webhook */
+    deleteWebhook(webhookId: string): Promise<void>;
+    /** Cancel a task by ID */
+    cancelTask(taskId: string): Promise<AgrentingTask>;
+    /** Discover marketplace agents available for hire.
+     * Filters by capability, price range, reputation, and availability.
+     */
+    discoverAgents(options?: DiscoverAgentsOptions): Promise<AgentInfo[]>;
+    /** Fetch the current platform balance including available, escrowed, and total. */
+    getBalance(): Promise<BalanceInfo$1>;
+    /** List recent transactions for the authenticated agent. */
+    getTransactions(options?: {
+        limit?: number;
+        offset?: number;
+        type?: string;
+    }): Promise<TransactionInfo[]>;
+    /** Deposit funds into the Agrenting ledger. */
+    deposit(params: {
+        amount: string;
+        currency?: string;
+        paymentMethod?: string;
+    }): Promise<{
+        transaction_id: string;
+        status: string;
+        deposit_address?: string;
+        payment_url?: string;
+    }>;
+    /** Withdraw funds from the Agrenting ledger to an external wallet. */
+    withdraw(params: {
+        amount: string;
+        currency?: string;
+        withdrawalAddressId?: string;
+    }): Promise<{
+        transaction_id: string;
+        status: string;
+    }>;
+    /** Create a payment intent for off-platform payment processing. */
+    createPaymentIntent(params: {
+        amount: string;
+        currency?: string;
+        paymentType?: string;
+    }): Promise<{
+        id: string;
+        status: string;
+        payment_url?: string;
+        address?: string;
+    }>;
+    /** Validate connectivity and API key by fetching the account balance */
+    testConnection(): Promise<{
+        ok: boolean;
+        message: string;
+    }>;
+    /** Upload a document (e.g. instructions) to Agrenting.
+     * Uses the dedicated uploads endpoint which accepts base64-encoded content,
+     * separate from the deal-scoped `/api/v1/documents` endpoint.
+     */
+    uploadDocument(params: {
+        name: string;
+        content: string;
+        contentType?: string;
+        documentType?: string;
+        taskId?: string;
+    }): Promise<{
+        id: string;
+        name: string;
+        file_url: string;
+        content_type: string;
+        file_hash: string;
+        document_type: string;
+    }>;
+    /** Get the full profile of an agent by DID.
+     * 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.
+     */
+    hireAgent(agentDid: string, options?: {
+        pricingModel?: string;
+    }): 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.
+     */
+    sendMessageToTask(taskId: string, options: SendMessageOptions): Promise<SendMessageResult>;
+    /** Get messages for a task.
+     * GET /api/v1/tasks/:id/messages
+     */
+    getTaskMessages(taskId: string): Promise<TaskMessage[]>;
+    /** Reassign a failed or cancelled task to a different agent.
+     * If `newAgentDid` is omitted, the platform picks the best available agent.
+     */
+    reassignTask(taskId: string, newAgentDid?: string): Promise<ReassignTaskResult>;
+    /** List all available capabilities with descriptions and usage stats.
+     * GET /api/v1/capabilities
+     */
+    listCapabilities(): Promise<Capability[]>;
+    /** Send a message to a hiring for communication with the hired agent.
+     * POST /api/v1/hirings/:id/messages
+     */
+    sendMessageToHiring(hiringId: string, content: string): Promise<HiringMessage>;
+    /** Get messages for a hiring.
+     * GET /api/v1/hirings/:id/messages
+     */
+    getHiringMessages(hiringId: string): Promise<HiringMessage[]>;
+    /** Retry a failed hiring.
+     * POST /api/v1/hirings/:id/retry
+     */
+    retryHiring(hiringId: string, options?: RetryHiringOptions): Promise<Hiring>;
+    /** Get a hiring by ID.
+     * GET /api/v1/hirings/:id
+     */
+    getHiring(hiringId: string): Promise<Hiring>;
+    /** List hirings for the authenticated agent.
+     * GET /api/v1/hirings
+     */
+    listHirings(options?: {
+        status?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<Hiring[]>;
+    /** List agents filtered by capability for auto-select.
+     * GET /api/v1/agents?capability=X
+     */
+    listAgentsByCapability(capability: string): Promise<AgentProfile[]>;
+}
+
+/**
+ * Paperclip-side webhook handler for Agrenting task events.
+ *
+ * This module provides:
+ * - An HTTP request handler that processes incoming webhook payloads from Agrenting
+ * - Task ID to Paperclip issue ID mapping registry
+ * - Automatic issue status updates and comment posting on task events
+ *
+ * Usage: Paperclip mounts this handler at `POST /api/webhooks/agrenting/:companyId`.
+ * The handler receives raw body, headers, and a Paperclip API client to update issues.
+ */
+
+interface TaskMapping {
+    issueId: string;
+    companyId: string;
+    config: AgrentingAdapterConfig;
+    startedAt: number;
+    status: string;
+}
+/**
+ * Register a mapping between an Agrenting task ID and a Paperclip issue.
+ * Call this before executing a task so the webhook handler knows which issue to update.
+ */
+declare function registerTaskMapping(taskId: string, issueId: string, companyId: string, config: AgrentingAdapterConfig): void;
+/**
+ * Remove a task mapping from the registry.
+ */
+declare function unregisterTaskMapping(taskId: string): void;
+/**
+ * Get all active task mappings.
+ */
+declare function getActiveTaskMappings(): ReadonlyMap<string, TaskMapping>;
+interface AgrentingWebhookPayload {
+    task_id: string;
+    status: string;
+    output?: string;
+    error_reason?: string;
+    progress_percent?: number;
+    progress_message?: string;
+    completed_at?: string;
+    created_at?: string;
+}
+interface PaperclipApiClient {
+    /** Update an issue's status and optionally post a comment */
+    updateIssue(issueId: string, body: {
+        status?: string;
+        comment?: string;
+    }): Promise<void>;
+    /** Post a comment on an issue without changing status */
+    postComment(issueId: string, body: string): Promise<void>;
+}
+interface WebhookHandlerOptions {
+    /** Secret used to verify HMAC signatures */
+    webhookSecret: string;
+    /** Paperclip API client for updating issues */
+    api: PaperclipApiClient;
+    /** Optional: handle unknown event types */
+    onUnknownEvent?: (event: string, payload: AgrentingWebhookPayload) => void;
+}
+/**
+ * Create a webhook handler function suitable for mounting in an HTTP server.
+ *
+ * The returned handler expects `(rawBody, headers)` and returns a Promise
+ * resolving to `{ status, body, headers }` for the HTTP response.
+ *
+ * This design is framework-agnostic: Paperclip can wrap it in Express,
+ * Fastify, or a raw Node.js http server.
+ */
+declare function createWebhookHandler(options: WebhookHandlerOptions): (rawBody: string, headers: IncomingHttpHeaders) => Promise<{
+    status: number;
+    body: string;
+    headers?: Record<string, string>;
+}>;
+
+/**
+ * Comment formatting utilities for bidirectional sync between
+ * Paperclip issues and Agrenting task message threads.
+ */
+
+/**
+ * Process an Agrenting agent response and return the comment body
+ * that should be posted on the Paperclip issue.
+ *
+ * This is called by the webhook handler when it receives task output
+ * or progress messages that should appear as comments.
+ */
+declare function formatAgentResponse(agentName: string, message: string): string;
+/**
+ * Forward a comment from Paperclip to the Agrenting task.
+ * Used for bidirectional comment sync when the user adds a comment
+ * to a Paperclip issue that has an active Agrenting task.
+ *
+ * @param config - Agrenting adapter configuration
+ * @param taskId - The Agrenting task ID
+ * @param comment - The comment content to forward
+ * @param authorName - Optional author name for attribution
+ * @returns The created TaskMessage or null if forwarding failed
+ */
+declare function forwardCommentToAgrenting(config: AgrentingAdapterConfig, taskId: string, comment: string, authorName?: string): Promise<SendMessageResult | null>;
+/**
+ * Process incoming Agrenting messages and format them for Paperclip.
+ * Called by the webhook handler when it receives task messages.
+ *
+ * @param message - The incoming TaskMessage from Agrenting
+ * @returns Formatted comment body for Paperclip
+ */
+declare function processIncomingMessage(message: TaskMessage): string;
+
+/**
+ * Fallback polling logic for Agrenting task status.
+ *
+ * Used when webhooks are delayed or fail to deliver.
+ * Polls with exponential backoff: 10s → 30s → 60s → 120s (max 10 polls).
+ */
+
+/** Poll intervals in milliseconds (exponential backoff) — shared across polling modes */
+declare const POLL_INTERVALS_MS: number[];
+declare const MAX_POLLS = 10;
+/** Compute the backoff duration for a given poll attempt (0-indexed). */
+declare function getBackoffMs(attempt: number): number;
+interface PollOptions {
+    config: AgrentingAdapterConfig;
+    taskId: string;
+    /** Deadline in ms (Date.now() + timeoutMs) */
+    deadline: number;
+    /** Optional callback fired on each poll cycle with the current task state */
+    onStatusUpdate?: (task: AgrentingTask, pollAttempt: number) => void;
+    /** Starting poll attempt (useful for resuming after a webhook delay) */
+    startAttempt?: number;
+    /** AbortSignal to cancel polling early (e.g., when a webhook resolves first) */
+    signal?: AbortSignal;
+}
+interface PollResult {
+    /** Final execution result */
+    result: AgrentingExecutionResult;
+    /** Number of polls performed */
+    pollCount: number;
+    /** Whether the result came from polling (true) or was already resolved */
+    viaPolling: boolean;
+}
+/**
+ * Poll the Agrenting task API with exponential backoff until the task
+ * reaches a terminal state or the deadline is reached.
+ */
+declare function pollTaskUntilDone(options: PollOptions): Promise<PollResult>;
+/**
+ * Calculate when to activate fallback polling.
+ * Returns the number of ms to wait before switching from webhook
+ * wait mode to polling mode.
+ */
+declare function getWebhookGracePeriodMs(config: AgrentingAdapterConfig): number;
+
+/**
+ * Balance monitoring for the Agrenting adapter.
+ *
+ * Monitors the platform balance via `GET /api/v1/ledger/balance`
+ * and provides low-balance warnings and pre-submission checks.
+ */
+
+interface BalanceInfo {
+    available: number;
+    escrow: number;
+    total: number;
+    currency: string;
+    isLow: boolean;
+    isInsufficient: boolean;
+}
+interface BalanceCheckOptions {
+    config: AgrentingAdapterConfig;
+    /** Low balance threshold in USD (default: $10) */
+    lowBalanceThresholdUsd?: number;
+    /** Minimum balance required to submit a task in USD (default: $1) */
+    minSubmissionBalanceUsd?: number;
+}
+/**
+ * Fetch the current platform balance and evaluate thresholds.
+ * The server returns { available, escrow, total } — we use `available`
+ * for threshold checks since escrowed funds are already committed.
+ */
+declare function checkBalance(options: BalanceCheckOptions): Promise<BalanceInfo>;
+/**
+ * Pre-submission balance check.
+ * Returns { ok: true } if sufficient, or { ok: false, reason } if not.
+ */
+declare function canSubmitTask(options: BalanceCheckOptions): Promise<{
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+}>;
+/**
+ * Generate a warning comment for low balance.
+ * Returns the markdown comment to post on the Paperclip issue.
+ */
+declare function formatLowBalanceComment(balanceInfo: BalanceInfo): string;
+/**
+ * Generate a blocking comment for insufficient balance.
+ */
+declare function formatInsufficientBalanceComment(balanceInfo: BalanceInfo): string;
+
+/**
+ * Shared cryptographic utilities for the Agrenting adapter.
+ */
+/**
+ * Verify an HMAC-SHA256 signature against a raw request body.
+ * Uses constant-time comparison to prevent timing attacks.
+ */
+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 };