@openparachute/agent 0.1.0

package/src/webhook-server.ts

@@ -0,0 +1,134 @@
+/**
+ * Minimal HTTP server for Chat SDK adapter webhooks.
+ *
+ * Starts lazily on first adapter registration. Routes requests by path:
+ *   /webhook/{adapterName} → chat.webhooks[adapterName](request)
+ *
+ * Multiple Chat instances can register adapters — each adapter name maps
+ * to its owning Chat instance.
+ */
+import http from 'http';
+
+import type { Chat } from 'chat';
+
+import { log } from './log.js';
+
+const DEFAULT_PORT = 3000;
+
+interface WebhookEntry {
+  chat: Chat;
+  adapterName: string;
+}
+
+const routes = new Map<string, WebhookEntry>();
+let server: http.Server | null = null;
+
+/** Convert Node.js IncomingMessage to a Web API Request. */
+async function toWebRequest(req: http.IncomingMessage): Promise<Request> {
+  const chunks: Buffer[] = [];
+  for await (const chunk of req) {
+    chunks.push(chunk as Buffer);
+  }
+  const body = Buffer.concat(chunks);
+
+  const host = req.headers.host || 'localhost';
+  const url = `http://${host}${req.url}`;
+
+  const headers: Record<string, string> = {};
+  for (const [key, val] of Object.entries(req.headers)) {
+    if (typeof val === 'string') headers[key] = val;
+    else if (Array.isArray(val)) headers[key] = val.join(', ');
+  }
+
+  const hasBody = req.method !== 'GET' && req.method !== 'HEAD';
+  return new Request(url, {
+    method: req.method || 'GET',
+    headers,
+    body: hasBody ? body : undefined,
+  });
+}
+
+/** Write a Web API Response back to a Node.js ServerResponse. */
+async function fromWebResponse(webRes: Response, nodeRes: http.ServerResponse): Promise<void> {
+  nodeRes.writeHead(webRes.status, Object.fromEntries(webRes.headers.entries()));
+  if (webRes.body) {
+    const reader = webRes.body.getReader();
+    try {
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        nodeRes.write(value);
+      }
+    } finally {
+      reader.releaseLock();
+    }
+  }
+  nodeRes.end();
+}
+
+/**
+ * Register a webhook adapter on the shared server.
+ * Starts the server lazily on first call.
+ */
+export function registerWebhookAdapter(chat: Chat, adapterName: string): void {
+  routes.set(adapterName, { chat, adapterName });
+  ensureServer();
+  log.info('Webhook adapter registered', { adapter: adapterName, path: `/webhook/${adapterName}` });
+}
+
+function ensureServer(): void {
+  if (server) return;
+
+  const port = parseInt(process.env.WEBHOOK_PORT || String(DEFAULT_PORT), 10);
+
+  server = http.createServer(async (req, res) => {
+    const url = req.url || '/';
+
+    // Route: /webhook/{adapterName}
+    const match = url.match(/^\/webhook\/([^/?]+)/);
+    if (!match) {
+      res.writeHead(404, { 'Content-Type': 'text/plain' });
+      res.end('Not found');
+      return;
+    }
+
+    const adapterName = match[1];
+    const entry = routes.get(adapterName);
+    if (!entry) {
+      res.writeHead(404, { 'Content-Type': 'text/plain' });
+      res.end(`Unknown adapter: ${adapterName}`);
+      return;
+    }
+
+    try {
+      const webReq = await toWebRequest(req);
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const webhooks = entry.chat.webhooks as Record<string, (r: Request, opts?: any) => Promise<Response>>;
+      const handler = webhooks[entry.adapterName];
+      const webRes = await handler(webReq, {
+        waitUntil: (p: Promise<unknown>) => {
+          p.catch(() => {});
+        },
+      });
+      await fromWebResponse(webRes, res);
+    } catch (err) {
+      log.error('Webhook handler error', { adapter: adapterName, url: req.url, err });
+      res.writeHead(500, { 'Content-Type': 'text/plain' });
+      res.end('Internal Server Error');
+    }
+  });
+
+  server.listen(port, '0.0.0.0', () => {
+    log.info('Webhook server started', { port, adapters: [...routes.keys()] });
+  });
+}
+
+/** Shut down the webhook server. */
+export async function stopWebhookServer(): Promise<void> {
+  if (server) {
+    await new Promise<void>((resolve) => server!.close(() => resolve()));
+    server = null;
+    routes.clear();
+    log.info('Webhook server stopped');
+  }
+}

package/tsconfig.json

@@ -0,0 +1,21 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "lib": ["ES2022"],
+    "types": ["bun-types", "node"],
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}

package/vitest.config.ts

@@ -0,0 +1,18 @@
+import { defineConfig } from 'vitest/config';
+import { fileURLToPath } from 'node:url';
+
+export default defineConfig({
+  resolve: {
+    alias: {
+      // Production runs under Bun where `bun:sqlite` is native. For the vitest
+      // test path (Node), alias to a thin shim around better-sqlite3 that
+      // mirrors the `bun:sqlite` surface. See src/db/_bun-sqlite-shim.ts.
+      'bun:sqlite': fileURLToPath(new URL('./src/db/_bun-sqlite-shim.ts', import.meta.url)),
+    },
+  },
+  test: {
+    // container/agent-runner tests run under Bun (they depend on bun:sqlite).
+    // See container/agent-runner/package.json "test" script.
+    include: ['src/**/*.test.ts'],
+  },
+});

