@agentproto/cli 0.5.0 → 0.6.0

package/dist/index.d.ts

@@ -1,4 +1,6 @@
 import { AgentCliMode, AgentCliHandle } from '@agentproto/driver-agent-cli';
+import { AdapterCatalogEntry } from '@agentproto/provider-kit';
+import { AcpAgentConfigEntry, AgentprotoConfig } from '@agentproto/runtime/config';
 
 /**
  * `agentproto install <slug>`
@@ -76,6 +78,26 @@ declare function runRun(args: readonly string[]): Promise<number>;
  */
 declare function runServe(args: readonly string[]): Promise<number>;
 
+/**
+ * `agentproto acp <subcommand>`
+ *
+ * Manage generic ACP agents — any CLI that already speaks the Agent
+ * Client Protocol, connectable with zero adapter code (see
+ * ../registry/acp-generic.ts).
+ *
+ * Subcommands:
+ *   ls                                    curated catalog + config agents, with status
+ *   add <slug> --bin <bin> [--args …]     write a config.acpAgents entry
+ *              [--name] [--desc] [--env]
+ *              [--resumable]
+ *   rm  <slug>                            remove a config.acpAgents entry
+ *
+ * `ls` reflects both the built-in `ACP_CATALOG` and the user's
+ * `~/.agentproto/config.json` `acpAgents`; `add`/`rm` only ever touch the
+ * config file — the curated catalog is read-only.
+ */
+declare function runAcp(args: readonly string[]): Promise<number>;
+
 /**
  * Resolve a slug like "claude-code" to a runnable `AgentCliHandle`.
  *
@@ -99,7 +121,7 @@ interface AgentCliCommand {
 interface ResolvedAdapter {
     readonly slug: string;
     readonly handle: AgentCliHandle;
-    readonly source: "npm" | "file" | "bundled";
+    readonly source: "npm" | "file" | "bundled" | "acp-config" | "acp-catalog";
     readonly packageName?: string;
 }
 /** Mode metadata surfaced in `adapter_list` — the UI-safe subset of an
@@ -174,5 +196,137 @@ declare function listInstalledAdapters(opts?: {
      *  package's own location until we hit a `node_modules/@agentproto`. */
     searchRoot?: string;
 }): Promise<AdapterInfo[]>;
