@okrlinkhub/agent-bridge 0.2.0 → 2.0.1

package/README.md

@@ -1,181 +1,191 @@
-# Convex Agent Bridge
+# Convex Agent Bridge (Config-First)
 
 [![npm version](https://badge.fury.io/js/@okrlinkhub%2Fagent-bridge.svg)](https://badge.fury.io/js/@okrlinkhub%2Fagent-bridge)
 
-A Convex component that acts as a **Security Gateway** between external AI agents
-(e.g. OpenClaw on Railway) and your Convex app's functions. It provides:
+`@okrlinkhub/agent-bridge` espone un gateway HTTP per agenti esterni con approccio **config-first**:
 
-- **Function Handle Registry**: Register which of your app's functions agents can call
-- **Dynamic Permissions**: Pattern-based access control (e.g. `"okr:read*"` -> allow)
-- **Distributed Provisioning**: Token-based agent registration with self-service onboarding
-- **Audit Logging**: Full access log of all agent interactions
-- **HTTP Gateway**: Single endpoint for agents to call registered functions securely
+- dichiari le funzioni Convex esposte in un solo file;
+- configuri i permessi in batch solo su quelle funzioni;
+- non modifichi query/mutation/action Convex esistenti.
 
-Found a bug? Feature request?
-[File it here](https://github.com/okrlinkhub/agent-bridge/issues).
-
-## Installation
+## Installazione
 
 ```sh
 npm install @okrlinkhub/agent-bridge
 ```
 
-Add the component to your `convex/convex.config.ts`:
+## Setup rapido
+
+### 1) Inizializza i file nel consumer
+
+```sh
+npx @okrlinkhub/agent-bridge init
+```
+
+Questo genera:
+
+- `agent-bridge.config.ts`
+- `convex/agentBridge.ts`
+
+### 2) Abilita il componente in `convex/convex.config.ts`
 
 ```ts
-// convex/convex.config.ts
 import { defineApp } from "convex/server";
 import agentBridge from "@okrlinkhub/agent-bridge/convex.config.js";
 
 const app = defineApp();
 app.use(agentBridge);
-
 export default app;
 ```
 
-## Quick Start
+### 3) Monta le route in `convex/http.ts`
 
-### 1. Initialize the client
+```ts
+import { httpRouter } from "convex/server";
+import { registerAgentBridgeRoutes } from "./agentBridge";
+
+const http = httpRouter();
+registerAgentBridgeRoutes(http);
+export default http;
+```
+
+Se vuoi usare il flusso multi-app gestito dal bridge, passa anche la service key:
 
 ```ts
-// convex/agentBridge.ts
-import { AgentBridge } from "@okrlinkhub/agent-bridge";
-import { components } from "./_generated/api";
-
-export const bridge = new AgentBridge(components.agentBridge, {
-  appName: "my-app",
-  defaultPermissions: [
-    { pattern: "myapp:read*", permission: "allow" },
-    { pattern: "myapp:write*", permission: "rate_limited", rateLimitConfig: { requestsPerHour: 50, tokenBudget: 50000 } },
-    { pattern: "*", permission: "deny" },
-  ],
+registerRoutes(http, components.agentBridge, bridgeConfig, {
+  pathPrefix: "/agent",
+  serviceKey:
+    (globalThis as { process?: { env?: Record<string, string> } }).process?.env
+      ?.AGENT_BRIDGE_SERVICE_KEY,
 });
 ```
 
-### 2. Register functions that agents can call
+### 4) Configura funzioni esposte in `agent-bridge.config.ts`
 
 ```ts
-import { mutation } from "./_generated/server";
-import { createFunctionHandle } from "convex/server";
-import { api } from "./_generated/api";
-import { bridge } from "./agentBridge";
-
-export const setup = mutation({
-  args: {},
-  returns: v.null(),
-  handler: async (ctx) => {
-    await bridge.configure(ctx);
-
-    const handle = await createFunctionHandle(api.myFunctions.getItems);
-    await bridge.registerFunction(ctx, {
-      name: "myapp:getItems",
-      handle,
-      type: "query",
-      description: "List all items",
-    });
-
-    return null;
+import { api } from "./convex/_generated/api";
+import { defineAgentBridgeConfig } from "@okrlinkhub/agent-bridge";
+
+export default defineAgentBridgeConfig({
+  functions: {
+    "cart.calculatePrice": { ref: api.cart.calculatePrice, type: "query" },
+    "cart.applyDiscount": { ref: api.cart.applyDiscount, type: "mutation" },
+    "okr.create": { ref: api.okr.create, type: "mutation" },
+  },
+  metadata: {
+    "cart.calculatePrice": {
+      description: "Calcola prezzo totale",
+      riskLevel: "low",
+      category: "commerce",
+    },
   },
 });
 ```
 
-### 3. Mount HTTP routes
+## Endpoint HTTP esposti
 
-```ts
-// convex/http.ts
-import { httpRouter } from "convex/server";
-import { registerRoutes } from "@okrlinkhub/agent-bridge";
-import { components } from "./_generated/api";
+- `POST /agent/execute`
+- `GET /agent/functions`
 
-const http = httpRouter();
+### `POST /agent/execute`
 
-// Exposes:
-//   POST /agent-bridge/execute    -- Gateway for agent function calls
-//   POST /agent-bridge/provision  -- Agent self-provisioning
-//   GET  /agent-bridge/health     -- Health check
-registerRoutes(http, components.agentBridge, {
-  appName: "my-app",
-});
+Header richiesti (una delle due modalita):
 
-export default http;
-```
+- Legacy:
+  - `X-Agent-API-Key: <api-key>`
+- Service-to-bridge (consigliato per OpenClaw multi-app):
+  - `X-Agent-Service-Key: <shared-service-secret>`
+  - `X-Agent-App: <app-key>` (es. `crm`, `billing`)
 
-### 4. Generate a provisioning token (admin)
+Body richiesto:
 
-```ts
-export const generateToken = mutation({
-  args: { email: v.string(), department: v.string() },
-  handler: async (ctx, args) => {
-    // Authenticate admin here
-    return await bridge.generateProvisioningToken(ctx, {
-      employeeEmail: args.email,
-      department: args.department,
-      createdBy: "admin@company.com",
-    });
-  },
-});
+```json
+{
+  "functionKey": "cart.calculatePrice",
+  "args": { "cartId": "..." }
+}
 ```
 
-## How It Works
+Risposta:
+
+- successo: `{ "success": true, "result": ... }`
+- errore: `{ "success": false, "error": "..." }`
 
-### Agent Provisioning Flow
+Codici principali: `401`, `403`, `404`, `429`, `500`.
 
-1. **IT Admin** generates a Provisioning Token (APT) via the `generateProvisioningToken` method
-2. **Employee** uses the APT to self-register on an app by calling `POST /agent-bridge/provision`
-3. The component creates an agent record and returns an `instanceToken` (valid 24h)
-4. The agent uses the `instanceToken` for all subsequent function calls
+## Setup OpenClaw multi-app (semplice su Railway)
 
-### Function Execution Flow
+Per un solo servizio OpenClaw che gestisce piu applicativi:
 
-1. Agent sends `POST /agent-bridge/execute` with `{ instanceToken, functionName, args }`
-2. The gateway validates the token, checks permissions via pattern matching
-3. If authorized, executes the registered function handle and returns the result
-4. All access attempts are logged to the audit table
+1. In Railway imposta solo:
+   - `AGENT_BRIDGE_SERVICE_KEY=<secret-unico>`
+2. In Convex registra un agente per app con `appKey` univoco:
+   - `crm`, `billing`, `warehouse`, ecc.
+3. OpenClaw invia per ogni chiamata:
+   - `X-Agent-Service-Key` (sempre uguale)
+   - `X-Agent-App` (varia per app target)
 
-### Permission Pattern Matching
+Puoi generare una service key con l'helper del package:
 
-Permissions use glob-style patterns with `*` wildcards:
+```ts
+import { generateAgentBridgeServiceKey } from "@okrlinkhub/agent-bridge";
+
+const serviceKey = generateAgentBridgeServiceKey(); // es: abs_live_<random>
+```
+
+Vantaggi:
+- controllo e debugging centralizzati nel bridge Convex;
+- nessun invio multiplo di API key nelle request;
+- rotazione e policy per app gestite nel bridge.
+
+## Gestione agenti e permessi
 
-| Pattern | Matches |
-|---------|---------|
-| `*` | Everything (catch-all) |
-| `okr:*` | All OKR functions |
-| `okr:read*` | `okr:readObjectives`, `okr:readKeyResults`, etc. |
-| `okr:createObjective` | Only this specific function |
+Mutation/query del componente disponibili in `components.agentBridge`:
 
-More specific patterns take priority over wildcards. Default behavior when no pattern matches: **deny**.
+- `agents.createAgent`
+- `agents.updateAgent`
+- `agents.rotateApiKey`
+- `agents.listAgents`
+- `gateway.authorizeByAppKey`
+- `permissions.setAgentPermissions` (batch)
+- `permissions.listAgentPermissions`
+- `permissions.setFunctionOverrides` (batch)
+- `permissions.listFunctionOverrides`
+- `gateway.queryAccessLog`
 
-## API Reference
+### Esempio permessi batch
 
-### `AgentBridge` class
+```ts
+await ctx.runMutation(components.agentBridge.permissions.setAgentPermissions, {
+  agentId,
+  rules: [
+    { pattern: "cart.*", permission: "allow" },
+    {
+      pattern: "okr.create",
+      permission: "rate_limited",
+      rateLimitConfig: { requestsPerHour: 60, tokenBudget: 50000 },
+    },
+  ],
+  availableFunctionKeys: Object.keys(config.functions),
+});
+```
 
-| Method | Description |
-|--------|-------------|
-| `configure(ctx)` | Initialize component configuration |
-| `registerFunction(ctx, fn)` | Register a callable function |
-| `registerFunctions(ctx, fns)` | Bulk register functions |
-| `unregisterFunction(ctx, name)` | Remove a function |
-| `listFunctions(ctx)` | List registered functions |
-| `generateProvisioningToken(ctx, opts)` | Create an APT (admin) |
-| `listAgents(ctx)` | List registered agents |
-| `revokeAgent(ctx, opts)` | Revoke an agent globally |
-| `revokeAppInstance(ctx, opts)` | Revoke a specific app instance |
-| `setPermission(ctx, opts)` | Set/update a permission |
-| `removePermission(ctx, opts)` | Remove a permission |
-| `listPermissions(ctx, agentId)` | List agent permissions |
-| `queryAccessLog(ctx, opts)` | Query audit logs |
+## Migrazione 0.2 -> next major
 
-### `registerRoutes(http, component, config)`
+Breaking changes principali:
 
-Registers HTTP endpoints on the host app's router:
+- rimosso il flusso provisioning token/instance token;
+- rimossa la registrazione runtime delle funzioni via `createFunctionHandle`;
+- rimosso l’uso della classe `AgentBridge` legacy.
 
-- `POST /agent-bridge/execute` -- Execute a registered function
-- `POST /agent-bridge/provision` -- Agent self-provisioning
-- `GET /agent-bridge/health` -- Health check
+Nuovo flusso:
 
-See [example/convex/example.ts](./example/convex/example.ts) for a complete working example.
+1. config funzioni in `agent-bridge.config.ts`;
+2. auth via `X-Agent-API-Key` (legacy) oppure `X-Agent-Service-Key + X-Agent-App` (multi-app);
+3. policy in batch via mutation del componente;
+4. log centralizzato in `agentLogs`.
 
-## Development
+## Sviluppo locale
 
 ```sh
 npm i

package/dist/cli/init.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=init.d.ts.map

package/dist/cli/init.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../src/cli/init.ts"],"names":[],"mappings":""}

package/dist/cli/init.js

@@ -0,0 +1,108 @@
+#!/usr/bin/env node
+import { access, mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+const cwd = process.cwd();
+async function exists(targetPath) {
+    try {
+        await access(targetPath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function writeIfMissing(relativePath, content) {
+    const absolutePath = path.join(cwd, relativePath);
+    if (await exists(absolutePath)) {
+        return "skipped";
+    }
+    await mkdir(path.dirname(absolutePath), { recursive: true });
+    await writeFile(absolutePath, content, "utf8");
+    return "created";
+}
+const configTemplate = `import { api } from "./convex/_generated/api";
+import { defineAgentBridgeConfig } from "@okrlinkhub/agent-bridge";
+
+export default defineAgentBridgeConfig({
+  functions: {
+    "cart.calculatePrice": {
+      ref: api.cart.calculatePrice,
+      type: "query",
+    },
+    "cart.applyDiscount": {
+      ref: api.cart.applyDiscount,
+      type: "mutation",
+    },
+  },
+  metadata: {
+    "cart.calculatePrice": {
+      description: "Calcola il prezzo totale del carrello",
+      riskLevel: "low",
+      category: "commerce",
+    },
+  },
+});
+`;
+const bridgeHttpTemplate = `import { registerRoutes } from "@okrlinkhub/agent-bridge";
+import { components } from "./_generated/api";
+import config from "../agent-bridge.config";
+
+export function registerAgentBridgeRoutes(
+  http: Parameters<typeof registerRoutes>[0],
+) {
+  registerRoutes(http, components.agentBridge, config, {
+    pathPrefix: "/agent",
+    serviceKey:
+      (globalThis as { process?: { env?: Record<string, string> } }).process?.env
+        ?.AGENT_BRIDGE_SERVICE_KEY,
+  });
+}
+`;
+const integrationNotes = `
+[agent-bridge] Init completed.
+
+Next steps:
+1) Add component in convex/convex.config.ts:
+
+import { defineApp } from "convex/server";
+import agentBridge from "@okrlinkhub/agent-bridge/convex.config.js";
+
+const app = defineApp();
+app.use(agentBridge);
+export default app;
+
+2) Mount routes in convex/http.ts:
+
+import { httpRouter } from "convex/server";
+import { registerAgentBridgeRoutes } from "./agentBridge";
+
+const http = httpRouter();
+registerAgentBridgeRoutes(http);
+export default http;
+
+3) Create agents and permissions with component mutations:
+- components.agentBridge.agents.createAgent
+- components.agentBridge.permissions.setAgentPermissions
+- components.agentBridge.permissions.setFunctionOverrides
+
+4) For multi-app OpenClaw deployments, set one service secret in Railway:
+- AGENT_BRIDGE_SERVICE_KEY=<shared-secret>
+- OpenClaw sends X-Agent-Service-Key and X-Agent-App headers
+- Bridge resolves app -> agent internally (keep legacy X-Agent-API-Key for compatibility)
+`;
+async function main() {
+    const commandArg = process.argv[2];
+    if (commandArg && commandArg !== "init") {
+        console.error(`[agent-bridge] Unknown command "${commandArg}".`);
+        console.error("Usage: npx @okrlinkhub/agent-bridge init");
+        process.exitCode = 1;
+        return;
+    }
+    const configResult = await writeIfMissing("agent-bridge.config.ts", configTemplate);
+    const bridgeResult = await writeIfMissing("convex/agentBridge.ts", bridgeHttpTemplate);
+    console.log(`[agent-bridge] agent-bridge.config.ts: ${configResult === "created" ? "created" : "skipped (already exists)"}`);
+    console.log(`[agent-bridge] convex/agentBridge.ts: ${bridgeResult === "created" ? "created" : "skipped (already exists)"}`);
+    console.log(integrationNotes.trim());
+}
+void main();
+//# sourceMappingURL=init.js.map

package/dist/cli/init.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"init.js","sourceRoot":"","sources":["../../src/cli/init.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC5D,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC;AAE1B,KAAK,UAAU,MAAM,CAAC,UAAkB;IACtC,IAAI,CAAC;QACH,MAAM,MAAM,CAAC,UAAU,CAAC,CAAC;QACzB,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED,KAAK,UAAU,cAAc,CAC3B,YAAoB,EACpB,OAAe;IAEf,MAAM,YAAY,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,YAAY,CAAC,CAAC;IAClD,IAAI,MAAM,MAAM,CAAC,YAAY,CAAC,EAAE,CAAC;QAC/B,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,MAAM,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,YAAY,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC7D,MAAM,SAAS,CAAC,YAAY,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;IAC/C,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,MAAM,cAAc,GAAG;;;;;;;;;;;;;;;;;;;;;;CAsBtB,CAAC;AAEF,MAAM,kBAAkB,GAAG;;;;;;;;;;;;;;CAc1B,CAAC;AAEF,MAAM,gBAAgB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA+BxB,CAAC;AAEF,KAAK,UAAU,IAAI;IACjB,MAAM,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACnC,IAAI,UAAU,IAAI,UAAU,KAAK,MAAM,EAAE,CAAC;QACxC,OAAO,CAAC,KAAK,CAAC,mCAAmC,UAAU,IAAI,CAAC,CAAC;QACjE,OAAO,CAAC,KAAK,CAAC,0CAA0C,CAAC,CAAC;QAC1D,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;QACrB,OAAO;IACT,CAAC;IAED,MAAM,YAAY,GAAG,MAAM,cAAc,CAAC,wBAAwB,EAAE,cAAc,CAAC,CAAC;IACpF,MAAM,YAAY,GAAG,MAAM,cAAc,CAAC,uBAAuB,EAAE,kBAAkB,CAAC,CAAC;IAEvF,OAAO,CAAC,GAAG,CACT,0CAA0C,YAAY,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,0BAA0B,EAAE,CAChH,CAAC;IACF,OAAO,CAAC,GAAG,CACT,yCAAyC,YAAY,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,0BAA0B,EAAE,CAC/G,CAAC;IACF,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC,IAAI,EAAE,CAAC,CAAC;AACvC,CAAC;AAED,KAAK,IAAI,EAAE,CAAC"}