@capagents/forgeqe 1.0.3 → 1.0.5

package/HOW_TO_USE.md

@@ -366,12 +366,45 @@ While a run is going, the bar under the prompt shows a spinner, the tokens used,
 
 The text is the agent's own result. Failed runs show `✗ Task failed` with the reason, and stopped runs show `■ Run stopped`. `forgeqe run` prints the same summary at the end.
 
+### The screen
+
+On a terminal 120 columns wide or more, the shell splits in two once you send a request:
+
+- **Left (40%)**: the **Session** panel (model and profile, folder, domain, requests so far), the conversation, and the prompt.
+- **Right (60%)**: a status line with who is working, for how long, and a **■ Stop** button (a running suite adds a progress bar, `██████░░░░░░ 5/8`); then **Plan** (the agent's to-do list, then each browser step or suite case with ✓, ✗ and why, ◐ running), **Activity** (every tool call, browser step, and the agents' reasoning), **Files** (each file read ◉, written ✚, or edited ✎, newest first), **Context** (how full the model's context window is, and the skills, product knowledge, domain, and MCP servers in it), and **Tokens** (total, input, output, cached; no prices, which are in reports and `forgeqe models`).
+
+On a narrower terminal the chat fills the screen, and Ctrl-O switches between the chat and the same panels.
+
+**Moving between panels.** Shift-Tab (or a click) moves the keys from the prompt to Plan, Activity, then Files; the focused panel's border lights up and shows its keys. Esc, or typing, goes back to the prompt.
+
+| Panel | Keys |
+|-------|------|
+| Plan | ↑/↓ select a step, Enter puts the whole step, with why it failed, in the chat |
+| Activity | ↑/↓, PgUp/PgDn scroll; `a` all, `e` errors, `s` steps (browser steps and reasoning), `t` tools (tool calls and files); the filter buttons are clickable too |
+| Files | ↑/↓ select, Enter (or a click) opens the file |
+
+**Links.** Report folders, report files, and web addresses in the chat are links: Cmd-click (Ctrl-click on Windows and Linux) opens them in terminals that support links, such as VS Code, iTerm2, Windows Terminal, and recent GNOME Terminal. A path that no longer exists stays plain text.
+
+**Setup checklist.** Until everything is set up, the start screen shows what most features rest on: **Model** (a live model profile), **Coding agent**, **Work items** (Azure DevOps, Jira, TestRail, Zephyr, qTest, or Xray), **Domain**, and **Notifications**, each ✓ or ○. Click an open item to see how to set it up; **Work items** starts `/auth`. The checks are the same ones `/features` uses, so the two always agree.
+
+**Command palette.** Ctrl-P opens a palette of every action, command, profile, and example request; type a few letters to find one ("rr" finds *Refine my request*, "auth" finds the sign-in commands), ↑/↓ to choose, Enter to run it. Example requests are put in the prompt for you to edit, never sent straight away.
+
+**`/` and `@` in the prompt.** Typing `/` lists the commands that match; typing `@` suggests references: recent runs (*last run*, then each by its folder), files in the repository by name or path (`@Login` finds `pages/Login.ts`), and, after `@` and a number such as `@1761`, the Azure DevOps work item with its title (read-only). Tab completes, ↑/↓ choose, Esc closes the list.
+
+**Refine.** Ctrl-R (or *Refine my request* in the palette) turns what you typed into a precise request before it is sent. A read-only agent checks it against this setup: what ForgeQE can do here, the systems that are set up, the project's sprints and test cases, and recent runs. It shows the refined request with what it **checked** ✓, what it **assumed** ~, and what is **missing** ?. Enter uses it, `e` puts it in the prompt to edit, Esc keeps yours. Refine never runs anything, writes files, or changes a work item.
+
+**Next steps.** When a request finishes, up to three suggestions appear above the prompt, such as *Write a test for this run*, *Why did it fail?*, *Open the report*, or *Rerun the cases that failed*. Click one or press Alt-1 to Alt-3; suggestions that start work are put in the prompt first.
+
 | Key | Action |
 |-----|--------|
 | Enter | Send the message or command |
-| Tab | Next LLM profile from `llms.json`; the conversation carries over to the new model |
-| Ctrl-P | Show commands |
-| Esc | Ask to stop the run: **Stop run**, **Stop and close ForgeQE**, or **Keep running** |
+| Tab | Next LLM profile from `llms.json`; the conversation carries over to the new model. While `/` or `@` suggestions show, completes the selected one |
+| Shift-Tab | Move between the chat and the Plan, Activity, and Files panels |
+| Ctrl-P | Command palette |
+| Ctrl-R | Refine the request in the prompt |
+| Ctrl-O | Chat or details, on a terminal narrower than 120 columns |
+| Alt-1 to Alt-3 | Take a suggested next step |
+| Esc | Ask to stop the run: **Stop run**, **Stop and close ForgeQE**, or **Keep running**. In a panel, back to the prompt |
 | Ctrl-C | Ask to close ForgeQE: **Close** or **Cancel**. A second Ctrl-C closes straight away |
 
 In the button prompt, ←/→ or Tab move between buttons, Enter confirms, Esc cancels, and a mouse click works too. `esc stop` and `ctrl+c close` in the bar under the prompt are also clickable. **Stop and close** waits until the browser has shut down and the run's files are saved, then closes ForgeQE.
@@ -1533,6 +1566,11 @@ Start with `--debug` (or set `FORGEQE_DEBUG=1`) for more: the browser engine log
 | `/auth [system]`, `/auth logout <system>` | Sign in to a system in the browser (the token is typed unseen), forget one; `/auth` alone shows what is signed in |
 | `/clear`, `/help`, `/exit` | Clear the transcript, show help, quit |
 | Drag with the mouse | Copy the selected text |
+| Ctrl-P | Command palette: actions, commands, profiles, example requests |
+| Ctrl-R | Refine the request before sending it |
+| `/`, `@` | Suggest commands; suggest runs, files, and work items to reference |
+| Shift-Tab | Move between the chat and the Plan, Activity, and Files panels |
+| Cmd/Ctrl-click a path | Open a report, file, or web address |
 
 ---
 

package/docs/user-guide.html

@@ -543,20 +543,48 @@ Add a GitHub Actions workflow that runs tests/cases.yaml on every PR, and make i
 ┃  Saved     .forgeqe/reports/20260928-172700/  run.json · workflow.yaml · trace.md · report.html
 </code></pre>
 <p>The text is the agent's own result. Failed runs show <code>✗ Task failed</code> with the reason, and stopped runs show <code>■ Run stopped</code>. <code>forgeqe run</code> prints the same summary at the end.</p>
+</div>
+<section class="doc sub" id="doc-how_to_use-the-screen"><h4>The screen</h4><div class="prose"><p>On a terminal 120 columns wide or more, the shell splits in two once you send a request:</p>
+<ul>
+<li><strong>Left (40%)</strong>: the <strong>Session</strong> panel (model and profile, folder, domain, requests so far), the conversation, and the prompt.</li>
+<li><strong>Right (60%)</strong>: a status line with who is working, for how long, and a <strong>■ Stop</strong> button (a running suite adds a progress bar, <code>██████░░░░░░ 5/8</code>); then <strong>Plan</strong> (the agent's to-do list, then each browser step or suite case with ✓, ✗ and why, ◐ running), <strong>Activity</strong> (every tool call, browser step, and the agents' reasoning), <strong>Files</strong> (each file read ◉, written ✚, or edited ✎, newest first), <strong>Context</strong> (how full the model's context window is, and the skills, product knowledge, domain, and MCP servers in it), and <strong>Tokens</strong> (total, input, output, cached; no prices, which are in reports and <code>forgeqe models</code>).</li>
+</ul>
+<p>On a narrower terminal the chat fills the screen, and Ctrl-O switches between the chat and the same panels.</p>
+<p><strong>Moving between panels.</strong> Shift-Tab (or a click) moves the keys from the prompt to Plan, Activity, then Files; the focused panel's border lights up and shows its keys. Esc, or typing, goes back to the prompt.</p>
+<div class="tbl"><table>
+<thead>
+<tr><th>Panel</th><th>Keys</th></tr>
+</thead>
+<tbody>
+<tr><td>Plan</td><td>↑/↓ select a step, Enter puts the whole step, with why it failed, in the chat</td></tr>
+<tr><td>Activity</td><td>↑/↓, PgUp/PgDn scroll; <code>a</code> all, <code>e</code> errors, <code>s</code> steps (browser steps and reasoning), <code>t</code> tools (tool calls and files); the filter buttons are clickable too</td></tr>
+<tr><td>Files</td><td>↑/↓ select, Enter (or a click) opens the file</td></tr>
+</tbody>
+</table></div>
+<p><strong>Links.</strong> Report folders, report files, and web addresses in the chat are links: Cmd-click (Ctrl-click on Windows and Linux) opens them in terminals that support links, such as VS Code, iTerm2, Windows Terminal, and recent GNOME Terminal. A path that no longer exists stays plain text.</p>
+<p><strong>Setup checklist.</strong> Until everything is set up, the start screen shows what most features rest on: <strong>Model</strong> (a live model profile), <strong>Coding agent</strong>, <strong>Work items</strong> (Azure DevOps, Jira, TestRail, Zephyr, qTest, or Xray), <strong>Domain</strong>, and <strong>Notifications</strong>, each ✓ or ○. Click an open item to see how to set it up; <strong>Work items</strong> starts <code>/auth</code>. The checks are the same ones <code>/features</code> uses, so the two always agree.</p>
+<p><strong>Command palette.</strong> Ctrl-P opens a palette of every action, command, profile, and example request; type a few letters to find one (&quot;rr&quot; finds <em>Refine my request</em>, &quot;auth&quot; finds the sign-in commands), ↑/↓ to choose, Enter to run it. Example requests are put in the prompt for you to edit, never sent straight away.</p>
+<p><strong><code>/</code> and <code>@</code> in the prompt.</strong> Typing <code>/</code> lists the commands that match; typing <code>@</code> suggests references: recent runs (<em>last run</em>, then each by its folder), files in the repository by name or path (<code>@Login</code> finds <code>pages/Login.ts</code>), and, after <code>@</code> and a number such as <code>@1761</code>, the Azure DevOps work item with its title (read-only). Tab completes, ↑/↓ choose, Esc closes the list.</p>
+<p><strong>Refine.</strong> Ctrl-R (or <em>Refine my request</em> in the palette) turns what you typed into a precise request before it is sent. A read-only agent checks it against this setup: what ForgeQE can do here, the systems that are set up, the project's sprints and test cases, and recent runs. It shows the refined request with what it <strong>checked</strong> ✓, what it <strong>assumed</strong> ~, and what is <strong>missing</strong> ?. Enter uses it, <code>e</code> puts it in the prompt to edit, Esc keeps yours. Refine never runs anything, writes files, or changes a work item.</p>
+<p><strong>Next steps.</strong> When a request finishes, up to three suggestions appear above the prompt, such as <em>Write a test for this run</em>, <em>Why did it fail?</em>, <em>Open the report</em>, or <em>Rerun the cases that failed</em>. Click one or press Alt-1 to Alt-3; suggestions that start work are put in the prompt first.</p>
 <div class="tbl"><table>
 <thead>
 <tr><th>Key</th><th>Action</th></tr>
 </thead>
 <tbody>
 <tr><td>Enter</td><td>Send the message or command</td></tr>
-<tr><td>Tab</td><td>Next LLM profile from <code>llms.json</code>; the conversation carries over to the new model</td></tr>
-<tr><td>Ctrl-P</td><td>Show commands</td></tr>
-<tr><td>Esc</td><td>Ask to stop the run: <strong>Stop run</strong>, <strong>Stop and close ForgeQE</strong>, or <strong>Keep running</strong></td></tr>
+<tr><td>Tab</td><td>Next LLM profile from <code>llms.json</code>; the conversation carries over to the new model. While <code>/</code> or <code>@</code> suggestions show, completes the selected one</td></tr>
+<tr><td>Shift-Tab</td><td>Move between the chat and the Plan, Activity, and Files panels</td></tr>
+<tr><td>Ctrl-P</td><td>Command palette</td></tr>
+<tr><td>Ctrl-R</td><td>Refine the request in the prompt</td></tr>
+<tr><td>Ctrl-O</td><td>Chat or details, on a terminal narrower than 120 columns</td></tr>
+<tr><td>Alt-1 to Alt-3</td><td>Take a suggested next step</td></tr>
+<tr><td>Esc</td><td>Ask to stop the run: <strong>Stop run</strong>, <strong>Stop and close ForgeQE</strong>, or <strong>Keep running</strong>. In a panel, back to the prompt</td></tr>
 <tr><td>Ctrl-C</td><td>Ask to close ForgeQE: <strong>Close</strong> or <strong>Cancel</strong>. A second Ctrl-C closes straight away</td></tr>
 </tbody>
 </table></div>
 <p>In the button prompt, ←/→ or Tab move between buttons, Enter confirms, Esc cancels, and a mouse click works too. <code>esc stop</code> and <code>ctrl+c close</code> in the bar under the prompt are also clickable. <strong>Stop and close</strong> waits until the browser has shut down and the run's files are saved, then closes ForgeQE.</p>
-</div>
+</div></section>
 </section>
 <section class="doc" id="doc-how_to_use-4-without-the-shell">
 <h3>Without the shell</h3>
@@ -2024,6 +2052,11 @@ agents: [browser]
 <tr><td><code>/auth [system]</code>, <code>/auth logout &lt;system&gt;</code></td><td>Sign in to a system in the browser (the token is typed unseen), forget one; <code>/auth</code> alone shows what is signed in</td></tr>
 <tr><td><code>/clear</code>, <code>/help</code>, <code>/exit</code></td><td>Clear the transcript, show help, quit</td></tr>
 <tr><td>Drag with the mouse</td><td>Copy the selected text</td></tr>
+<tr><td>Ctrl-P</td><td>Command palette: actions, commands, profiles, example requests</td></tr>
+<tr><td>Ctrl-R</td><td>Refine the request before sending it</td></tr>
+<tr><td><code>/</code>, <code>@</code></td><td>Suggest commands; suggest runs, files, and work items to reference</td></tr>
+<tr><td>Shift-Tab</td><td>Move between the chat and the Plan, Activity, and Files panels</td></tr>
+<tr><td>Cmd/Ctrl-click a path</td><td>Open a report, file, or web address</td></tr>
 </tbody>
 </table></div>
 <hr />

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@capagents/forgeqe",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "description": "ForgeQE: a browser agent CLI that runs goals and test cases in Chrome and turns passing runs into tests in your repo",
   "license": "MIT",
   "type": "module",

package/prompts/README.md

@@ -16,6 +16,7 @@ project; leave it as it is to keep getting ForgeQE's improvements when you updat
 | api-scenarios.md | Plans API scenarios from test cases or plain English |
 | explore-charters.md | Plans exploratory charters for a story |
 | eval-judge.md | Scores the agent's test cases in `forgeqe eval domain` |
+| refine.md | Refine (ctrl+r) in the shell: makes what you typed precise, checked against what ForgeQE knows |
 | skill-rule.md | How agents use skills (included in most prompts) |
 | domain-rule.md | How agents apply the product's industry risks and regulations, declared or worked out (included in every agent that analyses requirements or designs, writes, reviews, or heals tests) |
 | browser-*.md | The browser agent: error recovery, when a goal counts as done, recording checks, clicking so runs become tests, step verdicts for test cases, picking skills |

package/prompts/refine.md

@@ -0,0 +1,17 @@
+---
+name: refine
+description: "Turns what the user typed into a precise request for ForgeQE's agent, checked against what ForgeQE knows."
+used_by: "the shell's Refine (ctrl+r)"
+---
+You refine a request the user typed for ForgeQE, a test automation assistant, before it is sent to ForgeQE's agent. You do not carry the request out, and you do not change anything.
+
+Make it a request the agent can act on without guessing:
+- Keep the user's intent and scope exactly. Do not add work they did not ask for, and do not drop anything they did.
+- Name things the way ForgeQE knows them: the system and project ("Azure DevOps project QI-Payments"), ids ("test plan 412, suite 77", "story 1761", "SHOP-12"), files and folders, and the profile. Use "This session" and the capabilities tool to know what ForgeQE can do, but describe the action in plain words ("run the test cases", "write a Playwright test"): never name ForgeQE's tools or capability ids.
+- Resolve references from the session and the conversation ("the last run", "that story", "the payments plan") into what they point to, but only when exactly one thing fits.
+- Check what you can with your read-only tools: that a work item, test plan, suite, or run exists, what it is called, how many cases it has. Mark each fact you state as checked or assumed.
+- Never invent an id, a URL, a project, or a file. What you cannot resolve or check goes in missing, as a short question for the user.
+- Keep the user's settings when they give them (browsers at once, headed, whether results go back), and add none they did not.
+- Write the refined request as the user would say it, in one to four sentences, in their language.
+
+Finish with the structured result: refined (the request), grounded (each fact you state, and whether you checked it), assumed (what you took to be meant, in a few words each), and missing (questions, if any).

package/src/capabilities/status.ts

@@ -56,7 +56,8 @@ export type CapabilityStatus = {
   inputs: string[]
 }
 
-function gap(r: Requirement, cfg: AppConfig, probes: Probes): Omit<Gap, "requirement" | "optional"> | null {
+/** What `r` is missing in this setup, and how to fix it; null when it is met. */
+export function requirementGap(r: Requirement, cfg: AppConfig, probes: Probes = MACHINE): Omit<Gap, "requirement" | "optional"> | null {
   switch (r.kind) {
     case "live_model":
       return cfg.llm.provider === "none" || cfg.llm.provider === "mock"
@@ -89,7 +90,7 @@ function gap(r: Requirement, cfg: AppConfig, probes: Probes): Omit<Gap, "require
     case "input":
       return null
     case "either": {
-      const gaps = r.of.map((alt) => gap(alt, cfg, probes))
+      const gaps = r.of.map((alt) => requirementGap(alt, cfg, probes))
       if (gaps.some((g) => !g)) return null
       return { missing: gaps.map((g) => g!.missing).join(", or "), fix: gaps.map((g) => g!.fix).join("; or ") }
     }
@@ -99,7 +100,7 @@ function gap(r: Requirement, cfg: AppConfig, probes: Probes): Omit<Gap, "require
 export function capabilityStatus(c: Capability, cfg: AppConfig, probes: Probes = MACHINE): CapabilityStatus {
   const gaps: Gap[] = []
   for (const r of c.requires) {
-    const g = gap(r, cfg, probes)
+    const g = requirementGap(r, cfg, probes)
     if (g) gaps.push({ requirement: r, optional: Boolean("optional" in r && r.optional), ...g })
   }
   const state = gaps.some((g) => !g.optional) ? "needs_setup" : gaps.length ? "partial" : "ready"

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()
+  }
+}