@capagents/forgeqe 2.3.10 → 2.3.12

package/HOW_TO_USE.md

@@ -829,6 +829,74 @@ Each run gets its own folder, named by its run id (the start time), under `.forg
 - `report.html`: the run's report
 - `failure.png`: last screenshot, only when the run failed
 
+### A live agent for programs (`forgeqe chat --jsonl`)
+
+A program that needs what the shell has (one live agent per conversation, follow-ups, credentials remembered for the session, **Your turn** and questions, stop), such as a web UI or an IDE, starts `forgeqe chat --jsonl` 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.
+
+```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]
+```
+
+The flags mean what they mean for `forgeqe run` and `forgeqe start`. `--jsonl` is required (the only format so far). `--carry-over FILE` is a JSON list `[{"user": "...", "reply": "..."}, ...]`: 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 `--profile` and `--carry-over`. `--verbose` also writes readable event lines to stderr.
+
+The process opens ForgeQE's agent on the first message and keeps it for every later one; it ends it on `close`, 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 `--no-code`. A request that was run before and passed is run again as recorded, without the agent, as in the shell (Tier 0, `registry.mode`); its turn ends with the result as the reply. When the agent cannot run (no model, no agent runtime), the process writes `fatal` and exits 1 before it reads anything: it never falls back to a browser goal.
+
+**stdout** carries only JSON lines: one object per line, UTF-8, ending in `\n`. 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 `"v": 1`, `"seq"` (1, 2, 3, … in this process), and `"t"` (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.
+
+**Input** (stdin), one JSON object per line:
+
+| `type` | Fields | Meaning |
+|--------|--------|---------|
+| `message` | `id` (your turn id), `text` | A new user message. Refused with `error` `busy` while a turn runs |
+| `answer` | `id` (from an `ask`), `choice` (an option id, or `null` to cancel) | Answers the pending question |
+| `continue` | `id` (from a `wait`), `ok` (`true` = Done, continue; `false` = Cancel) | Ends the pending wait |
+| `stop` | | Stops the running turn (Esc or `/stop` in the shell). Nothing when idle |
+| `close` | | Stops any turn, closes the agent, stops monitors and the containers it started, writes `closed`, exits 0 |
+
+A line that is not JSON, has an unknown `type`, or misses a field gets `error` `bad_input` with the reason and the first 200 characters of the line; the process goes on. The end of stdin is the same as `close`.
+
+**Output** (stdout):
+
+| `type` | Fields | When |
+|--------|--------|------|
+| `ready` | `protocol` (1), `version`, `cwd`, `writeTests`, `profile` (`name` and `provider`, never a key) | Once, after the config is loaded and checked, before stdin is read |
+| `turn_start` | `id` | A message was accepted |
+| `agent` | `id`, `event`: a `CodeEvent` (`stream`, `say`, `start`, `tool`, `plan`, `usage`, `context`, `test`, `info`, …) | While the turn runs |
+| `tool` | `id`, `event`: a `ToolEvent` (`run-start`, `run-event`, `run-done`, `suite-*`, `card`, `info`, `agent`, `code-*`, …) | While the turn runs; `id` is `null` for a background monitor between turns |
+| `ask` | `id` (`ask-N`), `turn`, `question` (`title`, `detail`, `lines`, `options[{id, label}]`) | A tool asks you to choose |
+| `wait` | `id` (`wait-N`), `turn`, `prompt` | A tool waits for you to do something by hand |
+| `turn_done` | `id`, `outcome` (`done`, `failed`, `needs_input`, `stopped`), `reply` (the visible reply), `next` (follow-ups), `error` (when there is one), `usage` (the agent's usage so far, `null` before it opened) | The turn ended, whatever the way |
+| `error` | `code` (`bad_input`, `busy`, `unknown_id`, `internal`), `message`, `turn` (when one runs) | A problem that does not end the process |
+| `fatal` | `message` | The process cannot go on; exit code 1 follows |
+| `closed` | | The last line before a clean exit |
+
+`CodeEvent` and `ToolEvent` are passed through as they are: their types in `src/types.ts` and `src/mcp/tools.ts` are the contract. Rules:
+
+- Every turn that got `turn_start` gets exactly one `turn_done`, also after an error (`outcome: "failed"` with the `error`).
+- One `ask` and one `wait` can be pending at a time. `answer` or `continue` with an id that is not pending gets `error` `unknown_id`, and nothing else happens.
+- `stop` and `close` answer a pending `ask` with `null` and a pending `wait` with `false`, then stop the turn, which ends with `turn_done` `stopped`.
+- If the agent fails to start on a message, that turn ends `failed` with the error, and the next message tries again.
+- Exit codes: 0 after `closed`, 1 after `fatal`, 2 after SIGINT or SIGTERM (the turn is stopped and the agent closed first).
+
+A complete exchange (`→` stdout, `←` stdin; `t` left out):
+
+```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"}}
+← {"type":"message","id":"m1","text":"Run SHOP-12 on staging"}
+→ {"v":1,"seq":2,"type":"turn_start","id":"m1"}
+→ {"v":1,"seq":3,"type":"agent","id":"m1","event":{"type":"code","kind":"stream","id":"p1","text":"I'll run SHOP-12"}}
+→ {"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"}}
+→ {"v":1,"seq":5,"type":"tool","id":"m1","event":{"type":"run-start","goal":"SHOP-12: Checkout with a saved card"}}
+→ {"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"}]}}
+← {"type":"answer","id":"ask-1","choice":"s42"}
+→ {"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."}}}
+→ {"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}}
+← {"type":"close"}
+→ {"v":1,"seq":9,"type":"closed"}
+```
+
 ## 5. Page memory
 
 Live runs build a memory of the pages they visit, next to `forgeqe.yaml`. With no config file it goes to `~/.forgeqe/memory` (under `FORGEQE_HOME` when that is set), so runs from any folder share one memory.
@@ -2912,6 +2980,7 @@ Signing in stays `/auth` and `forgeqe login`; `forgeqe bi export` and `forgeqe l
 | `forgeqe start [--repo DIR] [--headed]` | The shell |
 | `forgeqe run "<request>" [--plain]` | One request without the shell |
 | `forgeqe run --direct "<goal>" [--skill NAME]` | One browser goal, no agent |
+| `forgeqe chat --jsonl [--carry-over FILE]` | One live agent for a program, in JSON lines (see [A live agent for programs](#a-live-agent-for-programs-forgeqe-chat---jsonl)) |
 | `forgeqe suite <source...> [--parallel N] [--skill NAME]` | Run test cases the same way every time (pipelines) |
 | `forgeqe cases <source...>` | List the cases a source gives, without running them |
 | `forgeqe bi [build] [--from FILE\|DIR]... [--static\|--evidence]` | The team report of every run here and the shared bundles (see [Team report](#team-report)) |

package/LICENSE

@@ -1,6 +1,6 @@
 ForgeQE Software Licence
 
-Copyright (c) 2026 Javed Khan. All rights reserved.
+Copyright (c) 2026 Capgemini. All rights reserved.
 
 ForgeQE, its documentation, prompts, skills, and accompanying files (together, "the Software") are proprietary and confidential. The Software is licensed, not sold.
 

package/README.md

@@ -130,6 +130,14 @@ ForgeQE's agent needs the agent runtime (downloaded automatically, see Install)
 
 `forgeqe run` exits 0 when the job is done, 1 when it failed, 2 when it was stopped, and 3 when the agent needs more information.
 
+**For programs.** `forgeqe chat --jsonl` gives a program that needs a live agent (a web UI, an IDE) what the shell has: one agent for the whole conversation, follow-ups, credentials remembered for the session, questions and **Your turn** waits, and stop. It reads one JSON object per line on stdin and writes the agent's and the tools' events, the same ones the shell draws, as JSON lines on stdout; nothing else is ever written there, and remembered secrets and keys are redacted. It takes the flags of `forgeqe run`, plus `--carry-over FILE` to continue an earlier conversation. The protocol is in [HOW_TO_USE.md](HOW_TO_USE.md#a-live-agent-for-programs-forgeqe-chat---jsonl).
+
+```text
+→ {"v":1,"seq":1,"type":"ready","protocol":1,"version":"2.3.11","cwd":"/work/app","writeTests":true,"profile":{"name":"copilot","provider":"github_copilot"},"t":"…"}
+← {"type":"message","id":"m1","text":"Run SHOP-12 on staging"}
+→ {"v":1,"seq":9,"type":"turn_done","id":"m1","outcome":"done","reply":"SHOP-12 passed on staging.","next":[],"usage":{"input":5200,"output":310},"t":"…"}
+```
+
 `forgeqe --help` lists every command, among them `forgeqe db`, `forgeqe data` and `forgeqe flows` (see [Databases, test data, and data flows](#databases-test-data-and-data-flows)) and `forgeqe generated`, which says how much of the code ForgeQE wrote and how much is still there (`--json` for a pipeline).
 
 ## Page memory