@agentproto/cli 0.5.0 → 0.7.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,8 +121,15 @@ 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;
+    /** True when this resolution was served from the last-known-good cache
+     *  because the current import attempt failed (see `importFresh`'s doc
+     *  comment for why that happens mid-rebuild). Never present on an
+     *  actually-fresh successful resolution — callers that only care about
+     *  spawning don't need to check it, callers that surface status
+     *  (`listAdaptersWithCatalog`) must not report it as plain "ready". */
+    readonly stale?: true;
 }
 /** Mode metadata surfaced in `adapter_list` — the UI-safe subset of an
  *  AIP-45 `modes[]` entry. Omits the spawn internals (`bin_args_*`, `env`)
@@ -141,13 +170,36 @@ interface AdapterInfo {
      *  adapter manifest's `models.allowed` field. Empty when the adapter
      *  doesn't declare a model list (accepts whatever the underlying
      *  binary accepts). Pass one of these as `model` in `agent_start`
-     *  to avoid trial-and-error validation errors. */
+     *  to avoid trial-and-error validation errors. Flat id list — kept
+     *  exactly as before so every existing consumer of this field keeps
+     *  working untouched; see `modelDetails` for the provider/mode a
+     *  structured entry additionally states. */
     models: string[];
     /** AIP-45 `modes[]` the adapter declares, projected to the UI-safe
      *  subset (id + description + honest status). Empty when the adapter
      *  declares no modes. `status` defaults to "active" when the manifest
      *  omits it, so a declared mode is never silently statusless. */
     modes: AdapterMode[];
+    /** Same models as `models`, in the same order, each carrying the
+     *  `provider`/`mode` a structured `models.allowed` entry states.
+     *  `provider`/`mode` are undefined for a bare-string entry — an
+     *  unstated provider is never guessed here (see AdapterModelInfo). */
+    modelDetails: AdapterModelInfo[];
+}
+/** One entry of an adapter's declared model menu, projected from a
+ *  `models.allowed` item — bare string or {@link AgentCliModelEntry}.
+ *  `provider`/`mode` stay undefined for a bare-string entry: an unstated
+ *  provider must never be guessed downstream (a wrong-but-confident
+ *  guess would bill the wrong account). See AGENTS.md / AIP-45 for the
+ *  three-facts-in-one-string problem this splits apart. */
+interface AdapterModelInfo {
+    id: string;
+    /** Who serves/bills this model (a ProviderPreset id, or a direct
+     *  provider like "anthropic"). Undefined when unstated. */
+    provider?: string;
+    /** This adapter's mode id that routes to `provider`. Undefined when
+     *  the adapter routes on its own or needs no mode switch. */
+    mode?: string;
 }
 declare function resolveAdapter(slug: string): Promise<ResolvedAdapter>;
 /**
@@ -174,5 +226,147 @@ 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).
+ *
+ * A fourth status, `"unresolvable"`, sits outside that kit-owned vocabulary:
+ * when `resolveAdapter` falls back to its last-known-good cache (see there),
+ * the kit sees a normally-resolved handle and would compute "ready" — which
+ * would silently hide the fact that the CURRENT import attempt just failed.
+ * `resolved.stale` (threaded through `wrapCliHandle` → `AgentCliInfo`) is
+ * checked below and overrides whatever the kit computed, so a rebuilding
+ * adapter reads as neither "ready" (a lie — a spawn against a half-written
+ * dist would still fail) nor "supported" (equally wrong — it tells the
+ * operator to reinstall something that's already there).
+ */
+declare function listAdaptersWithCatalog(catalog: readonly AdapterCatalogEntry[]): Promise<(AdapterInfo & {
+    status: "supported" | "available" | "ready" | "unresolvable";
+    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" | "unresolvable";
+    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 };