@agentproto/cli 0.1.0-alpha.1 → 0.1.0-alpha.3

package/dist/index.mjs

@@ -1,9 +1,15 @@
 import { spawn } from 'child_process';
+import { createHash } from 'crypto';
+import { mkdtemp, writeFile, chmod, rm, mkdir, readFile } from 'fs/promises';
+import { tmpdir, userInfo, hostname, homedir, platform } from 'os';
+import { resolve, join, dirname } from 'path';
 import { parseArgs } from 'util';
-import { resolve } from 'path';
+import { promises } from 'fs';
+import { createInterface } from 'readline/promises';
+import { stdout, stdin } from 'process';
 import { createAgentCliRuntime } from '@agentproto/driver-agent-cli';
-import { userInfo, hostname } from 'os';
 import { wrapWebSocket, createTunnelServer } from '@agentproto/acp/tunnel';
+import { createGateway } from '@agentproto/runtime';
 import WebSocket from 'ws';
 
 /**
@@ -11,8 +17,6 @@ import WebSocket from 'ws';
  * The `agentproto` binary — install / run / serve AIP-45 agent CLIs.
  */
 
-
-// src/registry/resolve.ts
 var slugToCamel = (slug) => slug.replace(/-([a-z0-9])/g, (_, c) => c.toUpperCase());
 async function resolveAdapter(slug) {
   if (!/^[a-z][a-z0-9-]*$/.test(slug)) {
@@ -40,6 +44,433 @@ async function resolveAdapter(slug) {
   }
   return { slug, handle: candidate, source: "npm", packageName };
 }
+async function listInstalledAdapters(opts) {
+  const roots = await collectAgentprotoNamespaceRoots(opts?.searchRoot);
+  const seen = /* @__PURE__ */ new Set();
+  const out = [];
+  for (const root of roots) {
+    let entries = [];
+    try {
+      entries = await promises.readdir(root);
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      if (!entry.startsWith("adapter-")) continue;
+      const slug = entry.slice("adapter-".length);
+      if (seen.has(slug)) continue;
+      seen.add(slug);
+      try {
+        const resolved = await resolveAdapter(slug);
+        const handle = resolved.handle;
+        const info = {
+          slug,
+          name: typeof handle.name === "string" ? handle.name : slug,
+          version: typeof handle.version === "string" ? handle.version : "?",
+          description: typeof handle.description === "string" ? handle.description : "",
+          protocol: typeof handle.protocol === "string" ? handle.protocol : "unknown",
+          streaming: !!handle.capabilities?.streaming,
+          packageName: resolved.packageName ?? `@agentproto/adapter-${slug}`
+        };
+        out.push(info);
+      } catch (err) {
+        console.warn(
+          `[agentproto/cli] listInstalledAdapters: skipping broken adapter '${slug}': ${err instanceof Error ? err.message : String(err)}`
+        );
+      }
+    }
+  }
+  return out.sort((a, b) => a.slug.localeCompare(b.slug));
+}
+async function collectAgentprotoNamespaceRoots(start) {
+  const roots = [];
+  let cur = start ?? process.cwd();
+  const candidatesAt = (dir) => [
+    resolve(dir, "node_modules", "@agentproto"),
+    resolve(dir, "node_modules", ".pnpm", "node_modules", "@agentproto")
+  ];
+  for (let depth = 0; depth < 16; depth++) {
+    for (const candidate of candidatesAt(cur)) {
+      try {
+        const stat = await promises.stat(candidate);
+        if (stat.isDirectory()) roots.push(candidate);
+      } catch {
+      }
+    }
+    const parent = resolve(cur, "..");
+    if (parent === cur) break;
+    cur = parent;
+  }
+  return roots;
+}
+async function runSetup(opts) {
+  const steps = opts.handle.setup ?? [];
+  if (steps.length === 0) {
+    process.stdout.write(`agentproto setup: no setup steps for '${opts.slug}'.
+`);
+    return 0;
+  }
+  const ledgerPath = ledgerPathFor(opts.slug);
+  const ledger = await loadLedger(ledgerPath, opts.slug);
+  const onlySet = opts.only && opts.only.length > 0 ? new Set(opts.only) : null;
+  for (const [i, step] of steps.entries()) {
+    if (onlySet && !onlySet.has(step.id)) continue;
+    const idx = `[${i + 1}/${steps.length}]`;
+    const head = `${idx} ${step.kind}/${step.id}`;
+    const prev = ledger.steps[step.id];
+    if (!opts.force && prev) {
+      process.stdout.write(
+        `${head} \u2713 already completed (${prev.completedAt}${prev.skippedViaSkipIf ? ", via skip_if" : ""}). Pass --force to re-run.
+`
+      );
+      continue;
+    }
+    if (step.skip_if && !opts.force) {
+      const ok = await checkSkipIf(step.skip_if);
+      if (ok) {
+        process.stdout.write(`${head} \u2713 skip_if matched \u2014 skipping.
+`);
+        ledger.steps[step.id] = {
+          stepId: step.id,
+          kind: step.kind,
+          completedAt: (/* @__PURE__ */ new Date()).toISOString(),
+          skippedViaSkipIf: true
+        };
+        continue;
+      }
+    }
+    if (opts.dryRun) {
+      process.stdout.write(`${head} (dry-run) \u2014 would execute.
+`);
+      continue;
+    }
+    let entry = null;
+    try {
+      switch (step.kind) {
+        case "cmd":
+          entry = await runCmdStep(step, ledger, head);
+          break;
+        case "prompt":
+          entry = await runPromptStep(step, ledger, head);
+          break;
+        case "external":
+          entry = await runExternalStep(step, ledger, head);
+          break;
+        case "oauth":
+          process.stderr.write(
+            `${head} \u2717 kind=oauth is not yet implemented in the local CLI host. Run the OAuth flow on the host that ships a SECRETS.md driver, then re-invoke.
+`
+          );
+          return 1;
+      }
+    } catch (err) {
+      process.stderr.write(
+        `${head} \u2717 failed: ${err instanceof Error ? err.message : String(err)}
+`
+      );
+      await saveLedger(ledgerPath, ledger);
+      return 1;
+    }
+    if (entry) {
+      ledger.steps[step.id] = entry;
+      await saveLedger(ledgerPath, ledger);
+    }
+  }
+  process.stdout.write(`agentproto: setup for '${opts.slug}' complete.
+`);
+  return 0;
+}
+async function runCmdStep(step, ledger, head) {
+  if (step.description) process.stdout.write(`${head} ${step.description}
+`);
+  process.stdout.write(`${head} $ ${step.cmd}
+`);
+  const captured = await runShellCapturing(step.cmd, {
+    timeoutMs: step.timeout_ms ?? 6e4,
+    interactive: step.interactive ?? false
+  });
+  if (captured.exitCode !== 0) {
+    throw new Error(
+      `cmd exited ${captured.exitCode}${captured.stderr ? ": " + truncate(captured.stderr, 400) : ""}`
+    );
+  }
+  let persistedTo;
+  if (step.persist) {
+    const value = captured.stdout.trim();
+    persistedTo = await applyPersist(step.persist, value, ledger);
+  }
+  return {
+    stepId: step.id,
+    kind: step.kind,
+    completedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    ...persistedTo ? { persistedTo } : {}
+  };
+}
+async function runPromptStep(step, ledger, head) {
+  if (step.description) process.stdout.write(`${head} ${step.description}
+`);
+  const type = step.type ?? "text";
+  let value;
+  switch (type) {
+    case "text":
+    case "secret":
+      value = await promptString(step.prompt, {
+        defaultValue: step.default,
+        masked: type === "secret"
+      });
+      break;
+    case "boolean":
+      value = await promptBoolean(step.prompt, step.default === "true") ? "true" : "false";
+      break;
+    case "select": {
+      const options = await resolveSelectOptions(step.options);
+      if (options.length === 0) {
+        throw new Error("select prompt has no options to choose from");
+      }
+      value = await promptSelect(step.prompt, options, step.default);
+      break;
+    }
+  }
+  let persistedTo;
+  if (step.persist) {
+    persistedTo = await applyPersist(step.persist, value, ledger);
+  }
+  return {
+    stepId: step.id,
+    kind: step.kind,
+    completedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    ...persistedTo ? { persistedTo } : {}
+  };
+}
+async function runExternalStep(step, ledger, head) {
+  if (step.description) process.stdout.write(`${head} ${step.description}
+`);
+  process.stdout.write(`${head} opening ${step.url}
+`);
+  const opener = platform() === "darwin" ? "open" : platform() === "win32" ? "cmd" : "xdg-open";
+  const args = platform() === "win32" ? ["/c", "start", step.url] : [step.url];
+  await new Promise((resolve) => {
+    const child = spawn(opener, args, { stdio: "ignore", detached: true });
+    child.once("error", () => resolve());
+    child.once("spawn", () => resolve());
+  });
+  let value = "";
+  if (step.callback?.param) {
+    value = await promptString(
+      `Paste the value of '${step.callback.param}' from the redirect`,
+      { masked: false }
+    );
+  } else {
+    process.stdout.write(`${head} done \u2014 press Enter when finished.
+`);
+    await promptString("(press Enter to continue)", { masked: false });
+  }
+  let persistedTo;
+  if (step.persist && value) {
+    persistedTo = await applyPersist(step.persist, value, ledger);
+  }
+  return {
+    stepId: step.id,
+    kind: step.kind,
+    completedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    ...persistedTo ? { persistedTo } : {}
+  };
+}
+async function checkSkipIf(skip) {
+  const expectedCode = skip.exit_code ?? 0;
+  const captured = await runShellCapturing(skip.cmd, {
+    timeoutMs: skip.timeout_ms ?? 5e3,
+    interactive: false
+  });
+  return captured.exitCode === expectedCode;
+}
+async function applyPersist(persist, value, ledger) {
+  if ("env" in persist && persist.env) {
+    if (!ledger.envValues) ledger.envValues = {};
+    ledger.envValues[persist.env] = value;
+    return `env:${persist.env}`;
+  }
+  if ("secret_slug" in persist && persist.secret_slug) {
+    process.stdout.write(
+      `agentproto setup: store the prompted value in your secrets backend under slug '${persist.secret_slug}' (value not echoed; ledger records the slot only).
+`
+    );
+    return `secret:${persist.secret_slug}`;
+  }
+  if ("cmd" in persist && persist.cmd) {
+    const cmd = persist.cmd.replace(/\$\{value\}/g, shellEscape(value));
+    const captured = await runShellCapturing(cmd, {
+      timeoutMs: 6e4,
+      interactive: false
+    });
+    if (captured.exitCode !== 0) {
+      throw new Error(`persist cmd exited ${captured.exitCode}`);
+    }
+    return "cmd";
+  }
+  throw new Error("persist block must declare exactly one of env / secret_slug / cmd");
+}
+async function promptString(question, opts) {
+  const isTty = process.stdin.isTTY ?? false;
+  const suffix = opts.defaultValue ? ` [${opts.defaultValue}]` : "";
+  const prompt = `${question}${suffix}: `;
+  if (opts.masked && !isTty) {
+    process.stdout.write(
+      `agentproto: stdin is not a TTY \u2014 masked input falls back to plain. Avoid piping secrets in non-interactive mode.
+`
+    );
+  }
+  const rl = createInterface({ input: stdin, output: stdout, terminal: isTty });
+  if (opts.masked && isTty) {
+    process.stdin.setRawMode?.(true);
+    let buf = "";
+    process.stdout.write(prompt);
+    return new Promise((resolve) => {
+      const onData = (chunk) => {
+        for (const code of chunk) {
+          if (code === 13 || code === 10) {
+            process.stdin.off("data", onData);
+            process.stdin.setRawMode?.(false);
+            process.stdout.write("\n");
+            rl.close();
+            resolve(buf || opts.defaultValue || "");
+            return;
+          }
+          if (code === 3) {
+            process.stdin.off("data", onData);
+            process.stdin.setRawMode?.(false);
+            rl.close();
+            process.exit(130);
+          }
+          if (code === 127 || code === 8) {
+            buf = buf.slice(0, -1);
+            continue;
+          }
+          buf += String.fromCharCode(code);
+          process.stdout.write("\u2022");
+        }
+      };
+      process.stdin.on("data", onData);
+    });
+  }
+  try {
+    const ans = (await rl.question(prompt)).trim();
+    return ans || opts.defaultValue || "";
+  } finally {
+    rl.close();
+  }
+}
+async function promptBoolean(question, defaultYes) {
+  const def = defaultYes ? "Y/n" : "y/N";
+  const ans = await promptString(`${question} [${def}]`, { masked: false });
+  if (!ans) return defaultYes;
+  return /^y(es)?$/i.test(ans);
+}
+async function promptSelect(question, options, defaultValue) {
+  process.stdout.write(`${question}
+`);
+  for (const [i, o] of options.entries()) {
+    const star = defaultValue && o.value === defaultValue ? "*" : i === 0 ? " " : " ";
+    process.stdout.write(
+      `  ${star} ${i + 1}) ${o.label ?? o.value}${o.label ? ` (${o.value})` : ""}
+`
+    );
+  }
+  const ans = await promptString(
+    `Choose 1-${options.length}`,
+    defaultValue ? { defaultValue } : { masked: false }
+  );
+  const asNum = Number.parseInt(ans, 10);
+  if (Number.isFinite(asNum) && asNum >= 1 && asNum <= options.length) {
+    return options[asNum - 1].value;
+  }
+  const exact = options.find((o) => o.value === ans);
+  if (exact) return exact.value;
+  if (defaultValue && options.some((o) => o.value === defaultValue)) {
+    return defaultValue;
+  }
+  throw new Error(
+    `invalid selection '${ans}'; expected one of ${options.map((o) => o.value).join(", ")}`
+  );
+}
+async function resolveSelectOptions(options) {
+  if (!options) return [];
+  if (Array.isArray(options)) {
+    return options.map((v) => ({ value: v }));
+  }
+  const captured = await runShellCapturing(options.cmd, {
+    timeoutMs: options.timeout_ms ?? 3e4,
+    interactive: false
+  });
+  if (captured.exitCode !== 0) {
+    throw new Error(
+      `select options cmd exited ${captured.exitCode}: ${truncate(captured.stderr, 400)}`
+    );
+  }
+  return captured.stdout.split("\n").map((l) => l.trim()).filter(Boolean).map((line) => {
+    const [value, label] = line.split("	");
+    const out = { value };
+    if (label) out.label = label;
+    return out;
+  });
+}
+async function runShellCapturing(cmd, opts) {
+  return new Promise((resolve) => {
+    const child = spawn("bash", ["-lc", cmd], {
+      stdio: opts.interactive ? "inherit" : ["ignore", "pipe", "pipe"]
+    });
+    let stdout = "";
+    let stderr = "";
+    child.stdout?.on("data", (c) => {
+      stdout += c.toString("utf8");
+    });
+    child.stderr?.on("data", (c) => {
+      stderr += c.toString("utf8");
+    });
+    const timer = setTimeout(() => {
+      child.kill("SIGTERM");
+      setTimeout(() => child.kill("SIGKILL"), 1e3);
+    }, opts.timeoutMs);
+    child.once("error", () => {
+      clearTimeout(timer);
+      resolve({ exitCode: 127, stdout, stderr: stderr || "spawn error" });
+    });
+    child.once("exit", (code) => {
+      clearTimeout(timer);
+      resolve({ exitCode: code ?? 0, stdout, stderr });
+    });
+  });
+}
+function shellEscape(s) {
+  return `'${s.replace(/'/g, `'"'"'`)}'`;
+}
+function truncate(s, max) {
+  return s.length <= max ? s : s.slice(0, max - 3) + "\u2026";
+}
+function ledgerPathFor(slug) {
+  const base = process.env["AGENTPROTO_HOME"] ?? join(homedir(), ".agentproto");
+  return join(base, "setup", `${slug}.json`);
+}
+async function loadLedger(path, slug) {
+  try {
+    const raw = await readFile(path, "utf8");
+    const parsed = JSON.parse(raw);
+    if (parsed.slug === slug && typeof parsed.steps === "object") return parsed;
+  } catch {
+  }
+  return {
+    slug,
+    updatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    steps: {}
+  };
+}
+async function saveLedger(path, ledger) {
+  ledger.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, JSON.stringify(ledger, null, 2));
+  await chmod(path, 384).catch(() => {
+  });
+}
 
 // src/commands/install.ts
 async function runInstall(args) {
@@ -49,7 +480,8 @@ async function runInstall(args) {
     strict: true,
     options: {
       force: { type: "boolean", short: "f" },
-      "dry-run": { type: "boolean" }
+      "dry-run": { type: "boolean" },
+      "skip-setup": { type: "boolean" }
     }
   });
   const slug = positionals[0];
