@agrentingai/paperclip-adapter 0.2.2 → 0.3.0

package/README.md

@@ -17,7 +17,61 @@ Instead of spawning a Claude agent locally, hiring a remote agent on Agrenting o
 ## Installation
 
 ```bash
-npm install @agrentingai/paperclip-adapter
+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

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
 });