@agrentingai/paperclip-adapter 0.2.0

package/server/src/crypto.ts

@@ -0,0 +1,25 @@
+/**
+ * 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.
+ */
+export async function verifyWebhookSignature(
+  rawBody: string,
+  signature: string,
+  secret: string
+): Promise<boolean> {
+  const crypto = await import("crypto");
+  const expected = crypto
+    .createHmac("sha256", secret)
+    .update(rawBody)
+    .digest("base64");
+  const sigBuf = Buffer.from(signature);
+  const expectedBuf = Buffer.from(expected);
+  if (sigBuf.byteLength !== expectedBuf.byteLength) {
+    return false;
+  }
+  return crypto.timingSafeEqual(sigBuf, expectedBuf);
+}

package/server/src/index.ts

@@ -0,0 +1,67 @@
+export { createServerAdapter } from "./adapter.js";
+export { AgrentingClient } from "./client.js";
+export {
+  createWebhookHandler,
+  registerTaskMapping,
+  unregisterTaskMapping,
+  getActiveTaskMappings,
+} from "./webhook-handler.js";
+export type {
+  AgrentingWebhookPayload,
+  PaperclipApiClient,
+  WebhookHandlerOptions,
+} from "./webhook-handler.js";
+export {
+  formatAgentResponse,
+  forwardCommentToAgrenting,
+  processIncomingMessage,
+} from "./comment-sync.js";
+export { pollTaskUntilDone, getWebhookGracePeriodMs, POLL_INTERVALS_MS, MAX_POLLS, getBackoffMs } from "./polling.js";
+export type { PollOptions, PollResult } from "./polling.js";
+export {
+  checkBalance,
+  canSubmitTask,
+  formatLowBalanceComment,
+  formatInsufficientBalanceComment,
+} from "./balance-monitor.js";
+export type { BalanceInfo, BalanceCheckOptions } from "./balance-monitor.js";
+export { verifyWebhookSignature } from "./crypto.js";
+export {
+  registerWebhook,
+  deregisterWebhook,
+  hireAgent,
+  getAgentProfile,
+  sendMessageToTask,
+  getTaskMessages,
+  reassignTask,
+  listCapabilities,
+  sendMessageToHiring,
+  getHiringMessages,
+  retryHiring,
+  getHiring,
+  listHirings,
+  autoSelectAgent,
+  executeWithRetry,
+} from "./adapter.js";
+export type {
+  AgrentingAdapterConfig,
+  AgrentingExecutionResult,
+  AgrentingTaskStatus,
+  AgrentingTask,
+  AgentInfo,
+  AgentProfile,
+  HireAgentResult,
+  SendMessageOptions,
+  SendMessageResult,
+  ReassignTaskResult,
+  PaymentInfo,
+  TransactionInfo,
+  DiscoverAgentsOptions,
+  CreateTaskPaymentOptions,
+  Hiring,
+  TaskMessage,
+  HiringMessage,
+  Capability,
+  AutoSelectOptions,
+  RetryHiringOptions,
+} from "./types.js";

package/server/src/polling.test.ts

