@agentproto/cli 0.6.0 → 0.8.0

package/dist/index.d.ts

@@ -98,6 +98,33 @@ declare function runServe(args: readonly string[]): Promise<number>;
  */
 declare function runAcp(args: readonly string[]): Promise<number>;
 
+declare function runPackSkill(args: readonly string[]): Promise<number>;
+
+/**
+ * Single shared `zip` implementation for a skill pack directory. Used by
+ * `claude-plugin.ts` (consumer-side install, `agentproto install skill/...`)
+ * and by a package's own release-time build script (producer-side, see
+ * `packages/skill-pack-<name>/scripts/build.mjs`) — one zip technique, not
+ * one per caller.
+ */
+interface ZipPackResult {
+    zipped: boolean;
+    zipPath: string;
+}
+/**
+ * Best-effort zip of `dirToZip` into `<dirToZip>.zip` (or `zipPath` when
+ * given). The directory is the canonical artifact; the archive is a
+ * convenience — `zip` may be absent on minimal/Windows environments, so a
+ * failure to zip is reported via `zipped: false` rather than thrown.
+ *
+ * Runs `zip` with cwd set to `dirToZip`'s parent and zips its bare basename,
+ * so archive entries read as `<name>/...` — not the full absolute path a
+ * naive `zip -r <zipPath> <dirToZip>` would bake in when `dirToZip` is
+ * absolute (as every caller here passes it). Unzipping must not recreate
+ * the machine's own directory tree.
+ */
+declare function zipPackDir(dirToZip: string, zipPath?: string): Promise<ZipPackResult>;
+
 /**
  * Resolve a slug like "claude-code" to a runnable `AgentCliHandle`.
  *
@@ -123,6 +150,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 +197,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>;
 /**
@@ -201,24 +258,43 @@ declare function listInstalledAdapters(opts?: {
  * 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)
+ *   "available" — package resolves; requiresSetup but no ledger yet, OR
+ *                 authRequired but no billing credential resolves
+ *   "ready"     — package resolves + setup complete (or no setup needed) AND
+ *                 (authRequired is false, or a credential DOES resolve)
  *
  * 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).
+ * ledger-exists × (authRequired × authConfigured) — never via `handle.check()`
+ * (per OQ-5). The auth axis is independent of `requiresSetup`: claude-code
+ * declares no `setup[]` at all (`requiresSetup` is always false for it) but
+ * `authEnforce:"always"` hard-fails every spawn without a billing credential
+ * — `authProbe` (wired to the runtime's `isAgentCliAuthConfigured`, which
+ * mirrors `resolveAuthSpec`'s exact precedence including the explicit-gate
+ * on the providers store, PR #321) is what makes that honest instead of the
+ * old `!requiresSetup` short-circuit reporting "ready" on zero credentials.
+ *
+ * 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";
 };
@@ -329,4 +405,4 @@ declare function listAcpGenericAdapters(opts?: {
     excludeSlugs?: ReadonlySet<string>;
 }): Promise<AcpGenericListEntry[]>;
 
-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 };
+export { ACP_CATALOG, type AcpAgentSpec, type AcpGenericListEntry, type AcpSpecSource, type AdapterInfo, type AdapterListing, type ResolvedAdapter, type ZipPackResult, acpHandleFromSpec, binOnPath, listAcpGenericAdapters, listAdaptersWithAcp, listAdaptersWithCatalog, listInstalledAdapters, resolveAcpSpec, resolveAdapter, runAcp, runInstall, runPackSkill, runRun, runServe, zipPackDir };