@absol-labs/agent 0.7.3 → 0.9.0

package/docs/eliza.md

@@ -0,0 +1,109 @@
+# ElizaOS Plugin
+
+Metrik ships a real ElizaOS plugin so an Eliza agent can **hire verified services**,
+monitor them, and reclaim unspent funds out of the box — without ever bypassing the
+signed spend mandate. It reuses the exact same SDK client and mandate budget-guard as
+the Coinbase AgentKit action provider (`src/frameworks/agentkit.ts`); the business logic
+is not forked.
+
+> _x402 proves the payment, Metrik proves the delivery._
+
+The plugin lives in [`src/frameworks/eliza.ts`](../src/frameworks/eliza.ts).
+
+## Actions
+
+| Action (Eliza name)     | What it does                                                                                                                                                                                                                           |
+| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `HIRE_VERIFIED_SERVICE` | Escrow USDC on Base for a per-second, oracle-verified delivery stream to a seller. Fails closed **before any transaction** if the hire would breach the signed mandate.                                                                |
+| `CHECK_STREAM_STATUS`   | Read verified accrual, current state, and claimable/reclaimable USDC. In V2, failed or unproven intervals do not advance entitlement; buyer close or expiry ends the session. Sets `shouldStop` when the stream is no longer `active`. |
+| `RECLAIM_UNSPENT`       | Return unspent escrowed USDC to the buyer (optionally `closeFirst`), under the original mandate and the V2 checkpoint / escape-window rules.                                                                                           |
+| `CLOSE_STREAM`          | Finalize accrual and halt further payment, under the original mandate.                                                                                                                                                                 |
+
+## Install
+
+`@elizaos/core` is a peer of `@absol-labs/agent`.
+
+```bash
+pnpm add @absol-labs/agent @elizaos/core
+```
+
+## Env
+
+The plugin needs a signing wallet + an SDK client pointed at the Metrik escrow. On
+testnet you may pass a raw private key; in production inject a Coinbase CDP wallet
+instead (`createWalletBackedAgentClient` accepts either).
+
+```
+METRIK_AGENT_RPC_URL      Base Sepolia RPC URL
+METRIK_AGENT_ESCROW       Metrik escrow contract address (0x...)
+METRIK_AGENT_USDC         Settlement USDC token address (0x...)
+METRIK_AGENT_PRIVATE_KEY  Agent signing key (testnet only)
+```
+
+## Add the plugin to a character
+
+The Metrik plugin is a **factory** — it needs a wallet-backed client — so it is built
+programmatically and attached to the agent, rather than referenced by a bare package
+name (the runtime cannot inject a funded wallet into a string-named plugin). A full,
+runnable-shaped example lives in
+[`examples/metrik-character.ts`](../examples/metrik-character.ts).
+
+```ts
+import { http } from "viem";
+import { baseSepolia } from "viem/chains";
+import { createMetrikElizaPlugin } from "@absol-labs/agent/eliza";
+import { createWalletBackedAgentClient } from "@absol-labs/agent";
+
+const { agentClient } = await createWalletBackedAgentClient(
+  {
+    chain: baseSepolia,
+    transport: http(process.env.METRIK_AGENT_RPC_URL!),
+    escrow: process.env.METRIK_AGENT_ESCROW! as `0x${string}`,
+    usdc: process.env.METRIK_AGENT_USDC! as `0x${string}`,
+    settlementTarget: {
+      chainId: baseSepolia.id,
+      escrow: process.env.METRIK_AGENT_ESCROW! as `0x${string}`,
+    },
+  },
+  { privateKey: process.env.METRIK_AGENT_PRIVATE_KEY as `0x${string}` },
+);
+
+const metrikPlugin = createMetrikElizaPlugin({ agentClient });
+
+export default {
+  agents: [
+    {
+      character: { name: "Metrik Buyer", plugins: [] },
+      plugins: [metrikPlugin],
+    },
+  ],
+};
+```
+
+## Action envelope
+
+Eliza actions receive a namespaced payload under `content.metrik`. Build it with
+`createMetrikElizaContent()` rather than hand-rolling the envelope:
+
+```ts
+import { createMetrikElizaContent } from "@absol-labs/agent/eliza";
+
+const hire = createMetrikElizaContent("HIRE_VERIFIED_SERVICE", {
+  operator: "0x2222222222222222222222222222222222222222", // seller payout wallet
+  serviceRef: "0x1111...1111", // bytes32 service id the oracle verifies
+  budgetUsdc: "90000000", // atomic units, 6 decimals
+  ratePerSecondUsdc: "1000000",
+  maxDurationSeconds: 3600,
+  signedMandate, // owner-signed spend mandate
+});
+```
+
+`RECLAIM_UNSPENT` and `CLOSE_STREAM` take `{ streamId, signedMandate }`
+(`RECLAIM_UNSPENT` also accepts `closeFirst`). `CHECK_STREAM_STATUS` takes `{ streamId }`.
+
+## Publishing
+
+The plugin is publish-ready under `@absol-labs/agent`. Submitting it to the ElizaOS
+plugin **registry** (or an npm publish) requires registry/npm credentials and a
+registry PR — those steps are human-gated and are **not** performed by this package.
+See the PR description for the follow-up.