+/**
+ * Enumerate adapters starting from a static catalog and enriching each entry
+ * with its runtime availability status:
+ *
+ *   "supported" — known to agentproto, package not importable (not installed)
+ *   "available" — package resolves; requiresSetup but no ledger yet
+ *   "ready"     — package resolves + setup complete (or no setup needed)
+ *
+ * Also appends any adapters discovered in node_modules that aren't in the
+ * catalog, so locally-installed custom adapters still appear.
+ *
+ * Status is derived via the kit's `computeStatus`: resolved × requiresSetup ×
+ * ledger-exists — never via `handle.check()` (per OQ-5).
+ */
+declare function listAdaptersWithCatalog(catalog: readonly AdapterCatalogEntry[]): Promise<(AdapterInfo & {
+    status: "supported" | "available" | "ready";
+    hint?: string;
+})[]>;
+/** A single row of the merged adapter listing — npm/native catalog
+ *  entries and generic ACP entries share this shape (the latter also
+ *  carry a `source`). */
+type AdapterListing = AdapterInfo & {
+    status: "supported" | "available" | "ready";
+    hint?: string;
+    source?: "acp-config" | "acp-catalog";
+};
+/**
+ * The full adapter listing surfaced by `adapter_list` / `GET /adapters`:
+ * every npm/native catalog adapter PLUS the generic ACP agents (curated
+ * `ACP_CATALOG` + user `config.acpAgents`). Generic entries whose slug is
+ * already covered by a native adapter are dropped, so a slug never appears
+ * twice. Native adapters keep their richer status (`ready` after setup);
+ * generic entries are `available` (bin on PATH) or `supported` (not yet).
+ */
+declare function listAdaptersWithAcp(catalog: readonly AdapterCatalogEntry[]): Promise<AdapterListing[]>;
+
+/**
+ * Generic ACP agents — connect any ACP-speaking CLI with zero adapter code.
+ *
+ * Our ACP protocol arm (`createAcpProtocolArm`) is fully adapter-agnostic:
+ * it performs the standard `initialize` / `session/new` handshake over stdio
+ * JSON-RPC and streams turns, regardless of which binary is on the other end.
+ * So any CLI that already speaks the Agent Client Protocol doesn't need a
+ * bespoke `@agentproto/adapter-*` package — it just needs a spawn recipe.
+ *
+ * `acpHandleFromSpec` mints a runnable `AgentCliHandle` from a plain
+ * `AcpAgentSpec` (bin + args + env + a few flags). Two sources feed it:
+ *   - `ACP_CATALOG` — a conservative, curated list of known ACP CLIs.
+ *   - `config.acpAgents` — user-defined entries in `~/.agentproto/config.json`.
+ * User entries shadow the catalog on slug collision.
+ *
+ * `resolveAdapter` (see ./resolve.ts) tries npm first, then these; so a real
+ * adapter package always wins over a generic spec of the same slug.
+ */
+
+/**
+ * A generic ACP agent's spawn recipe. The config-file form
+ * (`AcpAgentConfigEntry`, keyed by slug in `acpAgents`) plus the slug
+ * itself. Kept in sync with the runtime config type by extension so the
+ * two never drift.
+ */
+interface AcpAgentSpec extends AcpAgentConfigEntry {
+    /** Adapter slug, e.g. "gemini-cli". Lower-kebab, ≥3 chars (AIP-45 id). */
+    slug: string;
+}
+/** Distinguishes where a resolved generic handle came from. */
+type AcpSpecSource = "acp-config" | "acp-catalog";
+/**
+ * Mint a runnable `AgentCliHandle` from a plain spec by routing every
+ * field through `defineAgentCli` with `protocol: "acp"`. The result is a
+ * fully-validated AIP-45 handle — schema-identical to a hand-authored
+ * native ACP adapter, just without the npm package.
+ *
+ * The AIP-45 schema requires `install` / `version_check` / `sandbox`
+ * even though a generic agent is bring-your-own-binary: we synthesize
+ * truthful, minimal values (a `vendored` install pointing at the bin so
+ * `agentproto install` correctly treats it as pre-provided, a
+ * conventional `<bin> --version` check, and the shared GENERIC.ACP.md as
+ * both the `acp` wire ref and the `sandbox` ref). This keeps the existing
+ * schema unchanged — no fighting it.
+ */
+declare function acpHandleFromSpec(spec: AcpAgentSpec): AgentCliHandle;
+/**
+ * Curated catalog of known, publicly-documented ACP-speaking CLIs that do
+ * NOT ship a native `@agentproto/adapter-*` package. Conservative on
+ * purpose: every entry's ACP invocation is drawn from the agent's own
+ * public docs — no invented flags. Agents that already have a native
+ * adapter in `CATALOG` (claude-code, opencode, codex, hermes, …) are
+ * excluded; a native adapter always wins in `resolveAdapter` anyway.
+ *
+ * The `--experimental-acp` flag family below is the well-documented ACP
+ * entry point popularised by Gemini CLI and reused verbatim by its
+ * public forks.
+ */
+declare const ACP_CATALOG: readonly AcpAgentSpec[];
+/**
+ * Resolve a slug to a generic ACP spec: user config first (shadowing),
+ * then the curated catalog. Returns the matched spec + its source, or
+ * `null` when neither has the slug. Pass `config` to avoid a disk read
+ * (e.g. when the caller already loaded it); otherwise it's read lazily.
+ */
+declare function resolveAcpSpec(slug: string, config?: AgentprotoConfig): Promise<{
+    spec: AcpAgentSpec;
+    source: AcpSpecSource;
+} | null>;
+/**
+ * Is `bin` runnable — a path that exists+executable, or a bare name found
+ * on PATH? Used to classify generic ACP agents in the listing:
+ * `available` when present, `supported` (install_hint) when not.
+ */
+declare function binOnPath(bin: string): Promise<boolean>;
+/** A generic ACP entry as surfaced in the adapter listing — the same
+ *  UI-safe shape as `listAdaptersWithCatalog` entries, plus provenance. */
+type AcpGenericListEntry = AdapterInfo & {
+    status: "supported" | "available";
+    hint?: string;
+    source: AcpSpecSource;
+};
+/**
+ * List the generic ACP agents (curated catalog + user config, config
+ * shadowing catalog) with a runtime `status` derived from bin presence:
+ * `available` when the bin is on PATH, `supported` (not installed, shows
+ * `install_hint`) otherwise. Config-defined agents are always listed.
+ *
+ * `excludeSlugs` drops entries already covered by an npm adapter /
+ * native catalog entry, so a generic spec never double-appears next to a
+ * real adapter of the same slug in the merged `adapter_list`.
+ */
+declare function listAcpGenericAdapters(opts?: {
+    config?: AgentprotoConfig;
+    excludeSlugs?: ReadonlySet<string>;
+}): Promise<AcpGenericListEntry[]>;
 
-export { type AdapterInfo, type ResolvedAdapter, listInstalledAdapters, resolveAdapter, runInstall, runRun, runServe };
+export { ACP_CATALOG, type AcpAgentSpec, type AcpGenericListEntry, type AcpSpecSource, type AdapterInfo, type AdapterListing, type ResolvedAdapter, acpHandleFromSpec, binOnPath, listAcpGenericAdapters, listAdaptersWithAcp, listAdaptersWithCatalog, listInstalledAdapters, resolveAcpSpec, resolveAdapter, runAcp, runInstall, runRun, runServe };