@@ -0,0 +1,208 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import {
+  pollTaskUntilDone,
+  getBackoffMs,
+  getWebhookGracePeriodMs,
+  POLL_INTERVALS_MS,
+  MAX_POLLS,
+} from "./polling.js";
+
+// Mock the client so we don't hit the real API
+vi.mock("./client.js", () => {
+  return {
+    AgrentingClient: vi.fn().mockImplementation(function() {
+      return {
+        getTask: vi.fn().mockResolvedValue({
+          id: "task-1",
+          status: "completed",
+          output: "done",
+          client_agent_id: "c1",
+          provider_agent_id: "p1",
+          capability: "test",
+          input: "hello",
+          created_at: new Date().toISOString(),
+          updated_at: new Date().toISOString(),
+        }),
+      };
+    }),
+  };
+});
+
+const mockConfig = {
+  agrentingUrl: "https://api.agrenting.com",
+  apiKey: "test-key",
+  agentDid: "did:agrenting:test",
+};
+
+beforeEach(() => {
+  vi.clearAllMocks();
+});
+
+// ---------------------------------------------------------------------------
+// getBackoffMs
+// ---------------------------------------------------------------------------
+
+describe("getBackoffMs", () => {
+  it("returns 10s for attempt 0", () => {
+    expect(getBackoffMs(0)).toBe(10_000);
+  });
+
+  it("returns 30s for attempt 1", () => {
+    expect(getBackoffMs(1)).toBe(30_000);
+  });
+
+  it("returns 60s for attempt 2", () => {
+    expect(getBackoffMs(2)).toBe(60_000);
+  });
+
+  it("returns 120s for attempt 3", () => {
+    expect(getBackoffMs(3)).toBe(120_000);
+  });
+
+  it("caps at 120s for higher attempts", () => {
+    expect(getBackoffMs(10)).toBe(120_000);
+    expect(getBackoffMs(100)).toBe(120_000);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// POLL_INTERVALS_MS / MAX_POLLS constants
+// ---------------------------------------------------------------------------
+
+describe("constants", () => {
+  it("has 4 poll intervals with exponential backoff", () => {
+    expect(POLL_INTERVALS_MS).toEqual([10_000, 30_000, 60_000, 120_000]);
+  });
+
+  it("MAX_POLLS is 10", () => {
+    expect(MAX_POLLS).toBe(10);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// getWebhookGracePeriodMs
+// ---------------------------------------------------------------------------
+
+describe("getWebhookGracePeriodMs", () => {
+  it("returns 60s by default (10% of 600s, capped at 60s)", () => {
+    expect(getWebhookGracePeriodMs(mockConfig)).toBe(60_000);
+  });
+
+  it("returns 10% of timeout for short timeouts", () => {
+    const config = { ...mockConfig, timeoutSec: 30 };
+    // 30s * 1000 * 0.1 = 3000ms, min(60000, 3000) = 3000
+    expect(getWebhookGracePeriodMs(config)).toBe(3_000);
+  });
+
+  it("caps at 60s even for long timeouts", () => {
+    const config = { ...mockConfig, timeoutSec: 3600 };
+    // 3600s * 1000 * 0.1 = 360000, min(60000, 360000) = 60000
+    expect(getWebhookGracePeriodMs(config)).toBe(60_000);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// pollTaskUntilDone
+// ---------------------------------------------------------------------------
+
+describe("pollTaskUntilDone", () => {
+  it("returns completed task on first poll", { timeout: 30_000 }, async () => {
+    const result = await pollTaskUntilDone({
+      config: mockConfig,
+      taskId: "task-1",
+      deadline: Date.now() + 600_000,
+    });
+
+    expect(result.result.success).toBe(true);
+    expect(result.result.output).toBe("done");
+    expect(result.result.taskId).toBe("task-1");
+    expect(result.viaPolling).toBe(true);
+    expect(result.pollCount).toBeGreaterThanOrEqual(1);
+  });
+
+  it("returns timeout when deadline is in the past", async () => {
+    const result = await pollTaskUntilDone({
+      config: mockConfig,
+      taskId: "task-1",
+      deadline: Date.now() - 1000, // Already past
+    });
+
+    expect(result.result.success).toBe(false);
+    expect(result.result.error).toContain("timed out");
+    expect(result.pollCount).toBe(0);
+  });
+
+  it("fires onStatusUpdate callback on each poll", { timeout: 30_000 }, async () => {
+    const onStatusUpdate = vi.fn();
+
+    await pollTaskUntilDone({
+      config: mockConfig,
+      taskId: "task-1",
+      deadline: Date.now() + 600_000,
+      onStatusUpdate,
+    });
+
+    expect(onStatusUpdate).toHaveBeenCalledTimes(1);
+    expect(onStatusUpdate).toHaveBeenCalledWith(
+      expect.objectContaining({ status: "completed" }),
+      1
+    );
+  });
+
+  it("reports failure when task fails", { timeout: 30_000 }, async () => {
+    const { AgrentingClient } = await import("./client.js");
+    const MockClient = vi.mocked(AgrentingClient);
+    MockClient.mockImplementationOnce(function() {
+      return {
+        getTask: vi.fn().mockResolvedValue({
+          id: "fail-task",
+          status: "failed",
+          error_reason: "Agent crashed",
+          client_agent_id: "c1",
+          provider_agent_id: "p1",
+          capability: "test",
+          input: "hello",
+          created_at: new Date().toISOString(),
+          updated_at: new Date().toISOString(),
+        }),
+      };
+    });
+
+    const result = await pollTaskUntilDone({
+      config: mockConfig,
+      taskId: "fail-task",
+      deadline: Date.now() + 600_000,
+    });
+
+    expect(result.result.success).toBe(false);
+    expect(result.result.error).toBe("Agent crashed");
+  });
+
+  it("reports cancellation when task is cancelled", { timeout: 30_000 }, async () => {
+    const { AgrentingClient } = await import("./client.js");
+    const MockClient = vi.mocked(AgrentingClient);
+    MockClient.mockImplementationOnce(function() {
+      return {
+        getTask: vi.fn().mockResolvedValue({
+          id: "cancel-task",
+          status: "cancelled",
+          client_agent_id: "c1",
+          provider_agent_id: "p1",
+          capability: "test",
+          input: "hello",
+          created_at: new Date().toISOString(),
+          updated_at: new Date().toISOString(),
+        }),
+      };
+    });
+
+    const result = await pollTaskUntilDone({
+      config: mockConfig,
+      taskId: "cancel-task",
+      deadline: Date.now() + 600_000,
+    });
+
+    expect(result.result.success).toBe(false);
+    expect(result.result.error).toBe("Task was cancelled");
+  });
+});

package/server/src/polling.ts

@@ -0,0 +1,183 @@
+/**
+ * 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).
+ */
+
+import { AgrentingClient } from "./client.js";
+import type {
+  AgrentingAdapterConfig,
+  AgrentingExecutionResult,
+  AgrentingTask,
+} from "./types.js";
+
+/** Poll intervals in milliseconds (exponential backoff) — shared across polling modes */
+export const POLL_INTERVALS_MS = [10_000, 30_000, 60_000, 120_000];
+export const MAX_POLLS = 10;
+
+/** Compute the backoff duration for a given poll attempt (0-indexed). */
+export function getBackoffMs(attempt: number): number {
+  const index = Math.min(attempt, POLL_INTERVALS_MS.length - 1);
+  return POLL_INTERVALS_MS[index];
+}
+
+export 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;
+}
+
+export 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.
+ */
+export async function pollTaskUntilDone(
+  options: PollOptions
+): Promise<PollResult> {
+  const client = new AgrentingClient(options.config);
+  let pollAttempt = options.startAttempt ?? 0;
+  const startTime = Date.now();
+
+  while (pollAttempt < MAX_POLLS) {
+    // Check if polling was aborted (e.g., webhook resolved first)
+    if (options.signal?.aborted) {
+      return {
+        result: {
+          success: false,
+          error: "Polling aborted",
+          taskId: options.taskId,
+          durationMs: Date.now() - startTime,
+        },
+        pollCount: pollAttempt,
+        viaPolling: true,
+      };
+    }
+
+    const now = Date.now();
+    if (now >= options.deadline) {
+      return {
+        result: {
+          success: false,
+          error: `Task timed out after ${options.config.timeoutSec ?? 600}s`,
+          taskId: options.taskId,
+          durationMs: now - startTime,
+        },
+        pollCount: pollAttempt,
+        viaPolling: true,
+      };
+    }
+
+    // Wait for the next poll interval (respects abort signal).
+    // Skip the wait on the first iteration so the first poll is immediate.
+    if (pollAttempt > 0) {
+      const waitMs = getBackoffMs(pollAttempt);
+      await new Promise<void>((resolve) => {
+        const timer = setTimeout(resolve, waitMs);
+        if (options.signal) {
+          options.signal.addEventListener("abort", () => {
+            clearTimeout(timer);
+            resolve();
+          }, { once: true });
+        }
+      });
+    }
+
+    const task = await client.getTask(options.taskId);
+    pollAttempt++;
+
+    options.onStatusUpdate?.(task, pollAttempt);
+
+    if (task.status === "completed") {
+      return {
+        result: {
+          success: true,
+          output: task.output,
+          taskId: options.taskId,
+          durationMs: Date.now() - startTime,
+        },
+        pollCount: pollAttempt,
+        viaPolling: true,
+      };
+    }
+
+    if (task.status === "failed") {
+      return {
+        result: {
+          success: false,
+          error: task.error_reason ?? "Task failed with no reason provided",
+          taskId: options.taskId,
+          durationMs: Date.now() - startTime,
+        },
+        pollCount: pollAttempt,
+        viaPolling: true,
+      };
+    }
+
+    if (task.status === "cancelled") {
+      return {
+        result: {
+          success: false,
+          error: "Task was cancelled",
+          taskId: options.taskId,
+          durationMs: Date.now() - startTime,
+        },
+        pollCount: pollAttempt,
+        viaPolling: true,
+      };
+    }
+  }
+
+  // Max polls reached without terminal state — do one final check
+  const finalTask = await client.getTask(options.taskId);
+  if (finalTask.status === "completed") {
+    return {
+      result: {
+        success: true,
+        output: finalTask.output,
+        taskId: options.taskId,
+        durationMs: Date.now() - startTime,
+      },
+      pollCount: pollAttempt + 1,
+      viaPolling: true,
+    };
+  }
+
+  return {
+    result: {
+      success: false,
+      error: `Task did not complete after ${pollAttempt} polls (max ${MAX_POLLS})`,
+      taskId: options.taskId,
+      durationMs: Date.now() - startTime,
+    },
+    pollCount: pollAttempt,
+    viaPolling: true,
+  };
+}
+
+/**
+ * Calculate when to activate fallback polling.
+ * Returns the number of ms to wait before switching from webhook
+ * wait mode to polling mode.
+ */
+export function getWebhookGracePeriodMs(config: AgrentingAdapterConfig): number {
+  // Default: 60 seconds. If the timeout is very short, use a fraction of it.
+  const timeoutMs = (config.timeoutSec ?? 600) * 1000;
+  return Math.min(60_000, timeoutMs * 0.1);
+}