@capagents/forgeqe 2.3.13 → 2.3.14
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/forgeqe.js +878 -878
- package/docs/user-guide.html +64 -0
- package/package.json +1 -1
package/docs/user-guide.html
CHANGED
|
@@ -895,6 +895,69 @@ forgeqe run "Run the cases in smoke.yaml and don't post results" --pla
|
|
|
895
895
|
<li><code>failure.png</code>: last screenshot, only when the run failed</li>
|
|
896
896
|
</ul>
|
|
897
897
|
</div>
|
|
898
|
+
<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>
|
|
899
|
+
<pre><code class="language-bash">forgeqe chat --jsonl [--repo DIR | --no-code] [--profile NAME] [--url URL] [--headed]
|
|
900
|
+
[--browser-provider local|docker|browserstack|testmu] [--devices a,b] [--max-steps N]
|
|
901
|
+
[--replay MODE] [--no-memory] [--carry-over FILE] [--config forgeqe.yaml] [--verbose] [--debug]
|
|
902
|
+
</code></pre>
|
|
903
|
+
<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>[{"user": "...", "reply": "..."}, ...]</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>
|
|
904
|
+
<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>
|
|
905
|
+
<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>"v": 1</code>, <code>"seq"</code> (1, 2, 3, … in this process), and <code>"t"</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>
|
|
906
|
+
<p><strong>Input</strong> (stdin), one JSON object per line:</p>
|
|
907
|
+
<div class="tbl"><table>
|
|
908
|
+
<thead>
|
|
909
|
+
<tr><th><code>type</code></th><th>Fields</th><th>Meaning</th></tr>
|
|
910
|
+
</thead>
|
|
911
|
+
<tbody>
|
|
912
|
+
<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>
|
|
913
|
+
<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>
|
|
914
|
+
<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>
|
|
915
|
+
<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>
|
|
916
|
+
<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>
|
|
917
|
+
</tbody>
|
|
918
|
+
</table></div>
|
|
919
|
+
<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>
|
|
920
|
+
<p><strong>Output</strong> (stdout):</p>
|
|
921
|
+
<div class="tbl"><table>
|
|
922
|
+
<thead>
|
|
923
|
+
<tr><th><code>type</code></th><th>Fields</th><th>When</th></tr>
|
|
924
|
+
</thead>
|
|
925
|
+
<tbody>
|
|
926
|
+
<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>
|
|
927
|
+
<tr><td><code>turn_start</code></td><td><code>id</code></td><td>A message was accepted</td></tr>
|
|
928
|
+
<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>
|
|
929
|
+
<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>
|
|
930
|
+
<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>
|
|
931
|
+
<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>
|
|
932
|
+
<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>
|
|
933
|
+
<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>
|
|
934
|
+
<tr><td><code>fatal</code></td><td><code>message</code></td><td>The process cannot go on; exit code 1 follows</td></tr>
|
|
935
|
+
<tr><td><code>closed</code></td><td></td><td>The last line before a clean exit</td></tr>
|
|
936
|
+
</tbody>
|
|
937
|
+
</table></div>
|
|
938
|
+
<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>
|
|
939
|
+
<ul>
|
|
940
|
+
<li>Every turn that got <code>turn_start</code> gets exactly one <code>turn_done</code>, also after an error (<code>outcome: "failed"</code> with the <code>error</code>).</li>
|
|
941
|
+
<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>
|
|
942
|
+
<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>
|
|
943
|
+
<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>
|
|
944
|
+
<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>
|
|
945
|
+
</ul>
|
|
946
|
+
<p>A complete exchange (<code>→</code> stdout, <code>←</code> stdin; <code>t</code> left out):</p>
|
|
947
|
+
<pre><code class="language-text">→ {"v":1,"seq":1,"type":"ready","protocol":1,"version":"2.3.11","cwd":"/srv/studio/users/ana/workspace","writeTests":true,"profile":{"name":"copilot","provider":"github_copilot"}}
|
|
948
|
+
← {"type":"message","id":"m1","text":"Run SHOP-12 on staging"}
|
|
949
|
+
→ {"v":1,"seq":2,"type":"turn_start","id":"m1"}
|
|
950
|
+
→ {"v":1,"seq":3,"type":"agent","id":"m1","event":{"type":"code","kind":"stream","id":"p1","text":"I'll run SHOP-12"}}
|
|
951
|
+
→ {"v":1,"seq":4,"type":"agent","id":"m1","event":{"type":"code","kind":"start","text":"forgeqe_run_test_cases","tool":"forgeqe_run_test_cases","id":"c1"}}
|
|
952
|
+
→ {"v":1,"seq":5,"type":"tool","id":"m1","event":{"type":"run-start","goal":"SHOP-12: Checkout with a saved card"}}
|
|
953
|
+
→ {"v":1,"seq":6,"type":"ask","id":"ask-1","turn":"m1","question":{"title":"Which sprint?","options":[{"id":"s41","label":"Sprint 41"},{"id":"s42","label":"Sprint 42"}]}}
|
|
954
|
+
← {"type":"answer","id":"ask-1","choice":"s42"}
|
|
955
|
+
→ {"v":1,"seq":7,"type":"tool","id":"m1","event":{"type":"card","card":{"status":"passed","title":"SHOP-12","stats":[],"body":"Checkout with a saved card passed in 41 s."}}}
|
|
956
|
+
→ {"v":1,"seq":8,"type":"turn_done","id":"m1","outcome":"done","reply":"SHOP-12 passed on staging.","next":[{"label":"Write a test for it","request":"Write a test for SHOP-12"}],"usage":{"input":5200,"output":310}}
|
|
957
|
+
← {"type":"close"}
|
|
958
|
+
→ {"v":1,"seq":9,"type":"closed"}
|
|
959
|
+
</code></pre>
|
|
960
|
+
</div></section>
|
|
898
961
|
</section>
|
|
899
962
|
</section>
|
|
900
963
|
<section class="chapter" id="area-browser" aria-labelledby="area-browser-h">
|
|
@@ -1605,6 +1668,7 @@ Signing in stays <code>/auth</code> and <code>forgeqe login</code>; <code>forgeq
|
|
|
1605
1668
|
<tr><td><code>forgeqe start [--repo DIR] [--headed]</code></td><td>The shell</td></tr>
|
|
1606
1669
|
<tr><td><code>forgeqe run "<request>" [--plain]</code></td><td>One request without the shell</td></tr>
|
|
1607
1670
|
<tr><td><code>forgeqe run --direct "<goal>" [--skill NAME]</code></td><td>One browser goal, no agent</td></tr>
|
|
1671
|
+
<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>
|
|
1608
1672
|
<tr><td><code>forgeqe suite <source...> [--parallel N] [--skill NAME]</code></td><td>Run test cases the same way every time (pipelines)</td></tr>
|
|
1609
1673
|
<tr><td><code>forgeqe cases <source...></code></td><td>List the cases a source gives, without running them</td></tr>
|
|
1610
1674
|
<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
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@capagents/forgeqe",
|
|
3
|
-
"version": "2.3.
|
|
3
|
+
"version": "2.3.14",
|
|
4
4
|
"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",
|
|
5
5
|
"license": "SEE LICENSE IN LICENSE",
|
|
6
6
|
"repository": {
|