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

package/dist/cli.mjs

@@ -1,19 +1,460 @@
 #!/usr/bin/env node
 import { spawn } from 'child_process';
+import { userInfo, hostname, homedir, platform, tmpdir } from 'os';
 import { parseArgs } from 'util';
-import { resolve } from 'path';
+import { readFile, mkdir, writeFile, chmod, mkdtemp, rm, unlink } from 'fs/promises';
+import { resolve, basename, join, dirname } from 'path';
+import { createHash } from 'crypto';
+import { promises, existsSync } 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';
+import { DEFAULT_CONFIG_PATH, loadWorkspacesConfig, getActiveWorkspace, setActiveWorkspace, saveWorkspacesConfig, sanitizeSlug, removeWorkspace, addWorkspace } from '@agentproto/runtime/workspaces-config';
+import http from 'http';
+import https from 'https';
 
 /**
  * @agentproto/cli v0.1.0-alpha
  * The `agentproto` binary — install / run / serve AIP-45 agent CLIs.
  */
 
+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 saveCredentials(file) {
+  const path = credentialsPath();
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, JSON.stringify(file, null, 2));
+  await chmod(path, 384).catch(() => {
+  });
+}
+async function readHost(host) {
+  const f = await loadCredentials();
+  return f.hosts[normaliseHost(host)] ?? null;
+}
+async function writeHost(host, cred) {
+  const f = await loadCredentials();
+  f.hosts[normaliseHost(host)] = cred;
+  await saveCredentials(f);
+}
+async function deleteHost(host) {
+  const f = await loadCredentials();
+  const key = normaliseHost(host);
+  const prev = f.hosts[key] ?? null;
+  if (prev) {
+    delete f.hosts[key];
+    if (Object.keys(f.hosts).length === 0) {
+      await unlink(credentialsPath()).catch(() => {
+      });
+    } else {
+      await saveCredentials(f);
+    }
+  }
+  return prev;
+}
+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`;
+}
+
+// src/commands/auth.ts
+async function runAuth(args) {
+  const sub = args[0];
+  const rest = args.slice(1);
+  switch (sub) {
+    case "login":
+      return runAuthLogin(rest);
+    case "status":
+      return runAuthStatus(rest);
+    case "logout":
+      return runAuthLogout(rest);
+    case void 0:
+    case "--help":
+    case "-h":
+      process.stdout.write(USAGE);
+      return 0;
+    default:
+      process.stderr.write(
+        `agentproto auth: unknown subcommand '${sub}'.
 
