@capagents/forgeqe 2.3.12 → 2.3.14

package/docs/user-guide.html

@@ -728,6 +728,12 @@ Add a GitHub Actions workflow that runs tests/cases.yaml on every PR, and make i
 <tr><td><code>/runs</code>, <code>/reports</code></td><td>The runs and reports in the reports folder, newest first</td></tr>
 <tr><td><code>/jobs</code></td><td>The scheduled jobs: when each runs next, and how its last run ended</td></tr>
 <tr><td><code>/knowledge</code></td><td>The product knowledge the agents read (<code>.forgeqe/knowledge</code>)</td></tr>
+<tr><td><code>/memory</code></td><td>Page memory: the sites and pages ForgeQE remembers, and their flows</td></tr>
+<tr><td><code>/guardrails</code></td><td>The rules every agent follows here</td></tr>
+<tr><td><code>/doctor</code></td><td>Check what ForgeQE needs: programs, sign-ins, and the services it reaches</td></tr>
+<tr><td><code>/settings</code></td><td><code>forgeqe.yaml</code>: where it is and what it sets, opened to edit</td></tr>
+<tr><td><code>/home</code></td><td>Back to the start screen; the session stays</td></tr>
+<tr><td><code>/docs</code></td><td>The user guide</td></tr>
 <tr><td><code>/generated</code></td><td>How much of this repository's code ForgeQE wrote, and how much is still there</td></tr>
 <tr><td><code>/init</code></td><td>Set ForgeQE up in this folder: <code>forgeqe.yaml</code>, <code>llms.json</code>, editable prompts, skills, knowledge</td></tr>
 <tr><td><code>/skills [name]</code></td><td>The skills each agent can use, or one skill's instructions</td></tr>
@@ -826,8 +832,9 @@ Add a GitHub Actions workflow that runs tests/cases.yaml on every PR, and make i
 </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 how many of the five things most features rest on are set up: <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>. In a terminal 110 columns or wider it is the sidebar's <strong>Get set up</strong>: each finished item with what it found, and the next one as a card whose <strong>▸ Set up</strong> puts its steps in the chat (for <strong>Work items</strong>, it runs <code>/auth</code>). Narrower, it is one <strong>Setup</strong> line under the composer, and <strong>▸ how to set up</strong> gives the steps for every missing one. The checks are the same ones <code>/features</code> uses, so the two always agree.</p>
