@capagents/forgeqe 1.0.4 → 1.0.7

package/src/refine.ts

@@ -0,0 +1,116 @@
+import { realpathSync } from "node:fs"
+
+import type { AppConfig } from "./config.ts"
+import { openSession, type OpencodeSession } from "./code/runtime.ts"
+import { privateEnvNames } from "./childEnv.ts"
+import { MCP_NAME, TOOL_TIMEOUT_MS, localToolServer } from "./mcp/server.ts"
+import { TOOLS, environmentNotes, type ToolContext } from "./mcp/tools.ts"
+import { prompt } from "./prompts.ts"
+import type { CodeEvent } from "./types.ts"
+
+/**
+ * The shell's Refine (ctrl+r): what the user typed becomes a precise request for ForgeQE's agent, checked against what
+ * ForgeQE knows (its capabilities, the configured systems and project, the domain, product knowledge, recent runs)
+ * with read-only tools. It never runs anything, and the user decides what is sent.
+ */
+
+/** The only tools the refiner may call: each reads, none changes anything or starts a run. */
+export const REFINE_TOOLS = ["capabilities", "query_api", "find_test_cases", "list_sprints", "run_details"]
+
+export type Refined = {
+  refined: string
+  grounded: { fact: string; checked: boolean }[]
+  assumed: string[]
+  missing: string[]
+}
+
+export const REFINE_SCHEMA = {
+  type: "object",
+  properties: {
+    refined: { type: "string", description: "The request, precise and complete, as the user would say it" },
+    grounded: {
+      type: "array",
+      items: { type: "object", properties: { fact: { type: "string" }, checked: { type: "boolean" } }, required: ["fact", "checked"] },
+    },
+    assumed: { type: "array", items: { type: "string" } },
+    missing: { type: "array", items: { type: "string" } },
+  },
+  required: ["refined", "grounded", "assumed", "missing"],
+} as const
+
+const REFINE_AGENT = {
+  name: "forgeqe-refine",
+  description: "Turns what the user typed into a precise request, checked against what ForgeQE knows",
+  get prompt() {
+    return prompt("refine")
+  },
+  permission: { edit: "deny", bash: "deny", webfetch: "deny" },
+  steps: 8,
+}
+
+export function refineRequest(text: string, recent: { user: string; reply: string }[]): string {
+  const turns = recent.slice(-4).flatMap((t) => [`User: ${t.user.slice(0, 600)}`, `ForgeQE: ${t.reply.slice(0, 600)}`])
+  return [turns.length ? `The conversation so far:\n${turns.join("\n")}\n` : "", `Refine this request:\n${text}`].filter(Boolean).join("\n")
+}
+
+/** Keeps only what the schema allows, so the shell never shows a malformed answer. */
+export function cleanRefined(r: Partial<Refined> | null | undefined, original: string): Refined {
+  const strings = (v: unknown) => (Array.isArray(v) ? v.map(String).map((s) => s.trim()).filter(Boolean) : [])
+  return {
+    refined: String(r?.refined || "").trim() || original,
+    grounded: Array.isArray(r?.grounded) ? r!.grounded.filter((g) => g && String(g.fact || "").trim()).map((g) => ({ fact: String(g.fact).trim(), checked: g.checked === true })) : [],
+    assumed: strings(r?.assumed),
+    missing: strings(r?.missing),
+  }
+}
+
+export async function refine(opts: {
+  config: AppConfig
+  cwd: string
+  text: string
+  recent: { user: string; reply: string }[]
+  signal?: AbortSignal
+  onEvent?: (e: CodeEvent) => void
+  /** Replaces openSession in tests. */
+  open?: (o: Parameters<typeof openSession>[0]) => Promise<OpencodeSession<Refined>>
+}): Promise<Refined> {
+  const cwd = (() => {
+    try {
+      return realpathSync(opts.cwd)
+    } catch {
+      return opts.cwd
+    }
+  })()
+  const context = (): ToolContext => ({ config: opts.config, cwd, session: "shell", writeTests: false })
+  const tools = localToolServer({ tools: TOOLS.filter((t) => REFINE_TOOLS.includes(t.name)), context, instructions: () => environmentNotes(context()), timeoutMs: TOOL_TIMEOUT_MS })
+  try {
+    const session = await (opts.open || openSession<Refined>)({
+      repo: cwd,
+      profile: opts.config.llm,
+      // The refiner works on the request, not the domain: ForgeQE's agent applies that when it handles it.
+      domain: null,
+      model: opts.config.code.model,
+      bin: opts.config.code.opencode,
+      readDirs: [cwd],
+      hide: privateEnvNames(opts.config),
+      role: "refiner",
+      signal: opts.signal,
+      onEvent: opts.onEvent,
+      agent: { ...REFINE_AGENT, prompt: `${REFINE_AGENT.prompt}\n\nThis session:\n${environmentNotes(context())}` },
+      schema: REFINE_SCHEMA as unknown as Record<string, unknown>,
+      mcp: { [MCP_NAME]: tools.entry },
+      hideTool: (tool) => tool.startsWith(`${MCP_NAME}_`),
+      title: "ForgeQE refine",
+    })
+    try {
+      let out = await session.prompt(refineRequest(opts.text, opts.recent))
+      if (!out.report && !out.error && !opts.signal?.aborted) out = await session.prompt("Give the structured result: refined, grounded, assumed, and missing.")
+      if (!out.report) throw new Error(out.error ? `Refine failed: ${out.error}` : "Refine gave no result.")
+      return cleanRefined(out.report, opts.text)
+    } finally {
+      await session.close()
+    }
+  } finally {
+    tools.stop()
+  }
+}