@kpritam/grimoire-adapter-spawn-agent 0.1.7

package/src/eventFormatter.ts

@@ -0,0 +1,313 @@
+import * as path from "node:path"
+import * as process from "node:process"
+
+import type { AgentEvent, ToolKind } from "spawn-agent"
+
+/* ---------- ANSI palette ---------- */
+
+const IS_TTY = process.stdout.isTTY === true
+
+const ansi =
+  (code: string) =>
+  (s: string): string =>
+    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: Record<ToolKind, string> = {
+  read: "📖",
+  edit: "✍ ",
+  delete: "✘ ",
+  move: "↻ ",
+  search: "🔍",
+  execute: "⚡",
+  think: "✨",
+  fetch: "🌐",
+  switch_mode: "⇄ ",
+  other: "⚙ "
+}
+
+const TOOL_COLOR: Record<ToolKind, (s: string) => string> = {
+  read: warmGray,
+  edit: amberBright,
+  delete: red,
+  move: amber,
+  search: warmGray,
+  execute: amberBright,
+  think: warmGray,
+  fetch: warmGray,
+  switch_mode: amber,
+  other: warmGray
+}
+
+const iconFor = (kind: ToolKind | undefined): string => TOOL_ICON[kind ?? "other"]
+const colorFor = (kind: ToolKind | undefined): ((s: string) => string) =>
+  TOOL_COLOR[kind ?? "other"]
+
+/* ---------- Title compaction ---------- */
+
+const MAX_LABEL = 80
+const MAX_PLAN_ENTRY = 64
+
+const truncate = (s: string, max: number): string =>
+  s.length > max ? `${s.slice(0, max - 1)}…` : s
+
+const stripBold = (s: string): string => 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: string): string => {
+  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: string): string => {
+  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: string, kind: ToolKind | undefined): string => {
+  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)
+}
+
+/* ---------- Streaming state ---------- */
+
+/**
+ * Mutable state the formatter carries across events on a single stream.
+ * The only thing we need to track is whether we're mid-prose (so the
+ * next non-text event can flush a pending newline before printing).
+ */
+export interface FormatState {
+  inProse: boolean
+}
+
+export const newFormatState = (): FormatState => ({ inProse: false })
+
+/* ---------- Public formatter ---------- */
+
+export interface FormattedLine {
+  /** The text to write to stdout. */
+  readonly text: string
+  /** Append a trailing newline after `text`. False for `text-delta` streaming. */
+  readonly newline: boolean
+  /** Emit a leading newline first to terminate any unfinished prose line. */
+  readonly leadNewline: boolean
+}
+
+/**
+ * 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: AgentEvent,
+  verbose: boolean,
+  state: FormatState
+): FormattedLine | null => {
+  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: AgentEvent, verbose: boolean, state: FormatState): void => {
+  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: FormatState): void => {
+  if (state.inProse) {
+    process.stdout.write("\n")
+    state.inProse = false
+  }
+}

package/src/index.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/src/layer.ts

@@ -0,0 +1,189 @@
+import {
+  type AgentOptions,
+  AgentRunner,
+  type AgentRunnerService,
+  type CliAgentError,
+  Config
+} from "@kpritam/grimoire-core"
+import * as Effect from "effect/Effect"
+import * as Layer from "effect/Layer"
+import {
+  type ModelPreference,
+  SpawnAgent,
+  type SpawnAgentConnectOptions,
+  type SupportedAgentId,
+  type TurnResult
+} 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: AgentOptions,
+  cwd: string,
+  defaultInactivityMs: number,
+  logStream: boolean
+): SpawnAgentConnectOptions => {
+  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: string) => 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: TurnResult
+): {
+  readonly content: string
+  readonly stopReason?: string
+  readonly usage?: { readonly inputTokens?: number; readonly outputTokens?: number }
+  readonly raw: TurnResult
+} => ({
+  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 satisfies SupportedAgentId
+    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: string,
+      cwd: string,
+      logStream: boolean
+    ): Effect.Effect<ReturnType<typeof toAgentReply>, CliAgentError> =>
+      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: { modelPreference?: ModelPreference } =
+                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: string,
+      cwd: string,
+      logStream: boolean
+    ): Effect.Effect<ReturnType<typeof toAgentReply>, CliAgentError> =>
+      wallTimeoutMs > 0
+        ? runOnce(prompt, cwd, logStream).pipe(
+            Effect.timeoutOrElse({
+              duration: `${wallTimeoutMs} millis`,
+              orElse: () => Effect.fail(wallTimeoutError(agentId, wallTimeoutMs))
+            })
+          )
+        : runOnce(prompt, cwd, logStream)
+
+    const service: AgentRunnerService = {
+      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)
+  })
+)