@agrentingai/paperclip-adapter 0.2.2 → 0.4.0

package/CHANGELOG.md

@@ -0,0 +1,86 @@
+# Changelog
+
+## 0.4.0 (2026-07-17)
+
+### Paperclip compatibility
+
+- Implement the current `@paperclipai/adapter-utils@2026.707.0`
+  `ServerAdapterModule` contract at the package root, including structured
+  execution results, environment checks, declarative configuration, and
+  hiring-session serialization.
+- Keep the pre-0.4 task, ledger, webhook, discovery, and UI helpers available
+  from `./server` and `./ui`; expose legacy factory operations under explicit
+  compatibility names.
+- Export an Agrenting Apps v2 gallery descriptor for a future upstream
+  Paperclip gallery submission. Current canary users can connect the same
+  Streamable HTTP endpoint through Apps → Connect your own tool.
+
+### Marketplace hiring
+
+- Send the canonical `task_description`, `capability_requested`, `price`,
+  delivery, task input, repository, message, and idempotency fields to
+  `POST /api/v1/agents/:did/hire`.
+- Use the Paperclip run ID as `client_idempotency_key`, poll the canonical
+  hiring lifecycle, return remote output, and best-effort cancel on timeout.
+- Read hiring messages from the canonical detail response, support hiring
+  cancellation, and parse paginated hiring lists.
+- Treat string-valued reputation scores safely during auto-selection.
+- Stop retrying non-retryable 4xx and API-envelope failures; retain retries for
+  network errors, HTTP 429, and server errors.
+
+### Security and documentation
+
+- Test canonical connectivity against the user-only hiring API instead of
+  requiring ledger access or a local agent context.
+- Default delivery to `output`; expose `repoUrl` for optional push delivery
+  while keeping repository credentials out of Paperclip adapter config.
+- Document one-key least-privilege scopes, per-hire price caps, current stable
+  external-adapter installation, canary Apps v2 setup, and the correct array
+  shape for `~/.paperclip/adapter-plugins.json`.
+
+## 0.3.0 (2026-05-06)
+
+### Features
+- Implement the canonical Paperclip `AgentAdapter` contract: `invoke`, `status`, `cancel`. The package now loads cleanly via Paperclip's external-adapter system (`~/.paperclip/adapter-plugins.json`).
+- Add `detectModel` for adapter-UI pre-population; reads the agent's `ai_provider`/`ai_model` from the Agrenting profile when available.
+- Add `listSkills` / `syncSkills` to surface the agent's capabilities as Paperclip skills.
+- Add `sessionCodec` (`encode`/`decode`) for session-state serialisation across heartbeats.
+- Re-export the canonical names from `./server` so plugin loaders find them by name.
+
+### Notes
+- Backward-compatible: `createServerAdapter()` still bundles the original surface plus the new canonical members.
+
+## 0.2.1 (2026-04-14)
+
+### Fixes
+- Remove `cacp` from package.json keywords
+- Remove CACP protocol references from README and UI adapter description
+- Update `packages/adapter-agrenting/tutorial.md` to use `@agrentingai/paperclip-adapter` instead of old package name
+- Add "Why Hire a Remote Agent" section to README explaining cost benefits
+
+## 0.2.0 (2026-04-14)
+
+### Features
+- Add `hireAgent` for agent hiring via the Agrenting platform
+- Add `getAgentProfile` for fetching agent profile data
+- Add `sendMessageToTask` for messaging existing tasks
+- Add `reassignTask` for task reassignment flows
+
+### Fixes
+- Fix empty `companyId` handling
+- Deduplicate polling requests
+- Add `AbortSignal` support for request cancellation
+- Improve adapter client and test coverage
+- Use `/api/v1/uploads` for documents with flat webhook shape
+- Fix critical retry, webhook security, and API compatibility bugs
+- Resolve merge conflicts — deduplicate types, functions, and exports
+
+### Docs
+- Add comprehensive tutorial for Paperclip + Agrenting adapter
+- Document messaging, reassignment, and profile flows
+
+## 0.1.0 (2026-04-12)
+
+- Initial release
+- Paperclip adapter for Agrenting platform
+- Server and UI exports

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AgRenting
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,314 +1,229 @@
 # @agrentingai/paperclip-adapter
 
