feat: NEAR Intents Agent as the agents plugin (tickets 06-12)

.changeset/agents-plugin-ui-dev-wiring.md

@@ -0,0 +1,5 @@
+---
+"everything-dev": patch
+---
+
+Fix folder-form plugin UI dev wiring: a local plugin's associated `ui` development entry was stripped during config resolution (only entries with a nested bos.config.json kept local paths), so the dev harness never allocated a UI port or passed `BOS_UI_PORT` — the plugin's UI rsbuild then auto-ported into the plugin API's port and MF chunk loads returned HTML. A local plugin's associated ui now keeps its local development whenever the plugin entry itself resolves locally. Also declares the agents plugin (with its folder-form ui) in the authored citynode descriptor.

.changeset/agents-signature-delivery.md

@@ -0,0 +1,5 @@
+---
+"@everything-dev/agents-plugin": minor
+---
+
+Expose the upstream signature-delivery loop — `getSignature` (read a completed signature once, under the grant that authorized it) and `acknowledgeSignature` (erase it server-side, one-time-consume with idempotent acks) — grant-token-gated like `signMessage`, backed by the encrypted operation-artifacts store. Also variablize the runtime wiring: `agentsTrustedOrigins` (required; feeds the runtime's trusted origins) and `agentsServiceUrl` (optional; its hostname is the NEP-413 recipient owners sign into every owner message) replace the hardcoded citynode.app/agents.local placeholders.

.env.example

@@ -20,6 +20,12 @@ TWILIO_AUTH_TOKEN=
 TWILIO_PHONE_NUMBER=
 RESEND_API_KEY=
 
+# plugins.agents
+AGENTS_DATABASE_URL=postgres://everythingdev:everythingdev@localhost:5432/api_db
+AGENTS_SPONSOR_KEYS=
+AGENTS_SECRET_ENCRYPTION_KEYS=
+AGENTS_SECRET_ENCRYPTION_ACTIVE_KEY_ID=
+
 # plugins.template
 TEMPLATE_DATABASE_URL=postgres://everythingdev:everythingdev@localhost:5432/api_db
 

.env.test

@@ -8,6 +8,9 @@ API_DATABASE_URL=postgres://everythingdev:everythingdev@localhost:5434/api_test_
 AUTH_DATABASE_URL=postgres://everythingdev:everythingdev@localhost:5435/auth_test_db
 BETTER_AUTH_SECRET=regression-test-secret-do-not-use-in-production
 
+# plugins.agents
+AGENTS_DATABASE_URL=postgres://everythingdev:everythingdev@localhost:5434/api_test_db
+
 # plugins.template
 TEMPLATE_DATABASE_URL=postgres://everythingdev:everythingdev@localhost:5434/api_test_db
 

biome.json

@@ -57,7 +57,8 @@
       "!!**/virtual-modules.d.ts",
       "!!bos.config.json",
       "!!plans",
-      "!!.agents"
+      "!!.agents",
+      "!!packages/database/drizzle"
     ],
     "ignoreUnknown": true
   },

bos.citynode.app.ts

