@kpritam/grimoire-adapter-spawn-agent 0.1.7

package/src/probe.ts

@@ -0,0 +1,272 @@
+import { spawnSync } from "node:child_process"
+import type { AgentId } from "@kpritam/grimoire-core"
+import { ProviderUnavailable } from "@kpritam/grimoire-core"
+import * as Effect from "effect/Effect"
+import {
+  type AgentAdapter,
+  AgentNotInstalledError,
+  AgentUnauthenticatedError,
+  adapters,
+  detectAvailableAgents,
+  type SupportedAgentId
+} from "spawn-agent"
+
+/**
+ * Build the spawn-agent adapter for a given provider id, applying
+ * provider-specific workarounds on top of the built-in defaults.
+ *
+ * Two classes of bug exist in spawn-agent v0.0.1:
+ *
+ * A) npm-resolution failure (copilot, gemini)
+ *    The built-in adapter calls `resolvePackageBin("<pkg>")` in both
+ *    `checkInstalled` and `resolve`. That traverses the local
+ *    `node_modules` chain, which works for shim packages that are
+ *    spawn-agent dependencies (`@agentclientprotocol/claude-agent-acp`,
+ *    `@zed-industries/codex-acp`) but silently breaks for external CLIs
+ *    that are distributed as npm but installed globally
+ *    (`@github/copilot`, `@google/gemini-cli`). The fix: replace
+ *    `checkInstalled` with binary detection and set `binPath` so
+ *    `resolve()` calls the native binary directly.
+ *
+ * B) stdout-presence false negative (cursor, opencode)
+ *    `checkAuthenticated` and `resolve` require both exit-0 AND
+ *    non-empty stdout from an auth command. When auth is established via
+ *    an API key env-var the CLI exits 0 but may write only to stderr,
+ *    leaving stdout empty — causing a false "not authenticated". The
+ *    fix: check exit code only, which is what the CLIs use to signal
+ *    success.
+ *
+ * These are workarounds that belong upstream. Remove them once
+ * spawn-agent ships corrected adapters.
+ */
+export const buildAdapter = (id: AgentId): AgentAdapter => {
+  // --- class A: npm-resolution ---
+  if (id === "copilot") {
+    const builtin = adapters.builtInAdapter("copilot" satisfies SupportedAgentId, {
+      binPath: "copilot"
+    })
+    return {
+      ...builtin,
+      checkInstalled: async () =>
+        detectAvailableAgents().includes("copilot" satisfies SupportedAgentId)
+    }
+  }
+  if (id === "gemini") {
+    const builtin = adapters.builtInAdapter("gemini" satisfies SupportedAgentId, {
+      binPath: "gemini"
+    })
+    return {
+      ...builtin,
+      checkInstalled: async () =>
+        detectAvailableAgents().includes("gemini" satisfies SupportedAgentId)
+    }
+  }
+
+  // --- class B: wrong auth subcommand (cursor) ---
+  if (id === "cursor") {
+    const builtin = adapters.builtInAdapter("cursor" satisfies SupportedAgentId, {})
+    // spawn-agent calls `agent auth whoami` but the cursor CLI has no `auth`
+    // subcommand — that string is passed as a prompt to the agent process,
+    // which always exits 1. The correct command is `agent whoami`.
+    const checkCursorAuth = (): boolean => {
+      try {
+        const result = spawnSync("agent", ["whoami"], {
+          encoding: "utf8",
+          env: process.env,
+          stdio: ["ignore", "pipe", "pipe"]
+        })
+        return result.status === 0 && result.stdout.trim().length > 0
+      } catch {
+        return false
+      }
+    }
+    return {
+      ...builtin,
+      checkAuthenticated: async () => checkCursorAuth(),
+      resolve: async () => {
+        const version = spawnSync("agent", ["--version"], {
+          encoding: "utf8",
+          env: process.env,
+          stdio: ["ignore", "pipe", "pipe"]
+        })
+        if (version.status !== 0 || version.error != null) {
+          throw new AgentNotInstalledError(
+            "cursor",
+            "Cursor agent CLI is not installed. Install from https://cursor.com/docs/cli/acp.",
+            "https://cursor.com/docs/cli/acp"
+          )
+        }
+        if (!checkCursorAuth()) {
+          throw new AgentUnauthenticatedError(
+            "cursor",
+            "Cursor agent is not authenticated. Run `agent login` or set CURSOR_API_KEY.",
+            "agent login"
+          )
+        }
+        return { bin: "agent", args: ["acp"], env: {} }
+      }
+    }
+  }
+  if (id === "opencode") {
+    const builtin = adapters.builtInAdapter("opencode" satisfies SupportedAgentId, {})
+    const checkOpencodeAuth = (): boolean => {
+      try {
+        const result = spawnSync("opencode", ["auth", "list"], {
+          encoding: "utf8",
+          env: process.env,
+          stdio: ["ignore", "pipe", "pipe"]
+        })
+        return result.status === 0
+      } catch {
+        return false
+      }
+    }
+    return {
+      ...builtin,
+      checkAuthenticated: async () => checkOpencodeAuth(),
+      resolve: async () => {
+        const version = spawnSync("opencode", ["--version"], {
+          encoding: "utf8",
+          env: process.env,
+          stdio: ["ignore", "pipe", "pipe"]
+        })
+        if (version.status !== 0 || version.error != null) {
+          throw new AgentNotInstalledError(
+            "opencode",
+            "OpenCode is not installed. Install it with `npm install -g opencode-ai`.",
+            "npm install -g opencode-ai"
+          )
+        }
+        if (!checkOpencodeAuth()) {
+          throw new AgentUnauthenticatedError(
+            "opencode",
+            "OpenCode is not authenticated. Run `opencode auth login` and try again.",
+            "opencode auth login"
+          )
+        }
+        return { bin: "opencode", args: ["acp"], env: {} }
+      }
+    }
+  }
+
+  return adapters.builtInAdapter(id satisfies SupportedAgentId, {})
+}
+
+/**
+ * Is this agent's CLI on the host right now? Prefers the adapter's
+ * own `checkInstalled()` hook (each built-in adapter knows exactly
+ * what to look for — package on disk, binary on PATH, etc.) and falls
+ * back to spawn-agent's aggregate `detectAvailableAgents()` when an
+ * adapter omits the hook.
+ *
+ * Never throws — any upstream exception collapses to `false`.
+ */
+const isInstalled = (id: AgentId): Effect.Effect<boolean> =>
+  Effect.tryPromise({
+    try: async () => {
+      const adapter = buildAdapter(id)
+      if (adapter.checkInstalled !== undefined) {
+        return await adapter.checkInstalled()
+      }
+      return detectAvailableAgents().includes(id satisfies SupportedAgentId)
+    },
+    catch: () => new Error("probe failed")
+  }).pipe(Effect.orElseSucceed(() => false))
+
+/**
+ * Is the agent actually authenticated (valid token, logged in, API
+ * key present, etc.)? Delegates to the adapter's `checkAuthenticated()`
+ * hook — the same logic spawn-agent uses before spawning the CLI —
+ * so probe UX matches runtime UX. When the hook is missing (e.g. Pi,
+ * Codex), we treat "installed" as "good enough" so we don't falsely
+ * mark those providers as unauthenticated.
+ *
+ * Never throws — any upstream exception collapses to `false`.
+ */
+const isAuthenticated = (id: AgentId): Effect.Effect<boolean> =>
+  Effect.tryPromise({
+    try: async () => {
+      const adapter = buildAdapter(id)
+      if (adapter.checkAuthenticated !== undefined) {
+        return await adapter.checkAuthenticated()
+      }
+      return true
+    },
+    catch: () => new Error("auth probe failed")
+  }).pipe(Effect.orElseSucceed(() => false))
+
+/**
+ * Quick "is the binary installed?" check used by `grimoire doctor`
+ * and the `AgentRunner.probe` port. Defers to the adapter hook so
+ * binary/package-resolution rules stay in one place upstream.
+ */
+export const probeAgentBinary = (
+  id: AgentId
+): Effect.Effect<{ readonly available: boolean; readonly reason?: string }> =>
+  Effect.gen(function* () {
+    const installed = yield* isInstalled(id)
+    if (installed) return { available: true }
+    return { available: false, reason: `${id} CLI not found or not resolvable` }
+  })
+
+/**
+ * Best-effort auth gate for `grimoire doctor`. Combines install +
+ * auth checks so callers get a single yes/no on "can this agent
+ * actually run right now?"
+ *
+ * Fails with `ProviderUnavailable` so workflows can distinguish an
+ * environmental problem (operator action required) from a hard
+ * `CliAgentError` from `runner.run`.
+ */
+export const authenticateAgent = (id: AgentId): Effect.Effect<void, ProviderUnavailable> =>
+  Effect.gen(function* () {
+    const probe = yield* probeAgentBinary(id)
+    if (!probe.available) {
+      return yield* Effect.fail(
+        new ProviderUnavailable({
+          provider: id,
+          reason: probe.reason ?? `${id} CLI not found or not resolvable`
+        })
+      )
+    }
+    const authed = yield* isAuthenticated(id)
+    if (authed) return
+    return yield* Effect.fail(
+      new ProviderUnavailable({
+        provider: id,
+        reason: `${id} CLI is installed but not authenticated`
+      })
+    )
+  })
+
+/**
+ * One-shot probe used by `grimoire agent probe`. Combines install +
+ * auth into the row shape the workflow expects. Crucially, this tells
+ * the truth on the `authenticated` column — historically the probe
+ * reported `authenticated: yes` any time the binary was on PATH, which
+ * masked exactly the class of problem operators run the command to
+ * find.
+ */
+export const probeAgent = (
+  id: AgentId
+): Effect.Effect<{
+  readonly available: boolean
+  readonly authenticated: boolean
+  readonly detail?: string | undefined
+}> =>
+  Effect.gen(function* () {
+    const probe = yield* probeAgentBinary(id)
+    if (!probe.available) {
+      return {
+        available: false,
+        authenticated: false,
+        ...(probe.reason !== undefined ? { detail: probe.reason } : {})
+      }
+    }
+    const authed = yield* isAuthenticated(id)
+    return {
+      available: true,
+      authenticated: authed,
+      ...(authed ? {} : { detail: `${id} is installed but not authenticated` })
+    }
+  })