-Paperclip adapter for [Agrenting](https://www.agrenting.com) — remote AI agent orchestration via the Agrenting platform.
+Hire remote marketplace agents from [Agrenting](https://agrenting.com) during
+Paperclip runs. Version 0.4.0 exposes Paperclip's current
+`ServerAdapterModule` contract from the package root and keeps the previous
+task, ledger, webhook, and marketplace helpers available from `./server`.
 
-## Overview
+## Choose the integration
 
-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.
+| Paperclip release | Recommended path | What it provides |
+|---|---|---|
+| Stable `v2026.707.0` | Install this external adapter | A Paperclip agent delegates each run to one configured Agrenting marketplace agent through the REST hiring lifecycle. |
+| Canary/master `v2026.717.0-canary.5` | Apps → Connect your own tool | Governed Agrenting MCP tools for discovery, hiring, cancellation, artifact lookup, and status checks. |
 
-## Why Hire a Remote Agent?
+The two paths can use the same scoped Agrenting `ap_*` key. Apps v2 stores the
+credential and applies Paperclip's tool governance; this adapter does not add a
+second MCP bridge. Agrenting's Streamable HTTP endpoint is:
 
-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 @agrentingai/paperclip-adapter
+```text
+https://agrenting.com/mcp/hirer
 ```
 
-## Usage
+The Apps gallery is currently compiled into Paperclip. This package exports
+`agrentingAppGalleryEntry` as a ready descriptor for a future upstream gallery
+submission, but current users should choose **Connect your own tool**.
 
-### Server Adapter
+## Create one least-privilege API key
 
-```typescript
-import { createServerAdapter, AgrentingClient } from "@agrentingai/paperclip-adapter/server";
+For this external adapter alone, create a user API key in the Agrenting
+dashboard with these minimum scopes:
 
-const adapter = createServerAdapter();
+- `agents:discover`
+- `agents:read` (the adapter resolves the configured DID's capability and price)
+- `hire:create`
+- `hirings:read`
+- `hirings:cancel`
 
-// Get the config schema (used by Paperclip to validate agent config)
-const schema = adapter.getConfigSchema();
+For one key shared by this adapter, Paperclip Apps, and the Agrenting Claude
+hire/status skills, also grant:
 
-// Test connectivity
-const result = await adapter.testEnvironment({
-  agrentingUrl: "https://www.agrenting.com",
-  apiKey: process.env.AGRENTING_API_KEY!,
-  agentDid: "did:agrenting:my-agent",
-});
+- `balance:read`
+- `artifacts:read`
 
-// Execute a task
-const output = await adapter.execute(
-  {
-    agrentingUrl: "https://www.agrenting.com",
-    apiKey: process.env.AGRENTING_API_KEY!,
-    agentDid: "did:agrenting:my-agent",
-  },
-  {
-    input: "Analyze this dataset and summarize findings",
-    capability: "data-analysis",
-    instructions: "You are a data analysis agent...",
-  }
-);
+Grant `deposits:create` only if the clients should fund the account, and grant
+`account:read` / `account:write` only if they should inspect or manage stored
+account integrations such as the GitHub credential used for push delivery.
 
-// Or use the client directly for more control
-const client = new AgrentingClient({
-  agrentingUrl: "https://www.agrenting.com",
-  apiKey: process.env.AGRENTING_API_KEY!,
-  agentDid: "did:agrenting:my-agent",
-});
-const task = await client.createTask({
-  providerAgentId: "did:agrenting:my-agent",
-  capability: "data-analysis",
-  input: "Analyze this dataset",
-});
-```
+Set `max_price_per_hire` on the key to cap each paid action. Keep the `ap_*`
+value in Paperclip's secret storage or Apps credential field; never put it in
+agent instructions, task text, logs, source control, or adapter JSON checked
+into a repository.
 
-### UI Adapter
+## External adapter installation
 
-```typescript
-import { parseConfigSchema } from "@agrentingai/paperclip-adapter/ui";
+Install the package through Paperclip's supported adapter manager:
 
-const info = parseConfigSchema();
-// info.label => "Agrenting"
-// info.configFields => array of form field definitions
-// info.buildAdapterConfig(formValues) => adapter config object
+```text
+Settings → Adapters → Install from npm → @agrentingai/paperclip-adapter
 ```
 
-## Configuration
-
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| `agrentingUrl` | URL | Yes | Agrenting platform base URL |
-| `apiKey` | string | Yes | API key for authentication |
-| `agentDid` | string | Yes | Target agent's decentralized identifier |
-| `webhookSecret` | string | No | Webhook signing secret for callbacks |
-| `webhookCallbackUrl` | URL | No | Override URL for webhook callbacks |
-| `pricingModel` | enum | No | `fixed`, `per-token`, or `subscription` |
-| `timeoutSec` | number | No | Task timeout in seconds (default: 600) |
-| `instructionsBundleMode` | enum | No | `inline` or `managed` |
+The equivalent API request is:
 
-## Payment & Escrow
-
-Tasks can optionally use Agrenting's escrow system by providing a `maxPrice` budget:
-
-```typescript
-const output = await adapter.execute(config, {
-  input: "Analyze this dataset and summarize findings",
-  capability: "data-analysis",
-  maxPrice: "5.00",        // Budget in USD — triggers escrow lock
-  paymentType: "crypto",   // "crypto" | "escrow" | "nowpayments"
-});
+```bash
+curl -X POST http://localhost:3100/api/adapters/install \
+  -H "Authorization: Bearer <paperclip-token>" \
+  -H "Content-Type: application/json" \
+  -d '{"packageName":"@agrentingai/paperclip-adapter"}'
 ```
 
-When `maxPrice` is set:
-1. The task is created with a price budget
-2. `createTaskPayment()` is called to lock funds in escrow
-3. Funds are released to the provider agent on completion
-4. Failed/cancelled tasks return funds to the client's available balance
+For local development, point Paperclip at this checkout:
 
-Check your balance before submitting:
-
-```typescript
-import { checkBalance, canSubmitTask } from "@agrentingai/paperclip-adapter/server";
+```bash
+curl -X POST http://localhost:3100/api/adapters/install \
+  -H "Authorization: Bearer <paperclip-token>" \
+  -H "Content-Type: application/json" \
+  -d '{"packageName":"/absolute/path/to/paperclip-adapter","isLocalPath":true}'
+```
 
-const balance = await checkBalance({ config });
-// balance.available, balance.escrow, balance.total
+Directly editing `~/.paperclip/adapter-plugins.json` is a development fallback.
+The current store is an array, not a package-name map:
 
-const ok = await canSubmitTask({ config });
-// { ok: true } or { ok: false, reason: "Insufficient balance: ..." }
+```json
+[
+  {
+    "packageName": "@agrentingai/paperclip-adapter",
+    "localPath": "/absolute/path/to/paperclip-adapter",
+    "type": "agrenting",
+    "installedAt": "2026-07-17T00:00:00.000Z"
+  }
+]
 ```
 
-## Marketplace Discovery
+Restart Paperclip after a manual store edit.
 
-Browse available agents on the Agrenting marketplace:
+## Configure an Agrenting adapter agent
 
-```typescript
-import { discoverAgents } from "@agrentingai/paperclip-adapter/server";
-
-const agents = await discoverAgents(config, {
-  capability: "data-analysis",
-  maxPrice: 5,
-  minReputation: 4.0,
-  sortBy: "reputation",
-  limit: 10,
-});
-```
+Create a Paperclip agent with adapter type `agrenting` and configure:
 
-## Task Progress Monitoring
+| Field | Required | Default | Purpose |
+|---|---:|---|---|
+| `agrentingUrl` | Yes | `https://agrenting.com` | Agrenting base URL. |
+| `apiKey` | Yes | — | Scoped user token beginning with `ap_`; stored as a secret. |
+| `agentDid` | Yes | — | Marketplace agent DID to hire for each run. |
+| `capabilityRequested` | No | First profile capability | Capability sent in the hiring. |
+| `price` | No | Agent base price | USD price offered for each hiring. |
+| `timeoutSec` | No | `600` | Maximum time to wait for a terminal hiring state. |
+| `pollIntervalMs` | No | `2000` | Hiring status polling interval. |
+| `deliveryMode` | No | `output` | `output` returns task output; `push` requests repository delivery. |
+| `repoUrl` | Push only | — | Repository target for push delivery. |
 
-Monitor task progress in real-time via webhooks or polling:
+Each Paperclip run creates one canonical Agrenting hiring and uses the
+Paperclip run ID as `client_idempotency_key`. The adapter polls
+`GET /api/v1/hirings/:id`, returns completed output through Paperclip logs and
+`resultJson`, and best-effort cancels the hiring on timeout.
 
-```typescript
-import { getTaskProgress } from "@agrentingai/paperclip-adapter/server";
-
-const progress = await getTaskProgress(config, taskId);
-// progress.status, progress.progressPercent, progress.progressMessage, progress.timeline
-```
+`output` is the safe default. For `push`, configure `repoUrl` and store the
+user's GitHub credential in Agrenting first. The canonical Paperclip adapter
+does not accept or persist a repository access token in its agent config.
 
-## Agent Hiring
+### Package-root contract
 
-Hire agents directly from the marketplace for auto-provisioning:
+Paperclip loads `createServerAdapter()` from the package root:
 
 ```typescript
-import { hireAgent, getAgentProfile } from "@agrentingai/paperclip-adapter/server";
+import { createServerAdapter } from "@agrentingai/paperclip-adapter";
 
-// Get agent profile before hiring
-const profile = await getAgentProfile(config, "did:agrenting:code-reviewer");
-// profile.name, profile.capabilities, profile.pricing_model, profile.reputation_score
+const adapter = createServerAdapter();
 
-// Hire the agent - returns hiring record + adapter config for auto-provisioning
-const result = await hireAgent(config, "did:agrenting:code-reviewer");
-// result.hiring.id, result.hiring.status
-// result.config.agentDid, result.config.pricingModel, result.config.basePrice
+adapter.type; // "agrenting"
+adapter.execute; // (AdapterExecutionContext) => AdapterExecutionResult
+adapter.testEnvironment; // structured Paperclip environment checks
+adapter.getConfigSchema?.(); // declarative adapter configuration fields
 ```
 
-## Auto-Select Mode
+The factory also exposes explicitly named compatibility helpers such as
+`legacyExecute`, `legacyTestEnvironment`, `getLegacyConfigSchema`,
+`legacyDetectModel`, `legacyListSkills`, and `legacySyncSkills`.
 
-Automatically discover and hire the best agent for a capability:
+## Paperclip Apps v2
 
-```typescript
-import { autoSelectAgent } from "@agrentingai/paperclip-adapter/server";
-
-// Auto-select best agent for a capability
-const result = await autoSelectAgent(config, {
-  capability: "code-review",
-  maxPrice: "10.00",           // Optional budget limit
-  minReputation: 4.0,          // Optional reputation filter
-  sortBy: "reputation_score",  // Sort by: reputation_score, base_price, availability
-  preferAvailable: true,       // Prefer agents with "available" status
-});
-
-// Result includes hiring, config, and selected agent profile
-// result.hiring, result.config, result.selectedAgent
-```
-
-## Task Messaging
+On `v2026.717.0-canary.5` or newer:
 
-Send follow-up messages to agents mid-task for bidirectional communication:
+1. Open **Apps** and choose **Connect your own tool**.
+2. Enter `https://agrenting.com/mcp/hirer`.
+3. Choose API-key authentication.
+4. Put the `ap_*` key in the `Authorization` header with the `Bearer ` prefix.
+5. Grant access to the intended agents.
+6. Keep ask-first approval enabled for `write` and `destructive` tools.
 
-```typescript
-import { sendMessageToTask, getTaskMessages } from "@agrentingai/paperclip-adapter/server";
-
-// Send message to active task
-await sendMessageToTask(config, taskId, "Please also check the error handling");
+Paid `hire_agent` calls are write actions. Paperclip should show the selected
+agent and price for approval before funds are committed. Cancellation and
+credential-clearing operations are destructive. Read-only discovery and status
+tools can run without a paid action.
 
-// Get message history
-const messages = await getTaskMessages(config, taskId);
-// messages[].sender_agent_id, messages[].content, messages[].created_at
-```
+Apps v2 posts JSON-RPC directly to the Streamable HTTP URL; no local bridge or
+legacy GET-SSE session is required. The older `/mcp/hirer/sse` transport remains
+an Agrenting fallback for clients that specifically require legacy SSE.
 
-## Task Reassignment
+## Direct REST client
 
-Reassign failed or cancelled tasks to a different agent:
+The server subpath exports the lower-level client and compatibility helpers:
 
 ```typescript
-import { reassignTask } from "@agrentingai/paperclip-adapter/server";
+import { AgrentingClient } from "@agrentingai/paperclip-adapter/server";
 
-// Reassign to specific agent
-await reassignTask(config, taskId, "did:agrenting:new-agent");
-
-// Or let the system auto-select a replacement
-await reassignTask(config, taskId);
-```
-
-## Task Retry with Backoff
-
-Execute tasks with automatic retry logic:
-
-```typescript
-import { executeWithRetry } from "@agrentingai/paperclip-adapter/server";
+const client = new AgrentingClient({
+  agrentingUrl: "https://agrenting.com",
+  apiKey: process.env.AGRENTING_API_KEY!,
+  agentDid: "did:agrenting:code-reviewer",
+});
 
-// Execute with automatic retries (default: 2 retries with exponential backoff)
-const result = await executeWithRetry(config, {
-  input: "Analyze this dataset",
-  capability: "data-analysis",
-  maxRetries: 3,  // Optional: override default max retries
+const created = await client.hireAgent("did:agrenting:code-reviewer", {
+  taskDescription: "Review the authentication changes and return findings.",
+  capabilityRequested: "code-review",
+  price: "8.50",
+  deliveryMode: "output",
+  clientIdempotencyKey: "paperclip-run-123",
+  taskInput: { issue_id: "issue-42" },
 });
 
-// If task fails, it will retry with exponential backoff (1s, 2s, 4s...)
+let hiring = created.hiring;
+while (!["completed", "failed", "cancelled", "disputed", "refunded"].includes(hiring.status)) {
+  await new Promise((resolve) => setTimeout(resolve, 2_000));
+  hiring = await client.getHiring(hiring.id);
+}
 ```
 
-## Hiring Management
+Marketplace hiring uses:
 
-Manage hirings and communicate with hired agents:
-
-```typescript
-import { listHirings, getHiring, sendMessageToHiring, retryHiring } from "@agrentingai/paperclip-adapter/server";
+1. `GET /api/v1/agents/discover?capability=...`
+2. `POST /api/v1/agents/:did/hire`
+3. `GET /api/v1/hirings/:id`
+4. `/api/v1/hirings/:id/messages`, `/cancel`, or `/retry` as needed
 
-// List active hirings
-const hirings = await listHirings(config, { status: "active" });
+Do not use `/api/v1/tasks` for user marketplace hiring. The task helpers kept
+in this package serve Agrenting's separate agent-to-agent execution model.
 
-// Get specific hiring
-const hiring = await getHiring(config, hiringId);
+## Legacy helper surface
 
-// Send message to hired agent
-await sendMessageToHiring(config, hiringId, "Ready to start the next phase");
-
-// Retry a failed hiring
-await retryHiring(config, hiringId, { reason: "previous timeout" });
-```
-
-## Capabilities Discovery
-
-List available capabilities to help with agent selection:
+Existing integrations may continue importing from
+`@agrentingai/paperclip-adapter/server`. The subpath retains task execution,
+polling, webhook verification, balance/payment helpers, discovery, hiring,
+messaging, retry, cancellation, and skill helpers. The UI subpath is also kept
+for backward compatibility:
 
 ```typescript
-import { listCapabilities } from "@agrentingai/paperclip-adapter/server";
-
-const capabilities = await listCapabilities(config);
-// capabilities[].name, capabilities[].description, capabilities[].agent_count, capabilities[].avg_price
-```
-
-## Architecture
-
-```
-@agrentingai/paperclip-adapter/
-├── server/          # Server-side adapter (Node.js)
-│   └── src/
-│       ├── adapter.ts       # createServerAdapter, execute, getConfigSchema
-│       ├── client.ts        # Agrenting HTTP API client (AgrentingClient)
-│       ├── types.ts         # TypeScript interfaces
-│       └── index.ts         # Public exports
-├── ui/              # UI-side adapter (browser, React optional)
-│   └── src/
-│       ├── adapter.ts       # parseConfigSchema, UI type definitions
-│       └── index.ts         # Public exports
-├── package.json
-├── tsconfig.json
-└── tsup.config.ts
+import { parseConfigSchema } from "@agrentingai/paperclip-adapter/ui";
 ```
 
-## Task Execution Flow
-
-1. Paperclip calls `adapter.execute()` with task input, agent config, and optional `maxPrice`
-2. Adapter performs a balance pre-check (`GET /api/v1/ledger/balance`)
-3. Task is submitted to `POST /api/v1/tasks` on Agrenting with `external_client: true`
-4. If `maxPrice` is set, `POST /api/v1/tasks/:id/payments` locks escrow funds
-5. Adapter monitors progress via webhook callback or exponential backoff polling
-6. On completion, escrow is released to the provider agent; on failure, funds return
-7. Result is returned to Paperclip's execution engine
-
-## Ledger & Payments
-
-```typescript
-import { getBalance, getTransactions, deposit, withdraw } from "@agrentingai/paperclip-adapter/server";
+New Paperclip installations do not need a custom UI parser because Paperclip
+can render the canonical declarative configuration schema and generic run
+output.
 
-// Check platform balance (available + escrowed + total)
-const balance = await getBalance(config);
+## Development
 
-// View recent transactions
-const txs = await getTransactions(config, { limit: 20 });
-
-// Deposit funds
-const depositResult = await deposit(config, { amount: "100", currency: "USD", paymentMethod: "crypto" });
-
-// Withdraw to external wallet
-const withdrawResult = await withdraw(config, { amount: "50", withdrawalAddressId: "addr-123" });
+```bash
+npm install
+npm test
+npm run typecheck
+npm run lint
+npm run build
+npm pack --dry-run
 ```
 
+Node.js 20 or newer is required.
+
 ## License
 
 MIT

package/VERSION

@@ -0,0 +1 @@
+0.4.0