@@ -68,6 +500,7 @@ async function runInstall(args) {
     );
     return 0;
   }
+  let alreadyInstalled = false;
   if (!values.force) {
     const checked = await runVersionCheck(adapter.handle.version_check);
     if (checked.ok) {
@@ -75,26 +508,67 @@ async function runInstall(args) {
         `agentproto: '${slug}' already installed (${checked.message}). Pass --force to reinstall.
 `
       );
-      return 0;
+      alreadyInstalled = true;
     }
   }
-  for (const [i, step] of installSteps.entries()) {
-    process.stdout.write(
-      `agentproto install [${i + 1}/${installSteps.length}] ${describeStep(step)}
+  if (!alreadyInstalled) {
+    let lastFailure = null;
+    let succeeded = false;
+    for (const [i, step] of installSteps.entries()) {
+      if (step.experimental) {
+        process.stdout.write(
+          `agentproto install [${i + 1}/${installSteps.length}] ${describeStep(step)} (experimental \u2014 skipping)
 `
-    );
-    if (values["dry-run"]) continue;
-    const code = await runStep(step);
-    if (code !== 0) {
+        );
+        continue;
+      }
+      process.stdout.write(
+        `agentproto install [${i + 1}/${installSteps.length}] ${describeStep(step)}
+`
+      );
+      if (values["dry-run"]) {
+        succeeded = true;
+        continue;
+      }
+      const code = await runStep(step);
+      if (code === 0) {
+        succeeded = true;
+        break;
+      }
+      lastFailure = { step, code };
+      process.stdout.write(
+        `agentproto install: method '${step.method}' returned ${code}; trying next.
+`
+      );
+    }
+    if (!succeeded && lastFailure) {
+      process.stderr.write(
+        `agentproto install: all ${installSteps.length} install methods failed. Last failure: ${lastFailure.step.method} \u2192 exit ${lastFailure.code}.
+`
+      );
+      return lastFailure.code;
+    }
+    if (!succeeded && !lastFailure) {
       process.stderr.write(
-        `agentproto install: step ${i + 1} failed with exit ${code}.
+        `agentproto install: no usable install method found for '${slug}'.
 `
       );
-      return code;
+      return 1;
     }
