@agentproto/cli 0.6.0 → 0.7.0

package/dist/index.d.ts

@@ -123,6 +123,13 @@ interface ResolvedAdapter {
     readonly handle: AgentCliHandle;
     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`)
@@ -163,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>;
 /**
@@ -209,16 +239,26 @@ declare function listInstalledAdapters(opts?: {
  *
  * 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";
+    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";
+    status: "supported" | "available" | "ready" | "unresolvable";
     hint?: string;
     source?: "acp-config" | "acp-catalog";
 };