-// src/registry/resolve.ts
+${USAGE}`
+      );
+      return 2;
+  }
+}
+var USAGE = `agentproto auth \u2014 host-binding tokens (RFC 8628 device flow)
+
+Usage:
+  agentproto auth login   [--host <url>] [--label <name>] [--no-browser]
+  agentproto auth status  [--host <url>] [--json]
+  agentproto auth logout  [--host <url>]
+
+The default host is the one most recently logged into; on first use,
+\`--host\` is required. Examples:
+
+  agentproto auth login --host wss://guilde.work
+  agentproto auth status
+  agentproto auth logout --host wss://guilde.work
+`;
+async function runAuthLogin(args) {
+  const { values } = parseArgs({
+    args: [...args],
+    strict: true,
+    options: {
+      host: { type: "string" },
+      label: { type: "string" },
+      "no-browser": { type: "boolean" },
+      scope: { type: "string" }
+    }
+  });
+  const host = values.host ?? await pickDefaultHost();
+  if (!host) {
+    process.stderr.write(
+      "agentproto auth login: pass --host <url> on first login (e.g. --host wss://guilde.work).\n"
+    );
+    return 2;
+  }
+  const label = values.label ?? `${userInfo().username}@${hostname()}`;
+  const requestedScope = values.scope ?? "tunnel:connect agent-cli:dispatch";
+  const httpHost = toHttp(host);
+  const discoveryUrl = `${httpHost}/.well-known/agentproto-host.json`;
+  process.stdout.write(`agentproto auth: discovering ${discoveryUrl}
+`);
+  let discovery;
+  try {
+    discovery = await fetchJson(discoveryUrl);
+  } catch (err) {
+    process.stderr.write(
+      `agentproto auth: failed to fetch host metadata: ${err instanceof Error ? err.message : String(err)}
+  Hosts SHOULD expose /.well-known/agentproto-host.json with device_authorization_endpoint + token_endpoint.
+`
+    );
+    return 1;
+  }
+  let deviceRes;
+  try {
+    deviceRes = await postForm(
+      discovery.device_authorization_endpoint,
+      {
+        client_id: discovery.client_id,
+        scope: requestedScope,
+        // Custom field; hosts that ignore it stay compliant. The
+        // approval UI uses it to render "approve <label>" so the user
+        // recognises the device they're authorising.
+        device_label: label
+      }
+    );
+  } catch (err) {
+    process.stderr.write(
+      `agentproto auth: device authorization request failed: ${err instanceof Error ? err.message : String(err)}
+`
+    );
+    return 1;
+  }
+  const verifyUrl = deviceRes.verification_uri_complete ?? deviceRes.verification_uri;
+  process.stdout.write(
+    `
+agentproto auth: open
+  ${verifyUrl}
+and enter code  ${deviceRes.user_code}
+
+`
+  );
+  if (!values["no-browser"]) {
+    void openBrowser(verifyUrl);
+  }
+  process.stdout.write(
+    `agentproto auth: waiting for approval (expires in ${formatDuration(deviceRes.expires_in * 1e3)})\u2026
+`
+  );
+  const interval = Math.max(1, deviceRes.interval ?? 5);
+  const deadline = Date.now() + deviceRes.expires_in * 1e3;
+  let pollIntervalMs = interval * 1e3;
+  let token = null;
+  while (Date.now() < deadline) {
+    await sleep(pollIntervalMs);
+    let res;
+    try {
+      res = await postForm(
+        discovery.token_endpoint,
+        {
+          grant_type: "urn:ietf:params:oauth:grant-type:device_code",
+          device_code: deviceRes.device_code,
+          client_id: discovery.client_id
+        }
+      );
+    } catch (err) {
+      process.stderr.write(
+        `agentproto auth: token poll failed: ${err instanceof Error ? err.message : String(err)}
+`
+      );
+      return 1;
+    }
+    if ("access_token" in res) {
+      token = res;
+      break;
+    }
+    if (res.error === "authorization_pending") continue;
+    if (res.error === "slow_down") {
+      pollIntervalMs += 5e3;
+      continue;
+    }
+    if (res.error === "access_denied") {
+      process.stderr.write(`agentproto auth: approval denied. Aborting.
+`);
+      return 1;
+    }
+    if (res.error === "expired_token") {
+      process.stderr.write(
+        `agentproto auth: device code expired before approval. Re-run \`agentproto auth login\`.
+`
+      );
+      return 1;
+    }
+    process.stderr.write(
+      `agentproto auth: token endpoint returned '${res.error}'${res.error_description ? `: ${res.error_description}` : ""}
+`
+    );
+    return 1;
+  }
+  if (!token) {
+    process.stderr.write(
+      `agentproto auth: timed out waiting for approval. Re-run \`agentproto auth login\`.
+`
+    );
+    return 1;
+  }
+  const cred = {
+    token: token.access_token,
+    tokenType: "Bearer",
+    expiresAt: new Date(Date.now() + token.expires_in * 1e3).toISOString(),
+    obtainedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    ...token.refresh_token ? { refreshToken: token.refresh_token } : {},
+    ...token.scope ? { scope: token.scope } : {},
+    ...token.subject ? { subject: token.subject } : {},
+    ...token.revocation_id ? { revocationId: token.revocation_id } : {},
+    deviceLabel: label
+  };
+  await writeHost(host, cred);
+  process.stdout.write(
+    `agentproto auth: \u2713 logged in to ${normaliseHost(host)}
+  saved to ${credentialsPath()} (mode 0600)
+  ${formatExpiry(cred)}${cred.subject ? `, subject ${cred.subject}` : ""}
+`
+  );
+  return 0;
+}
+async function runAuthStatus(args) {
+  const { values } = parseArgs({
+    args: [...args],
+    strict: true,
+    options: {
+      host: { type: "string" },
+      json: { type: "boolean" }
+    }
+  });
+  const file = await loadCredentials();
+  const entries = Object.entries(file.hosts);
+  if (entries.length === 0) {
+    if (values.json) {
+      process.stdout.write(`{"hosts": []}
+`);
+    } else {
+      process.stdout.write(
+        `agentproto auth: no credentials. Try: agentproto auth login --host wss://guilde.work
+`
+      );
+    }
+    return 0;
+  }
+  const filtered = values.host ? entries.filter(([h]) => h === normaliseHost(values.host)) : entries;
+  if (values.json) {
+    process.stdout.write(
+      JSON.stringify(
+        {
+          hosts: filtered.map(([host, c]) => ({
+            host,
+            subject: c.subject ?? null,
+            scope: c.scope ?? null,
+            obtainedAt: c.obtainedAt,
+            expiresAt: c.expiresAt,
+            expired: isExpired(c),
+            deviceLabel: c.deviceLabel ?? null
+          }))
+        },
+        null,
+        2
+      ) + "\n"
+    );
+    return 0;
+  }
+  for (const [host, c] of filtered) {
+    const status = isExpired(c) ? "\u2717 EXPIRED" : "\u2713 active";
+    process.stdout.write(
+      `${status}  ${host}
+         subject: ${c.subject ?? "(none)"}
+         scope:   ${c.scope ?? "(none)"}
+         label:   ${c.deviceLabel ?? "(none)"}
+         ${formatExpiry(c)}  (obtained ${c.obtainedAt})
+`
+    );
+  }
+  return 0;
+}
+async function runAuthLogout(args) {
+  const { values } = parseArgs({
+    args: [...args],
+    strict: true,
+    options: { host: { type: "string" } }
+  });
+  const host = values.host ?? await pickDefaultHost();
+  if (!host) {
+    process.stderr.write(
+      `agentproto auth logout: no credentials to revoke. Pass --host <url> if you stored one.
+`
+    );
+    return 0;
+  }
+  const prev = await readHost(host);
+  if (!prev) {
+    process.stderr.write(
+      `agentproto auth logout: no credential found for ${host}.
+`
+    );
+    return 0;
+  }
+  let serverRevoked = "skipped";
+  try {
+    const httpHost = toHttp(host);
+    const discovery = await fetchJson(
+      `${httpHost}/.well-known/agentproto-host.json`
+    );
+    if (discovery.revocation_endpoint) {
+      const params = {
+        client_id: discovery.client_id,
+        token: prev.token
+      };
+      if (prev.revocationId) params["revocation_id"] = prev.revocationId;
+      await postForm(discovery.revocation_endpoint, params);
+      serverRevoked = "ok";
+    }
+  } catch {
+    serverRevoked = "failed";
+  }
+  await deleteHost(host);
+  const note = serverRevoked === "ok" ? " (server revoked)" : serverRevoked === "failed" ? " (server revocation failed; local copy still removed)" : " (no revocation endpoint advertised; local copy removed)";
+  process.stdout.write(`agentproto auth: \u2713 logged out of ${host}${note}
+`);
+  return 0;
+}
+async function pickDefaultHost() {
+  const f = await loadCredentials();
+  const keys = Object.keys(f.hosts);
+  if (keys.length === 0) return null;
+  let best = null;
+  for (const [host, cred] of Object.entries(f.hosts)) {
+    const t = Date.parse(cred.obtainedAt);
+    if (!Number.isFinite(t)) continue;
+    if (!best || t > best.obtainedAt) best = { host, obtainedAt: t };
+  }
+  return best?.host ?? keys[0] ?? null;
+}
+function toHttp(host) {
+  const trimmed = host.replace(/\/+$/, "");
+  if (trimmed.startsWith("wss://")) return "https://" + trimmed.slice(6);
+  if (trimmed.startsWith("ws://")) return "http://" + trimmed.slice(5);
+  return trimmed;
+}
+async function fetchJson(url) {
+  const res = await fetch(url, { headers: { Accept: "application/json" } });
+  if (!res.ok) {
+    throw new Error(`GET ${url} \u2192 ${res.status} ${res.statusText}`);
+  }
+  return await res.json();
+}
+async function postForm(url, body) {
+  const params = new URLSearchParams(body);
+  const res = await fetch(url, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/x-www-form-urlencoded",
+      Accept: "application/json"
+    },
+    body: params.toString()
+  });
+  if (!res.ok && res.status !== 400) {
+    const text = await res.text().catch(() => "");
+    throw new Error(
+      `POST ${url} \u2192 ${res.status} ${res.statusText}${text ? ": " + text.slice(0, 200) : ""}`
+    );
+  }
+  return await res.json();
+}
+function sleep(ms) {
+  return new Promise((resolve3) => setTimeout(resolve3, ms));
+}
+function formatDuration(ms) {
+  if (ms < 6e4) return `${Math.round(ms / 1e3)}s`;
+  if (ms < 36e5) return `${Math.round(ms / 6e4)}m`;
+  return `${Math.round(ms / 36e5)}h`;
+}
+function openBrowser(url) {
+  const p = platform();
+  const cmd = p === "darwin" ? "open" : p === "win32" ? "cmd" : "xdg-open";
+  const args = p === "win32" ? ["/c", "start", url] : [url];
+  return new Promise((resolve3) => {
+    try {
+      const child = spawn(cmd, args, { stdio: "ignore", detached: true });
+      child.once("error", () => resolve3());
+      child.once("spawn", () => {
+        child.unref();
+        resolve3();
+      });
+    } catch {
+      resolve3();
+    }
+  });
+}
 var slugToCamel = (slug) => slug.replace(/-([a-z0-9])/g, (_, c) => c.toUpperCase());
 async function resolveAdapter(slug) {
   if (!/^[a-z][a-z0-9-]*$/.test(slug)) {
@@ -41,6 +482,460 @@ 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 runSetupCommand(args) {
+  const { values, positionals } = parseArgs({
+    args: [...args],
+    allowPositionals: true,
+    strict: true,
+    options: {
+      force: { type: "boolean", short: "f" },
+      "dry-run": { type: "boolean" },
+      only: { type: "string", multiple: true }
+    }
+  });
+  const slug = positionals[0];
+  if (!slug) {
+    process.stderr.write(
+      "agentproto setup: missing adapter slug. Try: agentproto setup openclaw\n"
+    );
+    return 2;
+  }
+  const adapter = await resolveAdapter(slug);
+  return runSetup({
+    slug,
+    handle: adapter.handle,
+    force: values.force ?? false,
+    dryRun: values["dry-run"] ?? false,
+    ...values.only ? { only: values.only } : {}
+  });
+}
+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((resolve3) => {
+    const child = spawn(opener, args, { stdio: "ignore", detached: true });
+    child.once("error", () => resolve3());
+    child.once("spawn", () => resolve3());
+  });
+  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((resolve3) => {
+      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();
+            resolve3(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((resolve3) => {
+    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);
+      resolve3({ exitCode: 127, stdout, stderr: stderr || "spawn error" });
+    });
+    child.once("exit", (code) => {
+      clearTimeout(timer);
+      resolve3({ 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) {
@@ -50,7 +945,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];
@@ -69,6 +965,7 @@ async function runInstall(args) {
     );
     return 0;
   }
+  let alreadyInstalled = false;
   if (!values.force) {
     const checked = await runVersionCheck(adapter.handle.version_check);
     if (checked.ok) {
@@ -76,26 +973,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) {
@@ -105,48 +1043,233 @@ 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 ?? step.path ?? "(?)"}`;
+  }
+}
+async function runStep(step) {
+  switch (step.method) {
+    case "npm": {
+      if (!step.package) {
+        process.stderr.write("agentproto install: npm step missing package.\n");
+        return 2;
+      }
+      const argv = ["install"];
+      if (step.global) argv.push("-g");
+      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:
-      return `${step.method} ${step.package ?? step.url ?? "(?)"}`;
+      process.stderr.write(
+        `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 runStep(step) {
-  switch (step.method) {
-    case "npm": {
-      if (!step.package) {
-        process.stderr.write("agentproto install: npm step missing package.\n");
-        return 2;
+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;
       }
-      const argv = ["install"];
-      if (step.global) argv.push("-g");
-      argv.push(step.package);
-      return spawnInherit("npm", argv);
     }
-    default:
+    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: method '${step.method}' not yet implemented in this CLI version. Run it manually for now (see the adapter's INSTALL.md).
+        `agentproto install: unsupported archive format for ${filename}. Supported: .tar, .tar.gz, .tgz, .zip.
 `
       );
-      return 1;
+      return 5;
+    }
+    if (extractCode !== 0) return extractCode;
+    const srcBin = join(extractDir, opts.extractBin);
+    const binDir = process.env["AGENTPROTO_BIN_DIR"] ?? join(homedir3(), ".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 homedir3() {
+  return process.env["HOME"] ?? process.env["USERPROFILE"] ?? "/";
+}
 function spawnInherit(cmd, argv) {
-  return new Promise((resolve, reject) => {
+  return new Promise((resolve3, reject) => {
     const child = spawn(cmd, argv, { stdio: "inherit" });
     child.once("error", reject);
-    child.once("exit", (code) => resolve(code ?? 0));
+    child.once("exit", (code) => resolve3(code ?? 0));
   });
 }
 async function runVersionCheck(check) {
   if (!check) return { ok: false, message: "no version_check declared" };
-  return new Promise((resolve) => {
+  return new Promise((resolve3) => {
     const child = spawn("bash", ["-lc", check.cmd], {
       stdio: ["ignore", "pipe", "ignore"]
     });
@@ -154,19 +1277,19 @@ async function runVersionCheck(check) {
     child.stdout.on("data", (c) => {
       buf += c.toString("utf8");
     });
-    child.once("error", () => resolve({ ok: false, message: "check failed" }));
+    child.once("error", () => resolve3({ ok: false, message: "check failed" }));
     child.once("exit", (code) => {
       if (code !== 0) {
-        resolve({ ok: false, message: `check exited ${code}` });
+        resolve3({ ok: false, message: `check exited ${code}` });
         return;
       }
       const re = new RegExp(check.parse);
       const m = buf.match(re);
       if (!m || !m[1]) {
-        resolve({ ok: false, message: "could not parse version" });
+        resolve3({ ok: false, message: "could not parse version" });
         return;
       }
-      resolve({ ok: true, message: `version ${m[1]}` });
+      resolve3({ ok: true, message: `version ${m[1]}` });
     });
   });
 }
@@ -274,10 +1397,32 @@ 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;
+    }
   }
 }
 async function runServe(args) {
@@ -288,39 +1433,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((resolve3) => {
+      aborter.signal.addEventListener("abort", () => resolve3());
+    });
+    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;
@@ -330,24 +1579,23 @@ agentproto serve: received ${sig}, shutting down.
   reconnecting in ${backoffMs}ms\u2026
 `
       );
-      await sleep(backoffMs, aborter.signal);
+      await sleep2(backoffMs, aborter.signal);
       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"
   };
   if (opts.token) headers.authorization = `Bearer ${opts.token}`;
   const ws = new WebSocket(opts.connect, { headers });
-  await new Promise((resolve, reject) => {
+  await new Promise((resolve3, reject) => {
     const onOpen = () => {
       ws.off("error", onError);
-      resolve();
+      resolve3();
     };
     const onError = (err) => {
       ws.off("open", onOpen);
@@ -374,50 +1622,536 @@ 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) => {
+  await new Promise((resolve3) => {
     const offClose = sink.onClose(() => {
       offClose();
-      resolve();
+      resolve3();
     });
     if (signal.aborted) {
-      server.close().finally(() => resolve());
+      server.close().finally(() => resolve3());
     }
     signal.addEventListener("abort", () => {
-      server.close().finally(() => resolve());
+      server.close().finally(() => resolve3());
     });
   });
   process.stderr.write(`agentproto serve: tunnel closed.
 `);
 }
-function sleep(ms, signal) {
-  return new Promise((resolve) => {
-    if (signal.aborted) return resolve();
-    const timer = setTimeout(resolve, ms);
+function sleep2(ms, signal) {
+  return new Promise((resolve3) => {
+    if (signal.aborted) return resolve3();
+    const timer = setTimeout(resolve3, ms);
     signal.addEventListener("abort", () => {
       clearTimeout(timer);
-      resolve();
+      resolve3();
+    });
+  });
+}
+var USAGE2 = `agentproto workspace \u2014 manage local workspaces
+
+Usage:
+  agentproto workspace add <path> [--slug <slug>] [--label <text>]
+  agentproto workspace list  [--json]
+  agentproto workspace remove <slug>
+  agentproto workspace use <slug>
+  agentproto workspace --help
+
+Config file: ${DEFAULT_CONFIG_PATH()}
+`;
+async function runWorkspace(args) {
+  if (args.length === 0 || args.includes("--help") || args.includes("-h")) {
+    process.stdout.write(USAGE2);
+    return 0;
+  }
+  const sub = args[0];
+  const rest = args.slice(1);
+  switch (sub) {
+    case "add":
+      return runAdd(rest);
+    case "list":
+    case "ls":
+      return runList(rest);
+    case "remove":
+    case "rm":
+      return runRemove(rest);
+    case "use":
+      return runUse(rest);
+    default:
+      process.stderr.write(
+        `agentproto workspace: unknown subcommand '${sub}'
+
+${USAGE2}`
+      );
+      return 2;
+  }
+}
+async function runAdd(args) {
+  const { values, positionals } = parseArgs({
+    args: [...args],
+    allowPositionals: true,
+    strict: true,
+    options: {
+      slug: { type: "string" },
+      label: { type: "string" }
+    }
+  });
+  const rawPath = positionals[0];
+  if (!rawPath) {
+    process.stderr.write(
+      "agentproto workspace add: missing <path>. Try: agentproto workspace add ~/code/my-project\n"
+    );
+    return 2;
+  }
+  const absPath = resolve(rawPath.replace(/^~/, process.env.HOME ?? "~"));
+  if (!existsSync(absPath)) {
+    process.stderr.write(
+      `agentproto workspace add: "${absPath}" doesn't exist. Create the directory first or pass an existing one.
+`
+    );
+    return 2;
+  }
+  const slug = sanitizeSlug(values.slug ?? basename(absPath));
+  const config = await loadWorkspacesConfig();
+  const next = addWorkspace(config, {
+    slug,
+    path: absPath,
+    ...values.label ? { label: values.label } : {}
+  });
+  await saveWorkspacesConfig(next);
+  const wasActive = config.active === slug;
+  const becameActive = next.active === slug && !wasActive;
+  process.stdout.write(
+    `\u2713 ${slug} \u2192 ${absPath}` + (becameActive ? "  (set as active \u2014 first registered workspace)" : "") + "\n"
+  );
+  return 0;
+}
+async function runList(args) {
+  const { values } = parseArgs({
+    args: [...args],
+    allowPositionals: false,
+    strict: true,
+    options: { json: { type: "boolean" } }
+  });
+  const config = await loadWorkspacesConfig();
+  if (values.json) {
+    process.stdout.write(JSON.stringify(config, null, 2) + "\n");
+    return 0;
+  }
+  if (config.workspaces.length === 0) {
+    process.stdout.write(
+      "No workspaces registered.\nAdd one with: agentproto workspace add <path>\n"
+    );
+    return 0;
+  }
+  const sorted = [...config.workspaces].sort(
+    (a, b) => b.updatedAt.localeCompare(a.updatedAt)
+  );
+  const slugCol = Math.max(...sorted.map((w) => w.slug.length), 6);
+  for (const w of sorted) {
+    const marker = w.slug === config.active ? "\u25CF" : " ";
+    const slugCell = w.slug.padEnd(slugCol);
+    const labelSuffix = w.label ? `  (${w.label})` : "";
+    process.stdout.write(
+      `${marker} ${slugCell}  ${w.path}${labelSuffix}
+`
+    );
+  }
+  process.stdout.write(
+    `
+${sorted.length} workspace${sorted.length === 1 ? "" : "s"}` + (config.active ? `, active: ${config.active}` : ", no active") + "\n"
+  );
+  return 0;
+}
+async function runRemove(args) {
+  const { positionals } = parseArgs({
+    args: [...args],
+    allowPositionals: true,
+    strict: true,
+    options: {}
+  });
+  const slug = positionals[0];
+  if (!slug) {
+    process.stderr.write(
+      "agentproto workspace remove: missing <slug>.\n"
+    );
+    return 2;
+  }
+  const config = await loadWorkspacesConfig();
+  const sanitised = sanitizeSlug(slug);
+  const existed = config.workspaces.some((w) => w.slug === sanitised);
+  if (!existed) {
+    process.stderr.write(
+      `agentproto workspace remove: no workspace named "${sanitised}".
+`
+    );
+    return 2;
+  }
+  const next = removeWorkspace(config, sanitised);
+  await saveWorkspacesConfig(next);
+  process.stdout.write(`\u2717 removed ${sanitised}
+`);
+  if (next.active && next.active !== config.active) {
+    process.stdout.write(`  active reassigned to: ${next.active}
+`);
+  } else if (!next.active && config.active) {
+    process.stdout.write(`  no workspaces left \u2014 active cleared
+`);
+  }
+  return 0;
+}
+async function runUse(args) {
+  const { positionals } = parseArgs({
+    args: [...args],
+    allowPositionals: true,
+    strict: true,
+    options: {}
+  });
+  const slug = positionals[0];
+  if (!slug) {
+    process.stderr.write("agentproto workspace use: missing <slug>.\n");
+    return 2;
+  }
+  const config = await loadWorkspacesConfig();
+  try {
+    const next = setActiveWorkspace(config, slug);
+    await saveWorkspacesConfig(next);
+    const w = next.workspaces.find((x) => x.slug === next.active);
+    process.stdout.write(`\u25CF active: ${next.active}  (${w?.path ?? "?"})
+`);
+    return 0;
+  } catch (err) {
+    process.stderr.write(
+      `agentproto workspace use: ${err instanceof Error ? err.message : String(err)}
+`
+    );
+    return 2;
+  }
+}
+var USAGE3 = `agentproto sessions \u2014 browse local daemon sessions
+
+Usage:
+  agentproto sessions [--watch] [--json]
+  agentproto sessions --attach <id> [--no-color]
+
+Discovers the daemon via ~/.agentproto/runtime.json. Set
+AGENTPROTO_DAEMON_URL to override.
+`;
+async function runSessions(args) {
+  if (args.includes("--help") || args.includes("-h")) {
+    process.stdout.write(USAGE3);
+    return 0;
+  }
+  const { values } = parseArgs({
+    args: [...args],
+    allowPositionals: false,
+    strict: true,
+    options: {
+      watch: { type: "boolean" },
+      json: { type: "boolean" },
+      attach: { type: "string" },
+      "no-color": { type: "boolean" }
+    }
+  });
+  const baseUrl = await resolveDaemonUrl();
+  if (!baseUrl) {
+    process.stderr.write(
+      "agentproto sessions: no daemon found.\n  Start one with `agentproto serve` or set AGENTPROTO_DAEMON_URL.\n"
+    );
+    return 2;
+  }
+  if (values.attach) {
+    return runAttach({
+      baseUrl,
+      id: values.attach,
+      colour: !values["no-color"]
+    });
+  }
+  if (values.json) {
+    const list2 = await fetchSessions(baseUrl);
+    process.stdout.write(JSON.stringify(list2, null, 2) + "\n");
+    return 0;
+  }
+  if (values.watch) {
+    return runWatch(baseUrl);
+  }
+  const list = await fetchSessions(baseUrl);
+  printTable(list);
+  return 0;
+}
+async function resolveDaemonUrl() {
+  if (process.env.AGENTPROTO_DAEMON_URL) {
+    return process.env.AGENTPROTO_DAEMON_URL.replace(/\/+$/, "");
+  }
+  const config = await loadWorkspacesConfig().catch(() => null);
+  if (!config) return null;
+  const candidates = [
+    getActiveWorkspace(config),
+    ...config.workspaces
+  ].filter(
+    (w, i, arr) => !!w && arr.findIndex((x) => x?.slug === w.slug) === i
+  );
+  for (const w of candidates) {
+    const url = await readRuntimeJson(w.path);
+    if (url) return url;
+  }
+  return null;
+}
+async function readRuntimeJson(workspacePath) {
+  const path = resolve(workspacePath, ".agentproto", "runtime.json");
+  try {
+    const raw = await promises.readFile(path, "utf8");
+    const parsed = JSON.parse(raw);
+    if (typeof parsed.port !== "number") return null;
+    return `http://${parsed.bind ?? "127.0.0.1"}:${parsed.port}`;
+  } catch {
+    return null;
+  }
+}
+async function fetchSessions(baseUrl) {
+  const body = await httpGetJson(`${baseUrl}/sessions`);
+  if (!body || !Array.isArray(body.sessions)) {
+    return [];
+  }
+  return body.sessions;
+}
+function printTable(rows) {
+  if (rows.length === 0) {
+    process.stdout.write("No sessions.\n");
+    return;
+  }
+  const widths = {
+    id: Math.max(...rows.map((r) => r.id.length), 4),
+    kind: Math.max(...rows.map((r) => r.kind.length), 4),
+    workspace: Math.max(...rows.map((r) => r.workspaceSlug.length), 9),
+    status: Math.max(...rows.map((r) => r.status.length), 8),
+    age: 8
+  };
+  const header = pad("ID", widths.id) + "  " + pad("KIND", widths.kind) + "  " + pad("WORKSPACE", widths.workspace) + "  " + pad("STATUS", widths.status) + "  " + pad("AGE", widths.age) + "  COMMAND";
+  process.stdout.write(`\x1B[2m${header}\x1B[0m
+`);
+  const now = Date.now();
+  for (const r of rows) {
+    const age = humaniseDelta(now - new Date(r.startedAt).getTime());
+    const tone = statusColour(r.status);
+    process.stdout.write(
+      pad(r.id, widths.id) + "  " + pad(r.kind, widths.kind) + "  " + pad(r.workspaceSlug, widths.workspace) + `  ${tone}${pad(r.status, widths.status)}\x1B[0m  ` + pad(age, widths.age) + "  " + truncate2(r.command, 60) + "\n"
+    );
+  }
+}
+function statusColour(status) {
+  switch (status) {
+    case "running":
+      return "\x1B[32m";
+    // green
+    case "starting":
+    case "mounting":
+      return "\x1B[33m";
+    // yellow
+    case "exited":
+      return "\x1B[2m";
+    // dim
+    case "killed":
+    case "error":
+      return "\x1B[31m";
+    // red
+    default:
+      return "";
+  }
+}
+function pad(s, n) {
+  if (s.length >= n) return s;
+  return s + " ".repeat(n - s.length);
+}
+function truncate2(s, n) {
+  if (s.length <= n) return s;
+  return s.slice(0, n - 1) + "\u2026";
+}
+function humaniseDelta(ms) {
+  if (ms < 6e4) return `${Math.floor(ms / 1e3)}s`;
+  if (ms < 36e5) return `${Math.floor(ms / 6e4)}m`;
+  if (ms < 864e5) return `${Math.floor(ms / 36e5)}h`;
+  return `${Math.floor(ms / 864e5)}d`;
+}
+async function runWatch(baseUrl) {
+  const tty = process.stdin.isTTY === true;
+  if (tty) {
+    process.stdin.setRawMode(true);
+    process.stdin.resume();
+    process.stdin.setEncoding("utf8");
+  }
+  let stop = false;
+  const onKey = (key) => {
+    if (key === "q" || key === "") stop = true;
+  };
+  if (tty) process.stdin.on("data", onKey);
+  process.on("SIGINT", () => {
+    stop = true;
+  });
+  try {
+    while (!stop) {
+      const list = await fetchSessions(baseUrl).catch((err) => {
+        process.stdout.write(`\x1Bc[fetch error] ${String(err)}
+`);
+        return null;
+      });
+      process.stdout.write("\x1Bc");
+      process.stdout.write(
+        `\x1B[2magentproto sessions  \u2022  ${baseUrl}  \u2022  ${tty ? "press q to quit" : "Ctrl-C to quit"}\x1B[0m
+
+`
+      );
+      if (list) printTable(list);
+      await new Promise((res) => setTimeout(res, 2e3));
+    }
+  } finally {
+    if (tty) {
+      process.stdin.off("data", onKey);
+      process.stdin.setRawMode(false);
+      process.stdin.pause();
+    }
+    process.stdout.write("\n");
+  }
+  return 0;
+}
+async function runAttach({ baseUrl, id, colour }) {
+  return new Promise((resolve3) => {
+    const url = new URL(`${baseUrl}/sessions/${id}/stream`);
+    const lib = url.protocol === "https:" ? https : http;
+    const req = lib.get(
+      url,
+      { headers: { accept: "text/event-stream" } },
+      (res) => {
+        if (res.statusCode === 404) {
+          process.stderr.write(
+            `agentproto sessions --attach: no session "${id}".
+`
+          );
+          resolve3(2);
+          return;
+        }
+        if (res.statusCode !== 200) {
+          process.stderr.write(
+            `agentproto sessions --attach: HTTP ${res.statusCode}
+`
+          );
+          resolve3(1);
+          return;
+        }
+        let buf = "";
+        res.setEncoding("utf8");
+        res.on("data", (chunk) => {
+          buf += chunk;
+          let idx = buf.indexOf("\n\n");
+          while (idx !== -1) {
+            const event = buf.slice(0, idx);
+            buf = buf.slice(idx + 2);
+            for (const line of event.split("\n")) {
+              if (line.startsWith("data:")) {
+                const payload = line.slice(5).trim();
+                try {
+                  const json = JSON.parse(payload);
+                  if (typeof json.line !== "string") continue;
+                  if (colour && json.stream === "stderr") {
+                    process.stdout.write(`\x1B[31m${json.line}\x1B[0m
+`);
+                  } else {
+                    process.stdout.write(json.line + "\n");
+                  }
+                } catch {
+                }
+              }
+            }
+            idx = buf.indexOf("\n\n");
+          }
+        });
+        res.on("end", () => resolve3(0));
+      }
+    );
+    req.on("error", (err) => {
+      process.stderr.write(`agentproto sessions --attach: ${err.message}
+`);
+      resolve3(1);
+    });
+    process.on("SIGINT", () => {
+      req.destroy();
+      resolve3(0);
     });
   });
 }
+function httpGetJson(url) {
+  return new Promise((resolve3, reject) => {
+    const u = new URL(url);
+    const lib = u.protocol === "https:" ? https : http;
+    lib.get(u, (res) => {
+      let body = "";
+      res.setEncoding("utf8");
+      res.on("data", (c) => body += c);
+      res.on("end", () => {
+        if ((res.statusCode ?? 0) < 200 || (res.statusCode ?? 0) >= 300) {
+          reject(new Error(`HTTP ${res.statusCode}: ${body.slice(0, 200)}`));
+          return;
+        }
+        try {
+          resolve3(JSON.parse(body));
+        } catch (err) {
+          reject(err instanceof Error ? err : new Error(String(err)));
+        }
+      });
+    }).on("error", reject);
+  });
+}
 
 // src/cli.ts
-var USAGE = `agentproto \u2014 AIP-45 agent CLI host
+var USAGE4 = `agentproto \u2014 AIP-45 agent CLI host
 
 Usage:
-  agentproto install <slug> [--registry <path>]
-  agentproto run     <slug> [--cwd <dir>] [--prompt <text>] [--resume <session-id>]
-  agentproto serve   --connect <url> [--token <jwt>] [--label <name>]
+  agentproto auth      <login|status|logout> [--host <url>] [--label <name>]
+  agentproto install   <slug> [--force] [--dry-run] [--skip-setup]
+  agentproto setup     <slug> [--force] [--dry-run] [--only <stepId>...]
+  agentproto run       <slug> [--cwd <dir>] [--prompt <text>] [--resume <session-id>]
+  agentproto serve     [--workspace <dir>] [--port <n>] [--bind <ip>]
+                       [--connect <url> [--token <jwt>] [--label <name>]]
+  agentproto workspace <add|list|remove|use> [args]
+  agentproto sessions  [--watch] [--attach <id>] [--json]
   agentproto --help
   agentproto --version
 
 Examples:
+  agentproto auth login --host wss://guilde.work     # device flow \u2192 ~/.agentproto/credentials.json
   agentproto install claude-code
+  agentproto setup openclaw                # re-run setup (idempotent via skip_if + ledger)
   agentproto run claude-code --cwd . --prompt "summarise this repo"
-  agentproto serve --connect wss://guilde.work/api/v1/agentproto/tunnel --token $AGENTPROTO_TOKEN
+  agentproto workspace add ~/code/my-project --slug my-project
+  agentproto workspace list
+  agentproto serve --connect wss://guilde.work/api/v1/agentproto/tunnel
 `;
-var VERBS = /* @__PURE__ */ new Set(["install", "run", "serve"]);
+var VERBS = /* @__PURE__ */ new Set([
+  "auth",
+  "install",
+  "setup",
+  "run",
+  "serve",
+  "workspace",
+  "sessions"
+]);
 async function main(argv) {
   const verbIdx = argv.findIndex((a) => VERBS.has(a));
   if (verbIdx === -1) {
@@ -426,29 +2160,37 @@ async function main(argv) {
       return 0;
     }
     if (argv.includes("--help") || argv.includes("-h") || argv.length === 0) {
-      process.stdout.write(USAGE);
+      process.stdout.write(USAGE4);
       return 0;
     }
     process.stderr.write(
       `agentproto: unrecognised argument(s): ${argv.join(" ")}
 
-${USAGE}`
+${USAGE4}`
     );
     return 2;
   }
   const verb = argv[verbIdx];
   const rest = argv.slice(verbIdx + 1);
   switch (verb) {
+    case "auth":
+      return runAuth(rest);
     case "install":
       return runInstall(rest);
+    case "setup":
+      return runSetupCommand(rest);
     case "run":
       return runRun(rest);
     case "serve":
       return runServe(rest);
+    case "workspace":
+      return runWorkspace(rest);
+    case "sessions":
+      return runSessions(rest);
     default:
       process.stderr.write(`agentproto: unknown verb '${verb}'
 
-${USAGE}`);
+${USAGE4}`);
       return 2;
   }
 }