+    process.stdout.write(`agentproto: '${slug}' installed.
+`);
   }
-  process.stdout.write(`agentproto: '${slug}' installed.
+  if (!values["skip-setup"] && (adapter.handle.setup?.length ?? 0) > 0) {
+    process.stdout.write(`agentproto: running setup for '${slug}'\u2026
 `);
+    const setupCode = await runSetup({
+      slug,
+      handle: adapter.handle,
+      force: values.force ?? false,
+      dryRun: values["dry-run"] ?? false
+    });
+    if (setupCode !== 0) return setupCode;
+  }
   return 0;
 }
 function describeStep(step) {
@@ -104,16 +578,17 @@ function describeStep(step) {
     case "brew":
       return `brew install ${step.package ?? "(?)"}`;
     case "pip":
-      return `pip install ${step.package ?? "(?)"}`;
+      return `pip install ${step.user ? "--user " : ""}${step.package ?? "(?)"}`;
     case "cargo":
       return `cargo install ${step.package ?? "(?)"}`;
     case "go":
       return `go install ${step.package ?? "(?)"}`;
     case "curl":
+      return `curl ${step.url ?? "(?)"} | bash`;
     case "download":
-      return `${step.method} ${step.url ?? "(?)"} \u2192 ${step.path ?? "(default)"}`;
+      return `download ${step.url ?? "(?)"} \u2192 ${step.extract_bin ?? "(?)"}`;
     default:
-      return `${step.method} ${step.package ?? step.url ?? "(?)"}`;
+      return `${step.method} ${step.package ?? step.url ?? step.path ?? "(?)"}`;
   }
 }
 async function runStep(step) {
@@ -128,14 +603,198 @@ async function runStep(step) {
       argv.push(step.package);
       return spawnInherit("npm", argv);
     }
+    case "brew": {
+      if (!step.package) {
+        process.stderr.write("agentproto install: brew step missing package.\n");
+        return 2;
+      }
+      return spawnInherit("brew", ["install", step.package]);
+    }
+    case "pip": {
+      if (!step.package) {
+        process.stderr.write("agentproto install: pip step missing package.\n");
+        return 2;
+      }
+      const argv = ["install"];
+      if (step.user) argv.push("--user");
+      argv.push(step.package);
+      return spawnInherit("pip", argv);
+    }
+    case "cargo": {
+      if (!step.package) {
+        process.stderr.write(
+          "agentproto install: cargo step missing package.\n"
+        );
+        return 2;
+      }
+      return spawnInherit("cargo", ["install", step.package]);
+    }
+    case "go": {
+      if (!step.package) {
+        process.stderr.write("agentproto install: go step missing package.\n");
+        return 2;
+      }
+      return spawnInherit("go", ["install", step.package]);
+    }
+    case "curl": {
+      if (!step.url) {
+        process.stderr.write("agentproto install: curl step missing url.\n");
+        return 2;
+      }
+      return runCurlInstaller(step.url, step.verify_sha256);
+    }
+    case "download": {
+      if (!step.url || !step.extract_bin) {
+        process.stderr.write(
+          "agentproto install: download step missing url or extract_bin.\n"
+        );
+        return 2;
+      }
+      return runDownloadInstaller({
+        url: step.url,
+        extractBin: step.extract_bin,
+        verifySha256: step.verify_sha256
+      });
+    }
     default:
       process.stderr.write(
-        `agentproto install: method '${step.method}' not yet implemented in this CLI version. Run it manually for now (see the adapter's INSTALL.md).
+        `agentproto install: method '${step.method}' not yet implemented in this CLI version. Run it manually for now (see the adapter's docs).
 `
       );
       return 1;
   }
 }
