@kpritam/grimoire-adapter-spawn-agent 0.1.7

package/dist/probe.js

@@ -0,0 +1,225 @@
+import { spawnSync } from "node:child_process";
+import { ProviderUnavailable } from "@kpritam/grimoire-core";
+import * as Effect from "effect/Effect";
+import { AgentNotInstalledError, AgentUnauthenticatedError, adapters, detectAvailableAgents } 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) => {
+    // --- class A: npm-resolution ---
+    if (id === "copilot") {
+        const builtin = adapters.builtInAdapter("copilot", {
+            binPath: "copilot"
+        });
+        return {
+            ...builtin,
+            checkInstalled: async () => detectAvailableAgents().includes("copilot")
+        };
+    }
+    if (id === "gemini") {
+        const builtin = adapters.builtInAdapter("gemini", {
+            binPath: "gemini"
+        });
+        return {
+            ...builtin,
+            checkInstalled: async () => detectAvailableAgents().includes("gemini")
+        };
+    }
+    // --- class B: wrong auth subcommand (cursor) ---
+    if (id === "cursor") {
+        const builtin = adapters.builtInAdapter("cursor", {});
+        // 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 = () => {
+            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", {});
+        const checkOpencodeAuth = () => {
+            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, {});
+};
+/**
+ * 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) => Effect.tryPromise({
+    try: async () => {
+        const adapter = buildAdapter(id);
+        if (adapter.checkInstalled !== undefined) {
+            return await adapter.checkInstalled();
+        }
+        return detectAvailableAgents().includes(id);
+    },
+    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) => 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) => 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) => 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) => 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` })
+    };
+});

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@kpritam/grimoire-adapter-spawn-agent",
+  "version": "0.1.7",
+  "description": "Grimoire AgentRunner adapter backed by `spawn-agent`. Drives any locally-installed coding-agent CLI (Claude Code, Codex, Cursor, GitHub Copilot, Gemini, OpenCode, Factory Droid, Pi) over the Agent Client Protocol.",
+  "license": "MIT",
+  "homepage": "https://github.com/kpritam/grimoire/tree/main/packages/adapter-spawn-agent#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kpritam/grimoire.git",
+    "directory": "packages/adapter-spawn-agent"
+  },
+  "bugs": {
+    "url": "https://github.com/kpritam/grimoire/issues"
+  },
+  "keywords": [
+    "grimoire",
+    "spawn-agent",
+    "agent-client-protocol",
+    "acp",
+    "claude",
+    "claude-code",
+    "codex",
+    "copilot",
+    "cursor",
+    "gemini",
+    "opencode",
+    "droid",
+    "pi"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "effect": "4.0.0-beta.51",
+    "spawn-agent": "^0.0.1",
+    "@kpritam/grimoire-core": "0.1.7"
+  },
+  "devDependencies": {
+    "@effect/vitest": "4.0.0-beta.51",
+    "@types/node": "^25.7.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.6"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.json --emitDeclarationOnly false --incremental false --composite false --sourceMap false",
+    "check": "tsc -p tsconfig.json --noEmit --emitDeclarationOnly false --incremental false --composite false --sourceMap false",
+    "clean": "rm -rf dist",
+    "test": "vitest run --passWithNoTests"
+  }
+}

package/src/errorMap.ts

@@ -0,0 +1,224 @@
+import { CliAgentError, type CliAgentFailureReason } from "@kpritam/grimoire-core"
+import {
+  type AdapterNotFoundError,
+  type AgentConnectionClosedError,
+  type AgentInactivityError,
+  type AgentInitError,
+  type AgentNotInstalledError,
+  type AgentSessionCreateError,
+  type AgentSessionLoadError,
+  type AgentSpawnError,
+  type AgentStdinClosedError,
+  type AgentStreamError,
+  type AgentUnauthenticatedError,
+  type CapabilityNotSupportedError,
+  type InvalidPromptContentError,
+  type ProtocolVersionMismatchError,
+  SpawnAgentError
+} from "spawn-agent"
+
+/**
+ * Stringify an unknown cause into a single, compact message. The result
+ * is safe to put into `CliAgentError.message` / `stderr` without leaking
+ * huge payloads.
+ */
+const stringifyCause = (cause: unknown): string => {
+  if (cause instanceof Error) return cause.message
+  if (typeof cause === "string") return cause
+  try {
+    return JSON.stringify(cause)
+  } catch {
+    return String(cause)
+  }
+}
+
+/**
+ * Compose the stderr payload for a `CliAgentError` from a spawn-agent
+ * exception. We always lead with the upstream message, then append any
+ * actionable remediation the upstream error carries — install URL,
+ * `loginCommand`, missing package name. This is the text an operator
+ * reads when a run fails, so it should tell them exactly what to do.
+ */
+const composeStderr = (message: string, remediation: string | undefined): string =>
+  remediation === undefined || remediation.length === 0 ? message : `${message}\n${remediation}`
+
+interface MappedError {
+  readonly reason: CliAgentFailureReason
+  readonly remediation?: string
+  readonly exitCode?: number | null
+}
+
+/**
+ * Pure translator from spawn-agent's error hierarchy to Grimoire's
+ * {@link CliAgentError.reason} taxonomy plus user-facing remediation.
+ *
+ * The `switch` is exhaustive on `SpawnAgentError._tag`; adding a new
+ * upstream tag becomes a compile-time error here (`assertExhaustive`)
+ * rather than a silent slide into `"spawn"`. Retry semantics (see
+ * `isTransientCliFailure` in core) follow the mapped `reason`, so
+ * misclassifying an error here directly affects runtime behavior.
+ */
+const classifySpawnAgentError = (error: SpawnAgentError): MappedError => {
+  switch (error._tag) {
+    // --- Terminal user-setup failures (never retry) ---
+    case "NotInstalled": {
+      const e = error as AgentNotInstalledError
+      return {
+        reason: "not-found",
+        ...(e.install !== undefined ? { remediation: `Install: ${e.install}` } : {})
+      }
+    }
+    case "AdapterNotFound": {
+      const e = error as AdapterNotFoundError
+      return {
+        reason: "not-found",
+        remediation: `Install the missing adapter package: ${e.packageName}`
+      }
+    }
+    case "Unauthenticated": {
+      const e = error as AgentUnauthenticatedError
+      return {
+        reason: "auth",
+        ...(e.loginCommand !== undefined ? { remediation: `Run: ${e.loginCommand}` } : {})
+      }
+    }
+    case "CapabilityNotSupported": {
+      const e = error as CapabilityNotSupportedError
+      return {
+        reason: "spawn",
+        remediation: `Agent does not support capability: ${e.capability}`
+      }
+    }
+    case "InvalidContent": {
+      const e = error as InvalidPromptContentError
+      return {
+        reason: "parse",
+        remediation: `Content type "${e.contentType}" needs "${e.capability}" capability`
+      }
+    }
+
+    // --- Usage/quota — distinct so callers can stop retrying ---
+    case "UsageLimit":
+      return {
+        reason: "non-zero-exit",
+        remediation: "Usage limits reached — wait for your quota to reset or switch provider."
+      }
+
+    // --- Timeouts (transient, retryable) ---
+    case "Inactivity": {
+      const e = error as AgentInactivityError
+      return {
+        reason: "timeout",
+        remediation: `Idle for ${Math.round(e.elapsedMs / 1000)}s (session ${e.sessionId})`
+      }
+    }
+    case "InitTimeout":
+      return { reason: "timeout" }
+
+    // --- Signal kills & connection closes (retryable as killed-by-signal) ---
+    case "ConnectionClosed": {
+      const e = error as AgentConnectionClosedError
+      // A SIGTERM/SIGKILL is almost always transient — broken pipe, OS
+      // cleanup, a hung child cleared out. A clean non-zero exit could
+      // also be transient; treat it as `non-zero-exit` (retryable) when
+      // `exitCode` is non-null, else as `killed-by-signal`.
+      return {
+        reason: e.signal !== null ? "killed-by-signal" : "non-zero-exit",
+        exitCode: e.exitCode,
+        ...(e.stderrTail.length > 0
+          ? { remediation: `Last stderr: ${e.stderrTail.slice(-500)}` }
+          : {})
+      }
+    }
+
+    // --- Subprocess / ACP init / session failures (not retryable) ---
+    case "Spawn": {
+      const e = error as AgentSpawnError
+      return { reason: "spawn", remediation: stringifyCause(e.cause) }
+    }
+    case "Init": {
+      const e = error as AgentInitError
+      return { reason: "spawn", remediation: stringifyCause(e.cause) }
+    }
+    case "SessionCreate": {
+      const e = error as AgentSessionCreateError
+      return { reason: "spawn", remediation: stringifyCause(e.cause) }
+    }
+    case "SessionLoad": {
+      const e = error as AgentSessionLoadError
+      return { reason: "spawn", remediation: stringifyCause(e.cause) }
+    }
+    case "Stream": {
+      const e = error as AgentStreamError
+      return { reason: "spawn", remediation: stringifyCause(e.cause) }
+    }
+    case "StdinClosed": {
+      const e = error as AgentStdinClosedError
+      return { reason: "killed-by-signal", remediation: stringifyCause(e.cause) }
+    }
+    case "ProtocolVersion": {
+      const e = error as ProtocolVersionMismatchError
+      return {
+        reason: "spawn",
+        remediation: `Client supports up to v${e.clientVersion}, agent requires v${e.agentVersion}`
+      }
+    }
+    case "Cancelled": {
+      // Cancellation is operator-initiated — don't retry.
+      return { reason: "killed-by-signal" }
+    }
+
+    default: {
+      // Exhaustiveness check — if spawn-agent adds a new tag, this
+      // will fail to compile, forcing us to update the mapping.
+      const _exhaustive: never = error._tag as never
+      void _exhaustive
+      return { reason: "spawn" }
+    }
+  }
+}
+
+/**
+ * Single entry point used by the adapter's connect/run/close paths.
+ * Converts any upstream throw into a `CliAgentError` with a structured
+ * `reason`, populated `exitCode` where available, and a `stderr`
+ * composed of upstream message + actionable remediation.
+ *
+ * NEVER throws — the returned `CliAgentError` is always well-formed.
+ */
+export const mapSpawnAgentError = (id: string, cause: unknown): CliAgentError => {
+  if (cause instanceof SpawnAgentError) {
+    const mapped = classifySpawnAgentError(cause)
+    const stderr = composeStderr(cause.message, mapped.remediation)
+    return new CliAgentError({
+      agent: id,
+      exitCode: mapped.exitCode ?? null,
+      reason: mapped.reason,
+      message: cause.message,
+      stderr
+    })
+  }
+  const message = stringifyCause(cause)
+  return new CliAgentError({
+    agent: id,
+    exitCode: null,
+    reason: "spawn",
+    message,
+    stderr: message
+  })
+}
+
+/**
+ * Build a `CliAgentError` for the adapter's own wall-clock timeout —
+ * distinct from spawn-agent's `AgentInactivityError` (idle timeout).
+ */
+export const wallTimeoutError = (id: string, timeoutMs: number): CliAgentError => {
+  const message = `${id} exceeded wall timeout of ${timeoutMs}ms`
+  return new CliAgentError({
+    agent: id,
+    exitCode: null,
+    reason: "timeout",
+    message,
+    stderr: message
+  })
+}