package/docs/langchain.md

@@ -0,0 +1,63 @@
+# LangChain Adapter
+
+The Phase 2 LangChain surface is a small, mandate-gated toolset built on the
+existing agent client:
+
+- `hire_verified_service`
+- `check_stream_status`
+- `reclaim_unspent`
+
+Create them with [`createLangChainVerifiedStreamTools()`](../src/frameworks/langchain.ts).
+
+## Safety model
+
+- `hire_verified_service` checks the signed mandate before any stream open.
+- `reclaim_unspent` passes the same signed-mandate context into the agent client,
+  which re-checks authorization before the SDK can write.
+- `check_stream_status` is read-only and also returns `shouldStop` for a closed
+  stream. In V2, verification gaps do not auto-pause the stream; the buyer must
+  explicitly close it to end further exposure.
+
+## Example loop
+
+```ts
+import { createLangChainVerifiedStreamTools } from "@absol-labs/agent/langchain";
+
+const tools = createLangChainVerifiedStreamTools({
+  agentClient,
+  now: () => Math.floor(Date.now() / 1000),
+  mandateStateResolver: {
+    getSpentSoFarUsdc: async () => spentSoFarUsdc,
+    getRevokedMandateIds: async () => revokedMandateIds,
+  },
+});
+
+const opened = await tools.hire.invoke({
+  operator: "0xYourOperator",
+  serviceRef: "0xYourServiceRef",
+  budgetUsdc: "90000000",
+  ratePerSecondUsdc: "1000000",
+  maxDurationSeconds: 3600,
+  signedMandate,
+});
+
+for (;;) {
+  const status = await tools.status.invoke({ streamId: opened.streamId });
+  if (status.shouldStop) break;
+  await new Promise((resolve) => setTimeout(resolve, 10_000));
+}
+
+await tools.reclaim.invoke({
+  streamId: opened.streamId,
+  closeFirst: true,
+  signedMandate,
+});
+```
+
+## Reviewer checklist
+
+1. Provide a real `VerifiedStreamAgentClient` or compatible wrapper.
+2. Provide a real signed mandate plus resolver-backed cumulative-spend /
+   revocation state.
+3. Use `status.shouldStop` to halt work when the stream is no longer active.
+4. Reclaim explicitly through `reclaim_unspent` when the task ends or quality drops.

package/docs/mcp-hosted.md