+async function runCurlInstaller(url, verifySha256) {
+  if (!verifySha256) {
+    process.stdout.write(
+      `agentproto install: curl ${url} (\u26A0 no verify_sha256 declared \u2014 installer integrity not verified)
+`
+    );
+  }
+  const dir = await mkdtemp(join(tmpdir(), "agentproto-curl-"));
+  const scriptPath = join(dir, "install.sh");
+  try {
+    const res = await fetch(url, { redirect: "follow" });
+    if (!res.ok) {
+      process.stderr.write(
+        `agentproto install: curl fetch failed: ${res.status} ${res.statusText}
+`
+      );
+      return res.status;
+    }
+    const buf = Buffer.from(await res.arrayBuffer());
+    if (verifySha256) {
+      const got = createHash("sha256").update(buf).digest("hex");
+      if (got !== verifySha256.toLowerCase()) {
+        process.stderr.write(
+          `agentproto install: SHA-256 mismatch for ${url}
+  expected: ${verifySha256}
+  got:      ${got}
+`
+        );
+        return 4;
+      }
+      process.stdout.write(
+        `agentproto install: SHA-256 verified (${got.slice(0, 16)}\u2026)
+`
+      );
+    }
+    await writeFile(scriptPath, buf);
+    await chmod(scriptPath, 493);
+    return spawnInherit("bash", [scriptPath]);
+  } catch (err) {
+    process.stderr.write(
+      `agentproto install: curl install failed: ${err instanceof Error ? err.message : String(err)}
+`
+    );
+    return 1;
+  } finally {
+    await rm(dir, { recursive: true, force: true }).catch(() => {
+    });
+  }
+}
+async function runDownloadInstaller(opts) {
+  const dir = await mkdtemp(join(tmpdir(), "agentproto-dl-"));
+  try {
+    const filename = opts.url.split("/").pop() || "archive.bin";
+    const archivePath = join(dir, filename);
+    const res = await fetch(opts.url, { redirect: "follow" });
+    if (!res.ok) {
+      process.stderr.write(
+        `agentproto install: download fetch failed: ${res.status} ${res.statusText}
+`
+      );
+      return res.status;
+    }
+    const buf = Buffer.from(await res.arrayBuffer());
+    if (opts.verifySha256) {
+      const got = createHash("sha256").update(buf).digest("hex");
+      if (got !== opts.verifySha256.toLowerCase()) {
+        process.stderr.write(
+          `agentproto install: SHA-256 mismatch
+  expected: ${opts.verifySha256}
+  got:      ${got}
+`
+        );
+        return 4;
+      }
+    }
+    await writeFile(archivePath, buf);
+    const extractDir = join(dir, "extract");
+    await mkdir(extractDir, { recursive: true });
+    let extractCode;
+    if (filename.endsWith(".tar.gz") || filename.endsWith(".tgz") || filename.endsWith(".tar")) {
+      extractCode = await spawnInherit("tar", [
+        "-xf",
+        archivePath,
+        "-C",
+        extractDir
+      ]);
+    } else if (filename.endsWith(".zip")) {
+      extractCode = await spawnInherit("unzip", [
+        "-q",
+        archivePath,
+        "-d",
+        extractDir
+      ]);
+    } else {
+      process.stderr.write(
+        `agentproto install: unsupported archive format for ${filename}. Supported: .tar, .tar.gz, .tgz, .zip.
+`
+      );
+      return 5;
+    }
+    if (extractCode !== 0) return extractCode;
+    const srcBin = join(extractDir, opts.extractBin);
+    const binDir = process.env["AGENTPROTO_BIN_DIR"] ?? join(homedir2(), ".local", "bin");
+    await mkdir(binDir, { recursive: true });
+    const destBin = join(binDir, opts.extractBin.split("/").pop());
+    const cpCode = await spawnInherit("cp", ["-p", srcBin, destBin]);
+    if (cpCode !== 0) return cpCode;
+    await chmod(destBin, 493);
+    process.stdout.write(`agentproto install: ${destBin}
+`);
+    if (!process.env["PATH"]?.includes(binDir)) {
+      process.stdout.write(
+        `agentproto install: \u26A0  ${binDir} is not on PATH \u2014 add it to your shell profile so the binary is reachable.
+`
+      );
+    }
+    return 0;
+  } catch (err) {
+    process.stderr.write(
+      `agentproto install: download failed: ${err instanceof Error ? err.message : String(err)}
+`
+    );
+    return 1;
+  } finally {
+    await rm(dir, { recursive: true, force: true }).catch(() => {
+    });
+  }
+}
+function homedir2() {
+  return process.env["HOME"] ?? process.env["USERPROFILE"] ?? "/";
+}
 function spawnInherit(cmd, argv) {
   return new Promise((resolve, reject) => {
     const child = spawn(cmd, argv, { stdio: "inherit" });
@@ -273,12 +932,82 @@ function printPretty(ev) {
 \x1B[2m[turn-end: ${ev.reason}]\x1B[0m
 `);
       break;
-    case "error":
-      process.stderr.write(`\x1B[31m[error] ${ev.error.message}\x1B[0m
+    case "error": {
+      const code = typeof ev.error.code === "number" ? ` (code ${ev.error.code})` : "";
+      process.stderr.write(
+        `\x1B[31m[error]${code} ${ev.error.message}\x1B[0m
+`
+      );
+      const data = ev.error.data;
+      if (data && typeof data === "object") {
+        const stderr = data.stderr;
+        if (typeof stderr === "string" && stderr.trim()) {
+          process.stderr.write(`\x1B[2m\u2500\u2500 child stderr \u2500\u2500
+${stderr}\x1B[0m
 `);
+        }
+        const rest = { ...data };
+        delete rest.stderr;
+        if (Object.keys(rest).length > 0) {
+          process.stderr.write(
+            `\x1B[2m\u2500\u2500 error.data \u2500\u2500
+${JSON.stringify(rest, null, 2)}\x1B[0m
+`
+          );
+        }
+      }
       break;
+    }
   }
 }
+var FILE_VERSION = 1;
+function credentialsPath() {
+  const base = process.env["AGENTPROTO_HOME"] ?? join(homedir(), ".agentproto");
+  return join(base, "credentials.json");
+}
+function normaliseHost(host) {
+  return host.replace(/\/+$/, "");
+}
+async function loadCredentials() {
+  const path = credentialsPath();
+  try {
+    const raw = await readFile(path, "utf8");
+    const parsed = JSON.parse(raw);
+    if (parsed.version !== FILE_VERSION) {
+      throw new Error(
+        `credentials.json: unknown version ${parsed.version}; expected ${FILE_VERSION}. Delete the file and re-run \`agentproto auth login\`.`
+      );
+    }
+    return parsed;
+  } catch (err) {
+    if (err.code === "ENOENT") {
+      return { version: FILE_VERSION, hosts: {} };
+    }
+    throw err;
+  }
+}
+async function readHost(host) {
+  const f = await loadCredentials();
+  return f.hosts[normaliseHost(host)] ?? null;
+}
+function isExpired(cred, gracePeriodMs = 3e4) {
+  const exp = Date.parse(cred.expiresAt);
+  if (!Number.isFinite(exp)) return false;
+  return exp - gracePeriodMs <= Date.now();
+}
+function formatExpiry(cred) {
+  const exp = new Date(cred.expiresAt);
+  if (Number.isNaN(exp.getTime())) return "unknown";
+  const ms = exp.getTime() - Date.now();
+  if (ms < 0) return `expired ${formatRelative(-ms)} ago`;
+  return `expires in ${formatRelative(ms)}`;
+}
+function formatRelative(ms) {
+  if (ms < 6e4) return `${Math.round(ms / 1e3)}s`;
+  if (ms < 36e5) return `${Math.round(ms / 6e4)}m`;
+  if (ms < 864e5) return `${Math.round(ms / 36e5)}h`;
+  return `${Math.round(ms / 864e5)}d`;
+}
 async function runServe(args) {
   const { values } = parseArgs({
     args: [...args],
@@ -287,39 +1016,143 @@ async function runServe(args) {
     options: {
       connect: { type: "string", short: "c" },
       token: { type: "string", short: "t" },
-      label: { type: "string", short: "l" }
+      label: { type: "string", short: "l" },
+      workspace: { type: "string", short: "w" },
+      port: { type: "string", short: "p" },
+      bind: { type: "string", short: "b" }
     }
   });
-  if (!values.connect) {
+  const workspace = resolve(values.workspace ?? process.cwd());
+  try {
+    const stat = await promises.stat(workspace);
+    if (!stat.isDirectory()) {
+      process.stderr.write(
+        `agentproto serve: --workspace "${workspace}" is not a directory.
+`
+      );
+      return 2;
+    }
+  } catch {
     process.stderr.write(
-      "agentproto serve: --connect <url> is required.\n  example: agentproto serve --connect wss://guilde.work/api/v1/agentproto/tunnel --token $TOKEN\n"
+      `agentproto serve: --workspace "${workspace}" does not exist.
+  Create it first: mkdir -p "${workspace}"
+`
     );
     return 2;
   }
+  const port = values.port ? Number.parseInt(values.port, 10) : 18790;
+  if (!Number.isFinite(port) || port <= 0 || port > 65535) {
+    process.stderr.write(`agentproto serve: invalid --port "${values.port}".
+`);
+    return 2;
+  }
   const label = values.label ?? `${userInfo().username}@${hostname()}`;
+  let token = values.token ?? process.env.AGENTPROTO_TOKEN;
+  if (!token && values.connect) {
+    const cred = await readHost(values.connect);
+    if (cred) {
+      if (isExpired(cred)) {
+        process.stderr.write(
+          `agentproto serve: \u26A0 credentials for ${values.connect} are expired (${formatExpiry(cred)}). Re-run \`agentproto auth login --host ${values.connect}\`.
+`
+        );
+      }
+      token = cred.token;
+      process.stdout.write(
+        `agentproto serve: using token from credentials.json (${formatExpiry(cred)})
+`
+      );
+    }
+  }
   const opts = {
-    connect: values.connect,
-    token: values.token ?? process.env.AGENTPROTO_TOKEN,
+    workspace,
+    port,
+    bind: values.bind ?? "127.0.0.1",
+    ...values.connect ? { connect: values.connect } : {},
+    ...token ? { token } : {},
     label
   };
+  const resolveAgentAdapter = async (slug) => {
+    try {
+      const adapter = await resolveAdapter(slug);
+      const runtime = createAgentCliRuntime(adapter.handle);
+      return {
+        async startSession({ cwd }) {
+          return runtime.start({ cwd });
+        },
+        commandPreview: `${adapter.handle.bin} ${(adapter.handle.bin_args ?? []).join(" ")}`.trim()
+      };
+    } catch (err) {
+      console.warn(
+        `[agentproto serve] resolveAgentAdapter('${slug}') failed: ${err instanceof Error ? err.message : String(err)}`
+      );
+      return null;
+    }
+  };
+  let gateway;
+  try {
+    gateway = await createGateway({
+      workspace: opts.workspace,
+      port: opts.port,
+      bind: opts.bind,
+      specs: [],
+      name: "agentproto-serve",
+      // BOOT.md is silly for a tunnel daemon — skip it.
+      boot: false,
+      resolveAgentAdapter,
+      // Discovery for UIs / operators — `GET /adapters` + `list_adapters`
+      // MCP tool. Walks node_modules @agentproto/adapter-* on each call;
+      // cheap enough that we don't bother caching here.
+      listAgentAdapters: listInstalledAdapters
+    });
+  } catch (err) {
+    process.stderr.write(
+      `agentproto serve: gateway boot failed \u2014 ${err instanceof Error ? err.message : String(err)}
+`
+    );
+    return 1;
+  }
   process.stderr.write(
-    `agentproto serve: connecting to ${opts.connect} as '${opts.label}'\u2026
+    `agentproto serve: gateway up on ${gateway.url}
+  workspace: ${gateway.workspace}
+  mcp:       ${gateway.url}/mcp
+  sessions:  ${gateway.url}/sessions
+  events:    ${gateway.url}/events
 `
   );
   const aborter = new AbortController();
-  const onSignal = (sig) => {
+  let shuttingDown = false;
+  const shutdown = async (signal) => {
+    if (shuttingDown) return;
+    shuttingDown = true;
     process.stderr.write(`
-agentproto serve: received ${sig}, shutting down.
+agentproto serve: ${signal} \u2014 shutting down.
 `);
     aborter.abort();
+    await gateway.stop().catch(() => void 0);
+    process.exit(0);
   };
-  process.once("SIGINT", onSignal);
-  process.once("SIGTERM", onSignal);
+  process.once("SIGINT", () => void shutdown("SIGINT"));
+  process.once("SIGTERM", () => void shutdown("SIGTERM"));
+  if (!opts.connect) {
+    process.stderr.write(
+      `agentproto serve: running local-only (no --connect). Press Ctrl-C to stop.
+`
+    );
+    await new Promise((resolve) => {
+      aborter.signal.addEventListener("abort", () => resolve());
+    });
+    return 0;
+  }
+  process.stderr.write(
+    `agentproto serve: tunnel \u2014 connecting to ${opts.connect} as '${opts.label}'\u2026
+`
+  );
   let backoffMs = opts.reconnectMinMs ?? 1e3;
   const backoffMax = opts.reconnectMaxMs ?? 3e4;
   while (!aborter.signal.aborted) {
     try {
-      await runOneTunnel(opts, aborter.signal);
+      await runOneTunnel(opts, gateway, aborter.signal);
       backoffMs = opts.reconnectMinMs ?? 1e3;
     } catch (err) {
       if (aborter.signal.aborted) break;
@@ -333,11 +1166,10 @@ agentproto serve: received ${sig}, shutting down.
       backoffMs = Math.min(backoffMs * 2, backoffMax);
     }
   }
-  process.off("SIGINT", onSignal);
-  process.off("SIGTERM", onSignal);
   return 0;
 }
-async function runOneTunnel(opts, signal) {
+async function runOneTunnel(opts, gateway, signal) {
+  if (!opts.connect) throw new Error("runOneTunnel: --connect not set");
   const headers = {
     "user-agent": "agentproto/0.1.0-alpha"
   };
@@ -373,7 +1205,23 @@ async function runOneTunnel(opts, signal) {
     // v0 authorize hook: trust the bearer-authenticated host completely.
     // Token possession proves the host was provisioned for this daemon.
     // Per-spawn policy filtering will land alongside the policy.toml.
-    authorize: (req) => req
+    authorize: (req) => req,
+    // ── AIP-46 bridge: tunnel spawns land in the gateway registry ──
+    // Every cloud-driven spawn shows up in `gateway.url/sessions`
+    // and the LocalDaemonSessionsCard, alongside spawns originated
+    // through MCP tools or POST /sessions/agent. The execId is the
+    // host's stable id — keep it so cloud cli_sessions rows can
+    // cross-ref the daemon-side descriptor.
+    onChildSpawned: ({ execId, child, request }) => {
+      gateway.sessions.register({
+        id: execId,
+        child,
+        workspaceSlug: opts.label,
+        command: [request.command, ...request.args].join(" "),
+        kind: "agent-cli",
+        label: `tunnel: ${request.command.split("/").pop() ?? request.command}`
+      });
+    }
   });
   await new Promise((resolve) => {
     const offClose = sink.onClose(() => {
@@ -401,6 +1249,6 @@ function sleep(ms, signal) {
   });
 }
 
-export { resolveAdapter, runInstall, runRun, runServe };
+export { listInstalledAdapters, resolveAdapter, runInstall, runRun, runServe };
 //# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map