-<p><strong>Sidebar.</strong> Under setup, <strong>Work</strong> opens <strong>Runs</strong>, <strong>Reports</strong>, <strong>Jobs</strong> and <strong>Knowledge</strong> (<code>/runs</code>, <code>/reports</code>, <code>/jobs</code>, <code>/knowledge</code>) with how many of each there are, and <strong>Defects</strong> (with a tracker set up) puts a request for the open defects in the composer. <strong>System</strong> opens <strong>Features</strong>, <strong>Skills</strong>, <strong>Environments</strong>, <strong>Models</strong>, <strong>Sign in</strong> and <strong>Logs</strong>. The status line shows the branch, the model (click it to change), the tracker, and when the next scheduled job runs.</p>
+<p><strong>Setup checklist.</strong> Until everything is set up, the start screen shows how many of the five things most features rest on are set up: <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>. In a terminal 110 columns or wider it is the sidebar's <strong>Get set up</strong>: each finished item with what it found, and the next one as a card with <strong>▸ Set up</strong> (its steps in the chat; for <strong>Work items</strong>, it runs <code>/auth</code>) and <strong>skip</strong>. A skipped item is kept in <code>.forgeqe/setup.json</code> and not asked about again. Narrower, it is one <strong>Setup</strong> line with <strong>▸ how to set up</strong> and <strong>skip</strong>. The checks are the same ones <code>/features</code> uses, so the two always agree.</p>
+<p><strong>Sidebar and rail.</strong> The sidebar has three groups. <strong>Work</strong>: <strong>Home</strong>, <strong>This session</strong> (once you have asked something), <strong>Runs</strong>, <strong>Reports</strong>, <strong>Jobs</strong>, and <strong>Defects</strong> (with a tracker set up). <strong>Knowledge</strong>: <strong>Page memory</strong>, <strong>Test cases</strong> (with a tracker), <strong>Guardrails</strong>, <strong>Product</strong> (the knowledge files) and <strong>Skills</strong>. <strong>System</strong>: <strong>Models</strong>, <strong>Sign in</strong>, <strong>Environments</strong>, <strong>Doctor</strong>, <strong>Settings</strong>, <strong>Help</strong> and <strong>Docs</strong>. Each shows how many there are and opens its list (<code>/runs</code>, <code>/reports</code>, <code>/jobs</code>, <code>/memory</code>, <code>/guardrails</code>, <code>/knowledge</code>, <code>/skills</code>, <code>/doctor</code>, <code>/settings</code>, <code>/help</code>, <code>/docs</code>); <strong>Defects</strong> and <strong>Test cases</strong> put a request in the composer, since the agent reads them from the tracker. Narrower than 110 columns, and beside the chat at every width, the sidebar folds to a rail of its icons, so the start screen is always one click away: <strong>Home</strong> (or <code>/home</code>) shows it with the session still open, and <strong>▸ Back to the session</strong> or any request returns to it.</p>
+<p><strong>Needs you and Today.</strong> Once there are runs, the start screen shows what needs you (runs that failed this week and have not passed since, and jobs whose last run failed, each with <strong>open</strong> and <strong>rerun</strong>) and what ran today. The greeting says how many runs there were today and how many failed. The model is in the composer beside <strong>⏎ Send</strong>: click it to change it. The status line shows the branch, the tracker, and when the next scheduled job runs.</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 task specification for ForgeQE's agent, laid out as a system prompt and written in ASD-STE100 Simplified Technical English, before it is sent. It has these parts, in this order: <strong>Role</strong> (who the agent acts as), <strong>Objective</strong> (one instruction), <strong>Context</strong> (the facts, with names), <strong>Steps</strong> (only when they add something), <strong>Rules</strong> (your limits and the setup's), <strong>Output format</strong> (what comes back and how it is laid out), and <strong>Summary</strong> (what you get, in one sentence, read last):</p>
@@ -888,6 +895,69 @@ forgeqe run &quot;Run the cases in smoke.yaml and don't post results&quot; --pla
 <li><code>failure.png</code>: last screenshot, only when the run failed</li>
 </ul>
 </div>
