@agrentingai/paperclip-adapter 0.3.0 → 0.4.0

package/dist/server/index.js

@@ -1,6 +1,12 @@
 // server/src/client.ts
 var DEFAULT_TIMEOUT_MS = 3e4;
 var MAX_RETRIES = 3;
+var NonRetryableAgrentingError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "NonRetryableAgrentingError";
+  }
+};
 var AgrentingClient = class {
   baseUrl;
   apiKey;
@@ -47,17 +53,22 @@ var AgrentingClient = class {
             await new Promise((resolve) => setTimeout(resolve, delayMs));
             continue;
           }
-          throw new Error(
+          throw new NonRetryableAgrentingError(
             `Agrenting API ${response.status}: ${text.slice(0, 500)}`
           );
         }
         const envelope = await response.json();
         if (Array.isArray(envelope.errors) && envelope.errors.length) {
-          throw new Error(`API errors: ${envelope.errors.join(", ")}`);
+          throw new NonRetryableAgrentingError(
+            `API errors: ${envelope.errors.join(", ")}`
+          );
         }
         return envelope.data ?? envelope;
       } catch (err) {
         lastError = err instanceof Error ? err : new Error(String(err));
+        if (lastError instanceof NonRetryableAgrentingError) {
+          throw lastError;
+        }
         if (attempt < MAX_RETRIES) {
           clearTimeout(timer);
           const delayMs = Math.min(1e3 * 2 ** attempt, 3e4);
@@ -243,12 +254,23 @@ var AgrentingClient = class {
   async getAgentProfile(agentDid) {
     return this.request("GET", `/api/v1/agents/${encodeURIComponent(agentDid)}`);
   }
-  /** 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.
    */
-  async hireAgent(agentDid, options = {}) {
-    const body = {};
-    if (options.pricingModel) body.pricing_model = options.pricingModel;
+  async hireAgent(agentDid, options) {
+    const body = {
+      task_description: options.taskDescription,
+      capability_requested: options.capabilityRequested,
+      price: String(options.price),
+      delivery_mode: options.deliveryMode ?? "output"
+    };
+    if (options.repoUrl) body.repo_url = options.repoUrl;
+    if (options.repoAccessToken) body.repo_access_token = options.repoAccessToken;
+    if (options.clientIdempotencyKey) {
+      body.client_idempotency_key = options.clientIdempotencyKey;
+    }
+    if (options.taskInput) body.task_input = options.taskInput;
+    if (options.clientMessage) body.client_message = options.clientMessage;
     return this.request(
       "POST",
       `/api/v1/agents/${encodeURIComponent(agentDid)}/hire`,
@@ -307,13 +329,11 @@ var AgrentingClient = class {
     );
   }
   /** Get messages for a hiring.
-   * GET /api/v1/hirings/:id/messages
+   * The canonical API includes recent messages in GET /api/v1/hirings/:id.
    */
   async getHiringMessages(hiringId) {
-    return this.request(
-      "GET",
-      `/api/v1/hirings/${hiringId}/messages`
-    );
+    const hiring = await this.getHiring(hiringId);
+    return hiring.messages ?? [];
   }
   /** Retry a failed hiring.
    * POST /api/v1/hirings/:id/retry
@@ -335,6 +355,15 @@ var AgrentingClient = class {
   async getHiring(hiringId) {
     return this.request("GET", `/api/v1/hirings/${hiringId}`);
   }
+  /** Cancel an active hiring.
+   * POST /api/v1/hirings/:id/cancel
+   */
+  async cancelHiring(hiringId) {
+    return this.request(
+      "POST",
+      `/api/v1/hirings/${hiringId}/cancel`
+    );
+  }
   /** List hirings for the authenticated agent.
    * GET /api/v1/hirings
    */
@@ -342,9 +371,16 @@ var AgrentingClient = class {
     const params = new URLSearchParams();
     if (options.status) params.set("status", options.status);
     if (options.limit) params.set("limit", String(options.limit));
-    if (options.offset) params.set("offset", String(options.offset));
+    if (options.offset) {
+      const perPage = options.limit ?? 20;
+      params.set("page", String(Math.floor(options.offset / perPage) + 1));
+    }
     const query = params.toString() ? `?${params}` : "";
-    return this.request("GET", `/api/v1/hirings${query}`);
+    const result = await this.request(
+      "GET",
+      `/api/v1/hirings${query}`
+    );
+    return result.hirings;
   }
   /** List agents filtered by capability for auto-select.
    * GET /api/v1/agents?capability=X
@@ -357,6 +393,493 @@ var AgrentingClient = class {
   }
 };
 
+// server/src/paperclip.ts
+var type = "agrenting";
+var label = "Agrenting";
+var agentConfigurationDoc = `# agrenting agent configuration
+
+Adapter: agrenting
+
+Use when:
+- A Paperclip agent should delegate each heartbeat to a remote agent hired from Agrenting.
+- The operator has an Agrenting user API token and sufficient ledger balance.
+
+Core fields:
+- agrentingUrl (required): Agrenting base URL, normally https://agrenting.com
+- apiKey (required, secret): Agrenting user API token (ap_...)
+- agentDid (required): DID of the marketplace agent to hire
+- capabilityRequested (optional): defaults to the first capability on the agent profile
+- price (optional): defaults to the agent's current base price
+- timeoutSec (optional): maximum time to poll a hiring, default 600
+- pollIntervalMs (optional): hiring status poll interval, default 2000
+- deliveryMode (optional): output by default; push requires repository access
+- repoUrl (optional): repository URL used only when deliveryMode is push
+
+Recommended API-key scopes:
+- agents:discover, agents:read, hire:create, hirings:read, hirings:cancel
+- add balance:read and artifacts:read when sharing the key with Apps/Claude
+- deposits:create and account:read/account:write are optional elevated scopes
+- set max_price_per_hire on the key to cap paid actions
+
+Execution:
+- Each Paperclip run creates one canonical Agrenting hiring.
+- The Paperclip run id is sent as client_idempotency_key so safe retries deduplicate.
+- Paperclip polls the hiring until it completes, fails, is cancelled, or times out.
+- Push delivery can use a repository URL from Paperclip and an Agrenting-stored
+  GitHub token. The adapter never stores a repository token in agent config.
+`;
+var TERMINAL_STATUSES = /* @__PURE__ */ new Set([
+  "completed",
+  "failed",
+  "cancelled",
+  "disputed",
+  "refunded"
+]);
+var DEFAULT_TIMEOUT_SEC = 600;
+var DEFAULT_POLL_INTERVAL_MS = 2e3;
+var MAX_TASK_DESCRIPTION_LENGTH = 5e3;
+function asRecord(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return null;
+  }
+  return value;
+}
+function nonEmpty(value) {
+  return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
+}
+function positiveNumber(value, fallback) {
+  const parsed = typeof value === "number" ? value : Number(value);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+}
+function configFrom(raw) {
+  return {
+    agrentingUrl: nonEmpty(raw.agrentingUrl) ?? "https://agrenting.com",
+    apiKey: nonEmpty(raw.apiKey) ?? "",
+    agentDid: nonEmpty(raw.agentDid) ?? "",
+    capabilityRequested: nonEmpty(raw.capabilityRequested) ?? void 0,
+    price: nonEmpty(raw.price) ?? void 0,
+    timeoutSec: positiveNumber(raw.timeoutSec, DEFAULT_TIMEOUT_SEC),
+    pollIntervalMs: positiveNumber(
+      raw.pollIntervalMs,
+      DEFAULT_POLL_INTERVAL_MS
+    ),
+    deliveryMode: raw.deliveryMode === "push" ? "push" : "output",
+    repoUrl: nonEmpty(raw.repoUrl) ?? void 0
+  };
+}
+function taskDescriptionFrom(ctx) {
+  const context = ctx.context;
+  const title = nonEmpty(context.taskTitle) ?? nonEmpty(context.issueTitle) ?? nonEmpty(context.title);
+  const body = nonEmpty(context.paperclipTaskMarkdown) ?? nonEmpty(context.taskBody) ?? nonEmpty(context.taskDescription) ?? nonEmpty(context.issueDescription) ?? nonEmpty(context.prompt) ?? nonEmpty(context.input);
+  let description = [title, body].filter(Boolean).join("\n\n").trim();
+  if (!description) {
+    description = `Continue the assigned Paperclip work for ${ctx.agent.name}.`;
+  }
+  if (description.length <= MAX_TASK_DESCRIPTION_LENGTH) return description;
+  return `${description.slice(0, MAX_TASK_DESCRIPTION_LENGTH - 32)}
+
+[truncated by Paperclip adapter]`;
+}
+function capabilityFrom(config, context, profile) {
+  return nonEmpty(config.capabilityRequested) ?? nonEmpty(context.capabilityRequested) ?? nonEmpty(context.capability) ?? profile.capabilities.find((capability) => capability.trim().length > 0) ?? null;
+}
+function priceFrom(config, context, profile) {
+  return nonEmpty(config.price) ?? nonEmpty(context.price) ?? nonEmpty(context.maxPrice) ?? nonEmpty(profile.base_price);
+}
+function repoUrlFrom(ctx) {
+  const workspace = asRecord(ctx.context.paperclipWorkspace);
+  return nonEmpty(configFrom(ctx.config).repoUrl) ?? nonEmpty(workspace?.repoUrl) ?? void 0;
+}
+function taskInputFrom(ctx) {
+  const input = {
+    paperclip_run_id: ctx.runId,
+    paperclip_agent_id: ctx.agent.id,
+    paperclip_company_id: ctx.agent.companyId
+  };
+  const mappings = [
+    ["paperclip_issue_id", ctx.context.issueId ?? ctx.context.taskId],
+    ["paperclip_project_id", ctx.context.projectId],
+    ["paperclip_wake_reason", ctx.context.wakeReason]
+  ];
+  for (const [key, value] of mappings) {
+    const normalized = nonEmpty(value);
+    if (normalized) input[key] = normalized;
+  }
+  const wake = asRecord(ctx.context.paperclipWake);
+  if (wake) input.paperclip_wake = wake;
+  return input;
+}
+function outputText(hiring) {
+  const output = hiring.task_output;
+  if (typeof output === "string" && output.trim()) return output;
+  const record = asRecord(output);
+  if (record) {
+    for (const key of ["result", "output", "text", "summary"]) {
+      const direct = nonEmpty(record[key]);
+      if (direct) return direct;
+    }
+    return JSON.stringify(record, null, 2);
+  }
+  return `Agrenting hiring ${hiring.id} completed.`;
+}
+function firstLine(value) {
+  return value.split(/\r?\n/).map((line) => line.trim()).find(Boolean) ?? "Agrenting hiring completed";
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function resultForFailure(hiring, message) {
+  return {
+    exitCode: 1,
+    signal: null,
+    timedOut: false,
+    errorMessage: message,
+    errorCode: `agrenting_hiring_${hiring.status}`,
+    provider: "agrenting",
+    biller: "agrenting",
+    sessionParams: { hiringId: hiring.id },
+    sessionDisplayId: hiring.id,
+    resultJson: {
+      hiringId: hiring.id,
+      status: hiring.status,
+      failedReason: hiring.failed_reason ?? null
+    }
+  };
+}
+async function executePaperclip(ctx) {
+  const config = configFrom(ctx.config);
+  if (!config.apiKey || !config.agentDid) {
+    return {
+      exitCode: 1,
+      signal: null,
+      timedOut: false,
+      errorCode: "agrenting_config_invalid",
+      errorMessage: "Agrenting requires apiKey and agentDid."
+    };
+  }
+  const client = new AgrentingClient(config);
+  try {
+    const profile = await client.getAgentProfile(config.agentDid);
+    const capability = capabilityFrom(config, ctx.context, profile);
+    const price = priceFrom(config, ctx.context, profile);
+    if (!capability) {
+      throw new Error(
+        "No capabilityRequested was configured and the Agrenting agent profile has no capabilities."
+      );
+    }
+    if (!price) {
+      throw new Error(
+        "No price was configured and the Agrenting agent profile has no base_price."
+      );
+    }
+    const taskDescription = taskDescriptionFrom(ctx);
+    await ctx.onLog(
+      "stdout",
+      `[agrenting] Hiring ${config.agentDid} for ${capability} at ${price}
+`
+    );
+    const created = await client.hireAgent(config.agentDid, {
+      taskDescription,
+      capabilityRequested: capability,
+      price,
+      deliveryMode: config.deliveryMode,
+      clientIdempotencyKey: ctx.runId,
+      taskInput: taskInputFrom(ctx),
+      repoUrl: repoUrlFrom(ctx)
+    });
+    const hiringId = created.hiring.id;
+    await ctx.onMeta?.({
+      adapterType: type,
+      command: "POST /api/v1/agents/:did/hire",
+      context: { hiringId, agentDid: config.agentDid, capability, price }
+    });
+    await ctx.onLog(
+      "stdout",
+      `[agrenting] Hiring ${hiringId} created with status ${created.hiring.status}
+`
+    );
+    const timeoutMs = (config.timeoutSec ?? DEFAULT_TIMEOUT_SEC) * 1e3;
+    const pollIntervalMs = config.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+    const deadline = Date.now() + timeoutMs;
+    let hiring = created.hiring;
+    let lastStatus = hiring.status;
+    while (!TERMINAL_STATUSES.has(hiring.status) && Date.now() < deadline) {
+      await sleep(Math.min(pollIntervalMs, Math.max(1, deadline - Date.now())));
+      hiring = await client.getHiring(hiringId);
+      if (hiring.status !== lastStatus) {
+        lastStatus = hiring.status;
+        await ctx.onLog(
+          "stdout",
+          `[agrenting] Hiring ${hiringId} is ${hiring.status}
+`
+        );
+      }
+    }
+    if (!TERMINAL_STATUSES.has(hiring.status)) {
+      try {
+        await client.cancelHiring(hiringId);
+        await ctx.onLog(
+          "stderr",
+          `[agrenting] Hiring ${hiringId} timed out and was cancelled
+`
+        );
+      } catch (cancelError) {
+        await ctx.onLog(
+          "stderr",
+          `[agrenting] Hiring ${hiringId} timed out; cancellation failed: ${cancelError instanceof Error ? cancelError.message : String(cancelError)}
+`
+        );
+      }
+      return {
+        exitCode: null,
+        signal: null,
+        timedOut: true,
+        errorCode: "agrenting_hiring_timeout",
+        errorMessage: `Agrenting hiring ${hiringId} timed out after ${config.timeoutSec ?? DEFAULT_TIMEOUT_SEC}s.`,
+        provider: "agrenting",
+        biller: "agrenting",
+        sessionParams: { hiringId },
+        sessionDisplayId: hiringId
+      };
+    }
+    if (hiring.status !== "completed") {
+      return resultForFailure(
+        hiring,
+        hiring.failed_reason ?? `Agrenting hiring ended with status ${hiring.status}.`
+      );
+    }
+    const output = outputText(hiring);
+    await ctx.onLog("stdout", `${output}
+`);
+    const numericPrice = Number(hiring.price ?? price);
+    return {
+      exitCode: 0,
+      signal: null,
+      timedOut: false,
+      provider: "agrenting",
+      biller: "agrenting",
+      billingType: "fixed",
+      costUsd: Number.isFinite(numericPrice) ? numericPrice : null,
+      sessionParams: { hiringId },
+      sessionDisplayId: hiringId,
+      summary: firstLine(output),
+      resultJson: {
+        hiringId,
+        status: hiring.status,
+        taskOutput: hiring.task_output ?? null
+      }
+    };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const transient = /\b(429|5\d\d)\b|rate.?limit|temporar|timeout/i.test(message);
+    await ctx.onLog("stderr", `[agrenting] ${message}
+`);
+    return {
+      exitCode: 1,
+      signal: null,
+      timedOut: false,
+      errorCode: "agrenting_hiring_failed",
+      errorFamily: transient ? "transient_upstream" : null,
+      errorMessage: message,
+      provider: "agrenting",
+      biller: "agrenting"
+    };
+  }
+}
+function summarizeChecks(checks) {
+  if (checks.some((check) => check.level === "error")) return "fail";
+  if (checks.some((check) => check.level === "warn")) return "warn";
+  return "pass";
+}
+async function testPaperclipEnvironment(ctx) {
+  const config = configFrom(ctx.config);
+  const checks = [];
+  let parsedUrl = null;
+  try {
+    parsedUrl = new URL(config.agrentingUrl);
+    if (parsedUrl.protocol !== "http:" && parsedUrl.protocol !== "https:") {
+      parsedUrl = null;
+    }
+  } catch {
+    parsedUrl = null;
+  }
+  if (!parsedUrl) {
+    checks.push({
+      code: "agrenting_url_invalid",
+      level: "error",
+      message: "agrentingUrl must be an http:// or https:// URL."
+    });
+  }
+  if (!config.apiKey) {
+    checks.push({
+      code: "agrenting_api_key_missing",
+      level: "error",
+      message: "Agrenting requires a user API token.",
+      hint: "Create an ap_... token in Agrenting and store it as a Paperclip secret."
+    });
+  }
+  if (!config.agentDid) {
+    checks.push({
+      code: "agrenting_agent_did_missing",
+      level: "error",
+      message: "Agrenting requires agentDid."
+    });
+  }
+  if (!checks.some((check) => check.level === "error")) {
+    const client = new AgrentingClient(config);
+    let connectionOk = false;
+    try {
+      await client.listHirings({ limit: 1 });
+      connectionOk = true;
+      checks.push({
+        code: "agrenting_connection_ok",
+        level: "info",
+        message: "Connected to the authenticated Agrenting hiring API."
+      });
+    } catch (error) {
+      checks.push({
+        code: "agrenting_connection_failed",
+        level: "error",
+        message: "Could not access the authenticated Agrenting hiring API.",
+        detail: error instanceof Error ? error.message : String(error)
+      });
+    }
+    if (connectionOk) {
+      try {
+        const profile = await client.getAgentProfile(config.agentDid);
+        checks.push({
+          code: "agrenting_agent_profile_ok",
+          level: "info",
+          message: `Found Agrenting agent ${profile.name} (${profile.did}).`,
+          detail: `${profile.capabilities.length} capabilities; base price ${profile.base_price ?? "not reported"}.`
+        });
+      } catch (error) {
+        checks.push({
+          code: "agrenting_agent_profile_failed",
+          level: "error",
+          message: `Could not load Agrenting agent ${config.agentDid}.`,
+          detail: error instanceof Error ? error.message : String(error)
+        });
+      }
+    }
+  }
+  return {
+    adapterType: ctx.adapterType,
+    status: summarizeChecks(checks),
+    checks,
+    testedAt: (/* @__PURE__ */ new Date()).toISOString()
+  };
+}
+function getPaperclipConfigSchema() {
+  return {
+    fields: [
+      {
+        key: "agrentingUrl",
+        label: "Agrenting URL",
+        type: "text",
+        required: true,
+        default: "https://agrenting.com",
+        hint: "Base URL of the Agrenting platform."
+      },
+      {
+        key: "apiKey",
+        label: "API token",
+        type: "text",
+        required: true,
+        hint: "Agrenting user API token (ap_...). Stored as a Paperclip secret.",
+        meta: { secret: true }
+      },
+      {
+        key: "agentDid",
+        label: "Agent DID",
+        type: "text",
+        required: true,
+        hint: "Marketplace agent DID, for example did:agrenting:code-reviewer."
+      },
+      {
+        key: "capabilityRequested",
+        label: "Capability",
+        type: "text",
+        hint: "Optional default. Falls back to the first capability on the agent profile."
+      },
+      {
+        key: "price",
+        label: "Price per hiring (USD)",
+        type: "text",
+        hint: "Optional. Falls back to the agent's current base price."
+      },
+      {
+        key: "timeoutSec",
+        label: "Timeout seconds",
+        type: "number",
+        default: DEFAULT_TIMEOUT_SEC
+      },
+      {
+        key: "pollIntervalMs",
+        label: "Poll interval milliseconds",
+        type: "number",
+        default: DEFAULT_POLL_INTERVAL_MS
+      },
+      {
+        key: "repoUrl",
+        label: "Repository URL",
+        type: "text",
+        hint: "Optional push target. Push delivery uses a GitHub token already stored in Agrenting."
+      },
+      {
+        key: "deliveryMode",
+        label: "Delivery mode",
+        type: "select",
+        default: "output",
+        options: [
+          { value: "output", label: "Return output" },
+          { value: "push", label: "Push to repository" }
+        ],
+        hint: "Use output unless the hiring also has repository credentials."
+      }
+    ]
+  };
+}
+var paperclipSessionCodec = {
+  deserialize(raw) {
+    if (typeof raw === "string") {
+      try {
+        return asRecord(JSON.parse(raw));
+      } catch {
+        return null;
+      }
+    }
+    return asRecord(raw);
+  },
+  serialize(params) {
+    return params;
+  },
+  getDisplayId(params) {
+    return nonEmpty(params?.hiringId);
+  },
+  encode(state) {
+    return JSON.stringify(state ?? null);
+  },
+  decode(blob) {
+    if (!blob) return null;
+    try {
+      return JSON.parse(blob);
+    } catch {
+      return null;
+    }
+  }
+};
+function createCanonicalServerAdapter() {
+  return {
+    type,
+    execute: executePaperclip,
+    testEnvironment: testPaperclipEnvironment,
+    sessionCodec: paperclipSessionCodec,
+    getConfigSchema: getPaperclipConfigSchema,
+    agentConfigurationDoc
+  };
+}
+
 // server/src/crypto.ts
 async function verifyWebhookSignature(rawBody, signature, secret) {
   const crypto = await import("crypto");
@@ -1092,9 +1615,9 @@ async function cancelTask(config, taskId) {
 var TASK_MAX_RETRIES = 2;
 var TASK_RETRY_BASE_DELAY_MS = 1e3;
 var TASK_RETRY_MAX_DELAY_MS = 3e4;
-async function hireAgent(config, agentDid) {
+async function hireAgent(config, agentDid, options) {
   const client = new AgrentingClient(config);
-  return client.hireAgent(agentDid);
+  return client.hireAgent(agentDid, options);
 }
 async function getAgentProfile(config, agentDid) {
   const client = new AgrentingClient(config);
@@ -1136,6 +1659,10 @@ async function listHirings(config, options) {
   const client = new AgrentingClient(config);
   return client.listHirings(options);
 }
+async function cancelHiring(config, hiringId) {
+  const client = new AgrentingClient(config);
+  return client.cancelHiring(hiringId);
+}
 async function autoSelectAgent(config, options) {
   const client = new AgrentingClient(config);
   const capabilities = await client.listCapabilities();
@@ -1161,7 +1688,8 @@ async function autoSelectAgent(config, options) {
     const minRep = options.minReputation;
     filtered = filtered.filter((a) => {
       if (!a.reputation_score) return false;
-      return a.reputation_score >= minRep;
+      const reputation = Number(a.reputation_score);
+      return Number.isFinite(reputation) && reputation >= minRep;
     });
   }
   if (filtered.length === 0) {
@@ -1172,15 +1700,17 @@ async function autoSelectAgent(config, options) {
   const sortBy = options.sortBy ?? "reputation_score";
   if (options.preferAvailable ?? true) {
     filtered.sort((a, b) => {
-      const aAvail = a.availability_status === "available" ? 0 : 1;
-      const bAvail = b.availability_status === "available" ? 0 : 1;
+      const aAvail = (a.availability_status ?? a.availability ?? a.status) === "available" ? 0 : 1;
+      const bAvail = (b.availability_status ?? b.availability ?? b.status) === "available" ? 0 : 1;
       if (aAvail !== bAvail) return aAvail - bAvail;
       return 0;
     });
   }
   filtered.sort((a, b) => {
     if (sortBy === "reputation_score") {
-      return (b.reputation_score ?? 0) - (a.reputation_score ?? 0);
+      const aReputation = Number(a.reputation_score ?? 0);
+      const bReputation = Number(b.reputation_score ?? 0);
+      return (Number.isFinite(bReputation) ? bReputation : 0) - (Number.isFinite(aReputation) ? aReputation : 0);
     }
     if (sortBy === "base_price") {
       const aPrice = parseFloat(a.base_price ?? "999999");
@@ -1188,14 +1718,19 @@ async function autoSelectAgent(config, options) {
       return aPrice - bPrice;
     }
     if (sortBy === "availability") {
-      const aAvail = a.availability_status === "available" ? 0 : 1;
-      const bAvail = b.availability_status === "available" ? 0 : 1;
+      const aAvail = (a.availability_status ?? a.availability ?? a.status) === "available" ? 0 : 1;
+      const bAvail = (b.availability_status ?? b.availability ?? b.status) === "available" ? 0 : 1;
       return aAvail - bAvail;
     }
     return 0;
   });
   const selectedAgent = filtered[0];
-  const hireResult = await client.hireAgent(selectedAgent.did);
+  const hireResult = await client.hireAgent(selectedAgent.did, {
+    taskDescription: options.taskDescription,
+    capabilityRequested: options.capability,
+    price: selectedAgent.base_price ?? options.maxPrice ?? "0",
+    deliveryMode: "output"
+  });
   return {
     ...hireResult,
     selectedAgent
@@ -1291,19 +1826,7 @@ async function syncSkills(config, existing) {
     removed: existing.filter((s) => !remoteIds.has(s.id))
   };
 }
-var sessionCodec = {
-  encode(state) {
-    return JSON.stringify(state ?? null);
-  },
-  decode(blob) {
-    if (!blob) return null;
-    try {
-      return JSON.parse(blob);
-    } catch {
-      return null;
-    }
-  }
-};
+var sessionCodec = paperclipSessionCodec;
 async function invoke(config, params) {
   return execute(config, params);
 }
@@ -1322,11 +1845,15 @@ async function cancel(config, taskId) {
   }
 }
 function createServerAdapter() {
+  const canonical = createCanonicalServerAdapter();
   return {
+    ...canonical,
     name: "agrenting",
-    execute,
-    testEnvironment,
-    getConfigSchema,
+    // Legacy helpers remain available under explicit names. The canonical
+    // Paperclip keys above use AdapterExecutionContext and structured tests.
+    legacyExecute: execute,
+    legacyTestEnvironment: testEnvironment,
+    getLegacyConfigSchema: getConfigSchema,
     startWebhookListener,
     stopWebhookListener,
     registerWebhook,
@@ -1344,6 +1871,7 @@ function createServerAdapter() {
     sendMessageToHiring,
     getHiringMessages,
     retryHiring,
+    cancelHiring,
     getHiring,
     listHirings,
     autoSelectAgent,
@@ -1354,23 +1882,55 @@ function createServerAdapter() {
     getTransactions,
     deposit,
     withdraw,
-    // Canonical contract additions:
+    // Legacy pre-0.4 contract additions:
     invoke,
     status,
     cancel,
-    detectModel,
-    listSkills,
-    syncSkills,
-    sessionCodec
+    legacyDetectModel: detectModel,
+    legacyListSkills: listSkills,
+    legacySyncSkills: syncSkills
   };
 }
+
+// server/src/apps-v2.ts
+var agrentingAppGalleryEntry = {
+  key: "agrenting",
+  name: "Agrenting",
+  logoUrl: "https://www.google.com/s2/favicons?domain=agrenting.com&sz=64",
+  tagline: "Discover and hire governed remote AI agents.",
+  description: "Give Paperclip agents governed access to discover, hire, monitor, and cancel remote agents in the Agrenting marketplace.",
+  authKind: "api_key",
+  transportTemplate: {
+    transport: "remote_http",
+    url: "https://agrenting.com/mcp/hirer"
+  },
+  credentialFields: [
+    {
+      label: "Agrenting API key",
+      configPath: "credentials.authorization",
+      helpUrl: "https://agrenting.com/dashboard/api-keys",
+      required: true,
+      placement: "header",
+      key: "Authorization",
+      prefix: "Bearer "
+    }
+  ],
+  recommendedDefaults: {
+    access: "all_agents",
+    askFirstRiskLevels: ["write", "destructive"]
+  },
+  urlPatterns: ["https://agrenting.com/mcp/hirer*"]
+};
 export {
   AgrentingClient,
   MAX_POLLS,
   POLL_INTERVALS_MS,
+  agentConfigurationDoc,
+  agrentingAppGalleryEntry,
   autoSelectAgent,
   canSubmitTask,
   cancel,
+  cancelHiring,
   cancelTask,
   checkBalance,
   createServerAdapter,
@@ -1378,6 +1938,7 @@ export {
   deregisterWebhook,
   detectModel,
   execute,
+  executePaperclip,
   executeWithRetry,
   formatAgentResponse,
   formatInsufficientBalanceComment,
@@ -1389,14 +1950,17 @@ export {
   getConfigSchema,
   getHiring,
   getHiringMessages,
+  getPaperclipConfigSchema,
   getTaskMessages,
   getTaskProgress,
   getWebhookGracePeriodMs,
   hireAgent,
   invoke,
+  label,
   listCapabilities,
   listHirings,
   listSkills,
+  paperclipSessionCodec,
   pollTaskUntilDone,
   processIncomingMessage,
   reassignTask,
@@ -1409,6 +1973,8 @@ export {
   status,
   syncSkills,
   testEnvironment,
+  testPaperclipEnvironment,
+  type,
   unregisterTaskMapping,
   verifyWebhookSignature
 };