@capagents/forgeqe 0.0.0-stage → 1.0.1

package/src/brain/index.ts

@@ -0,0 +1,189 @@
+import { realpathSync } from "node:fs"
+import path from "node:path"
+
+import type { CodeEvent, Usage } from "../types.ts"
+import { findOpencode, openSession, type OpencodeSession } from "../code/runtime.ts"
+import { privateEnvNames } from "../childEnv.ts"
+import type { AppConfig } from "../config.ts"
+import { externalMcp, externalNotes, type ExternalPlan } from "../mcp/external.ts"
+import { MCP_NAME, TOOL_TIMEOUT_MS, localToolServer } from "../mcp/server.ts"
+import { TOOLS, environmentNotes, type ToolContext } from "../mcp/tools.ts"
+import { brainPrompt, BRAIN_SCHEMA, type BrainReport } from "./prompt.ts"
+import { redactSecrets } from "../sessionLogins.ts"
+import { logEvent } from "../sessionLog.ts"
+import { loadSkills } from "../skills/registry.ts"
+import { domainNotes } from "../domain.ts"
+
+export const BRAIN_AGENT = "forgeqe"
+
+export type BrainAnswer = { reply: string; outcome: "done" | "failed" | "needs_input" | "stopped"; error?: string }
+
+export type Brain = {
+  model: string
+  ask(text: string): Promise<BrainAnswer>
+  abort(): Promise<void>
+  close(): Promise<void>
+  usage: Usage
+}
+
+export type BrainOptions = {
+  config: AppConfig
+  /** The repository or folder the agent works in. */
+  cwd: string
+  /** The tools' context; read on every call so /profile and /headed apply. */
+  context: () => Omit<ToolContext, "config" | "cwd">
+  /** Extra lines for the agent about this session, e.g. whether passed runs become tests. */
+  notes?: string[]
+  signal?: AbortSignal
+  onEvent?: (e: CodeEvent) => void
+  /** Replaces openSession in tests. */
+  open?: (o: Parameters<typeof openSession>[0]) => Promise<OpencodeSession<BrainReport>>
+  /** Replaces the MCP servers derived from forgeqe.yaml (tests). */
+  external?: ExternalPlan
+}
+
+/** Why the brain cannot run with this config, or null when it can. */
+export function brainUnavailable(cfg: AppConfig): string | null {
+  if (cfg.llm.provider === "mock" && !cfg.code.model) return "the mock profile has no model"
+  if (cfg.llm.provider === "none" && !cfg.code.model) return "no model is set up"
+  if (!findOpencode(cfg.code.opencode)) return "the agent runtime is not installed"
+  return null
+}
+
+/**
+ * Where the agent works and whether passed runs become tests: `repo` is the --repo flag (null for --no-code),
+ * falling back to code.repo in forgeqe.yaml, then the current folder.
+ */
+export function sessionSetup(cfg: AppConfig, repo: string | null | undefined): { cwd: string; notes: string[]; writeTests: boolean } {
+  if (repo === null) return { cwd: process.cwd(), notes: ["Do not write tests unless the user asks for one."], writeTests: false }
+  return {
+    cwd: path.resolve(repo || cfg.code.repo || process.cwd()),
+    notes: [
+      "Passed browser runs become tests: after a browser_run with purpose test passes and returns a next_step, call write_test with its run_dir before you reply, unless the user says not to. " +
+        "A browser_run with purpose task (looking up or linking work items, reading a tool) never gets a test. " +
+        "run_test_cases does this itself, case by case: each passed case is coded right after its browser run, so do not call write_test for those. " +
+        "In the reply, name the test file ForgeQE's coding agent wrote and whether ForgeQE's own run of it passed.",
+    ],
+    writeTests: true,
+  }
+}
+
+/** One line per configured system: its MCP server connected, or ForgeQE's API tools cover it and why. */
+async function reportExternal(session: OpencodeSession<BrainReport>, plan: ExternalPlan, emit: (e: CodeEvent) => void) {
+  for (const s of plan.skipped) emit({ type: "code", kind: "info", text: `${s.label} not started: ${s.why}. ForgeQE's API tools cover it.` })
+  if (!plan.servers.length || !session.mcpStatus) return
+  const status = await session.mcpStatus().catch(() => ({}) as Record<string, { status: string; error?: string }>)
+  for (const s of plan.servers) {
+    const st = status[s.name]
+    if (st?.status === "connected") emit({ type: "code", kind: "test", ok: true, attempt: 0, text: `${s.label} connected` })
+    else {
+      const why = st?.status === "failed" ? (st.error || "failed").replace(/\s+/g, " ").slice(0, 200) : st?.status === "needs_auth" || st?.status === "needs_client_registration" ? "it needs a browser sign-in, which ForgeQE cannot do" : st?.status || "no status"
+      emit({ type: "code", kind: "test", ok: false, attempt: 0, text: `${s.label} did not connect (${why}). ForgeQE's API tools cover it.` })
+    }
+  }
+}
+
+function realpathOr(dir: string): string {
+  try {
+    return realpathSync(dir)
+  } catch {
+    return path.resolve(dir)
+  }
+}
+
+/**
+ * Start ForgeQE's agent: an agent runtime session with the ForgeQE prompt, the active profile's model, and ForgeQE's
+ * tools served over MCP from this process, so browser runs and suites report to the caller while they run.
+ */
+const CARRY_TURNS = 20
+const CARRY_CHARS = 3_000
+
+/**
+ * The first prompt of a new agent session that continues an earlier conversation (the user switched profiles):
+ * the earlier turns, with remembered secrets redacted, then the new message.
+ */
+export function carryOver(turns: { user: string; reply: string }[], text: string): string {
+  if (!turns.length) return text
+  const clip = (s: string) => (s.length > CARRY_CHARS ? `${s.slice(0, CARRY_CHARS)}…` : s)
+  const earlier = turns.slice(-CARRY_TURNS).flatMap((t) => [`User: ${clip(redactSecrets(t.user))}`, `You: ${clip(redactSecrets(t.reply || "(no reply)"))}`])
+  return [
+    "The user switched model profiles, so this is a new session continuing the conversation below. Nothing from those turns is still running; files and saved logins they produced are still there.",
+    "",
+    ...earlier,
+    "",
+    `User: ${text}`,
+  ].join("\n")
+}
+
+export async function openBrain(opts: BrainOptions): Promise<Brain> {
+  const { config } = opts
+  const cwd = realpathOr(opts.cwd)
+  const context = (): ToolContext => ({ ...opts.context(), config, cwd })
+  const tools = localToolServer({ tools: TOOLS, context, instructions: () => environmentNotes(context()), timeoutMs: TOOL_TIMEOUT_MS })
+  const external = opts.external || externalMcp(config)
+  const notes = [environmentNotes(context()), ...externalNotes(external), ...(opts.notes || [])].filter(Boolean).join("\n")
+  const readDirs = [...new Set([config.export.outDir, config.memory.dir, cwd].flatMap((d) => [path.resolve(d), realpathOr(d)]))]
+  const onEvent = (e: CodeEvent) => {
+    logEvent("agent.event", e)
+    opts.onEvent?.(e)
+  }
+  const emit = onEvent
+  if (external.servers.length) emit({ type: "code", kind: "info", text: `Connecting to ${external.servers.map((s) => s.label).join(", ")}…` })
+
+  let session: OpencodeSession<BrainReport>
+  try {
+    session = await (opts.open || openSession<BrainReport>)({
+      repo: cwd,
+      profile: config.llm,
+      domain: domainNotes(config),
+      model: config.code.model,
+      bin: config.code.opencode,
+      readDirs,
+      hide: privateEnvNames(config),
+      role: "ForgeQE's agent",
+      secrets: Object.assign({}, ...external.servers.map((s) => s.secrets)),
+      signal: opts.signal,
+      onEvent,
+      agent: { name: BRAIN_AGENT, description: "ForgeQE: browser runs, test cases, tests, and CI pipelines", prompt: `${brainPrompt()}\n\nThis session:\n${notes}`, skills: "forgeqe" },
+      skills: loadSkills(config.skills, cwd).skills,
+      schema: BRAIN_SCHEMA,
+      mcp: {
+        ...Object.fromEntries(external.servers.map((s) => [s.name, s.config])),
+        [MCP_NAME]: tools.entry,
+      },
+      hideTool: (tool) => tool.startsWith(`${MCP_NAME}_`),
+      title: "ForgeQE",
+    })
+  } catch (err) {
+    tools.stop()
+    throw err
+  }
+  await reportExternal(session, external, emit)
+
+  let stopped = false
+  return {
+    model: session.model,
+    usage: session.usage,
+    async ask(text) {
+      stopped = false
+      logEvent("agent.ask", { model: session.model, characters: text.length })
+      const out = await session.prompt(text)
+      // Written after the turn, when credentials the message gave are remembered and so redacted.
+      logEvent("agent.turn", { ask: text, error: out.error, report: out.report, text: out.text })
+      if (stopped || out.error === "stopped" || opts.signal?.aborted) return { reply: "", outcome: "stopped" }
+      const reply = out.report?.reply?.trim() || out.text.trim()
+      if (out.error && !out.report) return { reply, outcome: "failed", error: out.error }
+      return { reply, outcome: out.report?.outcome || (out.error ? "failed" : "done"), error: out.error }
+    },
+    abort: () => {
+      stopped = true
+      tools.server.abortAll()
+      return session.abort()
+    },
+    async close() {
+      tools.server.abortAll()
+      await session.close()
+      tools.stop()
+    },
+  }
+}