@@ -0,0 +1,137 @@
+# Hosted MCP over Streamable HTTP
+
+The agent lane ships two MCP transports over the **same** tool set
+(`hire_verified_service`, `check_stream_status`, `reclaim_unspent`, `list_streams`,
+and the optional `prove_https_response`):
+
+- **stdio** (`src/mcp/stdio.ts`, `pnpm mcp:stdio`) — local dev, one process per
+  caller. Unchanged.
+- **Streamable HTTP** (`src/mcp/http.ts` + `src/mcp/http-server.ts`,
+  `pnpm mcp:http`) — a hosted, **multi-tenant**, per-caller-authenticated
+  endpoint suitable for deployment. This document covers the HTTP transport.
+
+The HTTP transport uses the MCP SDK's `StreamableHTTPServerTransport` (the
+current remote transport; the deprecated HTTP+SSE transport is not used). It
+speaks the standard Streamable HTTP session contract: `POST /mcp` for JSON-RPC
+requests (an `initialize` opens a session and the server returns an
+`Mcp-Session-Id` header), `GET /mcp` for the server→client SSE stream, and
+`DELETE /mcp` to end a session — all carrying the `Mcp-Session-Id` header once a
+session exists.
+
+## Security model (fail-closed)
+
+- **Per-caller auth before anything runs.** Every request must carry
+  `Authorization: Bearer <token>`. A missing or invalid token is rejected with
+  `401` **before** any MCP session is created or any tool executes — so an
+  unauthenticated request can never move funds or read another caller's state.
+- **Constant-time token comparison.** Tokens are compared via SHA-256 +
+  `crypto.timingSafeEqual` across all configured tenants with no early exit;
+  tokens are never logged.
+- **Tenant isolation.** Each valid token maps to its **own** tenant context —
+  its own wallet-backed agent client and its own stream registry. One caller
+  can never drive another caller's funds or observe another caller's streams.
+  MCP sessions are bound to the tenant that opened them: presenting another
+  tenant's `Mcp-Session-Id` is rejected with `403`; an unknown session id is
+  `404`.
+- **Refuses to run open.** If no tenants/tokens are configured, the server
+  throws before binding — it will never serve an unauthenticated endpoint.
+- **No stack traces leak.** Errors are returned as generic JSON-RPC error
+  envelopes; internal detail stays server-side.
+- **CORS** is off by default (same-origin / non-browser clients). Set
+  `METRIK_MCP_ALLOWED_ORIGINS` to opt specific browser origins in.
+
+## Environment contract
+
+| Variable                     | Required | Default   | Meaning                                                                |
+| ---------------------------- | -------- | --------- | ---------------------------------------------------------------------- |
+| `METRIK_MCP_TENANTS`         | **yes**  | —         | JSON array of tenant configs (below). Empty/missing ⇒ refuse to start. |
+| `PORT` / `METRIK_MCP_PORT`   | no       | `8080`    | Listen port.                                                           |
+| `METRIK_MCP_HOST`            | no       | `0.0.0.0` | Bind host.                                                             |
+| `METRIK_MCP_PATH`            | no       | `/mcp`    | MCP endpoint path.                                                     |
+| `METRIK_MCP_ALLOWED_ORIGINS` | no       | _(none)_  | Comma-separated CORS origins, or `*`.                                  |
+
+Each entry in `METRIK_MCP_TENANTS` is:
+
+```jsonc
+{
+  "id": "acme", // stable tenant id (routing/logging only)
+  "token": "<secret-bearer>", // the caller's bearer token — never logged
+  "env": {
+    // optional: layered over the process env to
+    "METRIK_AGENT_CDP_OWNER_NAME": "acme-agent", // build THIS tenant's wallet
+  },
+}
+```
+
+A tenant's `env` is merged over the process environment and used to build that
+tenant's isolated, wallet-backed agent client via the same
+`METRIK_AGENT_*` / wallet / Reclaim variables the stdio server uses
+(`METRIK_AGENT_RPC_URL`, `METRIK_AGENT_ESCROW`, `METRIK_AGENT_USDC`,
+`METRIK_AGENT_PRIVATE_KEY` **or** the `CDP_*` wallet vars, etc. — see
+`src/mcp/server.ts` and `src/wallet/provider.ts`). Tenants that share the same
+network but need distinct wallets override only the wallet vars in their `env`.
+
+> Provide tokens and wallet secrets through your host's secret manager / env UI.
+> Never commit them, and never bake them into the image.
+
+## Run it
+
+```bash
+export METRIK_AGENT_RPC_URL="https://base-sepolia.example/rpc"
+export METRIK_AGENT_ESCROW="0x21948a5E6AE8d9A3D1050791AB6138657Fb54286"
+export METRIK_AGENT_USDC="0x036CbD53842c5426634e7929541eC2318f3dCF7e"
+# ... wallet vars (private key or CDP) ...
+export METRIK_MCP_TENANTS='[{"id":"acme","token":"REPLACE_WITH_SECRET"}]'
+export PORT=8080
+
+pnpm mcp:http          # dev (tsx)
+# or, from a build:
+node dist/mcp/http-server.js
+```
+
+The process binds `0.0.0.0:$PORT` and logs only its address (never secrets).
+`SIGINT`/`SIGTERM` trigger a graceful shutdown of all live sessions.
+
+## Connect an MCP client
+
+Point any Streamable HTTP MCP client at `http(s)://<host>:<port>/mcp` with the
+tenant's bearer token. With the TypeScript SDK:
+
+```ts
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+
+const transport = new StreamableHTTPClientTransport(
+  new URL("https://mcp.example.com/mcp"),
+  {
+    requestInit: {
+      headers: { Authorization: `Bearer ${process.env.METRIK_MCP_TOKEN}` },
+    },
+  },
+);
+const client = new Client({ name: "my-agent", version: "1.0.0" });
+await client.connect(transport);
+await client.listTools();
+await client.callTool({ name: "list_streams", arguments: {} });
+```
+
+Claude Desktop / other config-driven clients: add a remote MCP server pointing
+at the `/mcp` URL and set the `Authorization: Bearer <token>` header. The
+transport handles the session id, POST/GET/DELETE lifecycle automatically.
+
+## Programmatic embedding
+
+The transport is also exported from the package root for hosting inside another
+service:
+
+- `createHostedMcpHttpServer({ resolver, path?, allowedOrigins? })` — build a
+  Node `http.Server` around a `TenantResolver`; `listen(port, host)` /
+  `close()`.
+- `StaticTenantResolver` — constant-time, in-memory resolver over a list of
+  `HostedMcpTenant`s.
+- `parseHostedMcpServerConfig(env)` / `createHostedMcpTenants(config)` /
+  `startHostedMcpHttpServerFromEnv(env)` — the env-driven wiring used by
+  `pnpm mcp:http`.
+
+Supply your own `TenantResolver` to source tokens/tenants from a database or a
+secrets service instead of env.

