@agentproto/cli 0.1.0-alpha.0 → 0.1.0-alpha.2

package/dist/index.d.ts

@@ -11,9 +11,19 @@ import { AgentCliHandle } from '@agentproto/driver-agent-cli';
  * it before reading its manifest). Bootstrapping the adapter package is
  * a separate concern — `npm i -g @agentproto/adapter-<slug>` first.
  *
- * v0 implements `npm` only. Other methods (brew/pip/cargo/go/curl/
- * download) report a clear "not yet implemented" message — they're a
- * shellout exercise but each needs its own checksum / chmod handling.
+ * Method support matrix:
+ *   - `npm`            ✓
+ *   - `brew`           ✓ (macOS / Linux Homebrew)
+ *   - `curl`           ✓ (with optional verify_sha256)
+ *   - `download`       ✓ (tarball/zip + extract_bin + optional verify_sha256)
+ *   - `pip`            ✓ (with optional `user: true`)
+ *   - `cargo`          ✓
+ *   - `go`             ✓
+ *   - `apt/dnf/pacman` ✗ (privilege escalation needs explicit sudo policy)
+ *   - `choco/scoop`    ✗ (Windows-only; not yet platform-detected)
+ *   - `vendored`       ✗ (workspace-relative; needs a workspace root)
+ *
+ * After install, runs the optional `setup[]` pipeline (AIP-29 § Setup).
  */
 declare function runInstall(args: readonly string[]): Promise<number>;
 
@@ -30,20 +40,39 @@ declare function runInstall(args: readonly string[]): Promise<number>;
 declare function runRun(args: readonly string[]): Promise<number>;
 
 /**
- * `agentproto serve --connect <url>`
- *
- * Long-running daemon. Opens a WebSocket to a host (Guilde-shaped API),
- * authenticates with a token, then accepts spawn / stdin / stdout /
- * stderr / kill / exit frames over that channel — multiplexing many
- * ACP sessions through one process. The daemon owns local resources
- * (PTYs, child processes, JSONL session stores) so a host running in
- * the cloud can drive a CLI living on the user's laptop.
- *
- * v0.1 stub: argument parsing + connection scaffolding only. The wire
- * protocol is still being designed (tunnel frames need to land in
- * @agentproto/acp first); shipping a half-baked daemon would lock us
- * into the wrong shape. For now this verb prints a clear "not yet"
- * and exits non-zero so CI pipelines don't accidentally rely on it.
+ * `agentproto serve [--workspace <dir>] [--port <n>] [--connect <wss>]`
+ *
+ * The single canonical agentproto daemon. Boots a local gateway
+ * (HTTP + MCP server + sessions registry + workspace fs +
+ * heartbeat) on `--port` (default 18790), and OPTIONALLY opens an
+ * outbound WebSocket tunnel to a host (Guilde-shaped API) when
+ * `--connect <url>` is set. With or without the tunnel:
+ *
+ *   - HTTP /sessions, /sessions/agent, /sessions/:id/* routes work
+ *   - MCP tools (start_agent_session, prompt_agent_session, …) are
+ *     reachable via the daemon's /mcp transport
+ *   - the LocalDaemonSessionsCard in guilde-web sees every spawn
+ *
+ * When the tunnel is up, every tunnel-driven spawn is also adopted
+ * into the gateway's sessions registry via the
+ * `createTunnelServer.onChildSpawned` hook, so an operator
+ * dispatching from the cloud lands in the same /sessions list as a
+ * user spawning locally — single source of truth for what's running
+ * on the user's machine.
+ *
+ * Replaces the old `playground/scripts/gateway.ts` for production
+ * use (the playground keeps its own script for the MCP CRUD
+ * doctype demo). v1 reuses createGateway with empty specs + a
+ * noop heartbeat; the playground variant adds toolSpec/agentSpec/
+ * etc. for its specific spec-authoring use case.
+ *
+ * Reconnect-with-backoff is built in for the tunnel. The local
+ * gateway stays up across reconnects — only the tunnel cycles.
+ *
+ * Authorization: v0 trusts every spawn frame the host sends — there
+ * is no policy file. Future work will gate spawn requests on a
+ * `~/.agentproto/policy.toml` allowlist (see project_agentproto_repos
+ * memory). The token is the only access control today.
  */
 declare function runServe(args: readonly string[]): Promise<number>;
 
@@ -68,6 +97,52 @@ interface ResolvedAdapter {
     readonly source: "npm" | "file" | "bundled";
     readonly packageName?: string;
 }
+/**
+ * Compact metadata about an installed adapter — the shape returned
+ * by `listInstalledAdapters()` and exposed via the daemon's
+ * `GET /adapters` route + `list_adapters` MCP tool. Only fields
+ * safe to surface in a UI list (no install scripts, no env keys).
+ * For full handle access call `resolveAdapter(slug)`.
+ */
+interface AdapterInfo {
+    slug: string;
+    /** Display name from the manifest. */
+    name: string;
+    /** Adapter package version (matches npm package.json `version`). */
+    version: string;
+    /** One-line user-facing description. */
+    description: string;
+    /** Wire protocol — informs prompt/multi-turn semantics. */
+    protocol: string;
+    /** True when the adapter advertises a streaming session contract. */
+    streaming: boolean;
+    /** npm package name (for install hints / "open in npmjs.com" links). */
+    packageName: string;
+}
 declare function resolveAdapter(slug: string): Promise<ResolvedAdapter>;
+/**
+ * Enumerate every `@agentproto/adapter-*` package reachable from the
+ * current node module-resolution path. Used by the daemon's
+ * `GET /adapters` route and `list_adapters` MCP tool so UIs (web
+ * spawn dialog) and operators can pick from the installed set
+ * without trial-and-error against `resolveAdapter(slug)`.
+ *
+ * Implementation: walk `node_modules/@agentproto` looking for
+ * `adapter-*` directories; for each, dynamic-import the package +
+ * extract the AgentCliHandle's display fields. Failures (broken
+ * exports, missing dist) are collected as warnings rather than
+ * thrown — partial discovery beats failing the whole listing on
+ * one bad adapter.
+ *
+ * Discovery is async + reads disk on every call; cache at the
+ * caller layer if you list often. v0 does no caching here because
+ * adapter sets typically change rarely (npm i / rm) and a fresh
+ * scan stays fast (~10 packages worth of dynamic imports).
+ */
+declare function listInstalledAdapters(opts?: {
+    /** Override the search root. Defaults to walking up from the cli
+     *  package's own location until we hit a `node_modules/@agentproto`. */
+    searchRoot?: string;
+}): Promise<AdapterInfo[]>;
 
-export { type ResolvedAdapter, resolveAdapter, runInstall, runRun, runServe };
+export { type AdapterInfo, type ResolvedAdapter, listInstalledAdapters, resolveAdapter, runInstall, runRun, runServe };