package/src/brain/prompt.ts

@@ -0,0 +1,19 @@
+import { prompt } from "../prompts.ts"
+
+/** System prompt of ForgeQE's agent, which reads every request in the shell and `forgeqe run`. */
+export const brainPrompt = () => prompt("brain")
+
+export const BRAIN_SCHEMA = {
+  type: "object",
+  properties: {
+    reply: { type: "string", description: "What you did and found, or the question you need answered. Plain text, short." },
+    outcome: {
+      type: "string",
+      enum: ["done", "failed", "needs_input"],
+      description: "done: the request was carried out and everything checked passed. failed: a run, test, or pipeline failed or could not be done. needs_input: you asked the user something.",
+    },
+  },
+  required: ["reply", "outcome"],
+} as const
+
+export type BrainReport = { reply?: string; outcome?: "done" | "failed" | "needs_input" }

package/src/capabilities/docs.ts

@@ -0,0 +1,101 @@
+import { existsSync, readFileSync } from "node:fs"
+import path from "node:path"
+
+import type { DocRef } from "./registry.ts"
+
+/**
+ * README.md and HOW_TO_USE.md as addressable sections. The agent reads the contents, picks sections by id, and gets
+ * their exact text: nothing is ranked or guessed by keyword. Ids are the docs' own GitHub anchors (doc#anchor), so
+ * they are stable across releases while a heading keeps its name.
+ */
+
+export const DOCS: DocRef["doc"][] = ["README.md", "HOW_TO_USE.md"]
+
+export type DocSection = {
+  id: string
+  doc: DocRef["doc"]
+  heading: string
+  /** 2 for ##, 3 for ###. */
+  level: number
+  /** The ## section a ### belongs to. */
+  parent?: string
+  text: string
+}
+
+/** GitHub's heading anchor: lowercase, punctuation dropped, spaces to hyphens. */
+export function anchor(heading: string): string {
+  return heading
+    .trim()
+    .toLowerCase()
+    .replace(/[^\p{L}\p{N}\s_-]/gu, "")
+    .replace(/\s/g, "-")
+}
+
+const root = path.resolve(import.meta.dir, "..", "..")
+
+export function parseSections(doc: DocRef["doc"], markdown: string): DocSection[] {
+  const out: DocSection[] = []
+  const seen = new Map<string, number>()
+  let parent: DocSection | undefined
+  let current: DocSection | undefined
+  let fence = false
+  for (const line of markdown.split("\n")) {
+    if (/^\s*(```|~~~)/.test(line)) fence = !fence
+    const h = fence ? null : line.match(/^(#{2,3}) (.+?)\s*$/)
+    if (!h) {
+      if (current) current.text += `${line}\n`
+      continue
+    }
+    const base = anchor(h[2]!)
+    const n = seen.get(base) ?? 0
+    seen.set(base, n + 1)
+    current = { id: `${doc}#${n ? `${base}-${n}` : base}`, doc, heading: h[2]!, level: h[1]!.length, text: "" }
+    if (current.level === 2) parent = current
+    else if (parent) current.parent = parent.id
+    out.push(current)
+  }
+  for (const s of out) s.text = s.text.trim()
+  return out
+}
+
+let cache: DocSection[] | null = null
+
+export function docSections(): DocSection[] {
+  if (cache) return cache
+  cache = DOCS.flatMap((doc) => {
+    const file = path.join(root, doc)
+    return existsSync(file) ? parseSections(doc, readFileSync(file, "utf8")) : []
+  })
+  return cache
+}
+
+/** The section a DocRef names: the first heading in that doc with exactly that text. */
+export function resolveDoc(ref: DocRef, sections = docSections()): DocSection | undefined {
+  return sections.find((s) => s.doc === ref.doc && s.heading === ref.heading)
+}
+
+/** The table of contents: every section's id and heading, nested under its ## section. */
+export function docsContents(sections = docSections()): { id: string; heading: string; sections?: { id: string; heading: string }[] }[] {
+  return sections
+    .filter((s) => s.level === 2)
+    .map((s) => {
+      const children = sections.filter((c) => c.parent === s.id).map((c) => ({ id: c.id, heading: c.heading }))
+      return { id: s.id, heading: s.heading, ...(children.length ? { sections: children } : {}) }
+    })
+}
+
+/** The sections with these ids, exactly; a ## section also lists its subsections to read next. Unknown ids are named. */
+export function readDocs(ids: string[], sections = docSections()): { sections: { id: string; heading: string; text: string; subsections?: string[] }[]; unknown?: string[] } {
+  const found = []
+  const unknown = []
+  for (const id of ids) {
+    const s = sections.find((x) => x.id === id)
+    if (!s) {
+      unknown.push(id)
+      continue
+    }
+    const children = sections.filter((c) => c.parent === s.id).map((c) => c.id)
+    found.push({ id: s.id, heading: s.heading, text: s.text, ...(children.length ? { subsections: children } : {}) })
+  }
+  return { sections: found, ...(unknown.length ? { unknown } : {}) }
+}