@@ -84,6 +84,24 @@ export default App({
     },
   }),
   plugins: {
+    agents: Plugin("agents").path("plugins/agents", {
+      name: "@everything-dev/agents-plugin",
+      ui: { path: "plugins/agents/ui" },
+      variables: {
+        agentsNearRpcUrls: "https://near.drpc.org,https://free.rpc.fastnear.com",
+        agentsTrustedOrigins: "https://citynode.app",
+        agentsServiceUrl: "https://agents.local",
+        agentsSponsorDailyGlobalLimit: 100,
+        agentsSponsorDailyTenantLimit: 20,
+        agentsSponsorDailyAgentLimit: 10,
+      },
+      secrets: [
+        "AGENTS_DATABASE_URL",
+        "AGENTS_SPONSOR_KEYS",
+        "AGENTS_SECRET_ENCRYPTION_KEYS",
+        "AGENTS_SECRET_ENCRYPTION_ACTIVE_KEY_ID",
+      ],
+    }),
     template: Plugin("template").path("plugins/_template", {
       secrets: ["TEMPLATE_DATABASE_URL"],
     }),

bos.config.json

@@ -134,6 +134,27 @@
     }
   },
   "plugins": {
+    "agents": {
+      "development": "local:plugins/agents",
+      "variables": {
+        "agentsNearRpcUrls": "https://near.drpc.org,https://free.rpc.fastnear.com",
+        "agentsTrustedOrigins": "https://citynode.app",
+        "agentsServiceUrl": "https://agents.local",
+        "agentsSponsorDailyGlobalLimit": 100,
+        "agentsSponsorDailyTenantLimit": 20,
+        "agentsSponsorDailyAgentLimit": 10
+      },
+      "secrets": [
+        "AGENTS_DATABASE_URL",
+        "AGENTS_SPONSOR_KEYS",
+        "AGENTS_SECRET_ENCRYPTION_KEYS",
+        "AGENTS_SECRET_ENCRYPTION_ACTIVE_KEY_ID"
+      ],
+      "ui": {
+        "name": "_everything_dev_agents_plugin",
+        "development": "local:plugins/agents/ui"
+      }
+    },
     "template": {
       "development": "local:plugins/_template",
       "variables": {},

docs/agents/agents-plugin.md

@@ -0,0 +1,81 @@
+# Agents plugin — usage guide
+
+The `agents` plugin re-hosts the NEAR Intents Agent control plane as an
+everything.dev plugin: intents custody wallets operated by the platform's
+sponsor under the owner's signed policy. The wire contract is generated from
+the vendored `@near-intents-agent-api/contracts` schemas, so the public API
+surface matches the upstream control plane.
+
+## The three actors
+
+| Actor | Authenticates with | Can do |
+|-------|--------------------|--------|
+| Owner | NEAR SIWN session | Create agents, sign governance intents, read everything about their agents |
+| Grant holder | `x-grant-token` header | Execute within the grant's scope: swap, withdraw, transfer, sign messages |
+| MCP client | `x-api-key` (Settings → API Keys) | Everything the API exposes, as generated tools |
+
+## Owner flow
+
+1. Sign in with your NEAR wallet (SIWN). The session binds you as an owner.
+2. Open **Agents** in the sidebar (or `POST /api/rpc/agents/generateIntent`
+   with `type: "agent_create"`). The first intent creates the agent and its
+   custody wallet.
+3. The server builds every byte the owner signs and returns it as
+   `intent: { standard, payload }`:
+   - **Policy intents** (`agent_create`, `policy_update`, freeze/unfreeze)
+     sign as **NEP-366 delegate actions** — the UI calls
+     `authClient.near.buildSignedDelegateAction(...)`.
+   - **Consent intents** (`grant_issue`, `grant_revoke`, `budget_set`,
+     `timelock_set`, …) sign as **NEP-413 messages** — the UI calls
+     `Near.signMessage({ message, recipient, nonce })` with the base64
+     nonce decoded to bytes.
+4. Submit the wallet's output unchanged as
+   `submitIntent({ type, correlationId, signedData })` and poll
+   `intentStatus` for settlement. Submitting the same signature twice is
+   idempotent.
+
+The sponsor relays the wallet's delegate on-chain (gasless for the owner);
+sponsor keys come from the `AGENTS_SPONSOR_KEYS` plugin secret. Without
+them, sponsor features are disabled and the log explains what is missing.
+
+## Delegated flow (grants)
+
+A grant is the owner's delegation of bounded execution authority to one
+token. The token is created **client-side**; only its SHA-256 commitment is
+ever sent:
+
+1. `createGrantCredential()` → `{ token: "ngt_…", commitment: <sha256 hex> }`
+2. `generateIntent({ type: "grant_issue", label, credential, actions,
+   recipients, signingAudiences, expiresAt })` → sign (NEP-413) → submit.
+3. Keep the token in your secret manager. Execute with the header:
+   `x-grant-token: ngt_…` against the execution routes (`/agents/swap`,
+   `/agents/withdraw`, `/agents/transfer`, `/agents/sign-message`, …).
+
+Every execution is checked against three layers at dispatch: the grant's
+actions and destinations, the owner's USD spend budget, and the provider
+policy. `dry: true` previews a swap or withdraw (provider quote) without
+executing. Revoking a grant (`grant_revoke` intent) retracts future work;
+work that already reached its dispatch commitment is reported in
+`committedCorrelationIds`.
+
+## MCP usage
+
+Every route is generated as an MCP tool from the OpenAPI spec
+(`POST /api/mcp`, discovery at `/.well-known/mcp.json`). Owner routes
+require a session cookie or `x-api-key`; delegated routes additionally
+require the `x-grant-token` header — pass it per call.
+
+## Local development
+
+```bash
+bun run dev    # local bos CLI — boots the citynode runtime incl. agents on :3010
+```
+
+- `.env` needs `BETTER_AUTH_SECRET` set (auth validate-secrets) and, for the
+  submit leg, `AGENTS_SPONSOR_KEYS` (testnet sponsor full-access key).
+- The plugin's UI is folder-form (`plugins/agents/ui/`) — the dev harness
+  builds it automatically and composes its routes under the authenticated
+  mount; the sidebar entry comes from the route's `staticData.nav`.
+- Secrets: `AGENTS_DATABASE_URL` (auto-generated from resolved ports in
+  dev), `AGENTS_SPONSOR_KEYS`, `AGENTS_SECRET_ENCRYPTION_KEYS`,
+  `AGENTS_SECRET_ENCRYPTION_ACTIVE_KEY_ID`.

packages/agents-core/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@near-intents-agent-api/agents-core",
+  "private": true,
+  "version": "0.1.0",
+  "type": "module",
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts"
+    },
+    "./config": {
+      "types": "./src/config/env.ts",
+      "import": "./src/config/env.ts"
+    },
+    "./views": {
+      "types": "./src/api/views.ts",
+      "import": "./src/api/views.ts"
+    }
+  },
+  "dependencies": {
+    "@near-intents-agent-api/contracts": "workspace:*",
+    "@near-intents-agent-api/database": "workspace:*",
+    "@near-intents-agent-api/outlayer": "workspace:*",
+    "@near-intents-agent-api/owner-auth": "workspace:*",
+    "@near-intents-agent-api/relayer": "workspace:*",
+    "drizzle-orm": "catalog:",
+    "near-api-js": "7.2.0",
+    "zod": "catalog:"
+  },
+  "devDependencies": {
+    "@types/node": "catalog:"
+  }
+}

packages/agents-core/src/api/camel.ts

@@ -0,0 +1,30 @@
+/**
+ * Provider evidence and pass-through records reach the wire camelCased. Signed protocol objects
+ * (policies, owner messages, wallet requests) never pass through here: their field names are
+ * part of what the owner signed.
+ */
+
+export function camelKey(key: string): string {
+  return key.replace(/_([a-z0-9])/g, (_, letter: string) => letter.toUpperCase());
+}
+
+const maxDepth = 8;
+
+export function camelize(value: unknown, depth = 0): unknown {
+  if (depth > maxDepth) return value;
+  if (Array.isArray(value)) return value.map((entry) => camelize(entry, depth + 1));
+  if (value === null || typeof value !== "object") return value;
+  return Object.fromEntries(
+    Object.entries(value as Record<string, unknown>).map(([key, entry]) => [
+      camelKey(key),
+      camelize(entry, depth + 1),
+    ]),
+  );
+}
+
+export function camelRecord(value: unknown): Record<string, unknown> {
+  const result = camelize(value);
+  return result && typeof result === "object" && !Array.isArray(result)
+    ? (result as Record<string, unknown>)
+    : {};
+}