package/web/README.md

@@ -0,0 +1,63 @@
+# web/
+
+Paraclaw's web UI — the management surface for vault attachments per agent group.
+
+## Two pieces
+
+- **`server/`** — a small Node http server. Reads Paraclaw's central `data/v2.db` (agent_groups table) read-only, exposes `/api/groups` + attach/detach endpoints, shells out to the `parachute` CLI to mint scoped vault tokens. Static-serves the built UI bundle from `../ui/dist`.
+- **`ui/`** — Vite + React + TypeScript. Lists agent groups, drills into one to see its current vault attachment, has a form to attach a vault (mints a fresh scoped token via the server, or accepts a pasted one). Detach button and confirmation flow.
+
+## Run (dev)
+
+You need a Parachute Vault running on `127.0.0.1:1940` and Paraclaw initialized at least once (so `data/v2.db` exists).
+
+```sh
+# Terminal 1 — server
+cd web/server
+pnpm install --ignore-workspace
+pnpm dev
+# → http://127.0.0.1:1944
+
+# Terminal 2 — UI dev server (hot reload)
+cd web/ui
+pnpm install --ignore-workspace
+pnpm dev
+# → http://localhost:5173
+# (Vite proxies /api/* to the server on 1944)
+```
+
+Open `http://localhost:5173/` to use the UI in dev mode.
+
+## Run (built)
+
+```sh
+cd web/ui && pnpm build       # → dist/
+cd ../server && pnpm start    # serves dist/ at the server's root
+# → http://127.0.0.1:1944
+```
+
+## Auth model
+
+**v1 (today):** server runs locally, binds `127.0.0.1`, no auth. The minted vault tokens never round-trip to the browser — the server runs `parachute vault tokens create` and writes the result straight into `groups/<folder>/container.json`.
+
+If the user opts to paste an existing token instead of minting, that token *does* land in the browser briefly; the `paraclaw-web-server` doesn't persist it anywhere except where it would already go (the per-group container.json that the agent runner reads at startup).
+
+**Phase B:** server registers as an OAuth client of the user's vault (RFC 7591 DCR), the user approves once via the vault's consent page, the server holds the resulting admin token. Per-claw scoped tokens are minted from there. Users never see `pvt_…` tokens.
+
+## Why the bootstrap.ts dance
+
+Paraclaw's `src/config.ts` resolves `DATA_DIR` and `GROUPS_DIR` via `process.cwd()`. The web server is invoked from `web/server/`, which would resolve those to the wrong paths. `web/server/src/bootstrap.ts` is imported FIRST in `server.ts` and chdirs to the project root before any Paraclaw module loads.
+
+A more upstream-friendly fix would be to make Paraclaw's config compute paths from `import.meta.url` instead of `process.cwd()`. That'd be a one-line change worth proposing upstream eventually; for now bootstrap chdir is the smallest patch.
+
+## Pinned to canonical port?
+
+Yes — parachute-agent claims slot **1944** in the `1939–1949` Parachute range (per `parachute-patterns/patterns/canonical-ports.md`). The default is set in `web/server/src/server.ts`; override with `PARACHUTE_AGENT_WEB_PORT=<n>` for tests or non-default deployments (legacy `PARACLAW_WEB_PORT` accepted through 0.1.x). The hub-side reservation lives in `parachute-hub/src/service-spec.ts` (`PORT_RESERVATIONS`).
+
+## What's next
+
+See [`../docs/parachute-integration.md`](../docs/parachute-integration.md) for the full trajectory. Near-term:
+
+- **OAuth handshake** — replace the admin-token-as-env path in the server with vault OAuth. Phase B's biggest single add.
+- **New-agent wizard** — currently the UI manages vault attachment for *existing* agent groups (created via Paraclaw's setup flow). Adding a wizard for "spin up a new agent group + attach vault in one flow" is the next natural step, requires wrapping Paraclaw's `init-first-agent` / `create-agent` paths.
+- **Live status** — show whether a group's container is currently running, recent activity. Reads from Paraclaw's session tables.

package/web/ui/index.html

@@ -0,0 +1,13 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Paraclaw</title>
+    <meta name="description" content="Manage Parachute Vault access for your Paraclaw agents." />
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

package/web/ui/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@parachute-agent/web-ui",
+  "version": "0.0.16-rc.4",
+  "private": true,
+  "description": "Parachute Agent web UI — Vite + React + TypeScript. Manages vault attachments per agent group.",
+  "license": "AGPL-3.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc -b && vite build && node scripts/verify-base.mjs",
+    "preview": "vite preview",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "react-router-dom": "^7.0.0"
+  },
+  "devDependencies": {
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.2",
+    "@testing-library/user-event": "^14.6.1",
+    "@types/node": "^22.19.17",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "@vitejs/plugin-react": "^4.3.0",
+    "@vitest/ui": "^4.1.5",
+    "jsdom": "^25.0.1",
+    "typescript": "^5.6.0",
+    "vite": "^6.0.0",
+    "vitest": "^4.1.5"
+  }
+}