@agentvalet/register 0.1.0

package/README.md

@@ -0,0 +1,91 @@
+# @agentvalet/register
+
+Self-register AI agents with [AgentValet](https://agentvalet.ai) — the governance and proxy layer that sits between AI agents and SaaS platforms.
+
+## Install
+
+```bash
+# One-off use (no install):
+npx @agentvalet/register --name "My Agent" --scope slack:chat:write
+
+# Or install globally:
+npm install -g @agentvalet/register
+agentvalet-register --name "My Agent" --scope slack:chat:write
+```
+
+## Interactive mode
+
+Run with no flags for a guided wizard:
+
+```bash
+npx @agentvalet/register
+```
+
+## Flags
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--owner <uuid>` | `AGENTVALET_OWNER` env | Owner ID from https://agentvalet.ai/settings |
+| `--name <name>` | prompted | Agent name |
+| `--description <desc>` | — | Agent description |
+| `--scope <platform:scope>` | — | Repeatable, e.g. `--scope slack:chat:write --scope gmail:send` |
+| `--api-url <url>` | `https://api.agentvalet.ai` | AgentValet API base URL |
+| `--output <path>` | `./.env.agentvalet` | Path to write env vars |
+| `--key-path <path>` | `./agentvalet.key` | Path to write private key |
+| `--json` | — | Machine-readable JSON output |
+| `--no-wait` | — | Register only, don't wait for approval |
+| `--timeout <seconds>` | `300` | Approval wait timeout |
+
+## Exit codes
+
+| Code | Meaning |
+|------|---------|
+| `0` | Approved |
+| `1` | Denied |
+| `2` | Timeout |
+| `3` | Network or other error |
+
+## Integration examples
+
+**Claude Code (`CLAUDE.md`):**
+```markdown
+On startup, register with AgentValet:
+  npx @agentvalet/register --owner {uuid} --name "Claude Code Agent" --scope slack:chat:write
+
+Then source ./.env.agentvalet before calling any tool.
+```
+
+**Python agent:**
+```python
+import subprocess
+subprocess.run([
+    "npx", "@agentvalet/register",
+    "--name", "MyAgent",
+    "--owner", owner_id,
+    "--scope", "slack:chat:write",
+])
+```
+
+**LangChain / CrewAI / bash script:**
+
+Shell out to `npx @agentvalet/register` and parse the output env file:
+
+```bash
+npx @agentvalet/register --owner $OWNER_ID --name "BashAgent" --scope slack:chat:write
+source ./.env.agentvalet
+```
+
+## How it works
+
+1. POSTs to `/v1/register` with your owner ID, agent name, and requested scopes
+2. Prints the approval URL — the owner approves in the dashboard
+3. Waits for approval via SSE (with polling fallback)
+4. On approval, writes the private key to `--key-path` and env vars to `--output`
+
+The agent **never holds SaaS credentials** — AgentValet injects them at proxy time.
+
+## Links
+
+- Dashboard: https://agentvalet.ai
+- Docs: https://agentvalet.ai/docs
+- GitHub: https://github.com/MCSEdwin/agentvalet

package/dist/index.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/index.js

@@ -0,0 +1,309 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { Command } from "commander";
+import chalk2 from "chalk";
+
+// src/wizard.ts
+import prompts from "prompts";
+import chalk from "chalk";
+async function runWizard(prefilled) {
+  console.log(chalk.bold("\nAgentValet \u2014 Register Agent\n"));
+  const questions = [];
+  if (!prefilled.ownerId) {
+    questions.push({
+      type: "text",
+      name: "ownerId",
+      message: "Owner ID (from https://agentvalet.ai/settings):",
+      validate: (v) => v.trim() ? true : "Owner ID is required"
+    });
+  }
+  if (!prefilled.agentName) {
+    questions.push({
+      type: "text",
+      name: "agentName",
+      message: "Agent name:",
+      initial: "My Agent",
+      validate: (v) => v.trim() ? true : "Name is required"
+    });
+  }
+  questions.push(
+    {
+      type: "text",
+      name: "description",
+      message: "Description (optional):",
+      initial: prefilled.description
+    },
+    {
+      type: "text",
+      name: "scopesRaw",
+      message: "Scopes (comma-separated, e.g. slack:chat:write,gmail:send):",
+      initial: prefilled.scopes.join(",")
+    }
+  );
+  const answers = await prompts(questions, {
+    onCancel: () => {
+      console.log(chalk.yellow("\nCancelled."));
+      process.exit(0);
+    }
+  });
+  const ownerId = answers.ownerId ?? prefilled.ownerId;
+  const agentName = answers.agentName ?? prefilled.agentName;
+  const description = answers.description ?? prefilled.description;
+  const scopesRaw = answers.scopesRaw;
+  const scopes = scopesRaw?.split(",").map((s) => s.trim()).filter(Boolean) ?? prefilled.scopes;
+  return { ownerId: ownerId.trim(), agentName: agentName.trim(), description, scopes };
+}
+
+// src/register.ts
+import { fetch } from "undici";
+async function registerAgent(apiUrl, body) {
+  const res = await fetch(`${apiUrl}/v1/register`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(body)
+  });
+  const json = await res.json();
+  if (!res.ok) {
+    const wrapped = json.data;
+    const errMsg = wrapped?.error ?? json.error ?? `HTTP ${res.status}`;
+    throw new Error(errMsg);
+  }
+  const data = json.data ?? json;
+  const token = data.registration_token;
+  if (!token) throw new Error("No registration_token in response");
+  return token;
+}
+
+// src/wait.ts
+import { fetch as fetch2 } from "undici";
+async function waitForApproval(apiUrl, token, timeoutMs, onTick) {
+  const deadline = Date.now() + timeoutMs;
+  const sseResult = await trySSE(apiUrl, token, Math.min(3e4, timeoutMs), onTick);
+  if (sseResult) return sseResult;
+  return poll(apiUrl, token, deadline, onTick);
+}
+async function trySSE(apiUrl, token, windowMs, onTick) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), windowMs);
+  try {
+    const res = await fetch2(`${apiUrl}/v1/register/stream/${token}`, {
+      signal: controller.signal,
+      headers: { Accept: "text/event-stream" }
+    });
+    if (!res.ok || !res.body) return null;
+    const reader = res.body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = "";
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      buffer += decoder.decode(value, { stream: true });
+      const lines = buffer.split("\n");
+      buffer = lines.pop() ?? "";
+      for (const line of lines) {
+        if (line.startsWith(":")) {
+          onTick?.();
+          continue;
+        }
+        if (line.startsWith("data:")) {
+          const dataStr = line.slice(5).trim();
+          if (!dataStr) continue;
+          try {
+            const data = JSON.parse(dataStr);
+            const parsed = parseEvent(data);
+            if (parsed) return parsed;
+          } catch {
+          }
+        }
+      }
+    }
+    return null;
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+async function poll(apiUrl, token, deadline, onTick) {
+  while (Date.now() < deadline) {
+    await sleep(5e3);
+    onTick?.();
+    try {
+      const res = await fetch2(`${apiUrl}/v1/register/status/${token}`);
+      if (!res.ok) continue;
+      const json = await res.json();
+      const data = json.data ?? json;
+      const parsed = parseEvent(data);
+      if (parsed) return parsed;
+    } catch {
+    }
+  }
+  return { status: "timeout" };
+}
+function parseEvent(data) {
+  if (data.status === "approved") {
+    const agentId = data.agent_id ?? data.agentId;
+    if (!agentId) return null;
+    return { status: "approved", agentId };
+  }
+  if (data.status === "rejected") return { status: "rejected" };
+  if (data.status === "timeout" || data.status === "expired") return { status: "expired" };
+  return null;
+}
+function sleep(ms) {
+  return new Promise((resolve2) => setTimeout(resolve2, ms));
+}
+
+// src/save.ts
+import { writeFile, mkdir } from "fs/promises";
+import { dirname, resolve } from "path";
+async function saveOutput(opts) {
+  const keyPath = resolve(opts.keyFilePath);
+  const envPath = resolve(opts.envFilePath);
+  await mkdir(dirname(keyPath), { recursive: true });
+  await mkdir(dirname(envPath), { recursive: true });
+  await writeFile(keyPath, "", { mode: 384 });
+  const envContent = [
+    `# AgentValet \u2014 generated by agentvalet-register`,
+    `AGENTVALET_AGENT_ID=${opts.agentId}`,
+    `AGENTVALET_API_URL=${opts.apiUrl}`,
+    `AGENTVALET_PRIVATE_KEY_PATH=${keyPath}`,
+    ""
+  ].join("\n");
+  await writeFile(envPath, envContent, "utf-8");
+  return { keyPath, envPath };
+}
+
+// src/index.ts
+function collectScope(value, previous) {
+  return [...previous, value];
+}
+var program = new Command();
+program.name("agentvalet-register").description("Self-register an AI agent with AgentValet").version("0.1.0").option("--owner <uuid>", "Owner ID (or set AGENTVALET_OWNER env var)").option("--name <name>", "Agent name").option("--description <desc>", "Agent description").option("--scope <platform:scope>", "Requested scope, repeatable", collectScope, []).option("--api-url <url>", "AgentValet API base URL", "https://api.agentvalet.ai").option("--output <path>", "Path to write .env file", "./.env.agentvalet").option("--key-path <path>", "Path to write private key", "./agentvalet.key").option("--json", "Machine-readable JSON output").option("--no-wait", "Register only, do not wait for approval").option("--timeout <seconds>", "Approval wait timeout in seconds", "300").action(async (opts) => {
+  const isJson = !!opts.json;
+  let ownerId = opts.owner ?? process.env.AGENTVALET_OWNER ?? "";
+  let agentName = opts.name ?? "";
+  let description = opts.description ?? "";
+  let scopes = opts.scope;
+  if (!agentName) {
+    if (isJson) {
+      console.error(JSON.stringify({ error: "--name is required in non-interactive mode" }));
+      process.exit(3);
+    }
+    const answers = await runWizard({ ownerId, agentName, description, scopes });
+    ownerId = answers.ownerId;
+    agentName = answers.agentName;
+    description = answers.description;
+    scopes = answers.scopes;
+  }
+  if (!ownerId) {
+    if (isJson) {
+      console.error(JSON.stringify({ error: "--owner or AGENTVALET_OWNER is required" }));
+      process.exit(3);
+    }
+    console.error(chalk2.red("Error: --owner or AGENTVALET_OWNER environment variable is required"));
+    process.exit(3);
+  }
+  const scopeMap = /* @__PURE__ */ new Map();
+  for (const s of scopes) {
+    const colon = s.indexOf(":");
+    if (colon === -1) {
+      console.error(
+        isJson ? JSON.stringify({ error: `Invalid scope format: ${s} (expected platform:scope)` }) : chalk2.red(`Invalid scope format: ${s} (expected platform:scope)`)
+      );
+      process.exit(3);
+    }
+    const platform = s.slice(0, colon);
+    const scope = s.slice(colon + 1);
+    const existing = scopeMap.get(platform) ?? [];
+    scopeMap.set(platform, [...existing, scope]);
+  }
+  const requestedScopes = Array.from(scopeMap.entries()).map(([platformId, s]) => ({
+    platformId,
+    scopes: s
+  }));
+  let token;
+  try {
+    token = await registerAgent(opts.apiUrl, {
+      owner_id: ownerId,
+      agent_name: agentName,
+      agent_description: description || void 0,
+      requested_scopes: requestedScopes
+    });
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    console.error(isJson ? JSON.stringify({ error: msg }) : chalk2.red(`Registration failed: ${msg}`));
+    process.exit(3);
+  }
+  if (!isJson) {
+    console.log(chalk2.cyan(`
+Approve at: https://agentvalet.ai/registrations
+`));
+  }
+  if (!opts.wait) {
+    if (isJson) {
+      console.log(JSON.stringify({ status: "pending", token }));
+    } else {
+      console.log(chalk2.yellow("Registration submitted (--no-wait). Token:"), token);
+    }
+    process.exit(0);
+  }
+  const timeoutMs = parseInt(opts.timeout, 10) * 1e3;
+  let result;
+  try {
+    result = await waitForApproval(opts.apiUrl, token, timeoutMs, isJson ? void 0 : () => {
+    });
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    console.error(isJson ? JSON.stringify({ error: msg }) : chalk2.red(`Wait failed: ${msg}`));
+    process.exit(3);
+  }
+  if (result.status === "rejected") {
+    if (isJson) {
+      console.log(JSON.stringify({ status: "rejected" }));
+    } else {
+      console.log(chalk2.red("\nRegistration denied by owner."));
+    }
+    process.exit(1);
+  }
+  if (result.status === "timeout" || result.status === "expired") {
+    if (isJson) {
+      console.log(JSON.stringify({ status: "timeout" }));
+    } else {
+      console.log(chalk2.yellow("\nTimed out waiting for approval."));
+    }
+    process.exit(2);
+  }
+  const { agentId } = result;
+  let keyPath;
+  let envPath;
+  try {
+    ({ keyPath, envPath } = await saveOutput({
+      agentId,
+      apiUrl: opts.apiUrl,
+      keyFilePath: opts.keyPath,
+      envFilePath: opts.output
+    }));
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    console.error(isJson ? JSON.stringify({ error: msg }) : chalk2.red(`Failed to save output: ${msg}`));
+    process.exit(3);
+  }
+  if (isJson) {
+    console.log(JSON.stringify({ status: "approved", agentId, keyPath, envPath }));
+  } else {
+    console.log(chalk2.green(`
+Approved! Agent ID: ${agentId}`));
+    console.log(chalk2.gray(`Key:        ${keyPath}`));
+    console.log(chalk2.gray(`Env file:   ${envPath}`));
+    console.log(`
+Source the env file before calling any tool:`);
+    console.log(chalk2.cyan(`  source ${envPath}`));
+  }
+  process.exit(0);
+});
+program.parseAsync().catch((err) => {
+  console.error(err);
+  process.exit(3);
+});

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@agentvalet/register",
+  "version": "0.1.0",
+  "description": "Self-register AI agents with AgentValet",
+  "type": "module",
+  "bin": {
+    "agentvalet-register": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "dev": "tsx src/index.ts",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "pnpm build"
+  },
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "commander": "^12.0.0",
+    "ora": "^8.0.1",
+    "prompts": "^2.4.2",
+    "undici": "^6.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "@types/prompts": "^2.4.0",
+    "tsup": "^8.0.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^1.5.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MCSEdwin/agentvalet.git",
+    "directory": "apps/cli"
+  },
+  "keywords": [
+    "ai",
+    "agents",
+    "auth",
+    "credentials",
+    "mcp",
+    "valet",
+    "agentvalet"
+  ],
+  "license": "MIT"
+}