@kpritam/grimoire-adapter-spawn-agent 0.1.7

package/dist/eventFormatter.js

@@ -0,0 +1,262 @@
+import * as path from "node:path";
+import * as process from "node:process";
+/* ---------- ANSI palette ---------- */
+const IS_TTY = process.stdout.isTTY === true;
+const ansi = (code) => (s) => IS_TTY ? `\x1b[${code}m${s}\x1b[0m` : s;
+const bold = ansi("1");
+const yellow = ansi("33");
+const red = ansi("31");
+/* grimoire brand colors (256-color approximation) */
+const amber = ansi("38;5;179"); /* #C87837 warm primary */
+const amberBright = ansi("38;5;215"); /* #E09050 high accent */
+const teal = ansi("38;5;37"); /* #2DB89E secondary accent */
+const warmGray = ansi("38;5;101"); /* #9A8878 muted warm */
+/* ---------- Tool-kind ↔ glyph & colour ---------- */
+/**
+ * Per-{@link ToolKind} icon. Designed to read at a glance with grimoire
+ * personality: mystical glyphs that feel archival and incantatory.
+ */
+const TOOL_ICON = {
+    read: "📖",
+    edit: "✍ ",
+    delete: "✘ ",
+    move: "↻ ",
+    search: "🔍",
+    execute: "⚡",
+    think: "✨",
+    fetch: "🌐",
+    switch_mode: "⇄ ",
+    other: "⚙ "
+};
+const TOOL_COLOR = {
+    read: warmGray,
+    edit: amberBright,
+    delete: red,
+    move: amber,
+    search: warmGray,
+    execute: amberBright,
+    think: warmGray,
+    fetch: warmGray,
+    switch_mode: amber,
+    other: warmGray
+};
+const iconFor = (kind) => TOOL_ICON[kind ?? "other"];
+const colorFor = (kind) => TOOL_COLOR[kind ?? "other"];
+/* ---------- Title compaction ---------- */
+const MAX_LABEL = 80;
+const MAX_PLAN_ENTRY = 64;
+const truncate = (s, max) => s.length > max ? `${s.slice(0, max - 1)}…` : s;
+const stripBold = (s) => s.replace(/\*\*/g, "");
+/**
+ * Verbs the upstream agent (Claude Code, Codex, etc.) prepends to a tool
+ * title — e.g. `"Read foo/bar.md"`. Our icon already carries the action
+ * meaning, so we strip these leading words to keep the line short.
+ */
+const VERB_PREFIX_RE = /^(Read|Write|Edit|Update|Create|Delete|Remove|Move|Rename|Find|Search|Grep|Bash|Shell|Run|Execute|Fetch|Browse|Open)\s+/;
+/**
+ * Render the basename of a path string. Strips trailing markers like
+ * `(line 1)` / `(1-50)` that some agents append to read titles. POSIX
+ * basename rules — works fine on Windows paths because we already
+ * normalise to forward slashes for display.
+ */
+const basenameOf = (filePath) => {
+    const trimmed = filePath.trim();
+    if (trimmed.length === 0)
+        return trimmed;
+    const m = /^(.*?)(\s+\(.*\))?$/.exec(trimmed);
+    const core = m?.[1] ?? trimmed;
+    const suffix = m?.[2] ?? "";
+    const normalised = core.replaceAll("\\", "/");
+    const base = path.posix.basename(normalised);
+    return `${base.length > 0 ? base : core}${suffix}`;
+};
+/**
+ * For Bash/exec titles (which carry the actual command), keep the head
+ * of the command but drop trailing redirections / pipes / `&& echo …`
+ * noise that bloats the line without adding signal.
+ */
+const compactCommand = (cmd) => {
+    const head = cmd.split(/\s*\|\|\s*|\s*\|\s*|\s*&&\s*|\s*;\s*|\s*\d?>\s*/)[0] ?? cmd;
+    return truncate(head.trim(), MAX_LABEL);
+};
+/**
+ * Compact a tool title down to a single, scannable label.
+ *
+ * - file-tools (`read`, `edit`, `delete`, `move`): basename only — the
+ *   directory is usually obvious from the surrounding tool calls and
+ *   the full path duplicates information already in the title prefix.
+ * - `execute`: drop pipe/redirect/chain noise so a quick `npm test`
+ *   doesn't read like `npm test 2>&1 | tee log && echo done`.
+ * - `search`/`fetch`/`think`/`switch_mode`/`other`: keep as-is, just
+ *   truncated to {@link MAX_LABEL}.
+ */
+export const compactToolTitle = (rawTitle, kind) => {
+    let title = rawTitle.trim();
+    if (title.length === 0)
+        return "";
+    const verb = VERB_PREFIX_RE.exec(title);
+    if (verb !== null)
+        title = title.slice(verb[0].length);
+    if (kind === "read" || kind === "edit" || kind === "delete" || kind === "move") {
+        return basenameOf(title);
+    }
+    if (kind === "execute") {
+        return compactCommand(title);
+    }
+    return truncate(title, MAX_LABEL);
+};
+export const newFormatState = () => ({ inProse: false });
+/**
+ * Render one {@link AgentEvent} into a single line ready for stdout, or
+ * `null` to drop the event entirely.
+ *
+ * Behaviour notes:
+ *
+ * - `text-delta` is streamed verbatim with no trailing newline so the
+ *   agent's own line breaks render naturally. Earlier revisions added
+ *   a `\n` per chunk, which fragmented every paragraph into one-token
+ *   slivers.
+ * - `tool-call` uses {@link compactToolTitle} + a {@link ToolKind}-coded
+ *   icon so the operator can scan a long log for the action (read vs
+ *   write vs shell) without parsing words.
+ * - `tool-call-update` is suppressed unless `verbose` (debug log level)
+ *   except for failures, which always surface in red.
+ * - `plan` previews up to three entries inline so the operator can see
+ *   what the agent intends to do without scrolling back to a separate
+ *   pane.
+ * - High-frequency events (`usage`, `mode-changed`, `available-commands`)
+ *   stay hidden outside debug.
+ */
+export const formatEvent = (event, verbose, state) => {
+    if (event.type === "text-delta") {
+        if (event.text.length === 0)
+            return null;
+        state.inProse = true;
+        return { text: event.text, newline: false, leadNewline: false };
+    }
+    const lead = state.inProse;
+    state.inProse = false;
+    switch (event.type) {
+        case "thinking-delta": {
+            const text = stripBold(event.text).trim();
+            if (text.length === 0)
+                return null;
+            return {
+                text: warmGray(`✨ ${truncate(text, MAX_LABEL)}`),
+                newline: true,
+                leadNewline: lead
+            };
+        }
+        case "tool-call": {
+            const icon = iconFor(event.kind);
+            const color = colorFor(event.kind);
+            const subject = compactToolTitle(event.tool, event.kind);
+            const line = subject.length > 0 ? `${icon} ${color(bold(subject))}` : color(icon);
+            return { text: line, newline: true, leadNewline: lead };
+        }
+        case "tool-call-update": {
+            if (event.status === "failed") {
+                const tail = event.title !== undefined && event.title.length > 0 ? ` ${event.title}` : "";
+                return { text: red(`✗ ${tail}`), newline: true, leadNewline: lead };
+            }
+            if (!verbose)
+                return null;
+            const status = event.status ?? "update";
+            const tail = event.title !== undefined && event.title.length > 0 ? ` ${event.title}` : "";
+            return { text: warmGray(`  └─ ${status}${tail}`), newline: true, leadNewline: lead };
+        }
+        case "tool-call-cancelled":
+            return {
+                text: yellow(`⊘ ${event.tool ?? "tool"} cancelled`),
+                newline: true,
+                leadNewline: lead
+            };
+        case "plan": {
+            if (event.entries.length === 0)
+                return null;
+            const head = bold(amber(`📚 Ritual (${event.entries.length} steps)`));
+            const preview = event.entries
+                .slice(0, 3)
+                .map((e, i) => `  ${amber(bold((i + 1).toString()))}. ${truncate(e.content, MAX_PLAN_ENTRY)}`)
+                .join("\n");
+            const more = event.entries.length > 3
+                ? `\n  ${warmGray(`└─ +${event.entries.length - 3} more steps`)}`
+                : "";
+            return { text: `${head}\n${preview}${more}`, newline: true, leadNewline: lead };
+        }
+        case "permission-request":
+            return {
+                text: amber(`🔐 ${event.request.tool ?? "?"} permitted`),
+                newline: true,
+                leadNewline: lead
+            };
+        case "finish": {
+            const isSuccess = event.stopReason === "end_turn";
+            if (isSuccess) {
+                const celebrationLines = [
+                    amber(`✨ Cast complete — tome inscribed`),
+                    teal(`  The grimoire's pages are sealed with knowledge`)
+                ];
+                return {
+                    text: `\n${celebrationLines.join("\n")}\n`,
+                    newline: true,
+                    leadNewline: lead
+                };
+            }
+            return {
+                text: `\n${amber(`◆ ${event.stopReason}`)}\n`,
+                newline: true,
+                leadNewline: lead
+            };
+        }
+        case "usage":
+            if (!verbose)
+                return null;
+            return {
+                text: warmGray(`[usage] ${event.usage.used}/${event.usage.size}`),
+                newline: true,
+                leadNewline: lead
+            };
+        case "mode-changed":
+            if (!verbose)
+                return null;
+            return { text: warmGray(`[mode] ${event.modeId}`), newline: true, leadNewline: lead };
+        case "available-commands":
+            if (!verbose)
+                return null;
+            return {
+                text: warmGray(`[commands] ${event.commands.map((c) => c.name).join(", ")}`),
+                newline: true,
+                leadNewline: lead
+            };
+        case "config-options":
+        case "session-info":
+        case "raw":
+            return null;
+    }
+};
+/* ---------- Stream sink ---------- */
+/**
+ * Write one event's formatted line to stdout, flushing any pending
+ * newline first. Centralising this keeps the streaming loop in
+ * `layer.ts` free of formatting concerns.
+ */
+export const writeEvent = (event, verbose, state) => {
+    const line = formatEvent(event, verbose, state);
+    if (line === null)
+        return;
+    if (line.leadNewline)
+        process.stdout.write("\n");
+    process.stdout.write(line.newline ? `${line.text}\n` : line.text);
+};
+/**
+ * Flush a final newline if the stream ended mid-prose. Call once after
+ * the event loop exits so the next CLI line doesn't run on from the
+ * agent's last sentence.
+ */
+export const finishStream = (state) => {
+    if (state.inProse) {
+        process.stdout.write("\n");
+        state.inProse = false;
+    }
+};

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * `@kpritam/grimoire-adapter-spawn-agent` — concrete `AgentRunner`
+ * implementation backed by the upstream
+ * [`spawn-agent`](https://npmjs.com/package/spawn-agent) package.
+ *
+ * `spawn-agent` runs every supported coding-agent CLI (Claude Code,
+ * Codex, Copilot, Cursor, Gemini, OpenCode, Factory Droid, Pi) as a
+ * subprocess and talks to it over the Agent Client Protocol (ACP). The
+ * wire format and event surface is uniform across every agent — we
+ * just adapt that into the Effect-based {@link AgentRunner} port the
+ * rest of Grimoire depends on.
+ */
+export { SpawnAgentRunnerLayer } from "./layer.js";
+export { authenticateAgent, probeAgent, probeAgentBinary } from "./probe.js";

package/dist/index.js

@@ -0,0 +1,14 @@
+/**
+ * `@kpritam/grimoire-adapter-spawn-agent` — concrete `AgentRunner`
+ * implementation backed by the upstream
+ * [`spawn-agent`](https://npmjs.com/package/spawn-agent) package.
+ *
+ * `spawn-agent` runs every supported coding-agent CLI (Claude Code,
+ * Codex, Copilot, Cursor, Gemini, OpenCode, Factory Droid, Pi) as a
+ * subprocess and talks to it over the Agent Client Protocol (ACP). The
+ * wire format and event surface is uniform across every agent — we
+ * just adapt that into the Effect-based {@link AgentRunner} port the
+ * rest of Grimoire depends on.
+ */
+export { SpawnAgentRunnerLayer } from "./layer.js";
+export { authenticateAgent, probeAgent, probeAgentBinary } from "./probe.js";

package/dist/layer.d.ts

@@ -0,0 +1,21 @@
+import { AgentRunner, Config } from "@kpritam/grimoire-core";
+import * as Layer from "effect/Layer";
+/**
+ * Build a single `AgentRunner` Layer from `Config`. The bound agent is
+ * whatever `provider.id` selects; switching providers is a config edit
+ * (no code changes needed). Other Grimoire subsystems depend only on
+ * the `AgentRunner` port — see `core/services/AgentRunner.ts`.
+ *
+ * Each `run` call:
+ * 1. Opens a fresh `SpawnAgent` subprocess via `spawn-agent`.
+ * 2. Creates one ACP session for the requested `cwd`.
+ * 3. Streams the prompt through `agent.prompt(...)`. Events are
+ *    logged to stdout as they arrive (when `logStream` is on); the
+ *    final turn is mapped to `AgentReply`.
+ * 4. Closes the agent on the way out (always, via `Effect.acquireUseRelease`).
+ *
+ * Wall-clock timeouts come from `config.agentTimeoutMs`; idle / no-update
+ * timeouts come from `config.agentIdleTimeoutMs` and are forwarded to
+ * `spawn-agent`'s built-in inactivity watchdog.
+ */
+export declare const SpawnAgentRunnerLayer: Layer.Layer<AgentRunner, never, Config>;

package/dist/layer.js

@@ -0,0 +1,131 @@
+import { AgentRunner, Config } from "@kpritam/grimoire-core";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import { SpawnAgent } from "spawn-agent";
+import { mapSpawnAgentError, wallTimeoutError } from "./errorMap.js";
+import { finishStream, newFormatState, writeEvent } from "./eventFormatter.js";
+import { authenticateAgent, buildAdapter, probeAgentBinary } from "./probe.js";
+/**
+ * Translate Grimoire's typed {@link AgentOptions} block into
+ * `spawn-agent`'s {@link SpawnAgentConnectOptions}. One entry point —
+ * no per-provider shaping, no unsafe casts, no stringly-typed access.
+ *
+ * Note: Grimoire's `mcp.install` list is an *install spec* consumed by
+ * `@kpritam/grimoire-adapter-agent-install`, not a session-level ACP
+ * `McpServer` wire shape. They are deliberately not forwarded here;
+ * MCP servers are installed into the agent's own config before the
+ * cast starts, so spawn-agent sees them through the agent itself.
+ */
+const buildConnectOptions = (options, cwd, defaultInactivityMs, logStream) => {
+    const explicitInactivity = options["inactivity-timeout-ms"];
+    const additionalDirectories = options["additional-directories"];
+    const systemPrompt = options["system-prompt"];
+    return {
+        cwd,
+        permission: options.permission ?? "auto-allow",
+        inactivityTimeoutMs: typeof explicitInactivity === "number" ? explicitInactivity : defaultInactivityMs,
+        ...(additionalDirectories !== undefined && additionalDirectories.length > 0
+            ? { additionalDirectories: [...additionalDirectories] }
+            : {}),
+        ...(systemPrompt !== undefined ? { systemPrompt } : {}),
+        ...(logStream ? { onStderr: (line) => process.stderr.write(`${line}\n`) } : {})
+    };
+};
+/**
+ * Shape a spawn-agent {@link TurnResult} into Grimoire's
+ * {@link AgentReply}. Forwards token usage + stop reason for
+ * observability and stashes the full turn under `raw` so downstream
+ * telemetry layers can attach token counts / session ids to spans.
+ */
+const toAgentReply = (result) => ({
+    content: result.text,
+    ...(result.stopReason !== undefined ? { stopReason: String(result.stopReason) } : {}),
+    ...(result.usage !== undefined
+        ? {
+            usage: {
+                // spawn-agent's UsageReport is { size, used, cost? } — the
+                // cumulative counters for the whole session, not per-turn
+                // input/output split. We forward the `used` tokens into
+                // `outputTokens` as the most-honest approximation and leave
+                // `inputTokens` absent until upstream exposes the split.
+                outputTokens: result.usage.used
+            }
+        }
+        : {}),
+    raw: result
+});
+/**
+ * Build a single `AgentRunner` Layer from `Config`. The bound agent is
+ * whatever `provider.id` selects; switching providers is a config edit
+ * (no code changes needed). Other Grimoire subsystems depend only on
+ * the `AgentRunner` port — see `core/services/AgentRunner.ts`.
+ *
+ * Each `run` call:
+ * 1. Opens a fresh `SpawnAgent` subprocess via `spawn-agent`.
+ * 2. Creates one ACP session for the requested `cwd`.
+ * 3. Streams the prompt through `agent.prompt(...)`. Events are
+ *    logged to stdout as they arrive (when `logStream` is on); the
+ *    final turn is mapped to `AgentReply`.
+ * 4. Closes the agent on the way out (always, via `Effect.acquireUseRelease`).
+ *
+ * Wall-clock timeouts come from `config.agentTimeoutMs`; idle / no-update
+ * timeouts come from `config.agentIdleTimeoutMs` and are forwarded to
+ * `spawn-agent`'s built-in inactivity watchdog.
+ */
+export const SpawnAgentRunnerLayer = Layer.effect(AgentRunner, Effect.gen(function* () {
+    const config = yield* Config;
+    // Compile-time check: every `AgentId` Grimoire allows must be a
+    // valid `SupportedAgentId` upstream. If spawn-agent drops an id
+    // without us trimming `AGENT_IDS`, this line fails to compile,
+    // surfacing the drift at build time rather than runtime.
+    const agentId = config.provider.id;
+    const inactivityTimeoutMs = config.agentIdleTimeoutMs;
+    const wallTimeoutMs = config.agentTimeoutMs;
+    const providerOptions = config.providerOptions;
+    const verbose = config.logging?.level === "debug";
+    // Use a provider-specific adapter rather than the bare string id so
+    // provider-level workarounds (e.g. copilot binary-path override) are
+    // active during the actual connect, not just during probe/doctor.
+    const adapter = buildAdapter(agentId);
+    const runOnce = (prompt, cwd, logStream) => Effect.acquireUseRelease(Effect.tryPromise({
+        try: () => SpawnAgent.connect(adapter, buildConnectOptions(providerOptions, cwd, inactivityTimeoutMs, logStream)),
+        catch: (cause) => mapSpawnAgentError(agentId, cause)
+    }), (agent) => Effect.tryPromise({
+        try: async () => {
+            const sessionId = await agent.createSession({ cwd });
+            const modelPref = providerOptions.model !== undefined
+                ? { modelPreference: { configId: "model", value: providerOptions.model } }
+                : {};
+            const stream = agent.prompt(sessionId, { prompt, ...modelPref });
+            const state = logStream ? newFormatState() : null;
+            try {
+                for await (const event of stream) {
+                    if (state !== null)
+                        writeEvent(event, verbose, state);
+                }
+            }
+            finally {
+                if (state !== null)
+                    finishStream(state);
+            }
+            const result = await stream.completion;
+            return toAgentReply(result);
+        },
+        catch: (cause) => mapSpawnAgentError(agentId, cause)
+    }), (agent) => Effect.promise(() => agent.close().catch(() => undefined)).pipe(Effect.ignore));
+    const runWithWallTimeout = (prompt, cwd, logStream) => wallTimeoutMs > 0
+        ? runOnce(prompt, cwd, logStream).pipe(Effect.timeoutOrElse({
+            duration: `${wallTimeoutMs} millis`,
+            orElse: () => Effect.fail(wallTimeoutError(agentId, wallTimeoutMs))
+        }))
+        : runOnce(prompt, cwd, logStream);
+    const service = {
+        id: agentId,
+        probe: probeAgentBinary(agentId),
+        authenticate: authenticateAgent(agentId),
+        run: (prompt, cwd, opts) => runWithWallTimeout(prompt, cwd, opts?.logStream ?? config.logStream).pipe(Effect.withSpan(`grimoire.${agentId}.run`, {
+            attributes: { "agent.id": agentId }
+        }))
+    };
+    return AgentRunner.of(service);
+}));

package/dist/probe.d.ts

@@ -0,0 +1,65 @@
+import type { AgentId } from "@kpritam/grimoire-core";
+import { ProviderUnavailable } from "@kpritam/grimoire-core";
+import * as Effect from "effect/Effect";
+import { type AgentAdapter } 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 declare const buildAdapter: (id: AgentId) => AgentAdapter;
+/**
+ * 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 declare const probeAgentBinary: (id: AgentId) => Effect.Effect<{
+    readonly available: boolean;
+    readonly reason?: string;
+}>;
+/**
+ * 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 declare const authenticateAgent: (id: AgentId) => Effect.Effect<void, ProviderUnavailable>;
+/**
+ * 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 declare const probeAgent: (id: AgentId) => Effect.Effect<{
+    readonly available: boolean;
+    readonly authenticated: boolean;
+    readonly detail?: string | undefined;
+}>;