+<section class="doc sub" id="doc-how_to_use-a-live-agent-for-programs-forgeqe-chat---jsonl"><h4>A live agent for programs (<code>forgeqe chat --jsonl</code>)</h4><div class="prose"><p>A program that needs what the shell has (one live agent per conversation, follow-ups, credentials remembered for the session, <strong>Your turn</strong> and questions, stop), such as a web UI or an IDE, starts <code>forgeqe chat --jsonl</code> and talks to it in JSON lines. It is the shell's agent and the shell's events, not a screen to scrape. ForgeQE serves no HTTP here: the program that starts the process owns transport, users, and sign-in.</p>
+<pre><code class="language-bash">forgeqe chat --jsonl [--repo DIR | --no-code] [--profile NAME] [--url URL] [--headed]
+                     [--browser-provider local|docker|browserstack|testmu] [--devices a,b] [--max-steps N]
+                     [--replay MODE] [--no-memory] [--carry-over FILE] [--config forgeqe.yaml] [--verbose] [--debug]
+</code></pre>
+<p>The flags mean what they mean for <code>forgeqe run</code> and <code>forgeqe start</code>. <code>--jsonl</code> is required (the only format so far). <code>--carry-over FILE</code> is a JSON list <code>[{&quot;user&quot;: &quot;...&quot;, &quot;reply&quot;: &quot;...&quot;}, ...]</code>: the turns of an earlier conversation whose process has gone (a server closing idle chats). The first message then reaches the agent with those turns before it, as when you switch profiles in the shell. To change profiles, start a new process with <code>--profile</code> and <code>--carry-over</code>. <code>--verbose</code> also writes readable event lines to stderr.</p>
+<p>The process opens ForgeQE's agent on the first message and keeps it for every later one; it ends it on <code>close</code>, the end of stdin, or a signal. It works like the shell: background monitors are allowed and stop when it exits, and passed runs become tests unless <code>--no-code</code>. A request that was run before and passed is run again as recorded, without the agent, as in the shell (Tier 0, <code>registry.mode</code>); its turn ends with the result as the reply. When the agent cannot run (no model, no agent runtime), the process writes <code>fatal</code> and exits 1 before it reads anything: it never falls back to a browser goal.</p>
+<p><strong>stdout</strong> carries only JSON lines: one object per line, UTF-8, ending in <code>\n</code>. Logs, warnings, and anything a library prints go to stderr. Lines can be long (a card, a suite result); do not assume a maximum length. Every line has <code>&quot;v&quot;: 1</code>, <code>&quot;seq&quot;</code> (1, 2, 3, … in this process), and <code>&quot;t&quot;</code> (ISO time). Every string is passed through the session's secret redaction, so a password given in a message never comes back out, not even inside a tool result; profile keys and the values of ForgeQE's own secret variables never appear.</p>
+<p><strong>Input</strong> (stdin), one JSON object per line:</p>
+<div class="tbl"><table>
+<thead>
+<tr><th><code>type</code></th><th>Fields</th><th>Meaning</th></tr>
+</thead>
+<tbody>
+<tr><td><code>message</code></td><td><code>id</code> (your turn id), <code>text</code></td><td>A new user message. Refused with <code>error</code> <code>busy</code> while a turn runs</td></tr>
+<tr><td><code>answer</code></td><td><code>id</code> (from an <code>ask</code>), <code>choice</code> (an option id, or <code>null</code> to cancel)</td><td>Answers the pending question</td></tr>
+<tr><td><code>continue</code></td><td><code>id</code> (from a <code>wait</code>), <code>ok</code> (<code>true</code> = Done, continue; <code>false</code> = Cancel)</td><td>Ends the pending wait</td></tr>
+<tr><td><code>stop</code></td><td></td><td>Stops the running turn (Esc or <code>/stop</code> in the shell). Nothing when idle</td></tr>
+<tr><td><code>close</code></td><td></td><td>Stops any turn, closes the agent, stops monitors and the containers it started, writes <code>closed</code>, exits 0</td></tr>
+</tbody>
+</table></div>
+<p>A line that is not JSON, has an unknown <code>type</code>, or misses a field gets <code>error</code> <code>bad_input</code> with the reason and the first 200 characters of the line; the process goes on. The end of stdin is the same as <code>close</code>.</p>
+<p><strong>Output</strong> (stdout):</p>
+<div class="tbl"><table>
+<thead>
+<tr><th><code>type</code></th><th>Fields</th><th>When</th></tr>
+</thead>
+<tbody>
+<tr><td><code>ready</code></td><td><code>protocol</code> (1), <code>version</code>, <code>cwd</code>, <code>writeTests</code>, <code>profile</code> (<code>name</code> and <code>provider</code>, never a key)</td><td>Once, after the config is loaded and checked, before stdin is read</td></tr>
+<tr><td><code>turn_start</code></td><td><code>id</code></td><td>A message was accepted</td></tr>
+<tr><td><code>agent</code></td><td><code>id</code>, <code>event</code>: a <code>CodeEvent</code> (<code>stream</code>, <code>say</code>, <code>start</code>, <code>tool</code>, <code>plan</code>, <code>usage</code>, <code>context</code>, <code>test</code>, <code>info</code>, …)</td><td>While the turn runs</td></tr>
+<tr><td><code>tool</code></td><td><code>id</code>, <code>event</code>: a <code>ToolEvent</code> (<code>run-start</code>, <code>run-event</code>, <code>run-done</code>, <code>suite-*</code>, <code>card</code>, <code>info</code>, <code>agent</code>, <code>code-*</code>, …)</td><td>While the turn runs; <code>id</code> is <code>null</code> for a background monitor between turns</td></tr>
+<tr><td><code>ask</code></td><td><code>id</code> (<code>ask-N</code>), <code>turn</code>, <code>question</code> (<code>title</code>, <code>detail</code>, <code>lines</code>, <code>options[{id, label}]</code>)</td><td>A tool asks you to choose</td></tr>
+<tr><td><code>wait</code></td><td><code>id</code> (<code>wait-N</code>), <code>turn</code>, <code>prompt</code></td><td>A tool waits for you to do something by hand</td></tr>
+<tr><td><code>turn_done</code></td><td><code>id</code>, <code>outcome</code> (<code>done</code>, <code>failed</code>, <code>needs_input</code>, <code>stopped</code>), <code>reply</code> (the visible reply), <code>next</code> (follow-ups), <code>error</code> (when there is one), <code>usage</code> (the agent's usage so far, <code>null</code> before it opened)</td><td>The turn ended, whatever the way</td></tr>
+<tr><td><code>error</code></td><td><code>code</code> (<code>bad_input</code>, <code>busy</code>, <code>unknown_id</code>, <code>internal</code>), <code>message</code>, <code>turn</code> (when one runs)</td><td>A problem that does not end the process</td></tr>
+<tr><td><code>fatal</code></td><td><code>message</code></td><td>The process cannot go on; exit code 1 follows</td></tr>
+<tr><td><code>closed</code></td><td></td><td>The last line before a clean exit</td></tr>
+</tbody>
+</table></div>
+<p><code>CodeEvent</code> and <code>ToolEvent</code> are passed through as they are: their types in <code>src/types.ts</code> and <code>src/mcp/tools.ts</code> are the contract. Rules:</p>
+<ul>
+<li>Every turn that got <code>turn_start</code> gets exactly one <code>turn_done</code>, also after an error (<code>outcome: &quot;failed&quot;</code> with the <code>error</code>).</li>
+<li>One <code>ask</code> and one <code>wait</code> can be pending at a time. <code>answer</code> or <code>continue</code> with an id that is not pending gets <code>error</code> <code>unknown_id</code>, and nothing else happens.</li>
+<li><code>stop</code> and <code>close</code> answer a pending <code>ask</code> with <code>null</code> and a pending <code>wait</code> with <code>false</code>, then stop the turn, which ends with <code>turn_done</code> <code>stopped</code>.</li>
+<li>If the agent fails to start on a message, that turn ends <code>failed</code> with the error, and the next message tries again.</li>
+<li>Exit codes: 0 after <code>closed</code>, 1 after <code>fatal</code>, 2 after SIGINT or SIGTERM (the turn is stopped and the agent closed first).</li>
+</ul>
+<p>A complete exchange (<code>→</code> stdout, <code>←</code> stdin; <code>t</code> left out):</p>
+<pre><code class="language-text">→ {&quot;v&quot;:1,&quot;seq&quot;:1,&quot;type&quot;:&quot;ready&quot;,&quot;protocol&quot;:1,&quot;version&quot;:&quot;2.3.11&quot;,&quot;cwd&quot;:&quot;/srv/studio/users/ana/workspace&quot;,&quot;writeTests&quot;:true,&quot;profile&quot;:{&quot;name&quot;:&quot;copilot&quot;,&quot;provider&quot;:&quot;github_copilot&quot;}}
+← {&quot;type&quot;:&quot;message&quot;,&quot;id&quot;:&quot;m1&quot;,&quot;text&quot;:&quot;Run SHOP-12 on staging&quot;}
+→ {&quot;v&quot;:1,&quot;seq&quot;:2,&quot;type&quot;:&quot;turn_start&quot;,&quot;id&quot;:&quot;m1&quot;}
+→ {&quot;v&quot;:1,&quot;seq&quot;:3,&quot;type&quot;:&quot;agent&quot;,&quot;id&quot;:&quot;m1&quot;,&quot;event&quot;:{&quot;type&quot;:&quot;code&quot;,&quot;kind&quot;:&quot;stream&quot;,&quot;id&quot;:&quot;p1&quot;,&quot;text&quot;:&quot;I'll run SHOP-12&quot;}}
+→ {&quot;v&quot;:1,&quot;seq&quot;:4,&quot;type&quot;:&quot;agent&quot;,&quot;id&quot;:&quot;m1&quot;,&quot;event&quot;:{&quot;type&quot;:&quot;code&quot;,&quot;kind&quot;:&quot;start&quot;,&quot;text&quot;:&quot;forgeqe_run_test_cases&quot;,&quot;tool&quot;:&quot;forgeqe_run_test_cases&quot;,&quot;id&quot;:&quot;c1&quot;}}
+→ {&quot;v&quot;:1,&quot;seq&quot;:5,&quot;type&quot;:&quot;tool&quot;,&quot;id&quot;:&quot;m1&quot;,&quot;event&quot;:{&quot;type&quot;:&quot;run-start&quot;,&quot;goal&quot;:&quot;SHOP-12: Checkout with a saved card&quot;}}
+→ {&quot;v&quot;:1,&quot;seq&quot;:6,&quot;type&quot;:&quot;ask&quot;,&quot;id&quot;:&quot;ask-1&quot;,&quot;turn&quot;:&quot;m1&quot;,&quot;question&quot;:{&quot;title&quot;:&quot;Which sprint?&quot;,&quot;options&quot;:[{&quot;id&quot;:&quot;s41&quot;,&quot;label&quot;:&quot;Sprint 41&quot;},{&quot;id&quot;:&quot;s42&quot;,&quot;label&quot;:&quot;Sprint 42&quot;}]}}
+← {&quot;type&quot;:&quot;answer&quot;,&quot;id&quot;:&quot;ask-1&quot;,&quot;choice&quot;:&quot;s42&quot;}
+→ {&quot;v&quot;:1,&quot;seq&quot;:7,&quot;type&quot;:&quot;tool&quot;,&quot;id&quot;:&quot;m1&quot;,&quot;event&quot;:{&quot;type&quot;:&quot;card&quot;,&quot;card&quot;:{&quot;status&quot;:&quot;passed&quot;,&quot;title&quot;:&quot;SHOP-12&quot;,&quot;stats&quot;:[],&quot;body&quot;:&quot;Checkout with a saved card passed in 41 s.&quot;}}}
+→ {&quot;v&quot;:1,&quot;seq&quot;:8,&quot;type&quot;:&quot;turn_done&quot;,&quot;id&quot;:&quot;m1&quot;,&quot;outcome&quot;:&quot;done&quot;,&quot;reply&quot;:&quot;SHOP-12 passed on staging.&quot;,&quot;next&quot;:[{&quot;label&quot;:&quot;Write a test for it&quot;,&quot;request&quot;:&quot;Write a test for SHOP-12&quot;}],&quot;usage&quot;:{&quot;input&quot;:5200,&quot;output&quot;:310}}
+← {&quot;type&quot;:&quot;close&quot;}
+→ {&quot;v&quot;:1,&quot;seq&quot;:9,&quot;type&quot;:&quot;closed&quot;}
+</code></pre>
+</div></section>
 </section>
 </section>
 <section class="chapter" id="area-browser" aria-labelledby="area-browser-h">
@@ -1598,6 +1668,7 @@ Signing in stays <code>/auth</code> and <code>forgeqe login</code>; <code>forgeq
 <tr><td><code>forgeqe start [--repo DIR] [--headed]</code></td><td>The shell</td></tr>
 <tr><td><code>forgeqe run &quot;&lt;request&gt;&quot; [--plain]</code></td><td>One request without the shell</td></tr>
 <tr><td><code>forgeqe run --direct &quot;&lt;goal&gt;&quot; [--skill NAME]</code></td><td>One browser goal, no agent</td></tr>
+<tr><td><code>forgeqe chat --jsonl [--carry-over FILE]</code></td><td>One live agent for a program, in JSON lines (see <a href="../HOW_TO_USE.md#a-live-agent-for-programs-forgeqe-chat---jsonl">A live agent for programs</a>)</td></tr>
 <tr><td><code>forgeqe suite &lt;source...&gt; [--parallel N] [--skill NAME]</code></td><td>Run test cases the same way every time (pipelines)</td></tr>
 <tr><td><code>forgeqe cases &lt;source...&gt;</code></td><td>List the cases a source gives, without running them</td></tr>
 <tr><td><code>forgeqe bi [build] [--from FILE|DIR]... [--static|--evidence]</code></td><td>The team report of every run here and the shared bundles (see <a href="#doc-how_to_use-team-report">Team report</a>)</td></tr>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@capagents/forgeqe",
-  "version": "2.3.12",
+  "version": "2.3.14",
   "description": "ForgeQE: a browser agent CLI that runs goals and test cases in local Chrome or Chromium, or BrowserStack and TestMu AI/LambdaTest when configured, and turns passing runs into tests in your repo",
   "license": "SEE LICENSE IN LICENSE",
   "repository": {