@capagents/forgeqe 2.3.9 → 2.3.11

package/HOW_TO_USE.md

@@ -620,6 +620,9 @@ The slash commands control the session and show a few things directly (`/help` l
 | `/env [name]` | The test environments in `env.yaml` and their apps, or switch to one |
 | `/logs [shots]` | Save this session's log and runs in one archive to share (`shots`: with screenshots) |
 | `/features` | What ForgeQE can do, and what each capability still needs here |
+| `/runs`, `/reports` | The runs and reports in the reports folder, newest first |
+| `/jobs` | The scheduled jobs: when each runs next, and how its last run ended |
+| `/knowledge` | The product knowledge the agents read (`.forgeqe/knowledge`) |
 | `/generated` | How much of this repository's code ForgeQE wrote, and how much is still there |
 | `/init` | Set ForgeQE up in this folder: `forgeqe.yaml`, `llms.json`, editable prompts, skills, knowledge |
 | `/skills [name]` | The skills each agent can use, or one skill's instructions |
@@ -753,7 +756,9 @@ Over the conversation: **Files** (each file read ◉, written ✚, or edited ✎
 
 **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's **Setup** line shows how many of the five things most features rest on are set up, and names the ones that are not: **Model** (a live model profile), **Coding agent**, **Work items** (Azure DevOps, Jira, TestRail, Zephyr, qTest, or Xray), **Domain**, and **Notifications**. **▸ how to set up** puts the steps for each missing one in the chat (for **Work items**, type `/auth`). The checks are the same ones `/features` uses, so the two always agree.
+**Setup checklist.** Until everything is set up, the start screen shows how many of the five things most features rest on are set up: **Model** (a live model profile), **Coding agent**, **Work items** (Azure DevOps, Jira, TestRail, Zephyr, qTest, or Xray), **Domain**, and **Notifications**. In a terminal 110 columns or wider it is the sidebar's **Get set up**: each finished item with what it found, and the next one as a card whose **▸ Set up** puts its steps in the chat (for **Work items**, it runs `/auth`). Narrower, it is one **Setup** line under the composer, and **▸ how to set up** gives the steps for every missing one. The checks are the same ones `/features` uses, so the two always agree.
+
+**Sidebar.** Under setup, **Work** opens **Runs**, **Reports**, **Jobs** and **Knowledge** (`/runs`, `/reports`, `/jobs`, `/knowledge`) with how many of each there are, and **Defects** (with a tracker set up) puts a request for the open defects in the composer. **System** opens **Features**, **Skills**, **Environments**, **Models**, **Sign in** and **Logs**. The status line shows the branch, the model (click it to change), the tracker, and when the next scheduled job runs.
 
 **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.
 
@@ -824,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.
@@ -2907,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