package/docs/privy-embedded-wallet.md

@@ -0,0 +1,102 @@
+# Privy embedded-wallet integration
+
+`@absol-labs/agent` provides a small, provider-neutral adapter for a
+user-owned Privy embedded **EOA**. The site or host application must first
+authenticate the user with Privy's client SDK and obtain that user's EIP-1193
+wallet provider. The agent package does not authenticate users, create wallets
+from an app id alone, receive an app secret, or persist key material.
+
+```ts
+import { http } from "viem";
+import { baseSepolia } from "viem/chains";
+import {
+  createWalletBackedAgentClient,
+  type PrivyEip1193Provider,
+} from "@absol-labs/agent";
+
+// The authenticated Privy wallet/session is created by the host application.
+const provider: PrivyEip1193Provider =
+  await host.getAuthenticatedPrivyProvider();
+const address = await host.getAuthenticatedPrivyAddress();
+
+const { wallet, agentClient } = await createWalletBackedAgentClient(
+  {
+    chain: baseSepolia,
+    // The Privy mode replaces this transport with the authenticated provider
+    // so writes use eth_sendTransaction. It remains the default for other modes.
+    transport: http(process.env.BASE_SEPOLIA_RPC_URL!),
+    escrow: "0x…",
+    usdc: "0x…",
+  },
+  {
+    privy: {
+      appId: "your-public-privy-app-id",
+      address,
+      provider,
+      chainId: 84532,
+    },
+  },
+);
+
+// `wallet.account` is a viem-compatible JSON-RPC EOA. Every autonomous write
+// still goes through the signed Metrik spend-mandate checks in agentClient.
+await wallet.account.signMessage({ message: "user-approved test" });
+```
+
+The adapter verifies Base Sepolia (`chainId: 84532`) and the configured address
+against `eth_chainId` and `eth_accounts` before construction and before every
+`personal_sign` or `eth_signTypedData_v4` request. Contract writes are sent
+through the same authenticated provider with `eth_sendTransaction`; the adapter
+does not claim access to raw transaction signatures. A network or account switch
+fails closed with `PrivyEmbeddedWalletError`.
+
+## Headless external-agent session
+
+The Metrik dApp can attach a Privy additional signer under a non-empty Privy policy,
+collect an owner-signed Metrik spend mandate, and exchange those approvals for a
+short-lived broker token. An external agent adapts the copied session JSON without any
+Privy app secret or wallet key:
+
+```ts
+import {
+  createPrivySessionProvider,
+  createWalletBackedAgentClient,
+} from "@absol-labs/agent";
+
+const session = JSON.parse(process.env.METRIK_AGENT_SESSION_JSON!);
+const provider = createPrivySessionProvider({
+  brokerUrl: session.brokerUrl,
+  sessionToken: session.sessionToken,
+  address: session.address,
+});
+
+const { agentClient } = await createWalletBackedAgentClient(sdkConfig, {
+  privy: {
+    appId: session.appId,
+    address: session.address,
+    provider,
+    chainId: session.chainId,
+  },
+});
+```
+
+The broker permits only bounded USDC approval, V2 stream open/close/reclaim, and
+short-lived invocation-capability signatures for an active buyer stream. It stores a
+hash—not the plaintext—of the session token. Revoked or expired sessions fail closed.
+It asks Privy to sponsor only the first successful write in the session.
+
+## Boundary and limitations
+
+- The adapter supports a user-owned Privy EOA only.
+- It does not claim ERC-4337, EIP-1271, or smart-account support.
+- The browser adapter alone does not provide headless access. Headless operation requires
+  the deployed broker, a real Privy additional-signer policy, and user approval in the dApp.
+- The provider must implement the standard `eth_sendTransaction` EIP-1193 path.
+  In Privy mode, `createWalletBackedAgentClient` replaces the SDK transport with
+  that authenticated provider so a separate public RPC cannot bypass the wallet.
+- The host must keep the Privy app secret and any authorization material
+  server-side. Only the public app id belongs in browser configuration.
+
+Do not use an unauthenticated or arbitrary EIP-1193 provider as a substitute
+for Privy's authenticated user wallet. Do not put a Privy app secret in
+`PrivyEmbeddedWalletConfig`.