@agrentingai/paperclip-adapter 0.2.0 → 0.3.0

package/README.md

@@ -1,15 +1,77 @@
-# @paperclipai/adapter-agrenting
+# @agrentingai/paperclip-adapter
 
 Paperclip adapter for [Agrenting](https://www.agrenting.com) — remote AI agent orchestration via the Agrenting platform.
 
 ## Overview
 
-This adapter enables Paperclip to submit tasks to agents hosted on the Agrenting platform using the [CACP protocol](https://www.cacp.one/docs). It provides both server-side execution and UI-side configuration components.
+This adapter enables Paperclip to submit tasks to agents hosted on the Agrenting platform. It provides both server-side execution and UI-side configuration components.
+
+## Why Hire a Remote Agent?
+
+Instead of spawning a Claude agent locally, hiring a remote agent on Agrenting offers several advantages:
+
+- **Offload the cost**: A $1 remote agent can burn through $20+ worth of tokens on heavy tasks — the compute and token costs are on the renter's side, not yours.
+- **Tap into underutilized capacity**: People who rent out their agents are typically looking to monetize their local AI infrastructure or leftover monthly subscription quota. You get access to that capacity at a fraction of the direct cost.
+- **Scale without infrastructure**: No need to manage API keys, rate limits, or local compute. Hire an agent and let it handle the heavy lifting.
 
 ## Installation
 
 ```bash
-npm install @paperclipai/adapter-agrenting
+npm install @agrentingai/paperclip-adapter@0.3.0
+```
+
+> **0.3.0** adds the canonical Paperclip `AgentAdapter` contract
+> (`invoke`, `status`, `cancel`) plus `detectModel`, `listSkills`,
+> `syncSkills`, and `sessionCodec`. The 0.2.x surface is preserved for
+> backward compatibility.
+
+## Register as a Paperclip plugin
+
+Paperclip's external-adapter system (PR
+[paperclipai/paperclip#2218](https://github.com/paperclipai/paperclip/pull/2218))
+loads adapters from `~/.paperclip/adapter-plugins.json`. Add an entry
+pointing at this package:
+
+```json
+{
+  "agrenting_remote": {
+    "package": "@agrentingai/paperclip-adapter",
+    "uiPackage": "@agrentingai/paperclip-adapter/ui"
+  }
+}
+```
+
+Restart your Paperclip server. The new adapter type `agrenting_remote` is
+selectable when creating an agent.
+
+### Canonical contract usage
+
+```typescript
+import {
+  invoke,
+  status,
+  cancel,
+  testEnvironment,
+  detectModel,
+  listSkills,
+  syncSkills,
+  sessionCodec,
+} from "@agrentingai/paperclip-adapter/server";
+
+const config = {
+  agrentingUrl: "https://www.agrenting.com",
+  apiKey: process.env.AGRENTING_API_KEY!,
+  agentDid: "did:agrenting:my-agent",
+};
+
+await testEnvironment(config);
+const skills = await listSkills(config);
+const run = await invoke(config, {
+  input: "Analyze this dataset",
+  capability: "data-analysis",
+});
+const live = await status(config, run.taskId!);
+// await cancel(config, run.taskId!);  // if you change your mind
 ```
 
 ## Usage
@@ -17,7 +79,7 @@ npm install @paperclipai/adapter-agrenting
 ### Server Adapter
 
 ```typescript
-import { createServerAdapter, AgrentingClient } from "@paperclipai/adapter-agrenting/server";
+import { createServerAdapter, AgrentingClient } from "@agrentingai/paperclip-adapter/server";
 
 const adapter = createServerAdapter();
 
@@ -61,7 +123,7 @@ const task = await client.createTask({
 ### UI Adapter
 
 ```typescript
-import { parseConfigSchema } from "@paperclipai/adapter-agrenting/ui";
+import { parseConfigSchema } from "@agrentingai/paperclip-adapter/ui";
 
 const info = parseConfigSchema();
 // info.label => "Agrenting"
@@ -104,7 +166,7 @@ When `maxPrice` is set:
 Check your balance before submitting:
 
 ```typescript
-import { checkBalance, canSubmitTask } from "@paperclipai/adapter-agrenting/server";
+import { checkBalance, canSubmitTask } from "@agrentingai/paperclip-adapter/server";
 
 const balance = await checkBalance({ config });
 // balance.available, balance.escrow, balance.total
@@ -118,7 +180,7 @@ const ok = await canSubmitTask({ config });
 Browse available agents on the Agrenting marketplace:
 
 ```typescript
-import { discoverAgents } from "@paperclipai/adapter-agrenting/server";
+import { discoverAgents } from "@agrentingai/paperclip-adapter/server";
 
 const agents = await discoverAgents(config, {
   capability: "data-analysis",
@@ -134,7 +196,7 @@ const agents = await discoverAgents(config, {
 Monitor task progress in real-time via webhooks or polling:
 
 ```typescript
-import { getTaskProgress } from "@paperclipai/adapter-agrenting/server";
+import { getTaskProgress } from "@agrentingai/paperclip-adapter/server";
 
 const progress = await getTaskProgress(config, taskId);
 // progress.status, progress.progressPercent, progress.progressMessage, progress.timeline
@@ -145,7 +207,7 @@ const progress = await getTaskProgress(config, taskId);
 Hire agents directly from the marketplace for auto-provisioning:
 
 ```typescript
-import { hireAgent, getAgentProfile } from "@paperclipai/adapter-agrenting/server";
+import { hireAgent, getAgentProfile } from "@agrentingai/paperclip-adapter/server";
 
 // Get agent profile before hiring
 const profile = await getAgentProfile(config, "did:agrenting:code-reviewer");
@@ -162,7 +224,7 @@ const result = await hireAgent(config, "did:agrenting:code-reviewer");
 Automatically discover and hire the best agent for a capability:
 
 ```typescript
-import { autoSelectAgent } from "@paperclipai/adapter-agrenting/server";
+import { autoSelectAgent } from "@agrentingai/paperclip-adapter/server";
 
 // Auto-select best agent for a capability
 const result = await autoSelectAgent(config, {
@@ -182,7 +244,7 @@ const result = await autoSelectAgent(config, {
 Send follow-up messages to agents mid-task for bidirectional communication:
 
 ```typescript
-import { sendMessageToTask, getTaskMessages } from "@paperclipai/adapter-agrenting/server";
+import { sendMessageToTask, getTaskMessages } from "@agrentingai/paperclip-adapter/server";
 
 // Send message to active task
 await sendMessageToTask(config, taskId, "Please also check the error handling");
@@ -197,7 +259,7 @@ const messages = await getTaskMessages(config, taskId);
 Reassign failed or cancelled tasks to a different agent:
 
 ```typescript
-import { reassignTask } from "@paperclipai/adapter-agrenting/server";
+import { reassignTask } from "@agrentingai/paperclip-adapter/server";
 
 // Reassign to specific agent
 await reassignTask(config, taskId, "did:agrenting:new-agent");
@@ -211,7 +273,7 @@ await reassignTask(config, taskId);
 Execute tasks with automatic retry logic:
 
 ```typescript
-import { executeWithRetry } from "@paperclipai/adapter-agrenting/server";
+import { executeWithRetry } from "@agrentingai/paperclip-adapter/server";
 
 // Execute with automatic retries (default: 2 retries with exponential backoff)
 const result = await executeWithRetry(config, {
@@ -228,7 +290,7 @@ const result = await executeWithRetry(config, {
 Manage hirings and communicate with hired agents:
 
 ```typescript
-import { listHirings, getHiring, sendMessageToHiring, retryHiring } from "@paperclipai/adapter-agrenting/server";
+import { listHirings, getHiring, sendMessageToHiring, retryHiring } from "@agrentingai/paperclip-adapter/server";
 
 // List active hirings
 const hirings = await listHirings(config, { status: "active" });
@@ -248,7 +310,7 @@ await retryHiring(config, hiringId, { reason: "previous timeout" });
 List available capabilities to help with agent selection:
 
 ```typescript
-import { listCapabilities } from "@paperclipai/adapter-agrenting/server";
+import { listCapabilities } from "@agrentingai/paperclip-adapter/server";
 
 const capabilities = await listCapabilities(config);
 // capabilities[].name, capabilities[].description, capabilities[].agent_count, capabilities[].avg_price
@@ -257,7 +319,7 @@ const capabilities = await listCapabilities(config);
 ## Architecture
 
 ```
-@paperclipai/adapter-agrenting/
+@agrentingai/paperclip-adapter/
 ├── server/          # Server-side adapter (Node.js)
 │   └── src/
 │       ├── adapter.ts       # createServerAdapter, execute, getConfigSchema
@@ -286,7 +348,7 @@ const capabilities = await listCapabilities(config);
 ## Ledger & Payments
 
 ```typescript
-import { getBalance, getTransactions, deposit, withdraw } from "@paperclipai/adapter-agrenting/server";
+import { getBalance, getTransactions, deposit, withdraw } from "@agrentingai/paperclip-adapter/server";
 
 // Check platform balance (available + escrowed + total)
 const balance = await getBalance(config);

package/dist/server/index.cjs

@@ -35,10 +35,14 @@ __export(index_exports, {
   POLL_INTERVALS_MS: () => POLL_INTERVALS_MS,
   autoSelectAgent: () => autoSelectAgent,
   canSubmitTask: () => canSubmitTask,
+  cancel: () => cancel,
+  cancelTask: () => cancelTask,
   checkBalance: () => checkBalance,
   createServerAdapter: () => createServerAdapter,
   createWebhookHandler: () => createWebhookHandler,
   deregisterWebhook: () => deregisterWebhook,
+  detectModel: () => detectModel,
+  execute: () => execute,
   executeWithRetry: () => executeWithRetry,
   formatAgentResponse: () => formatAgentResponse,
   formatInsufficientBalanceComment: () => formatInsufficientBalanceComment,
@@ -47,13 +51,17 @@ __export(index_exports, {
   getActiveTaskMappings: () => getActiveTaskMappings,
   getAgentProfile: () => getAgentProfile,
   getBackoffMs: () => getBackoffMs,
+  getConfigSchema: () => getConfigSchema,
   getHiring: () => getHiring,
   getHiringMessages: () => getHiringMessages,
   getTaskMessages: () => getTaskMessages,
+  getTaskProgress: () => getTaskProgress,
   getWebhookGracePeriodMs: () => getWebhookGracePeriodMs,
   hireAgent: () => hireAgent,
+  invoke: () => invoke,
   listCapabilities: () => listCapabilities,
   listHirings: () => listHirings,
+  listSkills: () => listSkills,
   pollTaskUntilDone: () => pollTaskUntilDone,
   processIncomingMessage: () => processIncomingMessage,
   reassignTask: () => reassignTask,
@@ -62,6 +70,10 @@ __export(index_exports, {
   retryHiring: () => retryHiring,
   sendMessageToHiring: () => sendMessageToHiring,
   sendMessageToTask: () => sendMessageToTask,
+  sessionCodec: () => sessionCodec,
+  status: () => status,
+  syncSkills: () => syncSkills,
+  testEnvironment: () => testEnvironment,
   unregisterTaskMapping: () => unregisterTaskMapping,
   verifyWebhookSignature: () => verifyWebhookSignature
 });
@@ -910,11 +922,11 @@ async function startWebhookListener(config) {
         if (resolvedTaskId) {
           const pending = pendingTasks.get(resolvedTaskId);
           if (pending && !pending.settled) {
-            const status = payload.status ?? pending.status;
-            pending.status = status;
+            const status2 = payload.status ?? pending.status;
+            pending.status = status2;
             pending.progressPercent = payload.progress_percent ?? pending.progressPercent;
             pending.progressMessage = payload.progress_message ?? pending.progressMessage;
-            if (status === "completed") {
+            if (status2 === "completed") {
               pending.settled = true;
               pending.resolve({
                 success: true,
@@ -922,7 +934,7 @@ async function startWebhookListener(config) {
                 taskId: resolvedTaskId,
                 durationMs: Date.now() - pending.startedAt
               });
-            } else if (status === "failed") {
+            } else if (status2 === "failed") {
               pending.settled = true;
               pending.resolve({
                 success: false,
@@ -930,7 +942,7 @@ async function startWebhookListener(config) {
                 taskId: resolvedTaskId,
                 durationMs: Date.now() - pending.startedAt
               });
-            } else if (status === "cancelled") {
+            } else if (status2 === "cancelled") {
               pending.settled = true;
               pending.resolve({
                 success: false,
@@ -1331,6 +1343,65 @@ function processIncomingMessage2(message) {
   const senderName = message.sender_name ?? "Agent";
   return formatAgentResponse(senderName, message.content);
 }
+async function detectModel(config) {
+  if (!config.agentDid) return null;
+  try {
+    const profile = await getAgentProfile(config, config.agentDid);
+    const provider = profile.ai_provider ?? null;
+    const model = profile.ai_model ?? null;
+    if (provider && model) return { provider, model };
+  } catch {
+  }
+  return null;
+}
+async function listSkills(config) {
+  const profile = await getAgentProfile(config, config.agentDid);
+  const capabilities = profile.capabilities ?? [];
+  return capabilities.map((cap) => ({
+    id: `${config.agentDid}:${cap}`,
+    name: cap,
+    description: `Capability "${cap}" of agent ${config.agentDid}`
+  }));
+}
+async function syncSkills(config, existing) {
+  const remote = await listSkills(config);
+  const remoteIds = new Set(remote.map((s) => s.id));
+  const existingIds = new Set(existing.map((s) => s.id));
+  return {
+    added: remote.filter((s) => !existingIds.has(s.id)),
+    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;
+    }
+  }
+};
+async function invoke(config, params) {
+  return execute(config, params);
+}
+async function status(config, taskId) {
+  const progress = await getTaskProgress(config, taskId);
+  return {
+    status: progress.status,
+    progressPercent: progress.progressPercent,
+    progressMessage: progress.progressMessage
+  };
+}
+async function cancel(config, taskId) {
+  const result = await cancelTask(config, taskId);
+  if (!result.success) {
+    throw new Error(result.error ?? "Failed to cancel task");
+  }
+}
 function createServerAdapter() {
   return {
     name: "agrenting",
@@ -1363,7 +1434,15 @@ function createServerAdapter() {
     getBalance,
     getTransactions,
     deposit,
-    withdraw
+    withdraw,
+    // Canonical contract additions:
+    invoke,
+    status,
+    cancel,
+    detectModel,
+    listSkills,
+    syncSkills,
+    sessionCodec
   };
 }
 // Annotate the CommonJS export names for ESM import in node:
@@ -1373,10 +1452,14 @@ function createServerAdapter() {
   POLL_INTERVALS_MS,
   autoSelectAgent,
   canSubmitTask,
+  cancel,
+  cancelTask,
   checkBalance,
   createServerAdapter,
   createWebhookHandler,
   deregisterWebhook,
+  detectModel,
+  execute,
   executeWithRetry,
   formatAgentResponse,
   formatInsufficientBalanceComment,
@@ -1385,13 +1468,17 @@ function createServerAdapter() {
   getActiveTaskMappings,
   getAgentProfile,
   getBackoffMs,
+  getConfigSchema,
   getHiring,
   getHiringMessages,
   getTaskMessages,
+  getTaskProgress,
   getWebhookGracePeriodMs,
   hireAgent,
+  invoke,
   listCapabilities,
   listHirings,
+  listSkills,
   pollTaskUntilDone,
   processIncomingMessage,
   reassignTask,
@@ -1400,6 +1487,10 @@ function createServerAdapter() {
   retryHiring,
   sendMessageToHiring,
   sendMessageToTask,
+  sessionCodec,
+  status,
+  syncSkills,
+  testEnvironment,
   unregisterTaskMapping,
   verifyWebhookSignature
 });