mirror of
https://github.com/jparkerweb/plan2code.git
synced 2026-11-16 04:45:33 -08:00
Sync upstream web console updates into v2.5.0: a Subagents switch that tells the agent to use helpers (per project and skill, sent as a standing instruction only when it changes), a Subagents tab listing the helpers the agent reports, a standalone review that asks what to review instead of assuming the branch diff, a refusal for doc patches that move a version backwards, and the project name in the footer and browser tab title
This commit is contained in:
1 parent
57134cf36e
commit
977e462e76
179 files changed
+14955
-466
No files matched your search
@@ -173,12 +173,13 @@ Optional local browser UI shipped with **every** skill. Source lives in `src/web
|
||||
| `console.mjs` | the CLI the agent drives: `open`, `post`, `wait`, `chat` (the instant Quick question check), `keep` (copy a cited note attachment into `specs/<idea>/attachments/`), `status`, `stop`, `help` (a compact summary for an agent that found the binary but not `console.md`) |
|
||||
| `server.mjs` | HTTP server, spawned **detached** by `open` (never as a harness background task, which get killed on compaction and at assorted timeouts) |
|
||||
| `lib.mjs` | session paths, atomic writes, the patch merge, `validate()` (which also allows `templates` only as `"idea"` on a `text` item; anything else exits 3), `attachmentName()` (the kept-file name `<slug>-<id8>.<ext>`: the same upload always gets the same name), `repoRoots()` (returns `{ project, worktree, branch }`), `readOverview()`, and the three sweeps `open` runs fire-and-forget after it prints (see the cleanup design point below): `sweepUploads()`, `staleSessions()` / `removeSessions()` and `staleScratch()` / `removeScratch()`; plus `cleanupFindings()` / `removeCleanup()` for User Preferences → Cleanup |
|
||||
| `public/` | `index.html`, `app.js`, `answers.js`, `labels.js`, `boot.js`, `chat.js`, `help.js`, `starters.js`, `workspace.js`, `meter.js`, `mentions.js`, `favicon.js`, `app.css`, `render.js`, `palette.js`, `favicon.svg` (Planny peeking up from the tab bar, served as `image/svg+xml`) with `favicon.png` (the same icon at 192 px, served as `image/png`) as the fallback, `vendor/marked.esm.js`, the chimes (`start-skill.mp3`, `bootup.mp3`, `start-stop.mp3`, `next.mp3`, `insert.mp3`, `sleeping.mp3`; which moment plays which is `SOUND_EVENTS` in `palette.js`, one switch per event saved in `looks.json`), and a `package.json` that only says `"type": "module"`, so Node (the server, `console.mjs`, `lib.mjs` and the tests import several `public/*.js` modules) parses them as ES modules without a reparse warning |
|
||||
| `public/help.js` | the Help dialog's PURE rules: `HELP_TABS` (16 tabs: ids, order, labels, diagram flags; every tab uses the chosen highlight color), `helpTabFor()` (which tab opens, FR-8 order, first match wins: finished → Stopping and finishing, server gone or agent adrift → When something looks stuck, opened from the Workspace dialog → Your workspace, then Ask, a red-meter dashboard → Session meter, dashboard, a doc or the Overview, a build, else What this page is) and `helpKeyTarget()` (roving arrow keys, Home, End, wrapping). No module-scope DOM, so `node --test` covers it |
|
||||
| `public/` | `index.html`, `app.js`, `answers.js`, `labels.js`, `boot.js`, `chat.js`, `help.js`, `starters.js`, `workspace.js`, `meter.js`, `subagents.js`, `mentions.js`, `favicon.js`, `app.css`, `render.js`, `palette.js`, `favicon.svg` (Planny peeking up from the tab bar, served as `image/svg+xml`) with `favicon.png` (the same icon at 192 px, served as `image/png`) as the fallback, `vendor/marked.esm.js`, the chimes (`start-skill.mp3`, `bootup.mp3`, `start-stop.mp3`, `next.mp3`, `insert.mp3`, `sleeping.mp3`; which moment plays which is `SOUND_EVENTS` in `palette.js`, one switch per event saved in `looks.json`), and a `package.json` that only says `"type": "module"`, so Node (the server, `console.mjs`, `lib.mjs` and the tests import several `public/*.js` modules) parses them as ES modules without a reparse warning |
|
||||
| `public/help.js` | the Help dialog's PURE rules: `HELP_TABS` (17 tabs: ids, order, labels, diagram flags; every tab uses the chosen highlight color), `helpTabFor()` (which tab opens, FR-8 order, first match wins: finished → Stopping and finishing, server gone or agent adrift → When something looks stuck, opened from the Workspace dialog → Your workspace, then Ask, the Subagents tab → Helpers (subagents), a red-meter dashboard → Session meter, dashboard, a doc or the Overview, a build, else What this page is) and `helpKeyTarget()` (roving arrow keys, Home, End, wrapping). No module-scope DOM, so `node --test` covers it |
|
||||
| `public/workspace.js` | PURE, no imports: the Workspace's name rules (`nameProblem()`, `NAME_MAX`, `defaultName()`, `freeName()` for the `-2` suggestion), the footer label and its width tiers (`footerLabel()`, `FOOTER_TIERS`) and `changeLine()`, the `Workspace: …` reply line an agent is handed per change. Imported by the server, `console.mjs`, `lib.mjs` and the page |
|
||||
| `public/meter.js` | PURE, no imports: the session meter. `WEIGHTS` (the one place per-event points live; its keys are also `RUN_EVENTS`, the `run` events `post` accepts), `LAUNCH_COUNTED` (workflows whose launch itself scores), the built-phase sizing (`TASK_EVENTS`, the keys of `TASK_BONUS`: `implement-phase` +0 and `implement-review-phase` +1; `isTaskCount()` accepts a whole `tasks` from 1 to `MAX_TASKS` 999; `runPoints()` scores such a run `ceil(tasks / TASKS_PER_POINT)` (3) plus its bonus, and any other run its `WEIGHTS` value), `ANSWERS_PER_POINT` 2 (`answer` entries score per skill run, `floor(count / 2)`), `breakdownFrom()` (the click-the-ring list: one row per scoring entry plus one answers row per skill run), `pointsFrom()` (the count, its sum, folded from `ledger.ndjson` and deduplicated by id, never stored), `levelFor()` with `YELLOW_AT` 5 / `RED_AT` 10, `ringFraction()` (full at `RING_FULL` 15), `WORDS`, `tooltipFor()`, `RED_BANNER` and `meterView()` |
|
||||
| `public/mentions.js` | PURE, no imports: the `@name` popover's logic — `mentionAt()` finds an `@partial` at the caret, `matchNames()` filters the workspace names, `applyMention()` splices a pick in and returns the new caret. Used by the Ask box, notes and text answers |
|
||||
| `public/favicon.js` | The tab icon's status bar. `faviconState({ mood, spin, finished })` (PURE) maps the call `renderStatus()` makes for Planny's line to `busy` (the spinning ring), `ready` (`point`), `attention` (`adrift`, `gone`, or `work` without the ring — the stale line) or `plain` (finished, `happy`); `faviconSvg()` is `FAVICON_BODY` (kept equal to `favicon.svg` by a test) plus a bar along the bottom edge in the `FAVICON_COLORS` color (busy dashed on a white strip, so the states differ by pattern; the rest solid); `setFavicon()` swaps both `<link rel=icon>` hrefs only on a change — the SVG as a data URL, the PNG link drawn through a canvas. Called from `say()` in `renderStatus()`, which runs every second |
|
||||
| `public/subagents.js` | PURE, no imports: the Subagents switch. `SUBAGENT_WORKFLOWS` / `offered()` (the opt-in table: `implement`, `implement-review`, `quick-task`, `review`, `pathfinder`, each with its default instruction), `cleanSetting()` (`{ on, instruction, max }` or `{ error }`: `bad`, `too-long` past 2,000 characters, `max` outside 1-20), `FRAME_LINES`, `blockFor(setting, told)` (the `Subagents:` lines and `subagents` field an agent is owed, given the session setting and its cursor; never says "off" to an agent not told "on"), `checkHelper()` / `checkHelpers()` (the `helpers` house rule) and the page's view rules `showSwitch()`, `switchLabel()`, `helperRows()`, `showTab()`, `CHECKIN_LINE`. Imported by the server, `console.mjs`, `lib.mjs`, the page and the tests; in `SERVABLE` and preloaded |
|
||||
| `picker.mjs` | the per-OS native folder picker behind **Browse…** (`pickerCommand()` → `{ command, args, env }` or `null`; `pickFolder()` runs it with async `spawn`, so the server keeps serving while the dialog is open). Copied from `src/launcher/plan2code.js` (self-contained CommonJS, so it cannot be shared) with the prompt as a parameter; a drift test keeps the two in step |
|
||||
| `update-check.mjs` | the dashboard's release check, server-only (never in `SERVABLE`): `compareVersions()` (numeric X.Y.Z, `null` otherwise), `latestTag()` (the highest `refs/tags/vX.Y.Z`, peeled `^{}` and pre-release tags skipped), `checkForUpdate({ installed, cacheFile, now, run })` (never throws) and `runLsRemote()` (`git ls-remote --tags` on the repo: no shell, `GIT_TERMINAL_PROMPT=0`, `GCM_INTERACTIVE=never`, SSH `BatchMode` when `GIT_SSH_COMMAND` is unset, `windowsHide`, killed at 10 s; git authenticates itself, the console never touches a credential). The answer, failures included, is cached for an hour in `~/.plan2code/console/update-check.json` (`UPDATE_CHECK_FILE`, in `PROTECTED_CONSOLE_FILES` so no sweep removes it). `server.mjs` starts it after the ready line and never awaits it; `stateFrame()` carries `update: { installed, latest }` only when a newer release exists (its `latest` is part of `haveKey()`, so a page that connected first still gets it), and `GET /version` returns `{ version, latest }`. Tests seed a fresh cached failure in every console home, so no test server reaches the network |
|
||||
| `public/chat.js` | the Quick question chat's PURE rules, shared by the server and the page: `CHAT_LIMIT` / `CHAT_MAX_CHARS` / `CHAT_MAX_ATTACHMENTS` (the combined image + document cap; `CHAT_MAX_IMAGES` is kept as an alias of it), `chatOffline()` (the server's `409 offline` guard), and the page's view model (`chatView`, `sendState`, `nextAbout`, `contextOptions`, `unreadDot` / `shouldChime`). Ask context is the `{ history, about }` model: `nextAbout()` records the last 3 places visited in `history` and sets `about` only when the person picks one from **+ Add context** (`contextOptions()` lists that history plus *This spec*); dropping it or a successful send clears it, so the page never attaches context on its own. Imports only `answers.js`, no module-scope DOM, so `node --test` covers it |
|
||||
@@ -218,6 +219,16 @@ Key design points:
|
||||
| `workspace-cursor.json` | `console.mjs` | the last workspace `version` handed to the agent; advanced after the print, never backwards |
|
||||
|
||||
The page changes the workspace only through five routes: `GET /workspace` (`?check=1` re-stats every folder first), `POST /workspace/add` (path resolved against `state.worktree`, `~` expanded, case-insensitive duplicate check on win32/darwin; `not-a-folder`, `duplicate`, `bad-name`, `name-taken` + `suggest`), `POST /workspace/edit`, `POST /workspace/remove` (the original folder refuses) and `POST /workspace/browse` (one picker at a time, 409 `busy`; 404 `no-picker` when `remote` is set or no picker exists; `PLAN2CODE_PICKER_ECHO` stands in for the dialog in tests). `stateFrame()` carries `workspace` (folders, `missing`, `remote`, the current launch's folder `issues`) and `meter` (`meterView()` over the ledger), and both files are on the 1s poll; it also carries an optional `update` once the boot-time release check (`update-check.mjs`) finds a newer release. The agent hears of the workspace through `open` output (`workspace: { folders, missing? }`, which also seeds the cursor) and then each change once, as `workspace: [...]` plus `Workspace: …` reply lines on `wait` exit 0 or `chat`; a change alone never ends a `wait` slice (`pendingWorkspace` on exit 10). `post` and `open --file` lift `run` and `folderIssue` out of the patch into the ledger, never into `state.json`; an unknown event or a malformed issue is exit 3. **Remembered workspaces.** `lib.mjs` keeps `~/.plan2code/console/workspaces.json` (`WORKSPACES_FILE`, under `PLAN2CODE_CONSOLE_HOME` in tests): `projects[<case-folded worktree>] = { path, project, specs: { "specs/<name>": … } }`, each entry `{ original: { name, description }, folders: [{ path, name, description, nested? }], at }`. `rememberedWorkspace()` answers spec, else project, else nothing; `initialWorkspace(worktree, entry)` builds from it, both in the server's first `workspaceNow()` and in `open`'s read-only `workspaceOnOpen()`, so they agree. `workspace.json` carries `scope` (the spec key or `""`). Every user change (`bumpWorkspace`, not `missing`/`found`) calls `rememberWorkspace()`. `setScope()` swaps the list, logging `removed`/`added`/`renamed`/`described` changes so the cursor stays truthful; `POST /workspace/scope { spec }` (the dashboard picker, on selection and before a launch) seeds an unsaved spec from the project's list, and `followSpecDir()` (state poll, boot) moves the scope to a posted `specDir`, saving the current list as an unsaved spec's. Two writers, each a read-modify-write of one key: the server and `console.mjs forget --spec` (Finalize Step 6). The contract is in `console.md` (Workspace; Posting an update → Session meter) and `building.md` (per-phase `run`), so the skill prompts stay unchanged.
|
||||
- **The Subagents switch is a standing instruction, injected only on change.** The page's icon button (`#btn-subagents`, after Write a brief) and `#subagents-modal` show only when the frame's `subagents` block says `offered && supported`. `offered` comes from `public/subagents.js`; `supported` means the latest `{ "type": "open" }` line in `events.ndjson` carries `caps: ["subagents"]` (`latestOpenCaps()`), so an older skill copy's `open` hides the button. Four places hold it, one writer each:
|
||||
|
||||
| File | Writer | Holds |
|
||||
|---|---|---|
|
||||
| `~/.plan2code/console/subagents.json` | `server.mjs` | per project folder → workflow: `{ on, instruction, max }`, `instruction: null` being the shipped default; on `PROTECTED_CONSOLE_FILES` |
|
||||
| `<session>/subagents-setting.json` | `server.mjs` | `{ workflow, on, instruction, max, revision }`: synced from the store at boot and on any workflow change (`syncSubagentSetting()`), `revision` bumped only by a real change |
|
||||
| `<session>/subagents-cursor.json` | `console.mjs` | `{ revision, state }`, the last block handed over; `open` resets it, and it moves only after the print |
|
||||
| `state.json` → `helpers` | `console.mjs post` | the helpers the agent reports, merged by `id`, checked by `checkHelpers()` plus the prose scan; dropped by `switchWorkflow()` on a dashboard hop |
|
||||
|
||||
`POST /subagents` (origin-checked; `400` `not-offered` / `bad` / `too-long` / `max`) saves the store and bumps the session setting. `consume()`, `cmdChat()`, `deliverChat()` and `open` append `blockFor()`'s lines last in `reply` and the `subagents` field; a change alone never ends a `wait` slice. The page's Subagents tab (before Ask) draws `state.helpers` through `helperRows()`. Helpers never reach the meter ledger. Contract: `console.md` → Standing instructions.
|
||||
- **The filesystem is the transport.** Sessions live in `~/.plan2code/console/sessions/<sid>/`, deliberately not under `specs/`, so the console cannot trip the metrics scraper or the loop's marker parser, and survives `git clean`. A result written after the agent dies is picked up by the next session.
|
||||
- **Attachments on notes and quick questions live in `<sid>/uploads/`**, never in the project: images as `<uuid>.jpg`, documents as `<uuid>.<ext>` with `ext` from `DOC_TYPES` in `answers.js` (text, code, PDF). The browser re-encodes images to JPEG and sends raw bytes to `POST /upload` as `image/jpeg`; documents go as-is as `application/octet-stream`, the extension taken by `docExt()` from the uncut `x-p2c-name`. `readRaw(req, limit, cb)` in `server.mjs` caps images at `MAX_BODY` (4 MB) and documents at `MAX_DOC_BYTES` (10 MB), and drains rather than destroys so the client gets its 413. Images need the `FF D8 FF` magic; documents pass `checkDocument()` in `lib.mjs` (`%PDF-` for PDF, strict UTF-8 with no NUL for text), else 415. The server names the file with `crypto.randomUUID()`. `GET /uploads/<id>.<ext>` serves images as `image/jpeg` and documents under a fixed type (`application/pdf`, else `text/plain`) with `nosniff` and, on text, CSP `sandbox` (a sandboxed PDF cannot open in the viewer), so a browser can show but never run one; `recordSubmitted()` writes every send's note onto its item as `sentNote { at, text, images, files }` (paths and names only), which `noteAwaiting()` in `answers.js` turns into the Sent box's attachment links and the Notes pane's pending note until the agent's next thread message; `DELETE /uploads/<id>.<ext>` takes any allowed extension; both stay contained under `uploads/`. `isOwnUpload()` returns the kind (`"image"` / `"file"` / `false`), and `attachmentsOk()` makes `/submit` comments and `/chat` messages carry images only in `images[]` and documents only in `files[]`, this session's uploads only, at most 5 together (`MAX_ATTACHMENTS`). A comment's `reply` gains one ` Image: <path> (<name>)` or ` File: <path> (<name>)` line per attachment, in attach order; a chat entry's lines come from `chatReplyLines()`, its images first, then its files. `sweepUploads()` bounds disk growth, and the session sweep removes the whole session a month after that. A note attachment a spec file cites is copied out first by `console.mjs keep` (`--session --upload --name --spec [--from]`): it checks both paths (the upload must sit under the session's `uploads/`, and the spec folder under `state.project`, real paths included, so a symlinked folder cannot carry the copy outside), copies with `COPYFILE_EXCL` and reuses an existing copy, prints `{ ok, path, link, image, reused }` with a forward-slash link relative to `--from`, and logs a `keep` event. It is the agent's hand, not the server's: it runs in the agent's shell only when the agent decides to cite a file, so the server still never writes into a project.
|
||||
- **Answers carry their terminal token.** Each item ships `fallbackText` and `token`, so a click resolves to the literal word the prompt already expects (`approved`, `a`, `skip`). No workflow needs a second code path, and declining the console degrades to prose with nothing lost.
|
||||
@@ -228,7 +239,7 @@ Key design points:
|
||||
- **The Quick question chat is a second, append-only channel beside the card slot.** The page's **Ask** tab (always last, every workflow, still there after a finish) posts to `POST /chat` (a message, or `{ reset: true }` for New conversation) and `POST /chat/decision` (Approve / Decline on an edit the agent proposed). The server is the only writer of `<sid>/chat.ndjson` (one JSON line per `message` / `decision` / `reset`, each with a `seq`; `appendChat()` in `lib.mjs`); `console.mjs` is the only writer of `<sid>/chat-cursor.json` (the last seq handed over, advanced only after printing) and of the agent's replies in `state.json` → `chat.replies` (merged by `id`, checked by `validateChat()`: real `re`, proposal paths outside the running `specs/<idea>/`). The server never writes chat into `state.json` — `post` read-modify-writes it under `withStateLock()` — and `stateFrame()` merges inbox and replies into the frame's `chat` block (`conversation`, `messages`, `typed`, `limit`, `offline`) in memory. `/chat` never checks `pendingResult()`, so neither channel can block the other. `wait` keeps its exit codes 0/10/20/30: exit 0 gains `chat` (or is `type: "chat"` with no actions), and the instant `console.mjs chat` answers 0/10/20 without touching `result.json`, which builds run after every task. Guards: 10 typed messages per conversation (`409 limit`), 4,000 characters (`400 too-long`), own uploads only, of the right kind (`400 image`, `400 file`), `409 offline` when `chatOffline()` says no agent is there, `409 stale` for an old conversation. A hop through the dashboard (checked on every state change and at server start, so a restart still sees it) appends a `reset` and starts a new conversation. A lone reset never ends a `wait` slice (`deliverableChat()`); it rides along with the next message.
|
||||
- **`validate()` in `lib.mjs` enforces four workflow rules mechanically**: max three open required questions, no internal vocabulary in a title, one recommended option, and no loop markers or metrics-scraper bait.
|
||||
- **The palette is written twice for dark, and that duplication is the mechanism.** `@media (prefers-color-scheme: dark) :root:not([data-theme="light"])` follows the system; `:root[data-theme="dark"]` is the explicit choice from the colors panel. Drop the `:not()` and a system-dark browser overrides someone who asked for light. A chosen accent is applied as an inline custom property on `:root` (CSSOM, which the CSP allows), and the default is applied by REMOVING that override so the stylesheet's own per-theme values win. The server's `data-looks-accent` stand-in only lasts until `applyLooks()` runs, which removes it first thing — left on, its rule would beat "Back to default".
|
||||
- **Help is in the page, built on first open.** The **?** button (`#btn-about`) opens `<dialog id="help-modal">`, which replaced the old "What this page is" About dialog. Its 16 panels and their icon sheet are hand-written HTML and SVG in `<template id="help-content">` in `index.html` (after `#start-poses`), cloned into `#help-panels` the first time **?** is pressed, so first load builds nothing and Help still reads fully once the server is gone. `help.js` supplies the tab list and rules, `app.js` the wiring (tab buttons, roving focus, `renderAbout()` for the live connection line on tab 1, `lightDismiss()`, and a Ctrl/⌘+Enter guard scoped to this dialog). SVG is styled by class and CSS variables only — a `style=` attribute is dropped by the CSP, and a test fails on one — and every number the prose quotes sits in a `data-fact` span a test checks against the constant it comes from.
|
||||
- **Help is in the page, built on first open.** The **?** button (`#btn-about`) opens `<dialog id="help-modal">`, which replaced the old "What this page is" About dialog. Its 17 panels and their icon sheet are hand-written HTML and SVG in `<template id="help-content">` in `index.html` (after `#start-poses`), cloned into `#help-panels` the first time **?** is pressed, so first load builds nothing and Help still reads fully once the server is gone. `help.js` supplies the tab list and rules, `app.js` the wiring (tab buttons, roving focus, `renderAbout()` for the live connection line on tab 1, `lightDismiss()`, and a Ctrl/⌘+Enter guard scoped to this dialog). SVG is styled by class and CSS variables only — a `style=` attribute is dropped by the CSP, and a test fails on one — and every number the prose quotes sits in a `data-fact` span a test checks against the constant it comes from.
|
||||
- **Markdown is rendered to DOM nodes, never to an HTML string** (`public/render.js`), so agent-authored text that quotes a hostile source cannot execute. Only `marked.lexer()` is used.
|
||||
|
||||
Tests: `npm test` runs, in order, `validate-char-count.js`, `install.js --verify-skills`, `parse-check.mjs`, `check-skill-table.mjs`, then `node --test scripts/test-web-console.mjs scripts/test-launcher.mjs scripts/test-skill-scripts.mjs scripts/test-script-pathfinder.mjs scripts/test-script-finalize.mjs scripts/test-script-handoff.mjs`. The parse check exists because `node --check` parses a `.js` file as a CommonJS script and has already let a browser-fatal string literal through; it imports each shipped module as a real ES module instead. They live in `scripts/`, not `src/web-console/`, because everything under the latter ships into every skill.
|
||||
|
||||
@@ -1 +1 @@
|
||||
U0VOQwGE6gnFffEC/Dv8DbPj9gXzCNp4DSPL7X9/2NPC3i0bN8rPSi2rJ11aKFhGw6Y5eM6b8K4kShUQWLdEM2KSSBwkW90P18Xqv/W+ffeHPf+f+M9uYFheUeHqI9UytwiDNsnurdFtB69qGIlx2svo0CgoWmOPGloXxZckNqzgJsvukbIsLOfDtP/eFYRtzctXOwYLPwQ7uxwpQ7vbgxEp+fomem4tNPh2VdRuFXWdQ6XCVUjilAGMx7JCdAtvfYTkAnws1DDIcR5q9rMF/TJNWIJwMoQqs/FGCuPbGfAvX1jINqkY09ez8As+lGDeL3a45KPubcYNHSXHob0RLartkHfBoUDlTxP45rGpY1cwrnBmydDXpNLWo/+NtV+KeDKgLYtEndbuUIIV2V4zRJRLsdSaybrwkMNDxihXMFaUDE/ebezvBYcf+5UcxsH6WIaEGLn/LvwQxjZaLFHTF1tCHz6U15dJYKB0IwGU1eebt9slJM49c3Y213mPAvhiJkZhRispeExo+cvdTCxQzciUr8+vy+/5h+30ZYpeRGVP072uQYgmS3UIMDbcJNGhrHaES1SPB2YI934unEVNvwNZtOKsDuT18d7DI9nzLaOORWXd6F4xv7r+/sNzRz1IUhVQ9gNUejKJd6G92SyBvepevX+DCGFNuR2aE3cMmfzgxAK+/Nsmt0aMaSf5GwNX4xG1uAHMPyopYfLHvvMrQ6HiZDk0lcxoHclqRMgLQ/fdMFUtbOOSRArwE/aHPbwHE45JSKWZZHkU1JGQtUmPSAH55lpxukSt3gfnl0DZY0ApCQAcMTUE6HNSWRdeXROXCJc6UibjrlU4mBjbb6RDGQfs6X4NZ2WSuX7Gj0W35z7++LCqZ7cYRmIYXweaJc2rxnmZim0bUnJkzCjAS3sfUMakTFlJIzDnxZRhKGWsPukyl39axdQ6zTjj5hAkqTnlajNU7flHHXe80rwNzWlNhOERRB6su2wyrHcI8rgLFmVfSivQ9zw00wi5soqXjaYgGoXDxkzd9+vtMScfXcdJl5LtEWUrvKcP/Q+FpMnxf66SnpwOEHYL61ciAMw3zggJvAo9xyd9g9DySbaRgqVZBGPEI7+s7bTSLWv4lXcgIwAnFFchvK2wKxb+r5Dn6lcZPghWuLBYHhnloPmheCog5go19ANK9ik3xjmo8PFNUxdGPGTS/QCmYzrPpPhyCi5m41kYupPoPbH3gcTCQhQwQJ/A/nS9qnr9CkDsRXD4gpjEyRaMx0Ad3xxQ/aQFnZzqjo0RwpKs4L6qbXBJRRoZAMtXL+J3vLh9EBUfWig71poLLIDzsGS2m3D71ggPQBFlxxelv80IJ9MgEtFga9CWc/NsLark8dTzZyZnOOzvT0ikxzuY5tadrXiVZbunTNP+Alzf6mNPIuTZT1FGC7S3deLQz8i0mqGFRV9JIFzq1/Z3HkmK5HVWrRHZXCkcyueeF++N5rCHnIVJEsXLKLhr4e7OBLEIq38qv4b3NmTP46WvgGOeuGbNRhfHbh1+vfk2buGqdS7hdgNBTaNpaEaOsO3Uhq1y4HFN73861mlLUF0xr5GYCLjoQIleD0RiPF3oNw0GdOfJGmRXzV/u//XSU9DYi3yjyv+aqA5XoWduBFS6dBUDQN4k006ThqpOAMu8tXNvGQVsLv/ORifyWyZYfJFxkG3uB4qiAr1sMNhpzWlhOlb2JjrraRzQeHF9bp/DfrE5LcjMPl4XbhbcvxgyLtWAHjZRWjeglmJFdWXhgynMfyn2Zt4AShRY8Ou9CMOO/iy+ddiREje4ExLrl7bq6hboPi3BDuX95QPRKEBbtCwoLikTK5nDP43CaIGDpMu/i03f05UrGC6NNqblidP29XvCKXpY3ZqoX3yVG5p4nstRbtr+sacqKl0JguXwiG0xMEDS3VVnYkV0W+Kk/H0HkT2MfsJr6ppqjWY1l8mzmoqLkC9YluOskzEc7bWOmUOi7vbbghheQDmT0YmNFIJ+eqz4raXW2SkyTCQZKZuGlmrn7o6ApXamwzpacjYxe7/72xvMPUBWYYmwMRpK745ebNwVihtnks6cn/XWFKUz0wtrWSUYY+tEU/qrOQ7L8gznM53p0mjkVeWRMzqnBydwOdBPkjHtLU784u4BSTm3PgglLYJBM9jfSMFBh79srn99J7GqyBaT2QDZE/PNwOybcd+ap+l2jDV442UuqWSwMEV8xs5v/Bk/5kDnW7A2bN0xI6rdpfibJLs3c9i8M0+XM1yNlesPJAR5nDA/v19sP+wKYZSMO5jIrQLLCKA3Tsq07ujeAbOd62wGIJU4vjHfHAO8I2Hw38HbAM2SVzG6g8zMzEqm36Rl027Fdons3EBwqtMJ6hrx3nHvR96JOwJ866KmlPqT+vjoCh+2HYNLmsS4ipzAUkMYqVnPvnGICDPXX/WkL+0buKXu70jcaW+5Mys/ke41/IH8OJUf6ztLKclO4bBwtfUfE0vxXotj+6x8QNBEsdZl+OHXYemQ+fKd7jhqSTarJRx+cYtwOSUVzEWDxDt+zUp4EF06hfW5kyeY/0OW2t36rx9VULfG78ELo/zH2TXWQWgS2wEdmeXYJ5lzDtPW+XFxSRnYxr+qpceFXAVeMas9sFyG0hG8ey6pth6dPudgcD3fvfzobzaLtMgHiuCSEwHwwQptQ/YprDc2MV20UDW2IlG1yS9D3WgDuRBgQafJegjsDAPFvcpuBwf5JFdFRVBTEUv85GqZ91MNME2vPgo46amuNK3+OerpBitXChDDIw5RCcHIGdXu1+xqshgxvv0xahqRzYRmZr0mLg0jHoSYD3dyzX00//0ApefiRkKgw0yWfgJywQabrXv/NPrgaaK5+d6bwl7BnBAJfNHCDJ5R5CdbWRdkTw1XhD2QADZtURJ9yvnUDX1G2ftLZ/hmnlXGu1Kyin4snhMsnxwhX7mTaFUanY4u9QOGU+jUzbDqqDCHOfPWNDXYhaz4igr34MtAry+PM1LUHIV4UKM6ckI7q2k82LrG1UzfzjDUqtaXaTMeNEI72Gj8D+/jQPfFZeWvO3zvFYlRjSSGy3oIJnXz54TJLb2vpxFvjPDoQZ51V4VZm480b41f3EoX+iWC3Qejf6H0AGut+TSiO7mDStG9MqNApYS0DFubDokwvHNouZRRA2N5RMAnRkYWrLmvZ2MyVPpyU4SS5uiXY2EaV2Ld3RTmf3vGH3vR8I6fzcmcgGw0pkaTqeH/Z0p1Tn1hH9MqfEWMdFCCtOCZm2D9xa/OYI/0ZjkXQxYLjcPhZkMX7XyU/vuuhGkrPbAOWfO03qwx6b/1LCbXa3nM4zgdLR4oBc0wm2q1oHN2ahTT1G2kTxAqz+zeAn7WI2g7Di6X0lJ1b131MmO8Y9fgmXTiSO6FXmMQmddr6JaBHPl/0oUdA3+/m2smVuYuxtBhYVV4BlDRexfd5vm+fnqY1A3tAKJnI0cMzy86idcAIjnobpcJmnqwmIQ3rJGvz5+azOLPtckxeTyaoe2654lU4OBT3k2+tm+vYVJPDSobCrsxWIht1ij0Z6NvLjjy+yx+EYgNLNFPZ4Q1xEb0MYH3R4dyCC7zAlzzzxiofey1hZGvplsttyYlZVhKOuMuZbCtUmj90p6k85UeDhme+c6qVdz/hUhbnd8Lo4acV1HIWoj794XnsOSKME5ITGK8tx692eEbc9C+zEbycZ+u9zAcFhL8+5H1F0R4H+ByLArSHp48oEupL3fye4uBXH+m1cMXlc8lE0UzzD9lICvKWNlCyWfhSD8CVGtshVu7hwhRbgJUvkzxNSyhDhvk3x6XZtifBH6dYekmWJrjSPOWFjAJe349/fALLPJRobmyDywS0pZ/tWaGlezfI6q18w8ldvJulRn36rr7yQonNq8QZbtvj24QnIWgBoAEW4l3w+0TDcJsmKSQ7tg0oGfmgtcpULH8gry01h50abpI17enIY7UVt1+gvJKAg2Foyt4S+v0yBMZWA7C7VCh0LZJmHbHmR6qkB90McDyq/zp3Bc5PqVFaltyujbZP8XMN3pM9714hyqhA0F37ox2m7moIRB1XflyIB3D1tOUvLE16djurt6ew8GzeFDIMqph+h97Ufb8pgfVCzBfatCG0iDwBe2ETEkNLwRUDN/uVwl0Pr6pbILVEaOAS1xPebIK89eDaX6mlS/m0aWWaqt/xGncGPTVlSNWn6V9sB2WVgGz1IJqS2i0A/YwA0Qi6dW37BpS2rpQdD2BHniImTeSMQe6oJDZSOBf3iAAZnExl8PcAgEB/Dwc+RrQUHYtSIk5BJCtTFjEXcY/08lUix9C3o0uIGRIDTdTwN4smBokFawcSo3OPjFAiPZcLU0K0ppfpF7/AkWqYIV5weLd9ElFT6ajcNjdqm2PXrhtEu72TmiKKfioZHfanlB3PUjsOPm1+s7X5AwWWhJerScXfHpFPhX4GFBPe3GVGbZ6yWfpG4rjd166HBDFbRbRB0Pbe+AiQNJHBLcErss6mTOVMdy2uAKVyHStKWRPR1cMHy/pcLKsxYRKtBu4I0KWcdHLMtZ02f4wbapiKVAn2W8tN8J/m7f7yBvvrHFdj3eOlE6F8LBVtMNL3A5kCKQa4BBhMF0gmmWc/idHKLPu73hELAHmr4uI37ehgX5prXfB/wJ6jqPH+nu5El5MGGy8SYAQrQDL6tzooXqQoSO1txwMeCY/KTRMXAGdWLJGUiXzXLykZrEx6b3WvHhC9PcN7JGGmNgZ6oXNCzDPnan4UDfFyMW/PGFgoUBptZ2rLbkjeBVe/GQ9xTOuiOVcr1CpVPGv4FQCeKQmeH+08R7zTvuQA9iqngLE0o3g0WLioaMYVBkKFva3xw0TOPMv7Sj+NGPqeilr6QkcoVSxxf3H+wVBTPJForIutmbCOjvsrms7Vo6yaALIfeE4P9QvBthQ1lI52GbtvUhxSmUv7OZcw/QgYWg4R+MKkZxp8/Ombst1wUjIqraX2hac7iwdk81uroMLine truncated
|
||||
U0VOQwGovNAVPqFDBN7eYOJY9w4zdSme1IrzeoWpGr74/61wgcKXcBdLKhgz5v9A4iFBOH90m/q36/c3xcd/+gsiMk7U8iGD/O4kK/99yyoscIj2AvtuHV16jFqjWQGo5H0imPwjYeDJKh22S4+jL3bidIt6A2LVSNK3cevIoQl4T8Bg8ts5dkSlTbcP9ztChqSgxuGfZsETKK+eAhvgHZ+rIIkvdjMTM0oufKScatRRW/gaKHGYMdaw6fHyLr9u+lY/XJ9b1LwQnpAT6Yjj4lEOJ84h9o85RY6jLmubDHEUl6fuCMi9HD0PTzPC2s/Pni5ksX0Pw+WX3ZzfBqywuLvdEruH5DKSgktekRirr+9bSBVRdhV2YIeKZ+wsJjGG/LXSTySktAUYT9FCgO+wXX/knTzQy2zZZ07j/jcWPOeXdQ4yhhS60qHhVtvZixJG/i0Q07Vv+hSdfo8Uv4/nPyWctf2nrFEyYBHPQhLT4xWTbL86VSCnB+sCca+5xs0NkKWy6SJLp0LYDS483Bi+gIa/ZSDE8soFepIyoprNmOsNFOMjScpdZAb8Gv/7/Sc1giCS4SaIq4o8QWNxqxdxaE68IiDbKdpOcMv80s73scf8gFzIBoXL+Ta5UnhRBcOwZvNEOCEoFy18LpCwzZc3xmfhUoevaZaMsPcr/yao3tWe36zSlroaiM3A4d5Dx6qDFAlkaHllaYsGnCVlEXxVx9yMBbiFNpmy+MX5NqVT2xRYQ+FUcMhLykvFgud7HbTlFlIW4N8PEmpNWvcmG5FhOipmSUAxawmmVaEnqnsSG3ygLFgWIl3giIApGRxgH1OAUSFBxRmq5fpvYCyBrgT+I+pqKAHaOlTFCwPdaceYBqQey3kEBHe0mfbpJjxnoYpJm42Zi8ecPqkohQZ0VGPscePZ+IpoiliaNmiyIXk1AqlD7Gh9EEscuti9DHfpDbgUpCEsfeChMKjwAW8yFOia8JaaX0pfD/POZ6RU4vcM6BJppn9LLlb+7gU5hGsl8ZjT29UUcuBoU5EF6DxhOXdWmto3BYsOm+vD803xDmKKgk2x/VeHsfBezV9cusZdsja4hyd9nPMwH6qaGnkKdEkArp1mq6XNlQLw331tqEHRWiX/gWtQ31nJUhZEWgt5ewwezRQgZAE+gRjaNy9Eia/df8HEV9VNyNeUmbd3FkryB0fI/HgpIppVPt4ZIAB6KU2JSShBL5Iow3qYEvTkfYzyYZcMAsC9EQ4CpKf9m63UMPtw+NPkzvsFM+5052BiL1qmKdpCxecIeelkOOtXOKUFUg5EVqQIgZXrEHPtvERUrAFitrbowrD9ZdWiGRGAS3uZ/33l0fN/c5raZeZFdW1dZbmqAURsZdocBC0fsTQQnn/0OraSzrDJgBzyi2YAEN6+lTPoronbddrBKEOEify1XS8MXyuuJTadbyo+/4YqiyaWLglmyFsl9GHN0WMH5WFi6rjyE7+0IIKJ3i/x+rf081QiA/i+AYY9NKwtzITYJL+EHHr3+G8MzMmAnhhBkXH7yCTMAlpWLo0kX3X7z0+ne/THieIaAAYfnvsUHwolJFCfcl+OTVFhBrHblgqYu7QHuWd5Gc6iOL0LsBwnYUCritFSsAepEeFENOLkunWK7xaXtl/fIxvWGrLgjHxyok1u4iQi3HQdMeTxu29zJiLCIbAJHkNXc93/A4D+zOkZAeRKw5Wg5DVfvU4E4soiPs0j65u99E7rZhi7vsn4usTCD76Ya+nha9it6/xgnWe6h0Xh3wgGXFnJ48OlVf63k2Qyz601KqF7wPJJuYsoKt6HIwqeVWHwdsFIDyrhwcPOaJgfuS27Id0pGCtrHQ0x2zg8cbnvzdcwgy84tw7G8wQZxorqHfwYmmMJTcwi63p/OqF8iBtV38cMBplCOfIA3GMX3vHeh7N2oFbF3jg/aVI92DYsja24YqUOcMawFZlSVZxh3mmM1IHoub9E6Hf/1A5JoxeOjgRg7qFnam2oSSaQhYltx3hvj/USvuoftwm8ZPJuZGgaRdOBkTe8guCNo6Jan1jT1e/M/mnEsz3/wIrh1i2VQJ0exO0I8F+YNikm3JQBVyzdMxzYqA+IwH2YVU9G3kZitgBV3FMAOZcWEW8BTZUjtaac4Op7KrI9Y74CKEKrQbQR0R+mi5dm6aI0iiXz/0Upq+Bd28vuQljG5mygL0/ODObBj2imOsVn7z0Q4oGA3PLvh7haXEVo9Dr2+9Ishu0dsGp4K5seu5ujjhykYpN9PCTGUIYnMGImH38hluI5Y8rFlJJLYbU+DjGcOQpCmvuwGbOmexwZ/xkH9d+6+C+q1wv/hpsCZGzHiLoT0/WjB06mayDxOIBP5PZV4tzx2hFK+IuPaub/d0LcCHmw2BzcJ85WajYl9G9pKCkDWg5sDIdnqP4QNWVVxIV6N75/gGDmpT3oOEx8c3eUGMT0usz9mlgPBIPP8ZkTD69P2T9t8BLCUtM+sgGWZDBPxzRkdVjcLWHI/7r3DwsWW8eovZuBrjGorzNYR9QIYlEpAYQRZdiz2JQ0mXlT0Si/KexXT8SPMywa0eEp5DqWAzZcYo5g5OAsB7xriOzoRBXcwkXPxx1V9V9aHMguAAQ+yHQohVjquQhL+dWIzR95hC/7vIctKm9UfrTWn1xdYRl7n3UHAXERKxGdMR96i4pJbrWLRbRkSvJZZ1fxvGCf2MaQCLOgTD33pVpxJWc65QW62ugnF2R4UdJcFiC/Lk6d2rrrsYZKzwy5j6Sv647V+oHAASlpB6/9lVRUQpgqKLKIixFCeuq5R78qFA5iA7PkEwK2gXJGrBO+Mcs1EPHj6f9sXgiAjhjYCOTdyHi0+9VP326TULJqEL5AxqUThYBqsMz0/rQoE58IxSJ45M8863sKuFkWHXvqJ/HutFv/7GfFSec7KIr0Mr8g5dkrfzSso766KpmSKDXgJM5L/7/GkDHcZIccA4/xD+eOzel8cnKztecp1+NwiablsGCJy/nXMFrhlAkvXoHWyEuAS13TM4omGrBWxgLRFsqL3V1d6sRrQfd4fUIeIr+VIdOblPRbVGqECMhfZVf1olh++wQT8Iy7Gniekz9YMejGFJmopIk04lFLHdxg85bGP51wVcb1xVAWxkp55/4nPmMJ/XpP/2qYDVGIqnuT0GxF/KHk/Ts9Ddo9IDDlw5kAeIDNVGBOVUlYK802MU8b33y+BBX8WlEfFxYhgh7u7Tzckc/NivJuPknMYTAPCxD7UzsdS80ZtOcmuwBP10/4M6xzV8ZTnK8Pb7Wmp2lCnvhrOElGcztEeN6he9Bxb1JftVPQ1QYkEOce9WZB/pKwBwkktKrsyMO0svFpUdMWDXYoNyqc9R+/4Woum7FB2H+6p2sqODSYfZqjnirrBjUOD1YV19Q4+ccTfk7ofmLaNGP+K/cZaZn0EOMSKLPh6exbc/QreoJdGWmCwMNk9W0T83m+iZXb69whaxPJNPJfOroXDrnc46YDr5Kt7+tjZUS1TpzeDL5h+pj1TelC3kW3e//wtuDYnvJIBXrxbeoZUrz6On1UoQDqcymNSZUQwPNE7nWXNFSuvniQ1M7ScnuMyheJvb18rkTzJhkPRGvkCb6ash4f58bmm9otN5TQucKldyzxsicMt1AORUvvFRrrGNZVNjAbXwNm67z8oyVmvxyhXmBrEdpnEUH+h+6W9wc4v88b45eagxTb60aF6ROz/LZPhEBdOKSy1Njk/i+NZ/axD2aKCqD2T3BUiz+1P1abrYemivzWiUFEv2/Djuc9+q/Zwp8rJbMuFkrn04Zk5L4i+PwfjPTSYLxePEKdlEqV+KPqnkGTFbXIUxfeKUoC0RUV5XIugjeAeQQk1HufY1v8hrPNP1+MB78QBEW5bIrlfIZGLx0gZTjky6/k9PJBxKij9J3iIpr7Lk1Qellat/Jr7PZzkknNhvrIw+xCfx2hWEdn0yXZRnPB86GPIrwJdBDrmYBB9w0BClrchACJnHSW722P/b8CFtvUQY9/51a60q4Vgvfcq6QXoEty8XNpvUSFRJqjww44zuYbdgID4sb3MlgPr4WqdfDpL7z2vhGkOYYL+4LCI/U+TazHMXVw4wQ2YI3/EXLJgN0PDKTehMSP/QPVsv4F52T1A1sCAAT3JVv3FGtSBMZxhujOdMqbleFrEHF4f0dBhB0GbaONFv0L3CjweUW40KxpxGTUizeBFWWz7UW+B6GFfkuS8D8n7hY0/K7yDTNLI263v918fm/ER36cmBHPR1GWcMe+yo8o7paC4UBN7PSxhuYK3DFElrGNUY4tV9NK1FWfm85TPB+eAJn4UtNzzzdS4j6TgFwu4kkojqhktczKUYccLfDT+THij7ju4SPeoF5yMXmOwNtsgcxtN+hu5Iq/WiJzBWfuulyCoL8mkXk9D1JivLC2MxxzJA5qOhFu9NHgCw3nB7KIGm4lnsVkiXPQYwQD5/eKG6Kw3MbcNYkJ0ZWxYn/iR8D1OcNw7X5T5GTumT4VWHxyShVdbc1iEzAk6HZ7baKZH0qejB7f2JhdnpwHxTKGRFJ9irxnvAqpxq1ezxT/7yl/8GRmBEH/NFvW+FeOJwjl15Syi46NDK1XZb4m1Z0XJ5tTpJaIj15KtJ0cDJQKzcENSIbitFtd8MFmv+EPIXHeZe+/9Nmhd84pZLlEygLNbywYNLQXmg3xBG/WtF8geQN7kEQJZn0yTGSssZYw+g/6gHgTPAW9CoACZZgGZ512gyXrIAI8q3e+5dBS6rwJ0xeb6eoDqBqiJVlpOWqV4LDpFt0gDuGtwZJNFREsL5Bs+FuXo6FE41OUwD91dcRq7OFaGQ+0rZybRkBiQqcelNRX//BkwLZBfx9Ts+gPxQjS0/7ahpI1a1taOeyTequCFL+C4p0xumh3Iqg1ijyG0X7cWIbAuFt2By/jrM5tvZilA490yITU23wRnmtpcZui4MEeRq1oRUCYVyRD2N4fL0Ld55tAh6estfA+8qTzKI+Line truncated
|
||||
+32
-2
@@ -153,7 +153,7 @@ it opens on the page without asking.
|
||||
states differ by pattern, not only color). A finished session goes back to
|
||||
the plain icon, so a console left in a background tab can be checked at a
|
||||
glance.
|
||||
- **Help.** The **?** at the top right opens a Help dialog with 16 topics,
|
||||
- **Help.** The **?** at the top right opens a Help dialog with 17 topics,
|
||||
one per tab down the left (across the top on a narrow window), opening on
|
||||
the one for where you are. It is part of the page itself, so it still reads
|
||||
fully when the page has lost its program.
|
||||
@@ -339,6 +339,33 @@ it is remembered for next time:
|
||||
the spec's list and runs `console.mjs forget --spec specs/<name>` after the
|
||||
move.
|
||||
|
||||
### Subagents
|
||||
|
||||
On a build (Implement, Implement + review, Quick task), a review and
|
||||
Pathfinder, the agent can hand independent pieces of work to helpers
|
||||
(subagents) while it keeps the conversation with you.
|
||||
|
||||
- **The button.** An icon in the top bar, after Stop session (and Write a
|
||||
brief on Pathfinder): one larger node linked to three smaller ones, lit in
|
||||
your highlight color while helpers are on. It shows only on those skills,
|
||||
and only when the skill's copy of the console can pass the setting on.
|
||||
- **The dialog.** A click opens it; the button never switches anything by
|
||||
itself. **Use helpers** or **Work alone**, the instruction the agent follows
|
||||
(**Reset to default** puts the shipped one back), and how many helpers may
|
||||
run at once (1 to 20; your agent's own limit still applies). **Save** sends
|
||||
it; the agent hears of it at its next check-in, as a setting, not as
|
||||
something you typed.
|
||||
- **Saved per project and per skill**, off by default, in
|
||||
`~/.plan2code/console/subagents.json`. The next session of the same skill
|
||||
in the same folder starts the same way.
|
||||
- **The Subagents tab.** With the first helper the agent reports, a tab
|
||||
appears before Ask: one row per helper with what it was asked and whether it
|
||||
is running, done or failed, plus a one-line result at the end. Rows change at
|
||||
the agent's check-ins, not live. *Working alone* means your agent has no way
|
||||
to start helpers here. The tab clears when you go back to the dashboard.
|
||||
- **Pathfinder's research** always uses helpers, whatever the switch says, and
|
||||
they show in the tab too.
|
||||
|
||||
### Session meter
|
||||
|
||||
A small ring pill in the top bar — **Session: fresh** (green), **Session:
|
||||
@@ -621,6 +648,8 @@ exception being the note attachments the agent keeps for a spec, above):
|
||||
| `~/.plan2code/console/sessions/<id>/workspace.json`, `ledger.ndjson`, `workspace-cursor.json` | the workspace's folders (paths, names, descriptions — never their contents), the session meter's events, and how far the agent has been told of workspace changes. Kept beside the session, so they outlive every dashboard hop | with the session |
|
||||
| `~/.plan2code/console/sessions/<id>/uploads/` | images and documents attached to notes and quick questions | 30 days after the session was last touched |
|
||||
| `~/.plan2code/console/looks.json` | your role, theme, colors, sounds and card width | always |
|
||||
| `~/.plan2code/console/subagents.json` | your Subagents switch, instruction and limit, per project folder and skill | always |
|
||||
| `~/.plan2code/console/sessions/<id>/subagents-setting.json`, `subagents-cursor.json` | this session's copy of the switch, and how far the agent has been told of it | with the session |
|
||||
| your system temp directory | the port, process id and session token | until reboot |
|
||||
|
||||
Each of the workspace and meter files has exactly one writer: the server owns
|
||||
@@ -646,7 +675,7 @@ never the record, `specs/` in your project is.
|
||||
clean up** lists, with sizes, everything in `~/.plan2code/` that is not
|
||||
needed: sessions untouched for 30 days (never the one you are in), anything at
|
||||
the top of `~/.plan2code/console/` other than `sessions/`, `looks.json`,
|
||||
`workspaces.json`, `console-dir` and `update-check.json`, and anything at the top of `~/.plan2code/` other than
|
||||
`workspaces.json`, `subagents.json`, `console-dir` and `update-check.json`, and anything at the top of `~/.plan2code/` other than
|
||||
`console/`, `bin/`, `launcher.json` and `models.json`. A stray is listed once
|
||||
it has sat untouched for an hour, so a lock or temp file another session is
|
||||
writing right now is never caught. **Delete these** removes
|
||||
@@ -701,6 +730,7 @@ origin.
|
||||
| `POST /workspace/edit` | `{ id, name?, description? }`. Renames or re-describes one folder: 400 `bad-name` / `name-taken`, 404 `unknown`. |
|
||||
| `POST /workspace/remove` | `{ id }`. 400 `original` for the folder the session started in, 404 `unknown`. |
|
||||
| `POST /workspace/browse` | Opens the system folder picker and answers `{ path }` or `{ cancelled: true }`; never adds anything itself. 409 `busy` while one is open, 404 `no-picker` when the session looks remote or no picker exists. |
|
||||
| `POST /subagents` | `{ on, instruction, max }` (`instruction: null` for the shipped default). Saves the switch for this project and skill and answers `{ ok, setting }`; 400 `not-offered` on a skill without the switch, `bad`, `too-long` (over 2,000 characters) or `max` (outside 1 to 20). |
|
||||
|
||||
## For maintainers
|
||||
|
||||
|
||||
@@ -40,7 +40,7 @@ Details: [Architecture](./.agents-docs/AGENTS-architecture.md) (see Status Line
|
||||
|
||||
## Web Console
|
||||
|
||||
Optional local browser UI (`src/web-console/`, zero dependencies, detached `node` server on `127.0.0.1`) bundled into every skill via `additionalReferences`. The bare `plan2code` skill opens its dashboard, a card menu that launches any skill in the same session. Pages cover questions, sign-off gates (with an in-page code review), build progress, the living document, an **Ask** chat, a read-only **Workspace** of extra folders (remembered per folder and spec in `~/.plan2code/console/workspaces.json`), a session meter, a built-in 16-topic Help, a first-run Welcome, User Preferences (gear) and a bug/idea link to GitHub issues. The agent-facing contract is `console.md` / `building.md`; the server never writes into a project.
|
||||
Optional local browser UI (`src/web-console/`, zero dependencies, detached `node` server on `127.0.0.1`) bundled into every skill via `additionalReferences`. The bare `plan2code` skill opens its dashboard, a card menu that launches any skill in the same session. Pages cover questions, sign-off gates (with an in-page code review), build progress, the living document, an **Ask** chat, a read-only **Workspace** of extra folders (remembered per folder and spec in `~/.plan2code/console/workspaces.json`), a session meter, a built-in 17-topic Help, a first-run Welcome, User Preferences (gear) and a bug/idea link to GitHub issues. On opted-in skills (builds, review, Pathfinder) a **Subagents** button in the top bar turns helpers on or off per project and skill (off by default, saved in `~/.plan2code/console/subagents.json`); the agent hears of it as a standing instruction only when it changes, and reports its helpers in a **Subagents** tab beside Ask (contract in `console.md` → Standing instructions). The agent-facing contract is `console.md` / `building.md`; the server never writes into a project.
|
||||
|
||||
Details: [Architecture](./.agents-docs/AGENTS-architecture.md) (see Web Console section) and [.readme/web-console.md](./.readme/web-console.md)
|
||||
|
||||
|
||||
@@ -2,6 +2,20 @@
|
||||
|
||||
All notable changes to Plan2Code will be documented in this file.
|
||||
|
||||
## v2.5.0
|
||||
|
||||
### ✨ Added
|
||||
|
||||
- **web-console**: a **Subagents** switch for the skills that can hand work to helpers (Implement, Implement + review, Quick task, Review, Pathfinder). An icon button after Write a brief, lit while helpers are on, opens a **Subagents** dialog: **Use helpers** or **Work alone**, an editable instruction with **Reset to default**, and an advisory "at most N at once" (1 to 20). It is off by default and saved per project folder and skill in `~/.plan2code/console/subagents.json` (`POST /subagents`, on Cleanup's keep-list). The button shows only when the skill opts in (`public/subagents.js`) and the agent's console copy reported support (`caps: ["subagents"]` on its `open` event), so an older skill copy never shows a switch it cannot serve.
|
||||
- **web-console**: the switch reaches the agent as a standing instruction, and only when it changes. `wait` exit 0, `chat` and `open` carry a `subagents` field and `Subagents: on (revision N)` lines last in `reply`. A higher revision replaces a lower one, "off" goes only to an agent that was told "on", and a resume or dashboard launch with the switch on states it once. The per-session cursor moves only after the print, so a killed `wait` repeats a change rather than losing it. Contract: `console.md` → Standing instructions; `building.md` points at it.
|
||||
- **web-console**: a **Subagents** tab before Ask, from the first helper the agent reports through `post` (`helpers: [{ id, title, ask, state, result? }]`, merged by `id`, or one `{ id: "alone", alone: true }` entry when it has no way to start helpers). One row per helper with its ask, a Running / Done / Failed pill and a one-line result. It clears on a dashboard hop, and helper reports add no session meter points. `validate()` refuses malformed entries with exit 3 (house rule 8). Help gains a 17th topic, **Helpers (subagents)**.
|
||||
|
||||
### 🔧 Changed
|
||||
|
||||
- **review**: run on its own with nothing named (no argument, no conversation work, not from a build's review button), `plan2code-review` no longer assumes the branch diff. It does a quick scan (branch changes, uncommitted changes, specs) and asks what to review, each option with its size; on the web console that is the first scope question, a `choice`. A build's review keeps its already-decided scope.
|
||||
- **web-console**: `post` and `open --file` refuse a patch that sends a doc a lower `version` than the page already holds (exit 3, naming the doc and both versions; house rule 9). A version going back is almost always a stale or copied payload, which the page would otherwise show quietly under the new run's name. `building.md` now says a later phase in the same session continues `phase`, `phasefile`, `report` and `review` from the version the page holds instead of restarting at 1.
|
||||
- **web-console**: the project name in the footer's `<project> · <branch>` label now shows in your highlight color, and the browser tab title starts with it (`<project> · <title> · #<sid> · Plan2Code`), so consoles for different projects are easy to tell apart.
|
||||
|
||||
## v2.4.2
|
||||
|
||||
### ✨ Added
|
||||
|
||||
@@ -13,7 +13,7 @@ the next engineer all start from the same specs.
|
||||
|
||||
One command opens it, every step is a card, and the terminal is always there if you prefer it.
|
||||
|
||||
Version 2.4.2 · MIT · 📖 [plan2code.jparkerweb.com](https://plan2code.jparkerweb.com)
|
||||
Version 2.5.0 · MIT · 📖 [plan2code.jparkerweb.com](https://plan2code.jparkerweb.com)
|
||||
|
||||
---
|
||||
|
||||
|
||||
+1
-1
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "plan2code",
|
||||
"version": "2.4.2",
|
||||
"version": "2.5.0",
|
||||
"private": true,
|
||||
"bin": {
|
||||
"plan2code-install": "./install.js"
|
||||
|
||||
@@ -151,6 +151,24 @@ import {
|
||||
WEIGHTS,
|
||||
YELLOW_AT,
|
||||
} from "../src/web-console/public/meter.js";
|
||||
import {
|
||||
blockFor,
|
||||
CHECKIN_LINE,
|
||||
checkHelper,
|
||||
checkHelpers,
|
||||
cleanSetting,
|
||||
defaultInstruction,
|
||||
defaultSetting,
|
||||
effectiveInstruction,
|
||||
FRAME_LINES,
|
||||
helperRows,
|
||||
offered,
|
||||
offLine,
|
||||
showSwitch,
|
||||
showTab,
|
||||
SUBAGENT_WORKFLOWS,
|
||||
switchLabel,
|
||||
} from "../src/web-console/public/subagents.js";
|
||||
import { applyMention, matchNames, mentionAt } from "../src/web-console/public/mentions.js";
|
||||
import { FAVICON_BODY, FAVICON_COLORS, faviconState, faviconSvg } from "../src/web-console/public/favicon.js";
|
||||
import { CACHE_MS, RELEASES_URL, REPO_URL, checkForUpdate, compareVersions, latestTag } from "../src/web-console/update-check.mjs";
|
||||
@@ -167,12 +185,18 @@ import {
|
||||
cwdHash,
|
||||
handOff,
|
||||
initialWorkspace,
|
||||
latestOpenCaps,
|
||||
parseArgs,
|
||||
pendingWorkspaceChanges,
|
||||
PROTECTED_CONSOLE_FILES,
|
||||
readChat,
|
||||
readLedger,
|
||||
readSubagentCursor,
|
||||
readSubagentSetting,
|
||||
readWorkspaceCursor,
|
||||
resetSubagentCursor,
|
||||
writeSubagentCursor,
|
||||
writeSubagentSetting,
|
||||
readOverview,
|
||||
removeCleanup,
|
||||
removeScratch,
|
||||
@@ -709,6 +733,7 @@ test("every module the page imports is actually served", async () => {
|
||||
const html = fs.readFileSync(path.join(dir, "index.html"), "utf8");
|
||||
for (const m of html.matchAll(/<link rel="modulepreload" href="\/([^"]+)"/g)) wanted.add(m[1]);
|
||||
assert.ok(wanted.has("chat.js"), "the page preloads chat.js");
|
||||
assert.ok(wanted.has("subagents.js"), "the page preloads subagents.js");
|
||||
assert.ok(wanted.size > 1, "found the imports");
|
||||
for (const f of wanted) {
|
||||
const res = await fetch(`${baseUrl}/${f}`, { headers: { cookie: consoleCookie(baseUrl, token), connection: "close" } });
|
||||
@@ -822,9 +847,9 @@ const helpTemplate = () => {
|
||||
return tpl[1];
|
||||
};
|
||||
|
||||
test("help: 16 tabs with unique ids", () => {
|
||||
assert.equal(HELP_TABS.length, 16);
|
||||
assert.equal(new Set(HELP_TABS.map((t) => t.id)).size, 16);
|
||||
test("help: 17 tabs with unique ids", () => {
|
||||
assert.equal(HELP_TABS.length, 17);
|
||||
assert.equal(new Set(HELP_TABS.map((t) => t.id)).size, 17);
|
||||
assert.ok(Object.isFrozen(HELP_TABS) && HELP_TABS.every((t) => Object.isFrozen(t)), "the tab list is frozen");
|
||||
});
|
||||
|
||||
@@ -894,6 +919,8 @@ test("help: helpTabFor opens on the tab for where the person is", () => {
|
||||
[{ adrift: true, view: "ask" }, "stuck"],
|
||||
[{ view: "ask" }, "ask"],
|
||||
[{ view: "ask", dashboard: true }, "ask"],
|
||||
[{ view: "subagents" }, "subagents"],
|
||||
[{ view: "subagents", workflow: "implement" }, "subagents"],
|
||||
[{ dashboard: true }, "dashboard"],
|
||||
[{ dashboard: true, view: "overview" }, "dashboard"],
|
||||
[{ workspace: true }, "workspace"],
|
||||
@@ -3458,7 +3485,15 @@ test("the scratch sweep removes old patches and helpers, never looks, the pointe
|
||||
return p;
|
||||
};
|
||||
const removable = [file("p2.json"), file("helper.mjs")];
|
||||
const kept = [file("looks.json"), file("workspaces.json"), file("console-dir"), file("update-check.json"), file("notes.txt"), file("p3.json", false)];
|
||||
const kept = [
|
||||
file("looks.json"),
|
||||
file("workspaces.json"),
|
||||
file("subagents.json"),
|
||||
file("console-dir"),
|
||||
file("update-check.json"),
|
||||
file("notes.txt"),
|
||||
file("p3.json", false),
|
||||
];
|
||||
const subdir = path.join(dir, "x.json");
|
||||
fs.mkdirSync(subdir);
|
||||
backdate(subdir);
|
||||
@@ -3467,12 +3502,18 @@ test("the scratch sweep removes old patches and helpers, never looks, the pointe
|
||||
const stale = staleScratch(dir, Date.now(), SESSION_MAX_AGE_MS).sort();
|
||||
assert.deepEqual(stale, ["helper.mjs", "p2.json"]);
|
||||
assert.deepEqual(
|
||||
(await removeScratch(dir, [...stale, "looks.json", "workspaces.json", "../p.json", "console-dir", "update-check.json"])).sort(),
|
||||
(await removeScratch(dir, [...stale, "looks.json", "workspaces.json", "subagents.json", "../p.json", "console-dir", "update-check.json"])).sort(),
|
||||
["helper.mjs", "p2.json"]
|
||||
);
|
||||
for (const p of removable) assert.equal(fs.existsSync(p), false, p);
|
||||
for (const p of kept) assert.ok(fs.existsSync(p), p);
|
||||
assert.deepEqual([...PROTECTED_CONSOLE_FILES].sort(), ["console-dir", "looks.json", "update-check.json", "workspaces.json"]);
|
||||
assert.deepEqual([...PROTECTED_CONSOLE_FILES].sort(), [
|
||||
"console-dir",
|
||||
"looks.json",
|
||||
"subagents.json",
|
||||
"update-check.json",
|
||||
"workspaces.json",
|
||||
]);
|
||||
} finally {
|
||||
fs.rmSync(dir, { recursive: true, force: true });
|
||||
}
|
||||
@@ -3506,7 +3547,9 @@ test("cleanup finds old sessions and strays in both folders, and keeps every pro
|
||||
const drafted = session("20250801-101010-dddddd", true);
|
||||
put(path.join(drafted, "draft.json"));
|
||||
const kept = [
|
||||
...["looks.json", "workspaces.json", "console-dir", "update-check.json"].map((n) => put(path.join(consoleDir, n))),
|
||||
...["looks.json", "workspaces.json", "subagents.json", "console-dir", "update-check.json"].map((n) =>
|
||||
put(path.join(consoleDir, n))
|
||||
),
|
||||
put(path.join(plan2code, "launcher.json")),
|
||||
put(path.join(plan2code, "models.json")),
|
||||
put(path.join(plan2code, "bin", "plan2code.js"), "x"),
|
||||
@@ -5138,6 +5181,232 @@ test("workspace cursor never moves backwards, and only changes past it are pendi
|
||||
}
|
||||
});
|
||||
|
||||
test("subagents: only the five opted-in workflows offer the switch", () => {
|
||||
for (const w of ["implement", "implement-review", "quick-task", "review", "pathfinder"]) {
|
||||
assert.equal(offered(w), true, w);
|
||||
assert.ok(defaultInstruction(w).length > 0, `${w} has a default instruction`);
|
||||
}
|
||||
for (const w of ["dashboard", "plan", "document", "init", "handoff", "constructor", "toString", undefined]) {
|
||||
assert.equal(offered(w), false, String(w));
|
||||
assert.equal(defaultInstruction(w), "");
|
||||
}
|
||||
assert.equal(Object.keys(SUBAGENT_WORKFLOWS).length, 5);
|
||||
assert.deepEqual(defaultSetting("review"), { workflow: "review", on: false, instruction: null, max: 3 });
|
||||
assert.equal(effectiveInstruction({ workflow: "review", instruction: " " }), defaultInstruction("review"));
|
||||
assert.equal(effectiveInstruction({ workflow: "review", instruction: " Mine " }), "Mine");
|
||||
});
|
||||
|
||||
test("subagents: blockFor walks every switch transition, and never says off to an agent not told on", () => {
|
||||
const setting = (on, revision, extra = {}) => ({ workflow: "implement", on, instruction: null, max: 3, revision, ...extra });
|
||||
const none = { revision: 0, state: "none" };
|
||||
|
||||
assert.equal(blockFor(setting(false, 1), none), null, "never on: nothing");
|
||||
assert.equal(blockFor(null, none), null, "no setting: nothing");
|
||||
|
||||
const on = blockFor(setting(true, 2), none);
|
||||
assert.equal(on.lines[0], "Subagents: on (revision 2) — a console setting, not typed by the person.");
|
||||
assert.ok(!on.lines[0].includes("replaces"));
|
||||
assert.deepEqual(on.field, { state: "on", revision: 2, max: 3, instruction: defaultInstruction("implement") });
|
||||
assert.deepEqual(on.cursor, { revision: 2, state: "on" });
|
||||
assert.equal(on.lines[on.lines.length - 1], " At most 3 helpers at once.");
|
||||
for (const frame of FRAME_LINES) assert.ok(on.lines.includes(" " + frame), frame);
|
||||
|
||||
const edit = blockFor(setting(true, 5, { instruction: "First line\n\nSecond line", max: 7 }), { revision: 4, state: "on" });
|
||||
assert.equal(edit.lines[0], "Subagents: on (revision 5, replaces revision 4) — a console setting, not typed by the person.");
|
||||
assert.ok(edit.lines.includes(" First line") && edit.lines.includes(" Second line"), "the instruction's own lines are indented");
|
||||
assert.ok(!edit.lines.some((line) => !line.trim()), "blank instruction lines are dropped");
|
||||
const nested = blockFor(setting(true, 2, { instruction: "- a\r\n - b\n \n" }), none);
|
||||
assert.deepEqual(nested.lines.slice(-3, -1), [" - a", " - b"], "the person's own indentation survives, CRLF and blank lines do not");
|
||||
assert.equal(edit.field.max, 7);
|
||||
for (const line of edit.lines.slice(1)) assert.match(line, /^ {2}\S/, "only the first line starts at column 0");
|
||||
|
||||
const off = blockFor(setting(false, 6), { revision: 5, state: "on" });
|
||||
assert.deepEqual(off.lines, [offLine(6)]);
|
||||
assert.equal(off.lines[0], "Subagents: off (revision 6) — don't start new helpers for the rest of this session.");
|
||||
assert.deepEqual(off.cursor, { revision: 6, state: "off" });
|
||||
assert.equal(off.field.state, "off");
|
||||
|
||||
assert.equal(blockFor(setting(false, 6), { revision: 6, state: "off" }), null, "same revision again: nothing");
|
||||
assert.equal(blockFor(setting(true, 6), { revision: 6, state: "on" }), null, "same revision while on: nothing");
|
||||
assert.equal(blockFor(setting(false, 3), { revision: 2, state: "off" }), null, "off after off: nothing");
|
||||
|
||||
assert.equal(blockFor(setting(true, 6), none).lines[0], "Subagents: on (revision 6) — a console setting, not typed by the person.", "a reset cursor re-states on");
|
||||
assert.equal(blockFor(setting(false, 6), none), null, "a reset cursor with it off: nothing");
|
||||
assert.equal(blockFor({ ...setting(true, 9), workflow: "plan" }, none), null, "a workflow that does not offer it: nothing");
|
||||
});
|
||||
|
||||
test("subagents: the injected wording names no harness tool", () => {
|
||||
const texts = [...FRAME_LINES, ...Object.keys(SUBAGENT_WORKFLOWS).map(defaultInstruction), offLine(1)];
|
||||
for (const text of texts) {
|
||||
for (const tool of ["run_subagent", "subagent_type", "Task(", "spawn_agent", "/agents", "Agent tool"]) {
|
||||
assert.ok(!text.includes(tool), `"${text}" names ${tool}`);
|
||||
}
|
||||
}
|
||||
});
|
||||
|
||||
test("subagents: cleanSetting accepts a good setting and names the field that fails", () => {
|
||||
assert.deepEqual(cleanSetting({ on: true, instruction: null, max: 3 }), { on: true, instruction: null, max: 3 });
|
||||
assert.deepEqual(cleanSetting({ on: false, instruction: " Do it ", max: 20 }), { on: false, instruction: "Do it", max: 20 });
|
||||
assert.equal(cleanSetting({ on: true, instruction: "", max: 1 }).instruction, null, "an empty instruction is the default");
|
||||
for (const max of [0, 21, 2.5, "3"]) assert.deepEqual(cleanSetting({ on: true, instruction: null, max }), { error: "max" }, String(max));
|
||||
assert.deepEqual(cleanSetting({ on: true, instruction: "x".repeat(2001), max: 3 }), { error: "too-long" });
|
||||
assert.deepEqual(cleanSetting({ on: "yes", instruction: null, max: 3 }), { error: "bad" });
|
||||
assert.deepEqual(cleanSetting({ on: true, instruction: 7, max: 3 }), { error: "bad" });
|
||||
assert.deepEqual(cleanSetting(null), { error: "bad" });
|
||||
});
|
||||
|
||||
test("subagents: checkHelper and checkHelpers name the helper behind every problem", () => {
|
||||
const running = { id: "h1", title: "Read the store", ask: "Find the lock helpers", state: "running" };
|
||||
const done = { id: "h2", title: "Tests", ask: "Run the suite", state: "done", result: "All green" };
|
||||
assert.deepEqual(checkHelper(running), []);
|
||||
assert.deepEqual(checkHelper(done), []);
|
||||
assert.deepEqual(checkHelper({ id: "alone", alone: true }), []);
|
||||
assert.deepEqual(checkHelpers([running, done, { id: "alone", alone: true }]), []);
|
||||
|
||||
const one = (entry) => {
|
||||
const problems = checkHelper(entry);
|
||||
assert.equal(problems.length, 1, JSON.stringify(problems));
|
||||
assert.match(problems[0], new RegExp(`helper "${entry.id}"`));
|
||||
return problems[0];
|
||||
};
|
||||
one({ ...running, title: undefined });
|
||||
assert.match(one({ ...running, state: "paused" }), /state must be running, done or failed/);
|
||||
one({ ...running, title: "t".repeat(81) });
|
||||
one({ ...running, ask: "a".repeat(401) });
|
||||
one({ ...done, result: "r".repeat(201) });
|
||||
|
||||
const dupes = checkHelpers([running, { ...done, id: "h1" }]);
|
||||
assert.ok(dupes.some((p) => p === 'helper "h1": duplicate id'), dupes.join("; "));
|
||||
const alones = checkHelpers([{ id: "alone", alone: true }, { id: "alone", alone: true }]);
|
||||
assert.ok(alones.some((p) => /helper "alone": only one working-alone entry/.test(p)), alones.join("; "));
|
||||
assert.deepEqual(checkHelpers("nope"), ["helpers must be an array"]);
|
||||
});
|
||||
|
||||
test("subagents: the page shows the switch only when offered and supported, and the tab only with a helper", () => {
|
||||
assert.equal(showSwitch(null), false);
|
||||
assert.equal(showSwitch({ offered: false, supported: true, on: true }), false);
|
||||
assert.equal(showSwitch({ offered: true, supported: false, on: true }), false);
|
||||
assert.equal(showSwitch({ offered: true, supported: true, on: false }), true);
|
||||
assert.equal(switchLabel({ on: true }), "Subagents: on");
|
||||
assert.equal(switchLabel({ on: false }), "Subagents: off");
|
||||
|
||||
const on = { offered: true, supported: true, on: true };
|
||||
const off = { offered: true, supported: true, on: false };
|
||||
const helper = { id: "h1", title: "Research", ask: "Check the docs", state: "running" };
|
||||
assert.equal(showTab(on, []), false, "never an empty tab, even when on");
|
||||
assert.equal(showTab(on, undefined), false);
|
||||
assert.equal(showTab(off, [helper]), true, "a helper shows with the switch off (Pathfinder research)");
|
||||
assert.equal(showTab({ ...on, supported: false }, [helper]), false, "no tab where the switch cannot show");
|
||||
assert.ok(CHECKIN_LINE.includes("check-ins, not live"));
|
||||
});
|
||||
|
||||
test("subagents: helperRows labels each state, shows a result only once a helper ended, and collapses to working alone", () => {
|
||||
assert.deepEqual(helperRows([{ id: "alone", alone: true }]), { alone: true, rows: [] });
|
||||
assert.deepEqual(helperRows(undefined), { alone: false, rows: [] });
|
||||
const { alone, rows } = helperRows([
|
||||
{ id: "h1", title: "One", ask: "a", state: "running", result: "not yet" },
|
||||
{ id: "h2", title: "Two", ask: "b", state: "done", result: "Found 2 call sites" },
|
||||
{ id: "h3", title: "Three", ask: "c", state: "failed", result: "Timed out" },
|
||||
]);
|
||||
assert.equal(alone, false);
|
||||
assert.deepEqual(rows.map((r) => [r.id, r.stateLabel]), [["h1", "Running"], ["h2", "Done"], ["h3", "Failed"]]);
|
||||
assert.equal("result" in rows[0], false, "a running helper has no result in its row");
|
||||
assert.equal(rows[1].result, "Found 2 call sites");
|
||||
assert.equal(rows[2].result, "Timed out");
|
||||
});
|
||||
|
||||
test("page: the Subagents button sits right after Write a brief, and its dialog is in the page with no inline styles or scripts", () => {
|
||||
const html = fs.readFileSync(path.join(ROOT, "src", "web-console", "public", "index.html"), "utf8");
|
||||
const row = html.match(/<div class="row-left">([\s\S]*?)<\/div>\s*<div class="views-group">/);
|
||||
assert.ok(row, "index.html has the second row's left cluster");
|
||||
const ids = [...row[1].matchAll(/<button[^>]*\bid="([^"]+)"/g)].map((m) => m[1]);
|
||||
assert.equal(ids[ids.indexOf("btn-brief") + 1], "btn-subagents", "the Subagents button follows Write a brief");
|
||||
assert.match(row[1], /<button[^>]*id="btn-subagents"[^>]*\bhidden\b/, "the button starts hidden");
|
||||
for (const part of ["sa-hub", "sa-node", "sa-link"]) assert.ok(row[1].includes(`class="${part}"`), `the icon has ${part}`);
|
||||
const dialog = html.match(/<dialog class="modal looks subagents" id="subagents-modal" aria-labelledby="subagents-title">([\s\S]*?)<\/dialog>/);
|
||||
assert.ok(dialog, "index.html has the Subagents dialog");
|
||||
for (const id of ["subagents-instruction", "subagents-default", "subagents-max", "subagents-checkin", "subagents-research", "subagents-status", "subagents-cancel", "subagents-save"]) {
|
||||
assert.ok(dialog[1].includes(`id="${id}"`), `the dialog carries #${id}`);
|
||||
}
|
||||
assert.doesNotMatch(dialog[1], /\sstyle=/);
|
||||
assert.doesNotMatch(dialog[1], /<script/i);
|
||||
});
|
||||
|
||||
test("subagents: the store round-trips per project and workflow under the console home", () => {
|
||||
const home = fs.mkdtempSync(path.join(os.tmpdir(), "p2c-subagents-home-"));
|
||||
try {
|
||||
const project = path.join(home, "My Repo");
|
||||
const script = `
|
||||
const lib = await import(${JSON.stringify(new URL("../src/web-console/lib.mjs", import.meta.url).href)});
|
||||
const project = ${JSON.stringify(project)};
|
||||
lib.saveSubagentStoreEntry(project, "implement", { on: true, instruction: "Mine", max: 5 });
|
||||
const flipped = project.replace(/My Repo$/, "MY REPO");
|
||||
console.log(JSON.stringify({
|
||||
file: lib.SUBAGENTS_FILE,
|
||||
saved: lib.subagentStoreEntry(project, "implement"),
|
||||
otherCase: lib.subagentStoreEntry(flipped, "implement"),
|
||||
unsaved: lib.subagentStoreEntry(project, "review"),
|
||||
}));
|
||||
`;
|
||||
const res = spawnSync(process.execPath, ["--input-type=module", "-e", script], {
|
||||
env: { ...process.env, PLAN2CODE_CONSOLE_HOME: home },
|
||||
encoding: "utf8",
|
||||
});
|
||||
assert.equal(res.status, 0, res.stderr);
|
||||
const out = JSON.parse(res.stdout);
|
||||
assert.equal(out.file, path.join(home, "subagents.json"), "the store follows PLAN2CODE_CONSOLE_HOME");
|
||||
assert.deepEqual(out.saved, { on: true, instruction: "Mine", max: 5 });
|
||||
if (process.platform === "win32" || process.platform === "darwin") {
|
||||
assert.deepEqual(out.otherCase, out.saved, "a different-case path reads the same entry");
|
||||
}
|
||||
assert.deepEqual(out.unsaved, { on: false, instruction: null, max: 3 });
|
||||
assert.ok(!fs.existsSync(path.join(home, "subagents.json.lock")), "the lock is released");
|
||||
} finally {
|
||||
fs.rmSync(home, { recursive: true, force: true });
|
||||
}
|
||||
});
|
||||
|
||||
test("subagents: the session setting and the cursor never go backwards, except a reset", () => {
|
||||
const dir = fs.mkdtempSync(path.join(os.tmpdir(), "p2c-subagents-"));
|
||||
try {
|
||||
assert.equal(readSubagentSetting(dir), null);
|
||||
writeSubagentSetting(dir, { workflow: "implement", on: true, instruction: null, max: 3, revision: 5 });
|
||||
writeSubagentSetting(dir, { workflow: "implement", on: false, instruction: null, max: 3, revision: 3 });
|
||||
assert.equal(readSubagentSetting(dir).revision, 5);
|
||||
assert.equal(readSubagentSetting(dir).on, false, "the rest of the setting is still written");
|
||||
fs.writeFileSync(path.join(dir, "subagents-setting.json"), JSON.stringify({ workflow: "implement", on: "yes", max: 3, revision: 1 }));
|
||||
assert.equal(readSubagentSetting(dir), null, "malformed reads null");
|
||||
|
||||
assert.deepEqual(readSubagentCursor(dir), { revision: 0, state: "none" });
|
||||
writeSubagentCursor(dir, { revision: 4, state: "on" });
|
||||
writeSubagentCursor(dir, { revision: 2, state: "off" });
|
||||
assert.deepEqual(readSubagentCursor(dir), { revision: 4, state: "on" });
|
||||
resetSubagentCursor(dir);
|
||||
assert.deepEqual(readSubagentCursor(dir), { revision: 0, state: "none" });
|
||||
fs.writeFileSync(path.join(dir, "subagents-cursor.json"), JSON.stringify({ revision: 2, state: "maybe" }));
|
||||
assert.deepEqual(readSubagentCursor(dir), { revision: 0, state: "none" });
|
||||
} finally {
|
||||
fs.rmSync(dir, { recursive: true, force: true });
|
||||
}
|
||||
});
|
||||
|
||||
test("subagents: latestOpenCaps reads the last open event, skipping a torn line", () => {
|
||||
const dir = fs.mkdtempSync(path.join(os.tmpdir(), "p2c-caps-"));
|
||||
const events = path.join(dir, "events.ndjson");
|
||||
try {
|
||||
assert.deepEqual(latestOpenCaps(dir), [], "no events yet");
|
||||
fs.writeFileSync(events, [{ type: "open", caps: ["subagents"] }, { type: "open" }].map((e) => JSON.stringify(e)).join("\n") + "\n");
|
||||
assert.deepEqual(latestOpenCaps(dir), [], "the latest open has no caps");
|
||||
fs.appendFileSync(events, JSON.stringify({ type: "post" }) + "\n" + JSON.stringify({ type: "open", caps: ["subagents"] }) + "\n");
|
||||
assert.deepEqual(latestOpenCaps(dir), ["subagents"]);
|
||||
fs.appendFileSync(events, '{"type":"open","ca');
|
||||
assert.deepEqual(latestOpenCaps(dir), ["subagents"], "a torn final line is ignored");
|
||||
assert.ok(PROTECTED_CONSOLE_FILES.has("subagents.json"));
|
||||
} finally {
|
||||
fs.rmSync(dir, { recursive: true, force: true });
|
||||
}
|
||||
});
|
||||
|
||||
test("initialWorkspace names the original folder after itself and marks it original", () => {
|
||||
const ws = initialWorkspace(path.join("C:", "git", "My Repo"));
|
||||
assert.equal(ws.version, 0);
|
||||
@@ -5500,6 +5769,376 @@ test("workspace: chat hands over a workspace change on its own, then has nothing
|
||||
}
|
||||
});
|
||||
|
||||
/* ------------------------------------------- subagents: end to end */
|
||||
|
||||
// The switch is remembered per project folder in the console home, so every
|
||||
// test that starts from "off" clears it first.
|
||||
const SUBAGENTS_STORE = path.join(HOME, "subagents.json");
|
||||
const subagentsSession = (extra = {}, { keepStore = false } = {}) => {
|
||||
if (!keepStore) fs.rmSync(SUBAGENTS_STORE, { force: true });
|
||||
return openSession({ workflow: "implement", ...extra });
|
||||
};
|
||||
const setSubagents = async (s, body) => {
|
||||
const res = await s.send("/subagents", body);
|
||||
return { status: res.status, body: await res.json() };
|
||||
};
|
||||
const frameSubagents = async (s) =>
|
||||
(await (await fetch(`${s.base}/state`, { headers: { cookie: s.cookie, connection: "close" } })).json()).subagents;
|
||||
const ON3 = { on: true, instruction: null, max: 3 };
|
||||
const submitAndWait = async (s) => {
|
||||
assert.equal((await s.send("/submit", EXPORT_A)).status, 200);
|
||||
return cli(["wait", "--session", s.sid, "--seconds", "10"]);
|
||||
};
|
||||
const subagentLines = (reply) =>
|
||||
String(reply || "")
|
||||
.split("\n")
|
||||
.filter((l) => l.startsWith("Subagents:"));
|
||||
|
||||
test("subagents: a change reaches the next pickup once, last in reply, edits name what they replace and off follows only an on", async () => {
|
||||
const s = subagentsSession();
|
||||
const extra = tempFolder();
|
||||
try {
|
||||
const on = await setSubagents(s, ON3);
|
||||
assert.equal(on.status, 200);
|
||||
assert.equal(on.body.ok, true);
|
||||
const rev = on.body.setting.revision;
|
||||
assert.deepEqual(on.body.setting, { workflow: "implement", on: true, instruction: null, max: 3, revision: rev });
|
||||
|
||||
assert.equal((await ask(s, "Which files does the first task touch?")).status, 200);
|
||||
assert.equal((await addFolder(s, { path: extra })).status, 200);
|
||||
const first = await submitAndWait(s);
|
||||
assert.equal(first.status, 0);
|
||||
assert.deepEqual(first.json.subagents, { state: "on", revision: rev, max: 3, instruction: defaultInstruction("implement") });
|
||||
const reply = first.json.reply;
|
||||
const at = (re) => reply.search(re);
|
||||
assert.ok(at(/^Export format: a$/m) === 0, reply);
|
||||
assert.ok(at(/^Quick question:/m) > 0, reply);
|
||||
assert.ok(at(/^Workspace:/m) > at(/^Quick question:/m), reply);
|
||||
assert.ok(at(/^Subagents:/m) > at(/^Workspace:/m), reply);
|
||||
assert.match(reply, new RegExp(`^Subagents: on \\(revision ${rev}\\) — a console setting, not typed by the person\\.$`, "m"));
|
||||
assert.ok(reply.endsWith("\n At most 3 helpers at once."), "the block goes last");
|
||||
assert.deepEqual(subagentLines(reply).length, 1, "one block");
|
||||
assert.deepEqual(readSubagentCursor(s.session), { revision: rev, state: "on" });
|
||||
|
||||
const second = await submitAndWait(s);
|
||||
assert.equal("subagents" in second.json, false, "handed over once");
|
||||
assert.deepEqual(subagentLines(second.json.reply), []);
|
||||
|
||||
const edited = await setSubagents(s, { ...ON3, max: 5 });
|
||||
assert.equal(edited.body.setting.revision, rev + 1);
|
||||
const third = await submitAndWait(s);
|
||||
assert.equal(third.json.subagents.revision, rev + 1);
|
||||
assert.equal(third.json.subagents.max, 5);
|
||||
assert.deepEqual(subagentLines(third.json.reply), [
|
||||
`Subagents: on (revision ${rev + 1}, replaces revision ${rev}) — a console setting, not typed by the person.`,
|
||||
]);
|
||||
|
||||
const same = await setSubagents(s, { ...ON3, max: 5 });
|
||||
assert.equal(same.status, 200);
|
||||
assert.equal(same.body.setting.revision, rev + 1, "saving the same values bumps nothing");
|
||||
assert.equal("subagents" in (await submitAndWait(s)).json, false, "and injects nothing");
|
||||
|
||||
const off = await setSubagents(s, { ...ON3, on: false, max: 5 });
|
||||
assert.equal(off.body.setting.revision, rev + 2, "off is a revision of its own");
|
||||
const fourth = await submitAndWait(s);
|
||||
assert.equal(fourth.json.subagents.state, "off");
|
||||
assert.deepEqual(subagentLines(fourth.json.reply), [
|
||||
`Subagents: off (revision ${rev + 2}) — don't start new helpers for the rest of this session.`,
|
||||
]);
|
||||
assert.equal("subagents" in (await submitAndWait(s)).json, false, "off is said once");
|
||||
} finally {
|
||||
cli(["stop", "--session", s.sid]);
|
||||
fs.rmSync(extra, { recursive: true, force: true });
|
||||
}
|
||||
});
|
||||
|
||||
test("subagents: never on means never a line, and chat hands a pending block over on its own", async () => {
|
||||
const s = subagentsSession();
|
||||
try {
|
||||
const off = await setSubagents(s, { on: false, instruction: null, max: 4 });
|
||||
assert.equal(off.status, 200);
|
||||
const got = await submitAndWait(s);
|
||||
assert.equal("subagents" in got.json, false);
|
||||
assert.deepEqual(subagentLines(got.json.reply), [], "off is never said to an agent not told on");
|
||||
assert.equal(cli(["chat", "--session", s.sid]).status, 10);
|
||||
|
||||
assert.equal((await setSubagents(s, { on: true, instruction: "Split by file.", max: 4 })).status, 200);
|
||||
const chat = cli(["chat", "--session", s.sid]);
|
||||
assert.equal(chat.status, 0);
|
||||
assert.deepEqual(chat.json.chat, []);
|
||||
assert.equal(chat.json.subagents.state, "on");
|
||||
assert.equal(chat.json.subagents.instruction, "Split by file.");
|
||||
assert.match(chat.json.reply, /^Subagents: on \(revision \d+\)/);
|
||||
assert.match(chat.json.reply, /^ {2}Split by file\.$/m);
|
||||
assert.ok(chat.json.terminalLine);
|
||||
assert.equal(cli(["chat", "--session", s.sid]).status, 10, "then nothing");
|
||||
} finally {
|
||||
cli(["stop", "--session", s.sid]);
|
||||
}
|
||||
});
|
||||
|
||||
test("subagents: a resume re-states an on setting once, says nothing when off, and a lost cursor repeats the block", async () => {
|
||||
const s = subagentsSession();
|
||||
try {
|
||||
const rev = (await setSubagents(s, ON3)).body.setting.revision;
|
||||
const resumed = cli(["open", "--resume", s.sid, "--no-open"]);
|
||||
assert.equal(resumed.json.ok, true);
|
||||
assert.deepEqual(resumed.json.subagents, { state: "on", revision: rev, max: 3, instruction: defaultInstruction("implement") });
|
||||
assert.equal(subagentLines(resumed.json.reply)[0], `Subagents: on (revision ${rev}) — a console setting, not typed by the person.`);
|
||||
assert.ok(resumed.json.reply.split("\n").every((l, i) => i === 0 || l.startsWith(" ")), "only the block's lines");
|
||||
assert.equal("subagents" in (await submitAndWait(s)).json, false, "the next pickup carries nothing");
|
||||
|
||||
// The print happened but the cursor write did not: the block comes again.
|
||||
fs.writeFileSync(path.join(s.session, "subagents-cursor.json"), JSON.stringify({ revision: 0, state: "none" }));
|
||||
const again = await submitAndWait(s);
|
||||
assert.equal(again.json.subagents.state, "on");
|
||||
assert.deepEqual(subagentLines(again.json.reply), [`Subagents: on (revision ${rev}) — a console setting, not typed by the person.`]);
|
||||
assert.deepEqual(readSubagentCursor(s.session), { revision: rev, state: "on" });
|
||||
|
||||
assert.equal((await setSubagents(s, { ...ON3, on: false })).status, 200);
|
||||
const quiet = cli(["open", "--resume", s.sid, "--no-open"]);
|
||||
assert.equal("subagents" in quiet.json, false, "a resume with the switch off says nothing");
|
||||
assert.equal("reply" in quiet.json, false);
|
||||
assert.equal("subagents" in (await submitAndWait(s)).json, false, "nor does the next pickup");
|
||||
} finally {
|
||||
cli(["stop", "--session", s.sid]);
|
||||
}
|
||||
});
|
||||
|
||||
test("subagents: a dashboard launch into implement hears implement's saved setting once", async () => {
|
||||
const seed = subagentsSession();
|
||||
try {
|
||||
assert.equal((await setSubagents(seed, ON3)).status, 200);
|
||||
} finally {
|
||||
cli(["stop", "--session", seed.sid]);
|
||||
}
|
||||
const s = consoleSession(["--workflow", "dashboard"]);
|
||||
try {
|
||||
assert.equal((await s.get("/state")).subagents.offered, false, "the dashboard offers no switch");
|
||||
const launched = cli(["open", "--resume", s.sid, "--no-open", "--workflow", "implement"]);
|
||||
// On the launch itself, not at a later pickup: a skill may do its main
|
||||
// work before it ever collects anything.
|
||||
assert.equal(launched.json.subagents?.state, "on", "the launch's own open output carries the block");
|
||||
assert.match(launched.json.reply, /^Subagents: on \(revision \d+\)/);
|
||||
await sleep(1200);
|
||||
assert.equal(cli(["chat", "--session", s.sid]).status, 10, "never both");
|
||||
const view = await s.get("/state");
|
||||
assert.deepEqual([view.subagents.offered, view.subagents.supported, view.subagents.on], [true, true, true]);
|
||||
} finally {
|
||||
cli(["stop", "--session", s.sid]);
|
||||
}
|
||||
});
|
||||
|
||||
test("subagents: the setting survives a restart at the same revision and starts the next session in the project", async () => {
|
||||
const s = subagentsSession();
|
||||
let next = null;
|
||||
try {
|
||||
const saved = await setSubagents(s, { on: true, instruction: "Split by file.", max: 7 });
|
||||
assert.equal(saved.status, 200);
|
||||
const rev = saved.body.setting.revision;
|
||||
cli(["stop", "--session", s.sid]);
|
||||
const resumed = cli(["open", "--resume", s.sid, "--no-open"]);
|
||||
const frame = await (
|
||||
await fetch(`${sessionUrl(resumed.json.url).base}/state`, { headers: { cookie: sessionUrl(resumed.json.url).cookie, connection: "close" } })
|
||||
).json();
|
||||
assert.deepEqual(
|
||||
[frame.subagents.on, frame.subagents.instruction, frame.subagents.max, frame.subagents.revision],
|
||||
[true, "Split by file.", 7, rev],
|
||||
"a restart alone bumps nothing"
|
||||
);
|
||||
|
||||
next = subagentsSession({}, { keepStore: true });
|
||||
const fresh = await frameSubagents(next);
|
||||
assert.deepEqual([fresh.on, fresh.instruction, fresh.max], [true, "Split by file.", 7], "a new session in the same project starts there");
|
||||
} finally {
|
||||
cli(["stop", "--session", s.sid]);
|
||||
if (next) cli(["stop", "--session", next.sid]);
|
||||
}
|
||||
});
|
||||
|
||||
test("subagents: a save that matches this session still becomes the project's setting, without a bump", async () => {
|
||||
const b = subagentsSession();
|
||||
const a = subagentsSession({}, { keepStore: true });
|
||||
let c = null;
|
||||
try {
|
||||
const before = (await frameSubagents(b)).revision;
|
||||
assert.equal((await setSubagents(a, ON3)).status, 200, "another session turns it on for the project");
|
||||
const same = await setSubagents(b, { ...ON3, on: false });
|
||||
assert.equal(same.status, 200);
|
||||
assert.equal(same.body.setting.revision, before, "nothing changed for this session's agent");
|
||||
assert.equal("subagents" in (await submitAndWait(b)).json, false);
|
||||
|
||||
c = subagentsSession({}, { keepStore: true });
|
||||
assert.equal((await frameSubagents(c)).on, false, "the next session starts from the person's latest pick");
|
||||
} finally {
|
||||
for (const s of [a, b, c]) if (s) cli(["stop", "--session", s.sid]);
|
||||
}
|
||||
});
|
||||
|
||||
test("subagents: a workflow without the switch refuses it, bad bodies name the field, and an older copy's open hides it", async () => {
|
||||
const plan = subagentsSession({ workflow: "plan" });
|
||||
const s = subagentsSession();
|
||||
try {
|
||||
assert.deepEqual(await setSubagents(plan, ON3), { status: 400, body: { error: "not-offered" } });
|
||||
assert.equal((await frameSubagents(plan)).offered, false);
|
||||
assert.equal("subagents" in (await submitAndWait(plan)).json, false);
|
||||
|
||||
assert.deepEqual(await setSubagents(s, { ...ON3, max: 0 }), { status: 400, body: { error: "max" } });
|
||||
assert.deepEqual(await setSubagents(s, { ...ON3, max: 21 }), { status: 400, body: { error: "max" } });
|
||||
assert.deepEqual(await setSubagents(s, { ...ON3, instruction: "x".repeat(2001) }), { status: 400, body: { error: "too-long" } });
|
||||
assert.deepEqual(await setSubagents(s, { ...ON3, on: "yes" }), { status: 400, body: { error: "bad" } });
|
||||
|
||||
assert.equal((await frameSubagents(s)).supported, true, "this copy's open carries caps");
|
||||
fs.appendFileSync(path.join(s.session, "events.ndjson"), JSON.stringify({ at: new Date().toISOString(), type: "open", resumed: true }) + "\n");
|
||||
assert.equal((await frameSubagents(s)).supported, false, "an older copy's open has no caps");
|
||||
cli(["open", "--resume", s.sid, "--no-open"]);
|
||||
assert.equal((await frameSubagents(s)).supported, true);
|
||||
|
||||
// A session an older server ran has no setting file: nothing is injected,
|
||||
// whatever the store says.
|
||||
assert.equal((await setSubagents(s, ON3)).status, 200);
|
||||
fs.rmSync(path.join(s.session, "subagents-setting.json"), { force: true });
|
||||
assert.equal("subagents" in (await submitAndWait(s)).json, false);
|
||||
} finally {
|
||||
cli(["stop", "--session", plan.sid]);
|
||||
cli(["stop", "--session", s.sid]);
|
||||
}
|
||||
});
|
||||
|
||||
/* ------------------------------------------ subagents: helper reports */
|
||||
|
||||
const reportedHelper = (id, extra = {}) => ({ id, title: `Helper ${id}`, ask: "Find the callers of applyPatch", state: "running", ...extra });
|
||||
|
||||
test("helpers: post merges them by id, takes one working-alone entry, and null clears the list", () => {
|
||||
const s = consoleSession(["--workflow", "implement"]);
|
||||
try {
|
||||
assert.equal(postPatch(s, { helpers: [reportedHelper("h1")] }).status, 0);
|
||||
const done = reportedHelper("h1", { state: "done", result: "Found 2 call sites" });
|
||||
assert.equal(postPatch(s, { helpers: [done, reportedHelper("h2")] }).status, 0);
|
||||
assert.deepEqual(readState(s.session).helpers, [done, reportedHelper("h2")], "h1 updated in place, h2 added");
|
||||
|
||||
assert.equal(postPatch(s, { helpers: [{ id: "alone", alone: true }] }).status, 0);
|
||||
assert.deepEqual(readState(s.session).helpers.map((h) => h.id), ["h1", "h2", "alone"]);
|
||||
const second = postPatch(s, { helpers: [{ id: "solo", alone: true }] }, { expectFail: true });
|
||||
assert.equal(second.status, 3);
|
||||
assert.match(second.stderr, /helper "solo"/);
|
||||
assert.deepEqual(readState(s.session).helpers.map((h) => h.id), ["h1", "h2", "alone"], "the refused entry was not written");
|
||||
|
||||
assert.equal(postPatch(s, { helpers: null }).status, 0);
|
||||
assert.equal("helpers" in readState(s.session), false);
|
||||
} finally {
|
||||
cli(["stop", "--session", s.sid]);
|
||||
}
|
||||
});
|
||||
|
||||
test("helpers: every malformed report exits 3 naming the helper, and nothing is written", () => {
|
||||
const s = consoleSession(["--workflow", "implement"]);
|
||||
try {
|
||||
assert.equal(postPatch(s, { helpers: [reportedHelper("h1")] }).status, 0);
|
||||
const statePath = path.join(s.session, "state.json");
|
||||
const before = fs.readFileSync(statePath, "utf8");
|
||||
const cases = [
|
||||
["missing title", [{ id: "h3", ask: "Read the docs", state: "running" }], /helper "h3": title must be a non-empty string/],
|
||||
["unknown state", [reportedHelper("h3", { state: "paused" })], /helper "h3": state must be running, done or failed/],
|
||||
["81-char title", [reportedHelper("h3", { title: "t".repeat(81) })], /helper "h3": title must be at most 80 characters/],
|
||||
["401-char ask", [reportedHelper("h3", { ask: "a".repeat(401) })], /helper "h3": ask must be at most 400 characters/],
|
||||
["201-char result", [reportedHelper("h3", { state: "done", result: "r".repeat(201) })], /helper "h3": result must be at most 200 characters/],
|
||||
["completion marker", [reportedHelper("h3", { state: "done", result: "PHASE_COMPLETE" })], /helper "h3" result contains a loop completion marker/],
|
||||
["metrics bait", [reportedHelper("h3", { title: "Risk 3" })], /helper "h3" title contains "Risk 3"/],
|
||||
["not an array", { id: "h3" }, /"helpers" must be an array/],
|
||||
["null entry", [null], /"helpers" entries must be objects/],
|
||||
["string entry", ["h3"], /"helpers" entries must be objects/],
|
||||
];
|
||||
for (const [name, helpers, re] of cases) {
|
||||
const res = postPatch(s, { helpers }, { expectFail: true });
|
||||
assert.equal(res.status, 3, name);
|
||||
assert.match(res.stderr, re, name);
|
||||
assert.equal(fs.readFileSync(statePath, "utf8"), before, `${name}: nothing written`);
|
||||
}
|
||||
} finally {
|
||||
cli(["stop", "--session", s.sid]);
|
||||
}
|
||||
});
|
||||
|
||||
test("docs: a doc's version never goes back; the same version again is fine, and a hop starts every doc fresh", () => {
|
||||
const s = consoleSession(["--workflow", "implement"]);
|
||||
try {
|
||||
const doc = (version, md) => ({ docs: [{ id: "phase", title: "Phase 5 tasks", version, blocks: [{ id: "tasks", state: "settled", md }] }] });
|
||||
assert.equal(postPatch(s, doc(7, "- [x] Task 4.1")).status, 0);
|
||||
assert.equal(postPatch(s, doc(7, "- [x] Task 4.1 (again)")).status, 0, "the same version again is fine");
|
||||
const statePath = path.join(s.session, "state.json");
|
||||
const before = fs.readFileSync(statePath, "utf8");
|
||||
const stale = postPatch(s, doc(1, "- [ ] Task 4.1"), { expectFail: true });
|
||||
assert.equal(stale.status, 3);
|
||||
assert.match(stale.stderr, /doc "phase" is at version 7 on the page; this patch sends version 1/);
|
||||
assert.equal(fs.readFileSync(statePath, "utf8"), before, "nothing written");
|
||||
assert.equal(postPatch(s, doc(8, "- [ ] Task 5.1")).status, 0, "a higher version goes through");
|
||||
assert.equal(postPatch(s, { docs: [{ id: "phase", blocks: [{ id: "tasks", state: "settled", md: "- [x] Task 5.1" }] }] }).status, 0, "a patch with no version is not checked");
|
||||
|
||||
cli(["open", "--resume", s.sid, "--no-open", "--workflow", "dashboard"]);
|
||||
cli(["open", "--resume", s.sid, "--no-open", "--workflow", "implement"]);
|
||||
assert.equal(postPatch(s, doc(1, "- [ ] Task 1.1")).status, 0, "after a hop the doc starts fresh");
|
||||
} finally {
|
||||
cli(["stop", "--session", s.sid]);
|
||||
}
|
||||
});
|
||||
|
||||
test("docs: a second phase in one build session goes through as building.md teaches it", () => {
|
||||
const md = fs.readFileSync(path.join(ROOT, "src", "web-console", "building.md"), "utf8");
|
||||
assert.match(md, /`"version": 1` is for the first phase of a session only/);
|
||||
assert.match(md, /a later phase in the\s+same session reposts `phase` and `phasefile` at one more than the version the\s+page holds/);
|
||||
const s = consoleSession(["--workflow", "implement"]);
|
||||
try {
|
||||
const phase = (n, version, md) => ({
|
||||
headline: { stage: `Phase ${n}`, cleared: 0 },
|
||||
docs: [
|
||||
{ id: "phase", title: `Phase ${n} tasks`, version, blocks: [{ id: "tasks", state: "settled", md }] },
|
||||
{ id: "phasefile", title: `phase-${n}.md`, version, blocks: [{ id: "body", state: "settled", md }] },
|
||||
],
|
||||
});
|
||||
assert.equal(postPatch(s, phase(1, 1, "- [ ] Task 1.1")).status, 0);
|
||||
assert.equal(postPatch(s, phase(1, 2, "- [x] Task 1.1")).status, 0);
|
||||
const restarted = postPatch(s, phase(2, 1, "- [ ] Task 2.1"), { expectFail: true });
|
||||
assert.equal(restarted.status, 3, "restarting at version 1 is refused");
|
||||
assert.equal(postPatch(s, phase(2, 3, "- [ ] Task 2.1")).status, 0, "continuing from the page's version goes through");
|
||||
const docs = readState(s.session).docs;
|
||||
assert.deepEqual(
|
||||
docs.map((d) => [d.id, d.title, d.version]),
|
||||
[["phase", "Phase 2 tasks", 3], ["phasefile", "phase-2.md", 3]]
|
||||
);
|
||||
} finally {
|
||||
cli(["stop", "--session", s.sid]);
|
||||
}
|
||||
});
|
||||
|
||||
test("helpers: a dashboard hop clears them, a same-workflow or paused resume keeps them, and the meter never moves", async () => {
|
||||
const s = consoleSession(["--workflow", "implement"]);
|
||||
try {
|
||||
const meterBefore = (await s.get("/state")).meter;
|
||||
assert.equal(postPatch(s, { helpers: [reportedHelper("h1"), { id: "alone", alone: true }] }).status, 0);
|
||||
assert.deepEqual((await s.get("/state")).meter, meterBefore, "helper reports add nothing to the meter");
|
||||
assert.equal(readLedger(s.session).some((e) => JSON.stringify(e).includes("h1")), false, "nothing about helpers reaches the ledger");
|
||||
|
||||
cli(["open", "--resume", s.sid, "--no-open"]);
|
||||
assert.equal(readState(s.session).helpers.length, 2, "a resume with no --workflow keeps them");
|
||||
cli(["open", "--resume", s.sid, "--no-open", "--workflow", "implement"]);
|
||||
assert.equal(readState(s.session).helpers.length, 2, "a resume into the same workflow keeps them");
|
||||
|
||||
assert.equal(postPatch(s, { finish: { headline: "Paused at Task 2" } }).status, 0);
|
||||
cli(["open", "--resume", s.sid, "--no-open"]);
|
||||
const resumed = readState(s.session);
|
||||
assert.equal("finish" in resumed, false, "the pause came down");
|
||||
assert.equal(resumed.helpers.length, 2, "taking a pause down keeps them");
|
||||
|
||||
cli(["open", "--resume", s.sid, "--no-open", "--workflow", "dashboard"]);
|
||||
assert.equal("helpers" in readState(s.session), false, "the hop to the dashboard drops them");
|
||||
cli(["open", "--resume", s.sid, "--no-open", "--workflow", "implement"]);
|
||||
assert.equal("helpers" in readState(s.session), false, "and the hop back brings none");
|
||||
} finally {
|
||||
cli(["stop", "--session", s.sid]);
|
||||
}
|
||||
});
|
||||
|
||||
test("meter: a repeated run counts once, a bad one appends nothing, and neither reaches state.json", async () => {
|
||||
const s = openSession();
|
||||
try {
|
||||
|
||||
@@ -64,6 +64,13 @@ progress bar is the first thing someone watching a build looks at. The session
|
||||
meter counts the build's tasks from `cleared` as it rises, so keep it current,
|
||||
and start every phase (a second one in the same run too) at `"cleared": 0`.
|
||||
|
||||
`"version": 1` is for the first phase of a session only. A doc's version
|
||||
never goes back (console.md → House rules, rule 9), so a later phase in the
|
||||
same session reposts `phase` and `phasefile` at one more than the version the
|
||||
page holds, with the new phase's title and content. The same goes for
|
||||
`report` at sign-off and `review` in a mid-session review: version 1 the
|
||||
first time, then up from wherever the page has it.
|
||||
|
||||
`phasefile` is the whole `phase-X.md`, verbatim from disk, as its own tab —
|
||||
the person can read the prerequisites and task specs while you build. Re-post
|
||||
it whenever the file changes, which is every task: the checkbox write that
|
||||
@@ -111,6 +118,12 @@ printed), never into the project or into `~/.plan2code/console/` directly:
|
||||
- Do not call `wait` while building. There is nothing to collect, and the page
|
||||
holds anything the person sends until you next look.
|
||||
|
||||
A build may receive a `Subagents:` standing instruction, on `open` output or a
|
||||
`chat` check between tasks. Follow console.md → Standing instructions for
|
||||
handing independent tasks to helpers and reporting them as `helpers`. Keep the
|
||||
per-task progress posts, the checkbox writes, the chat checks and the sign-off
|
||||
with you.
|
||||
|
||||
### Quick questions between tasks
|
||||
|
||||
The person can ask a Quick question on the Ask tab at any point in a build
|
||||
@@ -195,7 +208,8 @@ only ever be offered once nothing could come of it:
|
||||
`reply` carries `Approve this phase: approved`, which is the terminal's
|
||||
`approved`. If the note that came with an approval asks for a change, treat it
|
||||
as "describe any issues": do the change first and ask again. `changes` means
|
||||
exactly what it says: address it, bump the report's version, and reopen the
|
||||
exactly what it says: address it, bump the report's version (a later phase's
|
||||
report starts above the last one's, too), and reopen the
|
||||
item (`"status": "reopened"`) with a reply in its `thread`. `review` is the
|
||||
person asking for the code review before they approve anything — see "The
|
||||
review, mid-session" below.
|
||||
|
||||
@@ -170,7 +170,7 @@ so even a kill at the worst possible moment costs you a repeat, never an answer.
|
||||
|
||||
| Exit | Meaning | What you do |
|
||||
| --- | --- | --- |
|
||||
| `0` | They pressed Send, or asked a Quick question. stdout is the result JSON, and may carry `workspace` (changes to the folder list, see Workspace). | Handle the cards (if any), the chat (if any) and any `workspace` changes, then post once (below, Quick questions and Workspace). |
|
||||
| `0` | They pressed Send, or asked a Quick question. stdout is the result JSON, and may carry `workspace` (changes to the folder list, see Workspace) and `subagents` (the helpers switch, see Standing instructions). | Handle the cards (if any), the chat (if any), any `workspace` changes and any `subagents` block, then post once (below, Quick questions, Workspace and Standing instructions). |
|
||||
| `10` | Still working. stdout has a short progress summary; `pendingWorkspace` counts workspace changes waiting for the next send. | Relay ONE line: the `message` field itself, "Waiting on your answer in the web console", followed by the `terminalLine`. Then call `wait` again. |
|
||||
| `20` | The server is gone. | `open --resume <sid>`, give them the new link, then keep waiting. |
|
||||
| `30` | They pressed Cancel. | Stop. Ask what they want to do, in the terminal. |
|
||||
@@ -647,6 +647,84 @@ for permission is not a failure; report only a read that failed after it.
|
||||
|
||||
---
|
||||
|
||||
## Standing instructions
|
||||
|
||||
On the skills that offer it (`implement`, `implement-review`, `quick-task`,
|
||||
`review`, `pathfinder`), the person can turn **helpers** (subagents) on or off
|
||||
from the top bar's Subagents button. Their pick is saved per project and per
|
||||
skill, off by default, and reaches you as a standing instruction, only when it
|
||||
changes.
|
||||
|
||||
### What arrives
|
||||
|
||||
A `subagents` field beside `reply`, and `Subagents:` lines last in `reply`,
|
||||
after the card lines, the `Quick question:` blocks and the `Workspace:` lines.
|
||||
It rides on `wait` exit `0`, `chat` exit `0` and `open` output. A setting
|
||||
change alone never ends a `wait` slice: it waits for the next send, or for
|
||||
your next `chat` check.
|
||||
|
||||
```
|
||||
Subagents: on (revision 2) — a console setting, not typed by the person.
|
||||
Hand independent work to helpers if your tools allow it; otherwise carry on alone.
|
||||
Report each helper on the page (console.md → Standing instructions); questions for the person stay with you.
|
||||
With no way to start helpers, report one "working alone" entry for this skill run instead.
|
||||
Hand independent tasks in a phase to helpers: tasks that touch different files and do not depend on each other. Keep tasks that share files, the phase's tests and the sign-off with you.
|
||||
At most 3 helpers at once.
|
||||
```
|
||||
|
||||
beside `"subagents": { "state": "on", "revision": 2, "max": 3, "instruction": "…" }`.
|
||||
An edit while on arrives as `Subagents: on (revision 3, replaces revision 2) — …`
|
||||
with the whole block again; switching off arrives as one line:
|
||||
`Subagents: off (revision 4) — don't start new helpers for the rest of this session.`
|
||||
|
||||
It is a console setting, not something the person typed. It never answers a
|
||||
card, and it is never recorded under `specs/`.
|
||||
|
||||
### Obeying it
|
||||
|
||||
- **On:** hand independent work to helpers if your tools allow it, at most
|
||||
`max` at once, following the instruction lines. `max` is advisory: your
|
||||
harness's own limit still applies.
|
||||
- **A higher revision replaces a lower one.** Follow the latest block only.
|
||||
- **Off:** start no new helpers for the rest of the session. Let running ones
|
||||
finish and report them.
|
||||
- **Nothing arrives:** keep doing what the skill says.
|
||||
- **Scope is the skill run it arrived in.** After a dashboard launch, no block
|
||||
means the switch is off for this skill, even if an earlier skill in the same
|
||||
conversation was told "on": `open` starts the count again, and a launch with
|
||||
the switch off sends nothing.
|
||||
|
||||
### Reporting helpers
|
||||
|
||||
Post them, at your check-ins, so the page's Subagents tab can show them. The
|
||||
page never hears from a helper directly:
|
||||
|
||||
```jsonc
|
||||
{ "helpers": [
|
||||
{ "id": "h1", "title": "Read the store helpers", "ask": "Find every caller of readSubagentSetting.", "state": "running" },
|
||||
{ "id": "h2", "title": "Check the tests", "ask": "Run the subagents tests and report failures.", "state": "done", "result": "All 9 pass." }
|
||||
] }
|
||||
```
|
||||
|
||||
- `id` (non-empty), `title` (at most 80 characters), `ask` (at most 400) and
|
||||
`state` (`running`, `done` or `failed`) are required; `result` (at most 200)
|
||||
is the one line you add once a helper ends.
|
||||
- Merged by `id`: post a helper again with its new `state` and `result` and it
|
||||
updates in place. `"helpers": null` clears the list. A dashboard hop clears it
|
||||
too; a resume into the same skill keeps it.
|
||||
- One post per change worth seeing, not a stream.
|
||||
- Questions for the person stay with you, never with a helper: most harnesses
|
||||
give helpers no way to ask, and an answer only reaches the agent holding the
|
||||
session.
|
||||
- **No way to start helpers?** Post one `{ "id": "alone", "alone": true }`
|
||||
entry for the skill run instead. The tab then says you are working alone.
|
||||
- **Pathfinder:** research questions always use helpers and are always
|
||||
reported, whatever the switch says. The switch governs recon, sketches and
|
||||
lookups beside the conversation.
|
||||
- Helpers add no session meter points. Post no `run` for them.
|
||||
|
||||
---
|
||||
|
||||
## Launches (dashboard only)
|
||||
|
||||
A `dashboard` session is not a conversation: the page draws a menu of every
|
||||
@@ -763,7 +841,10 @@ commands follow the pipeline: the sign-off's is
|
||||
|
||||
### Review (`review`)
|
||||
|
||||
Scope questions up front, then the findings report as a doc (`id: "report"`),
|
||||
Scope questions up front — run standalone with nothing named, the first is
|
||||
a `choice`, "What should I review?", built from a quick scan (branch changes,
|
||||
uncommitted changes, specs, files you name; each option with its size),
|
||||
never an assumed target; a build's review skips it (`building.md`). Then the findings report as a doc (`id: "report"`),
|
||||
then the pick-what-gets-fixed menu as a `multi` or `choice` keyed by finding
|
||||
id, carrying `"doc": "report"` so the card links straight to the findings.
|
||||
Settle that item (`"status": "answered"` plus the `answer` they sent) in
|
||||
@@ -797,6 +878,8 @@ that is what the person is there to download. The finish carries no
|
||||
- Chart Step 8's research subagents must all report back before the
|
||||
finish (Finishing → Nothing of yours may still be running); the finish
|
||||
body then names what each one found.
|
||||
- Report every research subagent as a helper, whatever the Subagents switch
|
||||
says (Standing instructions → Reporting helpers).
|
||||
- At every session end, post `finish` (headline, `body`, and Form A's command as
|
||||
`command`) BEFORE `stop`. Someone who spent the session in the browser never
|
||||
sees the Trail Footer, and without this their last screen promises a question
|
||||
@@ -1146,6 +1229,16 @@ A patch that breaks one of these is rejected with exit `3` and a message:
|
||||
(Session meter) and a non-empty `id`; a `folderIssue` needs non-empty
|
||||
`name` and `reason` strings, and `hint`, when present, is one too. Rules 4
|
||||
and 5 cover `reason` and `hint`.
|
||||
8. **`helpers` entries are well formed** (Standing instructions → Reporting
|
||||
helpers): an array of objects, each with a unique `id`, a `title`, an `ask`
|
||||
and a known `state` within their limits, plus at most one `alone` entry.
|
||||
Rules 4 and 5 cover `title`, `ask` and `result`.
|
||||
9. **A doc's `version` never goes back.** Sending a known doc a lower
|
||||
`version` than the page holds is refused: it is almost always a stale or
|
||||
copied payload. The same version again is fine, and a dashboard hop starts
|
||||
every doc fresh. Anything else reusing a doc id in the same session (a
|
||||
build's second phase, a second report or review) continues from the
|
||||
version the page holds.
|
||||
|
||||
These are workflow rules you already follow. The server just makes them checkable.
|
||||
|
||||
@@ -1167,7 +1260,9 @@ cannot see them, and the moment it says the session ended, the person is
|
||||
free to close that terminal and kill them mid-write. While you wait, post
|
||||
`{"agent":{"status":"working","activity":"Researching 3 questions (1 of 3 back)"}}`
|
||||
and update the count as each returns. Never write a `finish.body` that says
|
||||
work "is running in the background" or "will finish on its own".
|
||||
work "is running in the background" or "will finish on its own". Mark every
|
||||
reported helper `done` or `failed` before the finish, so the Subagents tab
|
||||
never ends on a row still running.
|
||||
|
||||
### 1. Post the finish
|
||||
|
||||
|
||||
@@ -64,6 +64,8 @@ import {
|
||||
readChat,
|
||||
readJson,
|
||||
readLedger,
|
||||
readSubagentCursor,
|
||||
readSubagentSetting,
|
||||
readWorkspace,
|
||||
reapHandles,
|
||||
rememberedWorkspace,
|
||||
@@ -71,6 +73,7 @@ import {
|
||||
removeScratch,
|
||||
removeSessions,
|
||||
repoRoots,
|
||||
resetSubagentCursor,
|
||||
scanProject,
|
||||
SESSION_MAX_AGE_MS,
|
||||
sessionDir,
|
||||
@@ -88,9 +91,11 @@ import {
|
||||
workspaceForAgent,
|
||||
writeCursor,
|
||||
writeJsonAtomic,
|
||||
writeSubagentCursor,
|
||||
writeWorkspaceCursor,
|
||||
} from "./lib.mjs";
|
||||
import { RUN_EVENTS, TASK_EVENTS, MAX_TASKS, isTaskCount, progressEntry } from "./public/meter.js";
|
||||
import { blockFor, offered } from "./public/subagents.js";
|
||||
import { changeLine } from "./public/workspace.js";
|
||||
|
||||
// Mirrors the server's absolute lifetime cap: a handle older than this cannot
|
||||
@@ -310,7 +315,11 @@ async function cmdOpen() {
|
||||
die(`could not write the session state: ${written ? written.error : "unknown"}`, 1);
|
||||
}
|
||||
state = written.state;
|
||||
appendEvent(dir, { type: "open", resumed: Boolean(args.resume || args.session), carried });
|
||||
appendEvent(dir, { type: "open", resumed: Boolean(args.resume || args.session), carried, caps: ["subagents"] });
|
||||
// A new agent conversation has been told nothing yet (FR-6).
|
||||
try {
|
||||
resetSubagentCursor(dir);
|
||||
} catch {}
|
||||
trace("open: state written");
|
||||
|
||||
// Dashboard launches are recorded too (they score nothing), so the folder
|
||||
@@ -337,9 +346,18 @@ async function cmdOpen() {
|
||||
removeScratch(HOME_DIR, sweptScratch).catch(() => {});
|
||||
};
|
||||
|
||||
// A standing instruction the new agent is owed, as `subagents` and a
|
||||
// `reply` holding only its lines; neither key when nothing is owed.
|
||||
const subagentsOwed = () => {
|
||||
awaitSubagentSync(dir, state.workflow);
|
||||
const [out, cursor] = withSubagents(dir, { reply: "" });
|
||||
return [out.subagents ? out : {}, cursor];
|
||||
};
|
||||
|
||||
// Reuse a live server if one is already serving this session.
|
||||
if (existing && (await reusable)) {
|
||||
if (!args["no-open"]) openBrowser(existing.url);
|
||||
const [owed, subCursor] = subagentsOwed();
|
||||
print({
|
||||
ok: true,
|
||||
sid,
|
||||
@@ -349,9 +367,11 @@ async function cmdOpen() {
|
||||
pendingResult: carried,
|
||||
terminalLine: terminalLine(existing.url),
|
||||
workspace,
|
||||
...owed,
|
||||
...swept,
|
||||
...remoteWarning(),
|
||||
});
|
||||
advanceSubagents(dir, subCursor);
|
||||
sweep();
|
||||
return;
|
||||
}
|
||||
@@ -384,6 +404,7 @@ async function cmdOpen() {
|
||||
const notes = [];
|
||||
if (remote.note) notes.push(remote.note);
|
||||
if (carried) notes.push("Answers are already waiting. Run `wait` to collect them.");
|
||||
const [owed, subCursor] = subagentsOwed();
|
||||
print({
|
||||
ok: true,
|
||||
sid,
|
||||
@@ -394,10 +415,12 @@ async function cmdOpen() {
|
||||
pendingResult: carried,
|
||||
terminalLine: terminalLine(handle.url),
|
||||
workspace,
|
||||
...owed,
|
||||
...swept,
|
||||
...(remote.remote ? { remote: remote.remote } : {}),
|
||||
...(notes.length ? { note: notes.join(" ") } : {}),
|
||||
});
|
||||
advanceSubagents(dir, subCursor);
|
||||
// After the print, never before it: the page and the link wait for nothing.
|
||||
sweep();
|
||||
}
|
||||
@@ -774,7 +797,7 @@ function serverGone(sid) {
|
||||
|
||||
// Quick questions and nothing else: an ordinary exit 0 with no card actions.
|
||||
function deliverChat(dir, sid, entries, url) {
|
||||
const [out, changes] = withWorkspace(dir, {
|
||||
const [withWs, changes] = withWorkspace(dir, {
|
||||
type: "chat",
|
||||
at: nowIso(),
|
||||
sid,
|
||||
@@ -782,9 +805,11 @@ function deliverChat(dir, sid, entries, url) {
|
||||
chat: entries,
|
||||
reply: chatReplyLines(entries),
|
||||
});
|
||||
const [out, subCursor] = withSubagents(dir, withWs);
|
||||
print({ ...out, ...(url ? { terminalLine: terminalLine(url) } : {}) });
|
||||
advanceCursor(dir, entries);
|
||||
advanceWorkspace(dir, changes);
|
||||
advanceSubagents(dir, subCursor);
|
||||
process.exitCode = 0;
|
||||
}
|
||||
|
||||
@@ -806,6 +831,52 @@ function advanceWorkspace(dir, changes) {
|
||||
} catch {}
|
||||
}
|
||||
|
||||
// The server rewrites the session's setting for a new workflow only once its
|
||||
// watcher sees the state `open` just wrote, so a launch or hop that read the
|
||||
// file at once would find the old workflow's and owe the agent nothing until
|
||||
// its next pickup. Give the server a moment to catch up instead, never
|
||||
// writing the file ourselves (FR-7). A session with no setting file at all is
|
||||
// an older server, which never writes one: a short look, not the full wait.
|
||||
const SUBAGENT_SYNC_WAIT_MS = 1500;
|
||||
const SUBAGENT_SYNC_MISSING_MS = 250;
|
||||
function awaitSubagentSync(dir, workflow) {
|
||||
if (!offered(workflow)) return;
|
||||
const start = Date.now();
|
||||
for (;;) {
|
||||
const setting = readSubagentSetting(dir);
|
||||
if (setting && setting.workflow === workflow) return;
|
||||
const budget = setting ? SUBAGENT_SYNC_WAIT_MS : SUBAGENT_SYNC_MISSING_MS;
|
||||
if (Date.now() - start >= budget) return;
|
||||
sleepSync(25);
|
||||
}
|
||||
}
|
||||
|
||||
// The Subagents switch the agent is owed, added to what it is about to read:
|
||||
// the setting as `subagents`, and its lines last in `reply`, after card lines,
|
||||
// Quick questions and Workspace lines (FR-9). Read from the session's own
|
||||
// setting file only, which only the server writes (FR-7). A setting for
|
||||
// another workflow is the server not having caught up with a hop yet: it
|
||||
// rides on the next pickup instead.
|
||||
function withSubagents(dir, out) {
|
||||
const setting = readSubagentSetting(dir);
|
||||
if (!setting) return [out, null];
|
||||
const workflow = (readJson(path.join(dir, "state.json")) || {}).workflow;
|
||||
if (setting.workflow !== workflow) return [out, null];
|
||||
const block = blockFor(setting, readSubagentCursor(dir));
|
||||
if (!block) return [out, null];
|
||||
const reply = [out.reply, ...block.lines].filter(Boolean).join("\n");
|
||||
return [{ ...out, subagents: block.field, reply }, block.cursor];
|
||||
}
|
||||
|
||||
// After the print, like advanceWorkspace(): a kill in between repeats the
|
||||
// block at the next pickup, never loses it.
|
||||
function advanceSubagents(dir, cursor) {
|
||||
if (!cursor) return;
|
||||
try {
|
||||
writeSubagentCursor(dir, cursor);
|
||||
} catch {}
|
||||
}
|
||||
|
||||
// Print first, then this, exactly as consume() stamps a result: a kill in
|
||||
// between can only hand the same chat over again, and collectChat() drops
|
||||
// anything that already has a reply.
|
||||
@@ -832,15 +903,17 @@ async function cmdChat() {
|
||||
}
|
||||
const entries = deliverableChat(collectChat(dir, readJson(path.join(dir, "state.json")) || {}));
|
||||
const changes = pendingWorkspaceChanges(dir);
|
||||
if (!entries.length && !changes.length) {
|
||||
const reply = [chatReplyLines(entries), ...changes.map(changeLine)].filter(Boolean).join("\n");
|
||||
const [out, subCursor] = withSubagents(dir, { chat: entries, workspace: changes, reply });
|
||||
if (!entries.length && !changes.length && !subCursor) {
|
||||
print({ chat: [] });
|
||||
process.exitCode = 10;
|
||||
return;
|
||||
}
|
||||
const reply = [chatReplyLines(entries), ...changes.map(changeLine)].filter(Boolean).join("\n");
|
||||
print({ chat: entries, workspace: changes, reply, terminalLine: terminalLine(handle.url) });
|
||||
print({ ...out, terminalLine: terminalLine(handle.url) });
|
||||
advanceCursor(dir, entries);
|
||||
advanceWorkspace(dir, changes);
|
||||
advanceSubagents(dir, subCursor);
|
||||
process.exitCode = 0;
|
||||
}
|
||||
|
||||
@@ -865,7 +938,8 @@ function consume(dir, resultPath, result, url, chat = []) {
|
||||
// never on result.json itself.
|
||||
const withChat = { ...collected, chat };
|
||||
if (chat.length) withChat.reply = [collected.reply, chatReplyLines(chat)].filter(Boolean).join("\n");
|
||||
const [out, changes] = withWorkspace(dir, withChat);
|
||||
const [withWs, changes] = withWorkspace(dir, withChat);
|
||||
const [out, subCursor] = withSubagents(dir, withWs);
|
||||
print(url ? { ...out, terminalLine: terminalLine(url) } : out);
|
||||
try {
|
||||
writeJsonAtomic(resultPath, collected);
|
||||
@@ -874,6 +948,7 @@ function consume(dir, resultPath, result, url, chat = []) {
|
||||
ledgerAnswers(dir, result);
|
||||
advanceCursor(dir, chat);
|
||||
advanceWorkspace(dir, changes);
|
||||
advanceSubagents(dir, subCursor);
|
||||
process.exitCode = result.type === "cancel" ? 30 : 0;
|
||||
}
|
||||
|
||||
@@ -986,12 +1061,18 @@ port, and the filesystem as transport; this CLI is the whole agent surface.
|
||||
path, description?, original? }], missing? }, the folders this
|
||||
console session reads as context, addressed as @name. The list is
|
||||
remembered per folder and spec in workspaces.json beside looks.json.
|
||||
May also print subagents: { state, revision, max, instruction } and
|
||||
a reply holding only its "Subagents: ..." lines, when a standing
|
||||
instruction (the page's Subagents switch) is owed to you.
|
||||
post --session <sid> --file <patch.json>
|
||||
Merge a patch into the session. Prints terminalLine while the
|
||||
server is live. Exit 3 = rejected; stderr says why. A patch may
|
||||
carry run: { event, id, tasks? } (session meter points) and folderIssue:
|
||||
{ name, reason, hint? } (a workspace folder you could not read);
|
||||
both go to the ledger, never into the state.
|
||||
both go to the ledger, never into the state. A patch may also
|
||||
carry helpers: [{ id, title, ask, state, result? }] or one
|
||||
{ id: "alone", alone: true }, merged by id, for the Subagents tab
|
||||
(see console.md → Standing instructions).
|
||||
wait --session <sid> [--seconds <N>]
|
||||
A bounded wait slice, sized below your shell timeout. Exit 0 = the
|
||||
result is on stdout, 10 = still waiting ("Waiting on your answer
|
||||
@@ -1002,10 +1083,14 @@ port, and the filesystem as transport; this CLI is the whole agent surface.
|
||||
"workspace" (changes since you last heard, each once, with a
|
||||
"Workspace: ..." line in reply); exit 10 counts them as
|
||||
pendingWorkspace, and a change alone never ends a slice.
|
||||
Exit 0 may also carry "subagents" (a console setting, not typed
|
||||
by the person, with its "Subagents: ..." lines last in reply); a
|
||||
setting change alone never ends a slice either.
|
||||
chat --session <sid>
|
||||
Collect Quick questions and workspace changes now, never waiting,
|
||||
never touching card sends. Exit 0 = { chat, workspace, reply,
|
||||
terminalLine }, 10 = none, 20 = server gone.
|
||||
Collect Quick questions, workspace changes and a Subagents
|
||||
setting change now, never waiting, never touching card sends.
|
||||
Exit 0 = { chat, workspace, subagents?, reply, terminalLine },
|
||||
10 = none, 20 = server gone.
|
||||
terminalLine is "→ Look at the web console: <url>": end your terminal
|
||||
messages with it during a console session.
|
||||
keep --session <sid> --upload <path> --name <name> --spec specs/<idea> [--from <file>]
|
||||
|
||||
@@ -25,6 +25,7 @@ import { fileURLToPath } from "node:url";
|
||||
import { CHAT_LIMIT } from "./public/chat.js";
|
||||
import { DOC_TYPES } from "./public/answers.js";
|
||||
import { defaultName } from "./public/workspace.js";
|
||||
import { checkHelpers, cleanSetting, defaultSetting, offered } from "./public/subagents.js";
|
||||
|
||||
export const HERE = path.dirname(fileURLToPath(import.meta.url));
|
||||
export const PUBLIC_DIR = path.join(HERE, "public");
|
||||
@@ -491,9 +492,16 @@ export async function removeSessions(sessionsDir, sids) {
|
||||
}
|
||||
|
||||
// The console folder's own files that no sweep may ever remove: the person's
|
||||
// looks, the folders remembered per project and spec, the pointer to this
|
||||
// console's directory, and the cached release check.
|
||||
export const PROTECTED_CONSOLE_FILES = new Set(["looks.json", "workspaces.json", "console-dir", "update-check.json"]);
|
||||
// looks, the folders remembered per project and spec, the Subagents switch
|
||||
// saved per project and workflow, the pointer to this console's directory,
|
||||
// and the cached release check.
|
||||
export const PROTECTED_CONSOLE_FILES = new Set([
|
||||
"looks.json",
|
||||
"workspaces.json",
|
||||
"subagents.json",
|
||||
"console-dir",
|
||||
"update-check.json",
|
||||
]);
|
||||
|
||||
function isScratchName(name) {
|
||||
return (
|
||||
@@ -1142,6 +1150,19 @@ const DOC_DEFAULTS = { version: 1, stale: false, blocks: [] };
|
||||
// Blocks merge by id like docs do, so a patch that only settles a block's
|
||||
// state keeps its text. Blocks left out of the patch stay as they are.
|
||||
function mergeDocs(current, patchList) {
|
||||
// A doc's version only moves forward. One going back is a stale or copied
|
||||
// payload (last phase's progress script, say), and the page would quietly
|
||||
// show the old content under the new run's name.
|
||||
for (const entry of patchList) {
|
||||
if (!isPlainObject(entry) || typeof entry.version !== "number") continue;
|
||||
const prev = (current || []).find((d) => d && d.id === entry.id);
|
||||
if (prev && typeof prev.version === "number" && entry.version < prev.version) {
|
||||
throw new Error(
|
||||
`doc "${entry.id}" is at version ${prev.version} on the page; this patch sends version ${entry.version}. ` +
|
||||
"Versions only go up: bump it, and check the payload is the current one."
|
||||
);
|
||||
}
|
||||
}
|
||||
const merged = mergeKeyed(current, patchList, "id", DOC_DEFAULTS, "docs");
|
||||
for (const entry of patchList) {
|
||||
if (!Array.isArray(entry.blocks)) continue;
|
||||
@@ -1184,6 +1205,13 @@ export function applyPatch(state, patch) {
|
||||
if (!Array.isArray(v)) throw new Error('"topics" must be an array');
|
||||
next.topics = mergeKeyed(next.topics, v, "id", {}, "topics");
|
||||
break;
|
||||
case "helpers":
|
||||
// The agent's report of its helpers, for the page's Subagents tab.
|
||||
// Only `post` writes it; the server's /submit never touches it.
|
||||
if (!Array.isArray(v)) throw new Error('"helpers" must be an array');
|
||||
if (!v.every(isPlainObject)) throw new Error('"helpers" entries must be objects, each { id, title, ask, state }');
|
||||
next.helpers = mergeKeyed(next.helpers, v, "id", {}, "helpers");
|
||||
break;
|
||||
case "docs":
|
||||
if (!Array.isArray(v)) throw new Error('"docs" must be an array');
|
||||
next.docs = mergeDocs(next.docs, v);
|
||||
@@ -1478,6 +1506,20 @@ export function validate(state) {
|
||||
JSON.stringify(state.menu || {});
|
||||
problems.push(...proseProblems(prose));
|
||||
|
||||
// The agent's report of its helpers: the shape the page draws from
|
||||
// (subagents.js), then the same prose scan as everything else it writes.
|
||||
if (state.helpers != null) {
|
||||
problems.push(...checkHelpers(state.helpers));
|
||||
for (const helper of Array.isArray(state.helpers) ? state.helpers : []) {
|
||||
if (!isPlainObject(helper)) continue;
|
||||
for (const field of ["title", "ask", "result"]) {
|
||||
if (typeof helper[field] === "string") {
|
||||
problems.push(...proseProblems(helper[field], `helper "${helper.id}" ${field}`));
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
return problems;
|
||||
}
|
||||
|
||||
@@ -1507,7 +1549,8 @@ export function blankState({ sid, workflow, title, project, specDir }) {
|
||||
* A resume that passes through the dashboard (a finished skill going back to
|
||||
* it, or a launch from its menu) is a new skill taking the page over, so it
|
||||
* starts from a blank page: the last skill's questions, sections, docs,
|
||||
* headline and ending are its record on disk, not the next skill's opening.
|
||||
* helpers, headline and ending are its record on disk, not the next skill's
|
||||
* opening.
|
||||
* Only the session's identity carries across. `workspace.json`,
|
||||
* `ledger.ndjson` and the cursors live beside `state.json`, so the workspace
|
||||
* and the meter outlive every hop.
|
||||
@@ -1534,6 +1577,8 @@ export function switchWorkflow(state, { workflow, title, specDir }) {
|
||||
// workspace.json the server. Folders, version, change log, missing, remote.
|
||||
// ledger.ndjson console.mjs. Append-only meter events and folder issues.
|
||||
// workspace-cursor.json console.mjs. The last workspace version handed to the agent.
|
||||
// subagents-setting.json the server. The Subagents switch for this session, with its revision.
|
||||
// subagents-cursor.json console.mjs. The last Subagents revision and state handed to the agent.
|
||||
export const CHAT_FILE = "chat.ndjson";
|
||||
export const CHAT_CURSOR_FILE = "chat-cursor.json";
|
||||
export const WORKSPACE_FILE = "workspace.json";
|
||||
@@ -1989,6 +2034,98 @@ export function pendingWorkspaceChanges(dir) {
|
||||
return (readWorkspace(dir)?.changes || []).filter((c) => c.version > cursor);
|
||||
}
|
||||
|
||||
/* ------------------------------------------------------ the Subagents switch */
|
||||
|
||||
// The person's Subagents switch, remembered per project folder and workflow:
|
||||
//
|
||||
// { "<folded project path>": { "<workflow>": { on, instruction, max } } }
|
||||
//
|
||||
// Keyed with foldKey(), as workspaces.json is. `instruction: null` is the
|
||||
// workflow's shipped default.
|
||||
export const SUBAGENTS_FILE = path.join(HOME_DIR, "subagents.json");
|
||||
const SUBAGENTS_LOCK = "subagents.json.lock";
|
||||
|
||||
function readSubagentStore() {
|
||||
const saved = readJson(SUBAGENTS_FILE, null);
|
||||
return saved && typeof saved === "object" && !Array.isArray(saved) ? saved : {};
|
||||
}
|
||||
|
||||
// The saved `{ on, instruction, max }` for this folder and workflow, or the
|
||||
// default's when nothing (or something malformed) is saved.
|
||||
export function subagentStoreEntry(worktree, workflow) {
|
||||
const { on, instruction, max } = defaultSetting(workflow);
|
||||
const project = offered(workflow) ? readSubagentStore()[foldKey(worktree)] : null;
|
||||
const saved = project && typeof project === "object" ? cleanSetting(project[workflow]) : null;
|
||||
return saved && !saved.error ? saved : { on, instruction, max };
|
||||
}
|
||||
|
||||
// Single-writer rule: only server.mjs may call this.
|
||||
export function saveSubagentStoreEntry(worktree, workflow, value) {
|
||||
ensureDir(path.dirname(SUBAGENTS_FILE));
|
||||
withStateLock(
|
||||
path.dirname(SUBAGENTS_FILE),
|
||||
() => {
|
||||
const store = readSubagentStore();
|
||||
const key = foldKey(worktree);
|
||||
const project = store[key] && typeof store[key] === "object" ? store[key] : {};
|
||||
store[key] = { ...project, [workflow]: { on: value.on, instruction: value.instruction, max: value.max } };
|
||||
writeJsonAtomic(SUBAGENTS_FILE, store);
|
||||
},
|
||||
SUBAGENTS_LOCK
|
||||
);
|
||||
}
|
||||
|
||||
export const SUBAGENTS_SETTING_FILE = "subagents-setting.json";
|
||||
|
||||
const isCount = (n) => Number.isInteger(n) && n >= 0;
|
||||
|
||||
// This session's switch, `{ workflow, on, instruction, max, revision }`, or
|
||||
// null when there is none or it is malformed.
|
||||
export function readSubagentSetting(dir) {
|
||||
const s = readJson(path.join(dir, SUBAGENTS_SETTING_FILE), null);
|
||||
if (!s || typeof s !== "object") return null;
|
||||
if (typeof s.workflow !== "string" || typeof s.on !== "boolean" || !Number.isInteger(s.max) || !isCount(s.revision)) return null;
|
||||
return s;
|
||||
}
|
||||
|
||||
// Single-writer rule: only server.mjs may call this. The revision never goes
|
||||
// backwards within a session.
|
||||
export function writeSubagentSetting(dir, setting) {
|
||||
const previous = readSubagentSetting(dir);
|
||||
const revision = Math.max(previous ? previous.revision : 0, setting.revision);
|
||||
return writeJsonAtomic(path.join(dir, SUBAGENTS_SETTING_FILE), { ...setting, revision });
|
||||
}
|
||||
|
||||
export const SUBAGENTS_CURSOR_FILE = "subagents-cursor.json";
|
||||
const CURSOR_STATES = new Set(["none", "on", "off"]);
|
||||
|
||||
// What the agent was last told: `{ revision, state }`.
|
||||
export function readSubagentCursor(dir) {
|
||||
const saved = readJson(path.join(dir, SUBAGENTS_CURSOR_FILE), null);
|
||||
if (!saved || !isCount(saved.revision) || !CURSOR_STATES.has(saved.state)) return { revision: 0, state: "none" };
|
||||
return { revision: saved.revision, state: saved.state };
|
||||
}
|
||||
|
||||
// Single-writer rule: only console.mjs may call this. Never backwards, like
|
||||
// writeWorkspaceCursor(): a killed `wait` may repeat a change, never skip one.
|
||||
export function writeSubagentCursor(dir, cursor) {
|
||||
const old = readSubagentCursor(dir);
|
||||
const next = cursor.revision < old.revision ? old : { revision: cursor.revision, state: cursor.state };
|
||||
writeJsonAtomic(path.join(dir, SUBAGENTS_CURSOR_FILE), next);
|
||||
}
|
||||
|
||||
// The one place the cursor may go back: `open`, which starts a fresh agent.
|
||||
export function resetSubagentCursor(dir) {
|
||||
writeJsonAtomic(path.join(dir, SUBAGENTS_CURSOR_FILE), { revision: 0, state: "none" });
|
||||
}
|
||||
|
||||
// The `caps` of the last `open` event: what the agent's console copy can do.
|
||||
export function latestOpenCaps(dir) {
|
||||
const opens = readJsonLines(path.join(dir, "events.ndjson")).filter((e) => e.type === "open");
|
||||
const last = opens[opens.length - 1];
|
||||
return last && Array.isArray(last.caps) ? last.caps : [];
|
||||
}
|
||||
|
||||
/**
|
||||
* Flag the case where the link cannot be opened by the person it is for.
|
||||
*
|
||||
|
||||
@@ -208,6 +208,26 @@ body {
|
||||
.stop-btn:hover:not(:disabled) { color: var(--warn); border-color: var(--warn); }
|
||||
.brief-btn:hover:not(:disabled) { color: var(--accent); border-color: var(--accent-line); }
|
||||
|
||||
/* Subagents: an orchestrator and its helpers. Unlit is a hollow outline in
|
||||
the quiet ink; lit fills the nodes with the highlight color. */
|
||||
.subagents-btn { border-color: var(--rule-2); color: var(--ink-2); display: inline-flex; align-items: center; justify-content: center; }
|
||||
.btn.subagents-btn { padding: 0 6px; align-self: stretch; }
|
||||
.subagents-btn[hidden] { display: none; }
|
||||
.subagents-btn svg { width: 16px; height: 16px; display: block; }
|
||||
.subagents-btn .sa-link { fill: none; stroke: var(--ink-2); stroke-width: 1.2; stroke-linecap: round; }
|
||||
.subagents-btn .sa-hub { fill: none; stroke: var(--ink-2); stroke-width: 1.4; }
|
||||
.subagents-btn .sa-node { fill: none; stroke: var(--ink-2); stroke-width: 1.2; }
|
||||
.subagents-btn[aria-pressed="true"] .sa-hub,
|
||||
.subagents-btn[aria-pressed="true"] .sa-node { fill: var(--accent); stroke: var(--accent); }
|
||||
.subagents-btn[aria-pressed="true"] .sa-link { stroke: var(--accent); }
|
||||
.subagents-btn:hover:not(:disabled) { color: var(--accent); border-color: var(--accent-line); }
|
||||
.subagents-btn:hover:not(:disabled) .sa-link,
|
||||
.subagents-btn:hover:not(:disabled) .sa-hub,
|
||||
.subagents-btn:hover:not(:disabled) .sa-node { stroke: var(--accent); }
|
||||
.subagents-btn:disabled .sa-link,
|
||||
.subagents-btn:disabled .sa-hub,
|
||||
.subagents-btn:disabled .sa-node { stroke: var(--ink-3); fill: none; }
|
||||
|
||||
.ident { display: flex; align-items: baseline; gap: 12px; min-width: 0; }
|
||||
|
||||
/* The session meter: a ring that fills with the points and a few words, in
|
||||
@@ -1430,6 +1450,30 @@ h1 {
|
||||
.pill.done { background: var(--ok-soft); color: var(--ok); }
|
||||
.pill.staged { background: var(--stage-soft); color: var(--stage); }
|
||||
|
||||
/* The Subagents tab: one row per reported helper, newest state in a pill. */
|
||||
.sa-card h2 { margin: 0 0 6px; }
|
||||
.sa-card > .help { margin: 0 0 16px; }
|
||||
.sa-alone { margin: 0; color: var(--ink-2); }
|
||||
.sa-list { list-style: none; margin: 0; padding: 0; display: grid; gap: 10px; }
|
||||
.sa-row { border: 1px solid var(--rule); border-radius: 8px; background: var(--panel-2); padding: 12px 14px; }
|
||||
.sa-head { display: flex; align-items: center; justify-content: space-between; gap: 10px; }
|
||||
.sa-title { min-width: 0; overflow-wrap: anywhere; }
|
||||
.sa-ask {
|
||||
margin: 4px 0 0; color: var(--ink-2); font-size: 13.5px;
|
||||
display: -webkit-box; -webkit-box-orient: vertical; -webkit-line-clamp: 2; line-clamp: 2; overflow: hidden;
|
||||
}
|
||||
.sa-result { margin: 8px 0 0; padding-top: 8px; border-top: 1px solid var(--rule); font-size: 13.5px; }
|
||||
.sa-pill { display: inline-flex; align-items: center; gap: 6px; flex: none; }
|
||||
.sa-pill.is-running { background: var(--accent-soft); color: var(--accent); border-color: var(--accent-line); }
|
||||
.sa-pill.is-done { background: var(--ok-soft); color: var(--ok); }
|
||||
.sa-pill.is-failed { background: var(--warn-soft); color: var(--warn); }
|
||||
.sa-pill .spinner.tiny { width: 10px; height: 10px; }
|
||||
/* The dialog's number box, themed like the page's other inputs. */
|
||||
.subagents input[type="number"] {
|
||||
width: 5em; font: inherit; color: var(--ink); background: var(--panel-2);
|
||||
border: 1px solid var(--rule-2); border-radius: 6px; padding: 4px 8px;
|
||||
}
|
||||
|
||||
/* ------------------------------------------------------ settled answer */
|
||||
|
||||
.answered {
|
||||
@@ -1971,6 +2015,8 @@ h4.md-h, h5.md-h, h6.md-h { font-size: 15px; }
|
||||
cursor: pointer;
|
||||
}
|
||||
.footer-where:hover { text-decoration: underline; }
|
||||
/* The project name, in the person's highlight color. */
|
||||
.where-project { color: var(--accent); font-weight: 600; }
|
||||
/* A folder is missing or the agent could not read one: the dialog says which. */
|
||||
.where-alert {
|
||||
display: inline-block; width: 7px; height: 7px; margin-left: 6px;
|
||||
|
||||
@@ -103,6 +103,15 @@ import { FOOTER_TIERS, footerLabel, nameProblem } from "./workspace.js";
|
||||
import { RED_BANNER } from "./meter.js";
|
||||
import { applyMention, matchNames, mentionAt } from "./mentions.js";
|
||||
import { faviconState, setFavicon } from "./favicon.js";
|
||||
import {
|
||||
CHECKIN_LINE,
|
||||
PATHFINDER_RESEARCH_LINE,
|
||||
defaultInstruction,
|
||||
helperRows,
|
||||
showSwitch,
|
||||
showTab,
|
||||
switchLabel,
|
||||
} from "./subagents.js";
|
||||
|
||||
const $ = (id) => document.getElementById(id);
|
||||
|
||||
@@ -530,6 +539,9 @@ let meterFrame = null;
|
||||
// The frame's update ({ installed, latest }), present only when a newer
|
||||
// release is out; null otherwise.
|
||||
let updateFrame = null;
|
||||
// The frame's Subagents switch ({ offered, supported, on, instruction, max,
|
||||
// revision }), or null before a server that sends it.
|
||||
let subagentsFrame = null;
|
||||
let chatDot = false;
|
||||
let chatSending = false;
|
||||
let chatResetting = false;
|
||||
@@ -880,6 +892,8 @@ function adopt(body) {
|
||||
if (body.meter) meterFrame = body.meter;
|
||||
// Always replaced: an absent key means no update.
|
||||
updateFrame = body.update || null;
|
||||
// Always replaced too: an older server sends none, and then there is no switch.
|
||||
subagentsFrame = body.subagents || null;
|
||||
lastContact = Date.now();
|
||||
if (gone) {
|
||||
gone = false;
|
||||
@@ -1301,6 +1315,7 @@ function render() {
|
||||
renderChrome();
|
||||
renderStatus();
|
||||
renderBriefButton();
|
||||
renderSubagentsButton();
|
||||
renderStopButton();
|
||||
renderHomeButton();
|
||||
tabAdded = renderViews();
|
||||
@@ -1566,7 +1581,7 @@ function renderChrome() {
|
||||
renderMeter();
|
||||
$("title").textContent = S.title || "Session";
|
||||
$("badge").textContent = workflowLabel(S.workflow);
|
||||
document.title = (S.title || "Session") + " · #" + String(S.sid || "").slice(-6) + " · Plan2Code";
|
||||
renderTabTitle();
|
||||
|
||||
const h = S.headline || {};
|
||||
// On a finished session an open item is frozen: the send on it counts as
|
||||
@@ -1835,6 +1850,69 @@ function renderBriefButton() {
|
||||
if (offer) btn.disabled = gone || pendingResult;
|
||||
}
|
||||
|
||||
// Shown only where the skill opts in and the agent's console copy can deliver
|
||||
// it. Lit while helpers are on; a click opens the dialog, never toggles.
|
||||
function renderSubagentsButton() {
|
||||
const btn = $("btn-subagents");
|
||||
const offer = showSwitch(subagentsFrame);
|
||||
btn.hidden = !offer;
|
||||
if (!offer) return;
|
||||
const label = switchLabel(subagentsFrame);
|
||||
btn.setAttribute("aria-pressed", String(Boolean(subagentsFrame.on)));
|
||||
btn.title = label;
|
||||
btn.setAttribute("aria-label", label);
|
||||
btn.disabled = gone;
|
||||
}
|
||||
|
||||
// The Subagents dialog, filled from the frame each time it opens. A null
|
||||
// instruction is the shipped default, shown as its text so it can be edited.
|
||||
function openSubagents() {
|
||||
if (!showSwitch(subagentsFrame)) return;
|
||||
const on = Boolean(subagentsFrame.on);
|
||||
for (const radio of document.querySelectorAll('input[name="subagents-on"]')) {
|
||||
radio.checked = radio.value === (on ? "on" : "off");
|
||||
}
|
||||
$("subagents-instruction").value = subagentsFrame.instruction ?? defaultInstruction(S.workflow);
|
||||
$("subagents-max").value = String(subagentsFrame.max);
|
||||
$("subagents-checkin").textContent = CHECKIN_LINE;
|
||||
const research = $("subagents-research");
|
||||
research.textContent = PATHFINDER_RESEARCH_LINE;
|
||||
research.hidden = S.workflow !== "pathfinder";
|
||||
$("subagents-status").textContent = "";
|
||||
$("subagents-save").disabled = false;
|
||||
$("subagents-modal").showModal();
|
||||
const checked = document.querySelector('input[name="subagents-on"]:checked');
|
||||
if (checked) checked.focus();
|
||||
}
|
||||
|
||||
const SUBAGENTS_ERRORS = {
|
||||
max: "Pick a number from 1 to 20.",
|
||||
"too-long": "The instruction is over 2,000 characters.",
|
||||
"not-offered": "This skill doesn't use helpers.",
|
||||
bad: "That didn't save. Try again.",
|
||||
};
|
||||
const SUBAGENTS_LOST = "Lost contact with Plan2Code. Try again once it's back.";
|
||||
|
||||
async function saveSubagents() {
|
||||
const save = $("subagents-save");
|
||||
const status = $("subagents-status");
|
||||
const picked = document.querySelector('input[name="subagents-on"]:checked');
|
||||
const text = $("subagents-instruction").value.trim();
|
||||
// The shipped default is stored as null, so a later release's wording
|
||||
// reaches everyone who never changed it.
|
||||
const instruction = text === defaultInstruction(S.workflow) ? null : text;
|
||||
const body = { on: Boolean(picked && picked.value === "on"), instruction, max: Number($("subagents-max").value) };
|
||||
save.disabled = true;
|
||||
status.textContent = "";
|
||||
const res = await postJson("/subagents", body);
|
||||
save.disabled = false;
|
||||
// The next state frame redraws the button.
|
||||
if (res.status === 200) return $("subagents-modal").close();
|
||||
if (res.status === 400) status.textContent = SUBAGENTS_ERRORS[res.body && res.body.error] || SUBAGENTS_ERRORS.bad;
|
||||
else if (res.status === 403 || res.status === 0) status.textContent = SUBAGENTS_LOST;
|
||||
else status.textContent = SUBAGENTS_ERRORS.bad;
|
||||
}
|
||||
|
||||
function renderViews() {
|
||||
const nav = $("views");
|
||||
nav.replaceChildren();
|
||||
@@ -1850,6 +1928,14 @@ function renderViews() {
|
||||
if (hasOverview) tabs.push({ id: "overview", label: "Overview", count: 0 });
|
||||
else if (view === "overview") view = "questions";
|
||||
for (const d of docs()) tabs.push({ id: "doc:" + d.id, label: d.title || "Document", count: 0 });
|
||||
// The helpers the agent reported, from the first one on; cleared by a
|
||||
// dashboard hop, which sends the person home like the Overview tab does.
|
||||
if (showTab(subagentsFrame, S.helpers)) {
|
||||
// From the rows the tab draws, so the badge never counts helpers the
|
||||
// working-alone note hides.
|
||||
const running = helperRows(S.helpers).rows.filter((r) => r.state === "running").length;
|
||||
tabs.push({ id: "subagents", label: "Subagents", count: running });
|
||||
} else if (view === "subagents") view = "questions";
|
||||
// Always last, on every workflow and after a finish: the Quick question chat.
|
||||
// The ring left of "Ask" shows exactly when the conversation's own ring does:
|
||||
// a question the agent picked up and has not answered yet.
|
||||
@@ -2130,6 +2216,7 @@ function paintMain(main) {
|
||||
if (view.startsWith("doc:")) return renderDoc(main, view.slice(4));
|
||||
if (view === "overview") return renderOverview(main);
|
||||
if (view === "ask") return renderAsk(main);
|
||||
if (view === "subagents") return renderSubagents(main);
|
||||
|
||||
// The session's own page, reached from the PAUSED / SESSION ENDED item at
|
||||
// the top of the rail. The hand-off lives here alone now, rather than
|
||||
@@ -4774,6 +4861,42 @@ function renderOverview(main) {
|
||||
main.appendChild(box);
|
||||
}
|
||||
|
||||
// The helpers the agent reported, as it last posted them. Everything here is
|
||||
// the agent's text, so it goes in as text, never as markup.
|
||||
function renderSubagents(main) {
|
||||
const card = el("section", "card sa-card");
|
||||
card.appendChild(el("h2", null, "Subagents"));
|
||||
card.appendChild(el("p", "help", CHECKIN_LINE));
|
||||
const { alone, rows } = helperRows(S.helpers);
|
||||
if (alone) {
|
||||
card.appendChild(
|
||||
el("p", "sa-alone", "Working alone: your agent has no way to start helpers here, so it is doing this skill's work itself.")
|
||||
);
|
||||
main.appendChild(card);
|
||||
return;
|
||||
}
|
||||
const list = el("ul", "sa-list");
|
||||
for (const row of rows) {
|
||||
const item = el("li", "sa-row");
|
||||
const head = el("div", "sa-head");
|
||||
head.appendChild(el("strong", "sa-title", row.title));
|
||||
const pill = el("span", "pill sa-pill is-" + row.state);
|
||||
if (row.state === "running") {
|
||||
const spin = el("span", "spinner tiny");
|
||||
spin.setAttribute("aria-hidden", "true");
|
||||
pill.appendChild(spin);
|
||||
}
|
||||
pill.appendChild(document.createTextNode(row.stateLabel));
|
||||
head.appendChild(pill);
|
||||
item.appendChild(head);
|
||||
item.appendChild(el("p", "sa-ask", row.ask));
|
||||
if (row.result) item.appendChild(el("p", "sa-result", row.result));
|
||||
list.appendChild(item);
|
||||
}
|
||||
card.appendChild(list);
|
||||
main.appendChild(card);
|
||||
}
|
||||
|
||||
/* ---------------------------------------------------------------- ask */
|
||||
|
||||
// The frame's chat block, with `offline` worked out now rather than when the
|
||||
@@ -5956,10 +6079,30 @@ const workspaceFolders = () => (wsFrame && Array.isArray(wsFrame.folders) ? wsFr
|
||||
// session opened before the server wrote `worktree` has nothing to show, so
|
||||
// the slot stays hidden. The footer renders on every tick, so the DOM is only
|
||||
// touched when the labels change, or when a resize clears the key.
|
||||
// The project's name: the workspace's original folder, or the session's
|
||||
// worktree folder before a frame carries the workspace.
|
||||
function projectName() {
|
||||
const folders = workspaceFolders();
|
||||
if (folders.length && folders[0].name) return folders[0].name;
|
||||
const path = (S && S.worktree) || "";
|
||||
return path ? path.split(/[\\/]/).filter(Boolean).pop() || path : "";
|
||||
}
|
||||
|
||||
// The browser tab's title, led by the project so tabs from different
|
||||
// projects are told apart. Called from the chrome and the footer, since the
|
||||
// workspace frame can arrive after either.
|
||||
function renderTabTitle() {
|
||||
if (!S) return;
|
||||
const name = projectName();
|
||||
document.title =
|
||||
(name ? name + " · " : "") + (S.title || "Session") + " · #" + String(S.sid || "").slice(-6) + " · Plan2Code";
|
||||
}
|
||||
|
||||
function renderWhere() {
|
||||
const b = $("footer-where");
|
||||
const folders = workspaceFolders();
|
||||
const path = S.worktree || "";
|
||||
renderTabTitle();
|
||||
const alert = Boolean(folders.length && ((wsFrame.missing || []).length || (wsFrame.issues || []).length));
|
||||
const labels = folders.length
|
||||
? Array.from({ length: FOOTER_TIERS }, (_, tier) => footerLabel({ folders, branch: S.branch }, tier))
|
||||
@@ -5972,7 +6115,16 @@ function renderWhere() {
|
||||
let label = labels[0];
|
||||
for (const text of labels) {
|
||||
label = text;
|
||||
b.textContent = text;
|
||||
// The project name takes the highlight color, so several consoles side by
|
||||
// side tell apart at a glance; the rest of the label stays quiet.
|
||||
const name = projectName();
|
||||
b.textContent = "";
|
||||
if (name && text.startsWith(name)) {
|
||||
b.appendChild(el("span", "where-project", name));
|
||||
b.appendChild(document.createTextNode(text.slice(name.length)));
|
||||
} else {
|
||||
b.textContent = text;
|
||||
}
|
||||
if (alert) {
|
||||
const dot = el("span", "where-alert");
|
||||
dot.setAttribute("aria-hidden", "true");
|
||||
@@ -7197,6 +7349,7 @@ function lightDismiss(dlg) {
|
||||
});
|
||||
}
|
||||
lightDismiss($("looks-modal"));
|
||||
lightDismiss($("subagents-modal"));
|
||||
lightDismiss($("help-modal"));
|
||||
lightDismiss($("workspace-modal"));
|
||||
lightDismiss($("welcome-modal"));
|
||||
@@ -7499,6 +7652,13 @@ $("cleanup-scan").addEventListener("click", scanCleanup);
|
||||
$("cleanup-delete").addEventListener("click", deleteCleanup);
|
||||
|
||||
$("btn-brief").addEventListener("click", openBrief);
|
||||
$("btn-subagents").addEventListener("click", openSubagents);
|
||||
$("subagents-default").addEventListener("click", () => {
|
||||
$("subagents-instruction").value = defaultInstruction(S.workflow);
|
||||
});
|
||||
$("subagents-save").addEventListener("click", saveSubagents);
|
||||
$("subagents-cancel").addEventListener("click", () => $("subagents-modal").close());
|
||||
$("subagents-modal").addEventListener("close", () => $("btn-subagents").focus());
|
||||
$("brief-cancel").addEventListener("click", () => $("brief-modal").close());
|
||||
$("brief-go").addEventListener("click", sendBrief);
|
||||
for (const radio of document.querySelectorAll('input[name="brief-range"]')) {
|
||||
|
||||
@@ -19,6 +19,7 @@ export const HELP_TABS = Object.freeze([
|
||||
tab("dashboard", "The dashboard", true),
|
||||
tab("meter", "Session meter", false),
|
||||
tab("build", "Watching a build", false),
|
||||
tab("subagents", "Helpers (subagents)", false),
|
||||
tab("ask", "Ask a quick question", false),
|
||||
tab("finishing", "Stopping and finishing", false),
|
||||
tab("stuck", "When something looks stuck", true),
|
||||
@@ -39,6 +40,7 @@ export function helpTabFor({ view, dashboard, gone, adrift, finished, workflow,
|
||||
if (gone || adrift) return "stuck";
|
||||
if (workspace) return "workspace";
|
||||
if (v === "ask") return "ask";
|
||||
if (v === "subagents") return "subagents";
|
||||
if (dashboard && meterRed) return "meter";
|
||||
if (dashboard) return "dashboard";
|
||||
if (v === "overview" || v.startsWith("doc:")) return "docs";
|
||||
|
||||
@@ -21,6 +21,7 @@
|
||||
<link rel="modulepreload" href="/starters.js" />
|
||||
<link rel="modulepreload" href="/workspace.js" />
|
||||
<link rel="modulepreload" href="/meter.js" />
|
||||
<link rel="modulepreload" href="/subagents.js" />
|
||||
<link rel="modulepreload" href="/mentions.js" />
|
||||
<link rel="modulepreload" href="/favicon.js" />
|
||||
<link rel="modulepreload" href="/vendor/marked.esm.js" />
|
||||
@@ -172,6 +173,18 @@
|
||||
<button type="button" class="btn ghost small brief-btn" id="btn-brief" hidden>
|
||||
Write a brief
|
||||
</button>
|
||||
<!-- Subagents: opted-in skills only. Lit while helpers are on; a click
|
||||
opens the Subagents dialog and never toggles them itself. -->
|
||||
<button type="button" class="btn ghost small subagents-btn" id="btn-subagents" aria-pressed="false" hidden>
|
||||
<!-- An orchestrator and its helpers: one larger node linked to three smaller ones. -->
|
||||
<svg viewBox="0 0 16 16" aria-hidden="true" focusable="false">
|
||||
<path class="sa-link" d="M6.9 6.6L10.9 3.9M7.4 8h3.5M6.9 9.4l4 2.7" />
|
||||
<circle cx="4.6" cy="8" r="2.6" class="sa-hub" />
|
||||
<circle cx="12.4" cy="3" r="1.5" class="sa-node" />
|
||||
<circle cx="12.4" cy="8" r="1.5" class="sa-node" />
|
||||
<circle cx="12.4" cy="13" r="1.5" class="sa-node" />
|
||||
</svg>
|
||||
</button>
|
||||
</div>
|
||||
<div class="views-group">
|
||||
<span class="views-arrow" aria-hidden="true">
|
||||
@@ -580,6 +593,13 @@
|
||||
<rect x="3" y="9" width="18" height="6" rx="3" />
|
||||
<path d="M6 12h7" />
|
||||
</symbol>
|
||||
<symbol id="hi-subagents" viewBox="0 0 24 24" fill="none">
|
||||
<circle cx="7" cy="12" r="3.5" />
|
||||
<circle cx="18" cy="5" r="2" />
|
||||
<circle cx="18" cy="12" r="2" />
|
||||
<circle cx="18" cy="19" r="2" />
|
||||
<path d="M10 10l6-4M10.5 12H16M10 14l6 4" />
|
||||
</symbol>
|
||||
<symbol id="hi-ask" viewBox="0 0 24 24" fill="none">
|
||||
<path d="M4 5h16v11H10l-4 4v-4H4z" />
|
||||
<path d="M8 9.5h8M8 12.5h5" />
|
||||
@@ -1477,7 +1497,61 @@
|
||||
</p>
|
||||
</section>
|
||||
|
||||
<!-- Tab 12: Ask a quick question -->
|
||||
<!-- Tab 12: Helpers (subagents) -->
|
||||
<section class="help-panel" data-tab="subagents">
|
||||
<h3>Helpers (subagents)</h3>
|
||||
<p>
|
||||
On a build, a review and Pathfinder, Plan2Code can hand independent
|
||||
pieces of work to helpers (subagents) while it keeps the conversation
|
||||
with you. The <strong>Subagents</strong> button in the top bar, after
|
||||
Stop session, is lit while helpers are on.
|
||||
</p>
|
||||
<h4>The switch</h4>
|
||||
<ul>
|
||||
<li>
|
||||
Clicking the button opens the <strong>Subagents</strong> dialog; it
|
||||
never switches helpers on or off by itself. Pick <strong>Use
|
||||
helpers</strong> or <strong>Work alone</strong>, edit the instruction
|
||||
Plan2Code follows (<strong>Reset to default</strong> puts the
|
||||
shipped one back), and say how many may run at once.
|
||||
</li>
|
||||
<li>
|
||||
It is off by default and saved for this project and this skill, so
|
||||
the next session of the same skill here starts the same way.
|
||||
</li>
|
||||
<li>
|
||||
The change reaches Plan2Code at its next check-in, as a setting,
|
||||
not as something you typed. How many helpers it can really start is
|
||||
up to your agent; some have no helpers at all.
|
||||
</li>
|
||||
<li>The button only appears on skills that use helpers, and only when Plan2Code can pass the setting on.</li>
|
||||
</ul>
|
||||
<h4>The Subagents tab</h4>
|
||||
<ul>
|
||||
<li>
|
||||
With the first helper, a <strong>Subagents</strong> tab appears before
|
||||
Ask: one row each, with what it was asked, whether it is running, done
|
||||
or failed, and a one-line result at the end. The number on the tab is
|
||||
how many are still running.
|
||||
</li>
|
||||
<li>
|
||||
Helpers report through Plan2Code, so the rows change at its
|
||||
check-ins, not live. The page cannot stop a helper; ask Plan2Code
|
||||
on the Ask tab if one should stop.
|
||||
</li>
|
||||
<li>
|
||||
<strong>Working alone</strong> means your agent has no way to start
|
||||
helpers here, so it is doing the work itself.
|
||||
</li>
|
||||
<li>
|
||||
Pathfinder always uses helpers for its research questions, whatever
|
||||
the switch says, and they show here too.
|
||||
</li>
|
||||
<li>The tab clears when you go back to the dashboard.</li>
|
||||
</ul>
|
||||
</section>
|
||||
|
||||
<!-- Tab 13: Ask a quick question -->
|
||||
<section class="help-panel" data-tab="ask">
|
||||
<h3>Ask a quick question</h3>
|
||||
<p class="help-lead">
|
||||
@@ -1568,7 +1642,7 @@
|
||||
</p>
|
||||
</section>
|
||||
|
||||
<!-- Tab 13: Stopping and finishing -->
|
||||
<!-- Tab 14: Stopping and finishing -->
|
||||
<section class="help-panel" data-tab="finishing">
|
||||
<h3>Stopping and finishing</h3>
|
||||
<p class="help-lead">
|
||||
@@ -1650,7 +1724,7 @@
|
||||
</p>
|
||||
</section>
|
||||
|
||||
<!-- Tab 14: When something looks stuck -->
|
||||
<!-- Tab 15: When something looks stuck -->
|
||||
<section class="help-panel" data-tab="stuck">
|
||||
<h3>When something looks stuck</h3>
|
||||
<p class="help-lead">
|
||||
@@ -1772,7 +1846,7 @@
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<!-- Tab 15: Keyboard and preferences -->
|
||||
<!-- Tab 16: Keyboard and preferences -->
|
||||
<section class="help-panel" data-tab="prefs">
|
||||
<h3>Keyboard and preferences</h3>
|
||||
<p class="help-lead">
|
||||
@@ -1888,7 +1962,7 @@
|
||||
</ul>
|
||||
</section>
|
||||
|
||||
<!-- Tab 16: Privacy and where things are saved -->
|
||||
<!-- Tab 17: Privacy and where things are saved -->
|
||||
<section class="help-panel" data-tab="privacy">
|
||||
<h3>Privacy and where things are saved</h3>
|
||||
<p class="help-lead">
|
||||
@@ -1925,7 +1999,11 @@
|
||||
</li>
|
||||
<li>
|
||||
your role, theme, colors, card width and sounds, in
|
||||
<code>looks.json</code>.
|
||||
<code>looks.json</code>;
|
||||
</li>
|
||||
<li>
|
||||
your Subagents switch for each project and skill, in
|
||||
<code>subagents.json</code>.
|
||||
</li>
|
||||
</ul>
|
||||
<p>
|
||||
@@ -2039,6 +2117,46 @@
|
||||
</div>
|
||||
</dialog>
|
||||
|
||||
<!-- Subagents: the switch for this skill, filled from the frame's
|
||||
`subagents` by app.js and saved through POST /subagents. It borrows
|
||||
the User Preferences dialog's classes, so it needs no dialog styles of
|
||||
its own, only a themed number box. -->
|
||||
<dialog class="modal looks subagents" id="subagents-modal" aria-labelledby="subagents-title">
|
||||
<h2 id="subagents-title">Subagents</h2>
|
||||
<p class="modal-blurb">
|
||||
Let Plan2Code hand independent work to helpers in this skill. Saved for this
|
||||
project and this skill.
|
||||
</p>
|
||||
<fieldset class="modal-ranges looks-row">
|
||||
<legend>Helpers</legend>
|
||||
<label><input type="radio" name="subagents-on" value="on" /> <span>Use helpers</span></label>
|
||||
<label><input type="radio" name="subagents-on" value="off" checked /> <span>Work alone</span></label>
|
||||
</fieldset>
|
||||
<fieldset class="modal-ranges">
|
||||
<legend>Instruction</legend>
|
||||
<textarea id="subagents-instruction" rows="4" maxlength="2000" aria-label="Instruction"></textarea>
|
||||
<div class="models-actions">
|
||||
<button type="button" class="btn small ghost" id="subagents-default">Reset to default</button>
|
||||
<span class="help">Passed to the agent as written, at its next check-in.</span>
|
||||
</div>
|
||||
</fieldset>
|
||||
<fieldset class="modal-ranges">
|
||||
<legend>At most</legend>
|
||||
<label>
|
||||
<input type="number" id="subagents-max" min="1" max="20" step="1" aria-label="At most this many helpers at once" />
|
||||
<span>helpers at once</span>
|
||||
</label>
|
||||
<p class="help">Advisory: your agent's own limit still applies.</p>
|
||||
</fieldset>
|
||||
<p class="help" id="subagents-checkin"></p>
|
||||
<p class="help" id="subagents-research" hidden></p>
|
||||
<p class="help" id="subagents-status" role="status"></p>
|
||||
<div class="modal-actions">
|
||||
<button type="button" class="btn ghost" id="subagents-cancel">Cancel</button>
|
||||
<button type="button" class="btn primary" id="subagents-save">Save</button>
|
||||
</div>
|
||||
</dialog>
|
||||
|
||||
<!-- The Workspace: the folder this session started in plus any added as
|
||||
context. The list is drawn by app.js from the frame's `workspace`;
|
||||
every change goes through the server's /workspace routes. -->
|
||||
|
||||
@@ -0,0 +1,223 @@
|
||||
// Plan2Code Web Console - the Subagents switch's opt-in table, wording and checks.
|
||||
//
|
||||
// The source of truth for which workflows offer the switch, the instruction
|
||||
// each one ships with, the fixed frame every "on" block carries, the exact
|
||||
// lines the agent reads at a pickup (blockFor()), and the house rules for the
|
||||
// helpers an agent reports back (checkHelper()). No DOM access at module scope
|
||||
// and no imports: the server, console.mjs, the page and `node --test` all
|
||||
// import this file.
|
||||
|
||||
// The one place a skill opts in (FR-1). Wording is behaviour-level and names
|
||||
// no harness tool, so any agent can follow it or harmlessly ignore it.
|
||||
export const SUBAGENT_WORKFLOWS = Object.freeze({
|
||||
implement: Object.freeze({
|
||||
instruction:
|
||||
"Hand independent tasks in a phase to helpers: tasks that touch different files and do not depend on each other. Keep tasks that share files, the phase's tests and the sign-off with you.",
|
||||
}),
|
||||
"implement-review": Object.freeze({
|
||||
instruction:
|
||||
"Hand independent tasks in a phase to helpers: tasks that touch different files and do not depend on each other. Keep tasks that share files, the phase's tests and the sign-off with you.",
|
||||
}),
|
||||
"quick-task": Object.freeze({
|
||||
instruction:
|
||||
"Use helpers for side lookups, such as reading unfamiliar code or checking documentation, while you make the change yourself.",
|
||||
}),
|
||||
review: Object.freeze({
|
||||
instruction:
|
||||
"Split the review across helpers by area (for example correctness, tests and security), then merge and de-duplicate their findings yourself before you report.",
|
||||
}),
|
||||
pathfinder: Object.freeze({
|
||||
instruction:
|
||||
"Use helpers for codebase recon, sketches and lookups beside the conversation. Keep every question for the person with you.",
|
||||
}),
|
||||
});
|
||||
|
||||
export function offered(workflow) {
|
||||
return typeof workflow === "string" && Object.prototype.hasOwnProperty.call(SUBAGENT_WORKFLOWS, workflow);
|
||||
}
|
||||
|
||||
export const MAX_MIN = 1;
|
||||
export const MAX_MAX = 20;
|
||||
export const DEFAULT_MAX = 3;
|
||||
export const INSTRUCTION_MAX_CHARS = 2000;
|
||||
export const HELPER_TITLE_MAX = 80;
|
||||
export const HELPER_ASK_MAX = 400;
|
||||
export const HELPER_RESULT_MAX = 200;
|
||||
export const HELPER_STATES = Object.freeze(["running", "done", "failed"]);
|
||||
|
||||
/* ------------------------------------------------------------- settings */
|
||||
|
||||
export function defaultInstruction(workflow) {
|
||||
return offered(workflow) ? SUBAGENT_WORKFLOWS[workflow].instruction : "";
|
||||
}
|
||||
|
||||
// The person's own text when they wrote some, else the workflow's default.
|
||||
export function effectiveInstruction(setting) {
|
||||
const own = setting && typeof setting.instruction === "string" ? setting.instruction.trim() : "";
|
||||
return own || defaultInstruction(setting && setting.workflow);
|
||||
}
|
||||
|
||||
export function defaultSetting(workflow) {
|
||||
return { workflow, on: false, instruction: null, max: DEFAULT_MAX };
|
||||
}
|
||||
|
||||
/**
|
||||
* `{ on, instruction, max }` from untrusted input, or `{ error }` naming the
|
||||
* field that failed: "bad" (wrong type), "too-long" (instruction) or "max".
|
||||
* Returns an error object rather than throwing, so the route and the store
|
||||
* reader share one validator. An empty instruction means the default: null.
|
||||
*/
|
||||
export function cleanSetting(input) {
|
||||
if (!input || typeof input !== "object" || Array.isArray(input)) return { error: "bad" };
|
||||
if (typeof input.on !== "boolean") return { error: "bad" };
|
||||
let instruction = null;
|
||||
if (input.instruction !== null && input.instruction !== undefined) {
|
||||
if (typeof input.instruction !== "string") return { error: "bad" };
|
||||
const trimmed = input.instruction.trim();
|
||||
if (trimmed.length > INSTRUCTION_MAX_CHARS) return { error: "too-long" };
|
||||
instruction = trimmed || null;
|
||||
}
|
||||
const max = input.max;
|
||||
if (!Number.isInteger(max) || max < MAX_MIN || max > MAX_MAX) return { error: "max" };
|
||||
return { on: input.on, instruction, max };
|
||||
}
|
||||
|
||||
/* ------------------------------------------------------------ the lines */
|
||||
|
||||
// The non-editable part of every "on" block (FR-8).
|
||||
export const FRAME_LINES = Object.freeze([
|
||||
"Hand independent work to helpers if your tools allow it; otherwise carry on alone.",
|
||||
"Report each helper on the page (console.md → Standing instructions); questions for the person stay with you.",
|
||||
'With no way to start helpers, report one "working alone" entry for this skill run instead.',
|
||||
]);
|
||||
|
||||
export const PATHFINDER_RESEARCH_LINE = "Research questions always use helpers, whatever this switch says.";
|
||||
|
||||
// Only the first line of a block starts at column 0, so no line inside it can
|
||||
// be read as an entry of its own (NFR-5).
|
||||
export function onLines({ revision, replaces, max, instruction }) {
|
||||
const label = replaces ? `revision ${revision}, replaces revision ${replaces}` : `revision ${revision}`;
|
||||
const own = String(instruction || "")
|
||||
.split("\n")
|
||||
.map((line) => line.trimEnd())
|
||||
.filter((line) => line.trim());
|
||||
return [
|
||||
`Subagents: on (${label}) — a console setting, not typed by the person.`,
|
||||
...[...FRAME_LINES, ...own, `At most ${max} helpers at once.`].map((line) => " " + line),
|
||||
];
|
||||
}
|
||||
|
||||
export function offLine(revision) {
|
||||
return `Subagents: off (revision ${revision}) — don't start new helpers for the rest of this session.`;
|
||||
}
|
||||
|
||||
/**
|
||||
* What the agent is owed at a pickup, given the session setting and the
|
||||
* cursor of what it was last told: `null`, or `{ field, lines, cursor }`
|
||||
* where `cursor` is what to write once the lines are printed. Never says
|
||||
* "off" to an agent that was not told "on" (FR-6). Pure: no clock, no I/O.
|
||||
*/
|
||||
export function blockFor(setting, told) {
|
||||
const last = told || { revision: 0, state: "none" };
|
||||
if (!setting || !offered(setting.workflow) || !(setting.revision > last.revision)) return null;
|
||||
const { revision, max } = setting;
|
||||
const instruction = effectiveInstruction(setting);
|
||||
if (setting.on) {
|
||||
const replaces = last.state === "on" ? last.revision : undefined;
|
||||
return {
|
||||
field: { state: "on", revision, max, instruction },
|
||||
lines: onLines({ revision, replaces, max, instruction }),
|
||||
cursor: { revision, state: "on" },
|
||||
};
|
||||
}
|
||||
if (last.state !== "on") return null;
|
||||
return {
|
||||
field: { state: "off", revision, max, instruction },
|
||||
lines: [offLine(revision)],
|
||||
cursor: { revision, state: "off" },
|
||||
};
|
||||
}
|
||||
|
||||
/* ------------------------------------------------------------ helpers */
|
||||
|
||||
const isPlainObject = (v) => !!v && typeof v === "object" && !Array.isArray(v);
|
||||
const nonEmpty = (v) => typeof v === "string" && v.trim() !== "";
|
||||
|
||||
// The problems with one reported helper, [] when it is fine.
|
||||
export function checkHelper(entry) {
|
||||
if (!isPlainObject(entry)) return ["helper: each entry must be an object"];
|
||||
if (!nonEmpty(entry.id)) return ["helper: id must be a non-empty string"];
|
||||
const who = `helper "${entry.id}"`;
|
||||
if (entry.alone === true) return entry.id === "alone" ? [] : [`${who}: the working-alone entry must have id "alone"`];
|
||||
const problems = [];
|
||||
if (!nonEmpty(entry.title)) problems.push(`${who}: title must be a non-empty string`);
|
||||
else if (entry.title.length > HELPER_TITLE_MAX) problems.push(`${who}: title must be at most ${HELPER_TITLE_MAX} characters`);
|
||||
if (!nonEmpty(entry.ask)) problems.push(`${who}: ask must be a non-empty string`);
|
||||
else if (entry.ask.length > HELPER_ASK_MAX) problems.push(`${who}: ask must be at most ${HELPER_ASK_MAX} characters`);
|
||||
if (!HELPER_STATES.includes(entry.state)) problems.push(`${who}: state must be running, done or failed`);
|
||||
if (entry.result !== undefined) {
|
||||
if (typeof entry.result !== "string") problems.push(`${who}: result must be a string`);
|
||||
else if (entry.result.length > HELPER_RESULT_MAX) problems.push(`${who}: result must be at most ${HELPER_RESULT_MAX} characters`);
|
||||
}
|
||||
return problems;
|
||||
}
|
||||
|
||||
// The problems with a whole merged list.
|
||||
export function checkHelpers(list) {
|
||||
if (!Array.isArray(list)) return ["helpers must be an array"];
|
||||
const problems = [];
|
||||
const seen = new Set();
|
||||
let alone = 0;
|
||||
for (const entry of list) {
|
||||
if (isPlainObject(entry) && nonEmpty(entry.id)) {
|
||||
if (seen.has(entry.id)) problems.push(`helper "${entry.id}": duplicate id`);
|
||||
seen.add(entry.id);
|
||||
if (entry.alone === true && ++alone === 2) problems.push(`helper "${entry.id}": only one working-alone entry is allowed`);
|
||||
}
|
||||
problems.push(...checkHelper(entry));
|
||||
}
|
||||
return problems;
|
||||
}
|
||||
|
||||
/* ------------------------------------------------------------ the page */
|
||||
|
||||
// The page's rules for the button, the modal and the tab, kept here so they
|
||||
// are tested without a browser. `frame` is the state frame's `subagents`
|
||||
// block; app.js only renders what these say.
|
||||
|
||||
export const CHECKIN_LINE = "Helpers report through Plan2Code, so their progress shows here at its check-ins, not live.";
|
||||
|
||||
const STATE_LABELS = Object.freeze({ running: "Running", done: "Done", failed: "Failed" });
|
||||
|
||||
// The switch shows only where the skill opts in AND the agent's console copy
|
||||
// said it can deliver it (FR-3).
|
||||
export function showSwitch(frame) {
|
||||
return Boolean(frame && frame.offered && frame.supported);
|
||||
}
|
||||
|
||||
// The button's tooltip and accessible name (FR-2).
|
||||
export function switchLabel(frame) {
|
||||
return frame && frame.on ? "Subagents: on" : "Subagents: off";
|
||||
}
|
||||
|
||||
// What the Subagents tab draws: the working-alone note, or one row per helper
|
||||
// in the order the agent reported them. A result shows once the helper ended.
|
||||
export function helperRows(helpers) {
|
||||
const list = Array.isArray(helpers) ? helpers.filter(isPlainObject) : [];
|
||||
if (list.some((h) => h.alone === true)) return { alone: true, rows: [] };
|
||||
const rows = list.map(({ id, title, ask, state, result }) => ({
|
||||
id,
|
||||
title,
|
||||
ask,
|
||||
state,
|
||||
stateLabel: STATE_LABELS[state] || STATE_LABELS.running,
|
||||
...((state === "done" || state === "failed") && typeof result === "string" && result ? { result } : {}),
|
||||
}));
|
||||
return { alone: false, rows };
|
||||
}
|
||||
|
||||
// Never an empty tab. Independent of on / off, so Pathfinder's research
|
||||
// helpers show even with the switch off (FR-11, FR-12).
|
||||
export function showTab(frame, helpers) {
|
||||
return showSwitch(frame) && Array.isArray(helpers) && helpers.length > 0;
|
||||
}
|
||||
@@ -25,6 +25,7 @@ import {
|
||||
LOOKS_FILE,
|
||||
PUBLIC_DIR,
|
||||
SHIPPED_MODELS_FILE,
|
||||
SUBAGENTS_SETTING_FILE,
|
||||
UPDATE_CHECK_FILE,
|
||||
USER_MODELS_FILE,
|
||||
WORKSPACE_FILE,
|
||||
@@ -38,6 +39,7 @@ import {
|
||||
fileStamp,
|
||||
handleFile,
|
||||
initialWorkspace,
|
||||
latestOpenCaps,
|
||||
nowIso,
|
||||
parseArgs,
|
||||
pendingChatCount,
|
||||
@@ -46,20 +48,25 @@ import {
|
||||
readJson,
|
||||
readLedger,
|
||||
readOverview,
|
||||
readSubagentSetting,
|
||||
readWorkspace,
|
||||
rememberWorkspace,
|
||||
rememberedWorkspace,
|
||||
removeCleanup,
|
||||
remoteWarning,
|
||||
saveSubagentStoreEntry,
|
||||
specKey,
|
||||
subagentStoreEntry,
|
||||
typedCount,
|
||||
withStateLock,
|
||||
writeJsonAtomic,
|
||||
writeSubagentSetting,
|
||||
writeWorkspace,
|
||||
} from "./lib.mjs";
|
||||
import { DOC_TYPES, MAX_ATTACHMENTS, MAX_DOC_BYTES, docExt, workflowLabel, workflowTitle } from "./public/answers.js";
|
||||
import { CHAT_LIMIT, CHAT_MAX_CHARS, chatOffline } from "./public/chat.js";
|
||||
import { meterView } from "./public/meter.js";
|
||||
import { cleanSetting, defaultSetting, offered } from "./public/subagents.js";
|
||||
import { ACCENTS, DEFAULT_ACCENT, DEFAULT_CARD_WIDTH, cardWidth } from "./public/palette.js";
|
||||
import { defaultName, freeName, nameProblem } from "./public/workspace.js";
|
||||
import { checkForUpdate } from "./update-check.mjs";
|
||||
@@ -212,6 +219,7 @@ const SERVABLE = new Set([
|
||||
"starters.js",
|
||||
"workspace.js",
|
||||
"meter.js",
|
||||
"subagents.js",
|
||||
"mentions.js",
|
||||
"favicon.js",
|
||||
"start-stop.mp3",
|
||||
@@ -601,6 +609,48 @@ function ensureConversation(state) {
|
||||
if (entry) appendEvent(DIR, { type: "chat-reset", reason: entry.reason });
|
||||
}
|
||||
|
||||
/* ------------------------------------------------------------ subagents */
|
||||
|
||||
// subagents-setting.json has one writer, this server, and the agent hears of
|
||||
// it only through what console.mjs reads there; events.ndjson's latest `open`
|
||||
// says whether the agent's console copy can carry it. Both re-read only when
|
||||
// their file has moved.
|
||||
const SUBAGENTS_SETTING_PATH = path.join(DIR, SUBAGENTS_SETTING_FILE);
|
||||
const EVENTS_PATH = path.join(DIR, "events.ndjson");
|
||||
|
||||
let subagentSettingSeen = { stamp: null, setting: null };
|
||||
function subagentSettingNow() {
|
||||
const stamp = fileStamp(SUBAGENTS_SETTING_PATH);
|
||||
if (stamp !== subagentSettingSeen.stamp) subagentSettingSeen = { stamp, setting: readSubagentSetting(DIR) };
|
||||
return subagentSettingSeen.setting;
|
||||
}
|
||||
|
||||
let capsSeen = { stamp: null, caps: [] };
|
||||
function openCapsNow() {
|
||||
const stamp = fileStamp(EVENTS_PATH);
|
||||
if (stamp !== capsSeen.stamp) capsSeen = { stamp, caps: latestOpenCaps(DIR) };
|
||||
return capsSeen.caps;
|
||||
}
|
||||
|
||||
const sameSetting = (a, b) => a.workflow === b.workflow && a.on === b.on && a.instruction === b.instruction && a.max === b.max;
|
||||
|
||||
/**
|
||||
* Turn the per-project store into this session's setting, for the workflow
|
||||
* the session is in now. The only place that happens (FR-7): a session an
|
||||
* older server ran has no setting file, so nothing is ever injected into it.
|
||||
* A record that already matches is left alone, revision and all, so a
|
||||
* restart alone never re-tells the agent anything.
|
||||
*/
|
||||
function syncSubagentSetting(state) {
|
||||
if (!state || typeof state.workflow !== "string") return;
|
||||
const { workflow } = state;
|
||||
const { on, instruction, max } = offered(workflow) ? subagentStoreEntry(sessionWorktree(), workflow) : defaultSetting(workflow);
|
||||
const target = { workflow, on, instruction, max };
|
||||
const current = readSubagentSetting(DIR);
|
||||
if (current && sameSetting(current, target)) return;
|
||||
writeSubagentSetting(DIR, { ...target, revision: (current ? current.revision : 0) + 1 });
|
||||
}
|
||||
|
||||
// What the page needs to draw itself, in the shape of the SSE state frame.
|
||||
// `have` names that exact view, for the page to hand back when it opens its
|
||||
// stream (see /events).
|
||||
@@ -615,20 +665,33 @@ function stateFrame(state) {
|
||||
chat: { ...chatForFrame(chatEntries(), state), pickedUp: chatPickedUp(), offline: chatOfflineNow(state) },
|
||||
workspace: workspaceView(),
|
||||
meter: meterView(ledgerEntries()),
|
||||
subagents: subagentsView(state),
|
||||
...(updateInfo ? { update: updateInfo } : {}),
|
||||
have: haveKey(),
|
||||
};
|
||||
}
|
||||
|
||||
// The page shows the switch only when `offered && supported` (FR-3); the
|
||||
// frame says both and leaves combining them to the page. `instruction: null`
|
||||
// is the shipped default, which the page reads from subagents.js itself.
|
||||
function subagentsView(state) {
|
||||
const workflow = state && state.workflow;
|
||||
const { on, instruction, max, revision } = subagentSettingNow() || { ...defaultSetting(workflow), revision: 0 };
|
||||
return { offered: offered(workflow), supported: openCapsNow().includes("subagents"), on, instruction, max, revision };
|
||||
}
|
||||
|
||||
function haveKey() {
|
||||
const { pending, stop } = resultFlags();
|
||||
chatEntries();
|
||||
chatPickedUp();
|
||||
workspaceNow();
|
||||
ledgerEntries();
|
||||
subagentSettingNow();
|
||||
openCapsNow();
|
||||
return (
|
||||
`${STARTED}.${rev}.${pending ? 1 : 0}${stop ? 1 : 0}.${chatSeen.stamp || ""}.${cursorSeen.stamp || ""}` +
|
||||
`.${workspaceSeen.stamp || ""}.${ledgerSeen.stamp || ""}.${updateInfo ? updateInfo.latest : ""}`
|
||||
`.${workspaceSeen.stamp || ""}.${ledgerSeen.stamp || ""}.${updateInfo ? updateInfo.latest : ""}` +
|
||||
`.${subagentSettingSeen.stamp || ""}.${capsSeen.stamp || ""}`
|
||||
);
|
||||
}
|
||||
|
||||
@@ -1172,6 +1235,39 @@ const server = http.createServer((req, res) => {
|
||||
});
|
||||
}
|
||||
|
||||
// The Subagents switch for the session's workflow. Saved per project folder
|
||||
// for the next session, and applied to this one with a bumped revision, which
|
||||
// is what console.mjs hands the agent at its next pickup. Never blocked by,
|
||||
// and never blocking, a card send.
|
||||
if (pathname === "/subagents" && req.method === "POST") {
|
||||
if (!originOk(req, port)) return json(res, 403, { error: "bad origin" });
|
||||
return readBody(req, (err, body) => {
|
||||
if (err) return json(res, err.tooBig ? 413 : 400, { error: err.tooBig ? "too large" : "body must be JSON" });
|
||||
const state = readState();
|
||||
if (!state || !offered(state.workflow)) return json(res, 400, { error: "not-offered" });
|
||||
const clean = cleanSetting(body);
|
||||
if (clean.error) return json(res, 400, { error: clean.error });
|
||||
const { on, instruction, max } = clean;
|
||||
const current = readSubagentSetting(DIR);
|
||||
const next = { workflow: state.workflow, on, instruction, max };
|
||||
// The store is per project, so another session may have moved it since
|
||||
// this one synced: it always takes the person's latest pick. Only a
|
||||
// real change to this session's setting bumps what the agent hears.
|
||||
const unchanged = Boolean(current && sameSetting(current, next));
|
||||
try {
|
||||
saveSubagentStoreEntry(sessionWorktree(), state.workflow, { on, instruction, max });
|
||||
if (!unchanged) writeSubagentSetting(DIR, { ...next, revision: (current ? current.revision : 0) + 1 });
|
||||
} catch (e) {
|
||||
return json(res, 500, { error: String(e.message) });
|
||||
}
|
||||
if (unchanged) return json(res, 200, { ok: true, setting: current });
|
||||
const setting = readSubagentSetting(DIR);
|
||||
appendEvent(DIR, { type: "subagents", on, revision: setting.revision });
|
||||
pushState();
|
||||
return json(res, 200, { ok: true, setting });
|
||||
});
|
||||
}
|
||||
|
||||
// The launcher's model menu: what ships (read-only here) and what the user added.
|
||||
if (pathname === "/models" && req.method === "GET") {
|
||||
const saved = readJson(USER_MODELS_FILE, null) || {};
|
||||
@@ -1400,6 +1496,9 @@ const server = http.createServer((req, res) => {
|
||||
try {
|
||||
ensureConversation(written.state);
|
||||
} catch {}
|
||||
try {
|
||||
syncSubagentSetting(written.state);
|
||||
} catch {}
|
||||
}
|
||||
}
|
||||
// Name the items that went. A page with OTHER answers staged should drop
|
||||
@@ -1726,6 +1825,9 @@ function checkState() {
|
||||
try {
|
||||
ensureConversation(parsed);
|
||||
} catch {}
|
||||
try {
|
||||
syncSubagentSetting(parsed);
|
||||
} catch {}
|
||||
try {
|
||||
followSpecDir(parsed);
|
||||
} catch {}
|
||||
@@ -1900,6 +2002,9 @@ function onListening(port) {
|
||||
try {
|
||||
bootWorkspace();
|
||||
} catch {}
|
||||
try {
|
||||
syncSubagentSetting(readState());
|
||||
} catch {}
|
||||
process.stdout.write(JSON.stringify({ type: "ready", url, port, sid: SID }) + "\n");
|
||||
try {
|
||||
startUpdateCheck();
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "Plan2Code",
|
||||
"version": "2.4.2",
|
||||
"version": "2.5.0",
|
||||
"description": "A structured 4-step workflow methodology for AI-assisted software development",
|
||||
"keywords": [
|
||||
"ai",
|
||||
@@ -17,6 +17,6 @@
|
||||
"url": "https://github.com/jparkerweb/plan2code"
|
||||
},
|
||||
"homepage": "https://github.com/jparkerweb/plan2code",
|
||||
"releaseDate": "2026-10-05",
|
||||
"releaseDate": "2026-10-06",
|
||||
"mode": "utility"
|
||||
}
|
||||
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "Plan2Code",
|
||||
"version": "2.4.2",
|
||||
"version": "2.5.0",
|
||||
"description": "A structured 4-step workflow methodology for AI-assisted software development",
|
||||
"keywords": [
|
||||
"ai",
|
||||
@@ -17,6 +17,6 @@
|
||||
"url": "https://github.com/jparkerweb/plan2code"
|
||||
},
|
||||
"homepage": "https://github.com/jparkerweb/plan2code",
|
||||
"releaseDate": "2026-10-05",
|
||||
"releaseDate": "2026-10-06",
|
||||
"mode": "utility"
|
||||
}
|
||||
@@ -64,6 +64,13 @@ progress bar is the first thing someone watching a build looks at. The session
|
||||
meter counts the build's tasks from `cleared` as it rises, so keep it current,
|
||||
and start every phase (a second one in the same run too) at `"cleared": 0`.
|
||||
|
||||
`"version": 1` is for the first phase of a session only. A doc's version
|
||||
never goes back (console.md → House rules, rule 9), so a later phase in the
|
||||
same session reposts `phase` and `phasefile` at one more than the version the
|
||||
page holds, with the new phase's title and content. The same goes for
|
||||
`report` at sign-off and `review` in a mid-session review: version 1 the
|
||||
first time, then up from wherever the page has it.
|
||||
|
||||
`phasefile` is the whole `phase-X.md`, verbatim from disk, as its own tab —
|
||||
the person can read the prerequisites and task specs while you build. Re-post
|
||||
it whenever the file changes, which is every task: the checkbox write that
|
||||
@@ -111,6 +118,12 @@ printed), never into the project or into `~/.plan2code/console/` directly:
|
||||
- Do not call `wait` while building. There is nothing to collect, and the page
|
||||
holds anything the person sends until you next look.
|
||||
|
||||
A build may receive a `Subagents:` standing instruction, on `open` output or a
|
||||
`chat` check between tasks. Follow console.md → Standing instructions for
|
||||
handing independent tasks to helpers and reporting them as `helpers`. Keep the
|
||||
per-task progress posts, the checkbox writes, the chat checks and the sign-off
|
||||
with you.
|
||||
|
||||
### Quick questions between tasks
|
||||
|
||||
The person can ask a Quick question on the Ask tab at any point in a build
|
||||
@@ -195,7 +208,8 @@ only ever be offered once nothing could come of it:
|
||||
`reply` carries `Approve this phase: approved`, which is the terminal's
|
||||
`approved`. If the note that came with an approval asks for a change, treat it
|
||||
as "describe any issues": do the change first and ask again. `changes` means
|
||||
exactly what it says: address it, bump the report's version, and reopen the
|
||||
exactly what it says: address it, bump the report's version (a later phase's
|
||||
report starts above the last one's, too), and reopen the
|
||||
item (`"status": "reopened"`) with a reply in its `thread`. `review` is the
|
||||
person asking for the code review before they approve anything — see "The
|
||||
review, mid-session" below.
|
||||
|
||||
@@ -170,7 +170,7 @@ so even a kill at the worst possible moment costs you a repeat, never an answer.
|
||||
|
||||
| Exit | Meaning | What you do |
|
||||
| --- | --- | --- |
|
||||
| `0` | They pressed Send, or asked a Quick question. stdout is the result JSON, and may carry `workspace` (changes to the folder list, see Workspace). | Handle the cards (if any), the chat (if any) and any `workspace` changes, then post once (below, Quick questions and Workspace). |
|
||||
| `0` | They pressed Send, or asked a Quick question. stdout is the result JSON, and may carry `workspace` (changes to the folder list, see Workspace) and `subagents` (the helpers switch, see Standing instructions). | Handle the cards (if any), the chat (if any), any `workspace` changes and any `subagents` block, then post once (below, Quick questions, Workspace and Standing instructions). |
|
||||
| `10` | Still working. stdout has a short progress summary; `pendingWorkspace` counts workspace changes waiting for the next send. | Relay ONE line: the `message` field itself, "Waiting on your answer in the web console", followed by the `terminalLine`. Then call `wait` again. |
|
||||
| `20` | The server is gone. | `open --resume <sid>`, give them the new link, then keep waiting. |
|
||||
| `30` | They pressed Cancel. | Stop. Ask what they want to do, in the terminal. |
|
||||
@@ -647,6 +647,84 @@ for permission is not a failure; report only a read that failed after it.
|
||||
|
||||
---
|
||||
|
||||
## Standing instructions
|
||||
|
||||
On the skills that offer it (`implement`, `implement-review`, `quick-task`,
|
||||
`review`, `pathfinder`), the person can turn **helpers** (subagents) on or off
|
||||
from the top bar's Subagents button. Their pick is saved per project and per
|
||||
skill, off by default, and reaches you as a standing instruction, only when it
|
||||
changes.
|
||||
|
||||
### What arrives
|
||||
|
||||
A `subagents` field beside `reply`, and `Subagents:` lines last in `reply`,
|
||||
after the card lines, the `Quick question:` blocks and the `Workspace:` lines.
|
||||
It rides on `wait` exit `0`, `chat` exit `0` and `open` output. A setting
|
||||
change alone never ends a `wait` slice: it waits for the next send, or for
|
||||
your next `chat` check.
|
||||
|
||||
```
|
||||
Subagents: on (revision 2) — a console setting, not typed by the person.
|
||||
Hand independent work to helpers if your tools allow it; otherwise carry on alone.
|
||||
Report each helper on the page (console.md → Standing instructions); questions for the person stay with you.
|
||||
With no way to start helpers, report one "working alone" entry for this skill run instead.
|
||||
Hand independent tasks in a phase to helpers: tasks that touch different files and do not depend on each other. Keep tasks that share files, the phase's tests and the sign-off with you.
|
||||
At most 3 helpers at once.
|
||||
```
|
||||
|
||||
beside `"subagents": { "state": "on", "revision": 2, "max": 3, "instruction": "…" }`.
|
||||
An edit while on arrives as `Subagents: on (revision 3, replaces revision 2) — …`
|
||||
with the whole block again; switching off arrives as one line:
|
||||
`Subagents: off (revision 4) — don't start new helpers for the rest of this session.`
|
||||
|
||||
It is a console setting, not something the person typed. It never answers a
|
||||
card, and it is never recorded under `specs/`.
|
||||
|
||||
### Obeying it
|
||||
|
||||
- **On:** hand independent work to helpers if your tools allow it, at most
|
||||
`max` at once, following the instruction lines. `max` is advisory: your
|
||||
harness's own limit still applies.
|
||||
- **A higher revision replaces a lower one.** Follow the latest block only.
|
||||
- **Off:** start no new helpers for the rest of the session. Let running ones
|
||||
finish and report them.
|
||||
- **Nothing arrives:** keep doing what the skill says.
|
||||
- **Scope is the skill run it arrived in.** After a dashboard launch, no block
|
||||
means the switch is off for this skill, even if an earlier skill in the same
|
||||
conversation was told "on": `open` starts the count again, and a launch with
|
||||
the switch off sends nothing.
|
||||
|
||||
### Reporting helpers
|
||||
|
||||
Post them, at your check-ins, so the page's Subagents tab can show them. The
|
||||
page never hears from a helper directly:
|
||||
|
||||
```jsonc
|
||||
{ "helpers": [
|
||||
{ "id": "h1", "title": "Read the store helpers", "ask": "Find every caller of readSubagentSetting.", "state": "running" },
|
||||
{ "id": "h2", "title": "Check the tests", "ask": "Run the subagents tests and report failures.", "state": "done", "result": "All 9 pass." }
|
||||
] }
|
||||
```
|
||||
|
||||
- `id` (non-empty), `title` (at most 80 characters), `ask` (at most 400) and
|
||||
`state` (`running`, `done` or `failed`) are required; `result` (at most 200)
|
||||
is the one line you add once a helper ends.
|
||||
- Merged by `id`: post a helper again with its new `state` and `result` and it
|
||||
updates in place. `"helpers": null` clears the list. A dashboard hop clears it
|
||||
too; a resume into the same skill keeps it.
|
||||
- One post per change worth seeing, not a stream.
|
||||
- Questions for the person stay with you, never with a helper: most harnesses
|
||||
give helpers no way to ask, and an answer only reaches the agent holding the
|
||||
session.
|
||||
- **No way to start helpers?** Post one `{ "id": "alone", "alone": true }`
|
||||
entry for the skill run instead. The tab then says you are working alone.
|
||||
- **Pathfinder:** research questions always use helpers and are always
|
||||
reported, whatever the switch says. The switch governs recon, sketches and
|
||||
lookups beside the conversation.
|
||||
- Helpers add no session meter points. Post no `run` for them.
|
||||
|
||||
---
|
||||
|
||||
## Launches (dashboard only)
|
||||
|
||||
A `dashboard` session is not a conversation: the page draws a menu of every
|
||||
@@ -763,7 +841,10 @@ commands follow the pipeline: the sign-off's is
|
||||
|
||||
### Review (`review`)
|
||||
|
||||
Scope questions up front, then the findings report as a doc (`id: "report"`),
|
||||
Scope questions up front — run standalone with nothing named, the first is
|
||||
a `choice`, "What should I review?", built from a quick scan (branch changes,
|
||||
uncommitted changes, specs, files you name; each option with its size),
|
||||
never an assumed target; a build's review skips it (`building.md`). Then the findings report as a doc (`id: "report"`),
|
||||
then the pick-what-gets-fixed menu as a `multi` or `choice` keyed by finding
|
||||
id, carrying `"doc": "report"` so the card links straight to the findings.
|
||||
Settle that item (`"status": "answered"` plus the `answer` they sent) in
|
||||
@@ -797,6 +878,8 @@ that is what the person is there to download. The finish carries no
|
||||
- Chart Step 8's research subagents must all report back before the
|
||||
finish (Finishing → Nothing of yours may still be running); the finish
|
||||
body then names what each one found.
|
||||
- Report every research subagent as a helper, whatever the Subagents switch
|
||||
says (Standing instructions → Reporting helpers).
|
||||
- At every session end, post `finish` (headline, `body`, and Form A's command as
|
||||
`command`) BEFORE `stop`. Someone who spent the session in the browser never
|
||||
sees the Trail Footer, and without this their last screen promises a question
|
||||
@@ -1146,6 +1229,16 @@ A patch that breaks one of these is rejected with exit `3` and a message:
|
||||
(Session meter) and a non-empty `id`; a `folderIssue` needs non-empty
|
||||
`name` and `reason` strings, and `hint`, when present, is one too. Rules 4
|
||||
and 5 cover `reason` and `hint`.
|
||||
8. **`helpers` entries are well formed** (Standing instructions → Reporting
|
||||
helpers): an array of objects, each with a unique `id`, a `title`, an `ask`
|
||||
and a known `state` within their limits, plus at most one `alone` entry.
|
||||
Rules 4 and 5 cover `title`, `ask` and `result`.
|
||||
9. **A doc's `version` never goes back.** Sending a known doc a lower
|
||||
`version` than the page holds is refused: it is almost always a stale or
|
||||
copied payload. The same version again is fine, and a dashboard hop starts
|
||||
every doc fresh. Anything else reusing a doc id in the same session (a
|
||||
build's second phase, a second report or review) continues from the
|
||||
version the page holds.
|
||||
|
||||
These are workflow rules you already follow. The server just makes them checkable.
|
||||
|
||||
@@ -1167,7 +1260,9 @@ cannot see them, and the moment it says the session ended, the person is
|
||||
free to close that terminal and kill them mid-write. While you wait, post
|
||||
`{"agent":{"status":"working","activity":"Researching 3 questions (1 of 3 back)"}}`
|
||||
and update the count as each returns. Never write a `finish.body` that says
|
||||
work "is running in the background" or "will finish on its own".
|
||||
work "is running in the background" or "will finish on its own". Mark every
|
||||
reported helper `done` or `failed` before the finish, so the Subagents tab
|
||||
never ends on a row still running.
|
||||
|
||||
### 1. Post the finish
|
||||
|
||||
|
||||
@@ -64,6 +64,8 @@ import {
|
||||
readChat,
|
||||
readJson,
|
||||
readLedger,
|
||||
readSubagentCursor,
|
||||
readSubagentSetting,
|
||||
readWorkspace,
|
||||
reapHandles,
|
||||
rememberedWorkspace,
|
||||
@@ -71,6 +73,7 @@ import {
|
||||
removeScratch,
|
||||
removeSessions,
|
||||
repoRoots,
|
||||
resetSubagentCursor,
|
||||
scanProject,
|
||||
SESSION_MAX_AGE_MS,
|
||||
sessionDir,
|
||||
@@ -88,9 +91,11 @@ import {
|
||||
workspaceForAgent,
|
||||
writeCursor,
|
||||
writeJsonAtomic,
|
||||
writeSubagentCursor,
|
||||
writeWorkspaceCursor,
|
||||
} from "./lib.mjs";
|
||||
import { RUN_EVENTS, TASK_EVENTS, MAX_TASKS, isTaskCount, progressEntry } from "./public/meter.js";
|
||||
import { blockFor, offered } from "./public/subagents.js";
|
||||
import { changeLine } from "./public/workspace.js";
|
||||
|
||||
// Mirrors the server's absolute lifetime cap: a handle older than this cannot
|
||||
@@ -310,7 +315,11 @@ async function cmdOpen() {
|
||||
die(`could not write the session state: ${written ? written.error : "unknown"}`, 1);
|
||||
}
|
||||
state = written.state;
|
||||
appendEvent(dir, { type: "open", resumed: Boolean(args.resume || args.session), carried });
|
||||
appendEvent(dir, { type: "open", resumed: Boolean(args.resume || args.session), carried, caps: ["subagents"] });
|
||||
// A new agent conversation has been told nothing yet (FR-6).
|
||||
try {
|
||||
resetSubagentCursor(dir);
|
||||
} catch {}
|
||||
trace("open: state written");
|
||||
|
||||
// Dashboard launches are recorded too (they score nothing), so the folder
|
||||
@@ -337,9 +346,18 @@ async function cmdOpen() {
|
||||
removeScratch(HOME_DIR, sweptScratch).catch(() => {});
|
||||
};
|
||||
|
||||
// A standing instruction the new agent is owed, as `subagents` and a
|
||||
// `reply` holding only its lines; neither key when nothing is owed.
|
||||
const subagentsOwed = () => {
|
||||
awaitSubagentSync(dir, state.workflow);
|
||||
const [out, cursor] = withSubagents(dir, { reply: "" });
|
||||
return [out.subagents ? out : {}, cursor];
|
||||
};
|
||||
|
||||
// Reuse a live server if one is already serving this session.
|
||||
if (existing && (await reusable)) {
|
||||
if (!args["no-open"]) openBrowser(existing.url);
|
||||
const [owed, subCursor] = subagentsOwed();
|
||||
print({
|
||||
ok: true,
|
||||
sid,
|
||||
@@ -349,9 +367,11 @@ async function cmdOpen() {
|
||||
pendingResult: carried,
|
||||
terminalLine: terminalLine(existing.url),
|
||||
workspace,
|
||||
...owed,
|
||||
...swept,
|
||||
...remoteWarning(),
|
||||
});
|
||||
advanceSubagents(dir, subCursor);
|
||||
sweep();
|
||||
return;
|
||||
}
|
||||
@@ -384,6 +404,7 @@ async function cmdOpen() {
|
||||
const notes = [];
|
||||
if (remote.note) notes.push(remote.note);
|
||||
if (carried) notes.push("Answers are already waiting. Run `wait` to collect them.");
|
||||
const [owed, subCursor] = subagentsOwed();
|
||||
print({
|
||||
ok: true,
|
||||
sid,
|
||||
@@ -394,10 +415,12 @@ async function cmdOpen() {
|
||||
pendingResult: carried,
|
||||
terminalLine: terminalLine(handle.url),
|
||||
workspace,
|
||||
...owed,
|
||||
...swept,
|
||||
...(remote.remote ? { remote: remote.remote } : {}),
|
||||
...(notes.length ? { note: notes.join(" ") } : {}),
|
||||
});
|
||||
advanceSubagents(dir, subCursor);
|
||||
// After the print, never before it: the page and the link wait for nothing.
|
||||
sweep();
|
||||
}
|
||||
@@ -774,7 +797,7 @@ function serverGone(sid) {
|
||||
|
||||
// Quick questions and nothing else: an ordinary exit 0 with no card actions.
|
||||
function deliverChat(dir, sid, entries, url) {
|
||||
const [out, changes] = withWorkspace(dir, {
|
||||
const [withWs, changes] = withWorkspace(dir, {
|
||||
type: "chat",
|
||||
at: nowIso(),
|
||||
sid,
|
||||
@@ -782,9 +805,11 @@ function deliverChat(dir, sid, entries, url) {
|
||||
chat: entries,
|
||||
reply: chatReplyLines(entries),
|
||||
});
|
||||
const [out, subCursor] = withSubagents(dir, withWs);
|
||||
print({ ...out, ...(url ? { terminalLine: terminalLine(url) } : {}) });
|
||||
advanceCursor(dir, entries);
|
||||
advanceWorkspace(dir, changes);
|
||||
advanceSubagents(dir, subCursor);
|
||||
process.exitCode = 0;
|
||||
}
|
||||
|
||||
@@ -806,6 +831,52 @@ function advanceWorkspace(dir, changes) {
|
||||
} catch {}
|
||||
}
|
||||
|
||||
// The server rewrites the session's setting for a new workflow only once its
|
||||
// watcher sees the state `open` just wrote, so a launch or hop that read the
|
||||
// file at once would find the old workflow's and owe the agent nothing until
|
||||
// its next pickup. Give the server a moment to catch up instead, never
|
||||
// writing the file ourselves (FR-7). A session with no setting file at all is
|
||||
// an older server, which never writes one: a short look, not the full wait.
|
||||
const SUBAGENT_SYNC_WAIT_MS = 1500;
|
||||
const SUBAGENT_SYNC_MISSING_MS = 250;
|
||||
function awaitSubagentSync(dir, workflow) {
|
||||
if (!offered(workflow)) return;
|
||||
const start = Date.now();
|
||||
for (;;) {
|
||||
const setting = readSubagentSetting(dir);
|
||||
if (setting && setting.workflow === workflow) return;
|
||||
const budget = setting ? SUBAGENT_SYNC_WAIT_MS : SUBAGENT_SYNC_MISSING_MS;
|
||||
if (Date.now() - start >= budget) return;
|
||||
sleepSync(25);
|
||||
}
|
||||
}
|
||||
|
||||
// The Subagents switch the agent is owed, added to what it is about to read:
|
||||
// the setting as `subagents`, and its lines last in `reply`, after card lines,
|
||||
// Quick questions and Workspace lines (FR-9). Read from the session's own
|
||||
// setting file only, which only the server writes (FR-7). A setting for
|
||||
// another workflow is the server not having caught up with a hop yet: it
|
||||
// rides on the next pickup instead.
|
||||
function withSubagents(dir, out) {
|
||||
const setting = readSubagentSetting(dir);
|
||||
if (!setting) return [out, null];
|
||||
const workflow = (readJson(path.join(dir, "state.json")) || {}).workflow;
|
||||
if (setting.workflow !== workflow) return [out, null];
|
||||
const block = blockFor(setting, readSubagentCursor(dir));
|
||||
if (!block) return [out, null];
|
||||
const reply = [out.reply, ...block.lines].filter(Boolean).join("\n");
|
||||
return [{ ...out, subagents: block.field, reply }, block.cursor];
|
||||
}
|
||||
|
||||
// After the print, like advanceWorkspace(): a kill in between repeats the
|
||||
// block at the next pickup, never loses it.
|
||||
function advanceSubagents(dir, cursor) {
|
||||
if (!cursor) return;
|
||||
try {
|
||||
writeSubagentCursor(dir, cursor);
|
||||
} catch {}
|
||||
}
|
||||
|
||||
// Print first, then this, exactly as consume() stamps a result: a kill in
|
||||
// between can only hand the same chat over again, and collectChat() drops
|
||||
// anything that already has a reply.
|
||||
@@ -832,15 +903,17 @@ async function cmdChat() {
|
||||
}
|
||||
const entries = deliverableChat(collectChat(dir, readJson(path.join(dir, "state.json")) || {}));
|
||||
const changes = pendingWorkspaceChanges(dir);
|
||||
if (!entries.length && !changes.length) {
|
||||
const reply = [chatReplyLines(entries), ...changes.map(changeLine)].filter(Boolean).join("\n");
|
||||
const [out, subCursor] = withSubagents(dir, { chat: entries, workspace: changes, reply });
|
||||
if (!entries.length && !changes.length && !subCursor) {
|
||||
print({ chat: [] });
|
||||
process.exitCode = 10;
|
||||
return;
|
||||
}
|
||||
const reply = [chatReplyLines(entries), ...changes.map(changeLine)].filter(Boolean).join("\n");
|
||||
print({ chat: entries, workspace: changes, reply, terminalLine: terminalLine(handle.url) });
|
||||
print({ ...out, terminalLine: terminalLine(handle.url) });
|
||||
advanceCursor(dir, entries);
|
||||
advanceWorkspace(dir, changes);
|
||||
advanceSubagents(dir, subCursor);
|
||||
process.exitCode = 0;
|
||||
}
|
||||
|
||||
@@ -865,7 +938,8 @@ function consume(dir, resultPath, result, url, chat = []) {
|
||||
// never on result.json itself.
|
||||
const withChat = { ...collected, chat };
|
||||
if (chat.length) withChat.reply = [collected.reply, chatReplyLines(chat)].filter(Boolean).join("\n");
|
||||
const [out, changes] = withWorkspace(dir, withChat);
|
||||
const [withWs, changes] = withWorkspace(dir, withChat);
|
||||
const [out, subCursor] = withSubagents(dir, withWs);
|
||||
print(url ? { ...out, terminalLine: terminalLine(url) } : out);
|
||||
try {
|
||||
writeJsonAtomic(resultPath, collected);
|
||||
@@ -874,6 +948,7 @@ function consume(dir, resultPath, result, url, chat = []) {
|
||||
ledgerAnswers(dir, result);
|
||||
advanceCursor(dir, chat);
|
||||
advanceWorkspace(dir, changes);
|
||||
advanceSubagents(dir, subCursor);
|
||||
process.exitCode = result.type === "cancel" ? 30 : 0;
|
||||
}
|
||||
|
||||
@@ -986,12 +1061,18 @@ port, and the filesystem as transport; this CLI is the whole agent surface.
|
||||
path, description?, original? }], missing? }, the folders this
|
||||
console session reads as context, addressed as @name. The list is
|
||||
remembered per folder and spec in workspaces.json beside looks.json.
|
||||
May also print subagents: { state, revision, max, instruction } and
|
||||
a reply holding only its "Subagents: ..." lines, when a standing
|
||||
instruction (the page's Subagents switch) is owed to you.
|
||||
post --session <sid> --file <patch.json>
|
||||
Merge a patch into the session. Prints terminalLine while the
|
||||
server is live. Exit 3 = rejected; stderr says why. A patch may
|
||||
carry run: { event, id, tasks? } (session meter points) and folderIssue:
|
||||
{ name, reason, hint? } (a workspace folder you could not read);
|
||||
both go to the ledger, never into the state.
|
||||
both go to the ledger, never into the state. A patch may also
|
||||
carry helpers: [{ id, title, ask, state, result? }] or one
|
||||
{ id: "alone", alone: true }, merged by id, for the Subagents tab
|
||||
(see console.md → Standing instructions).
|
||||
wait --session <sid> [--seconds <N>]
|
||||
A bounded wait slice, sized below your shell timeout. Exit 0 = the
|
||||
result is on stdout, 10 = still waiting ("Waiting on your answer
|
||||
@@ -1002,10 +1083,14 @@ port, and the filesystem as transport; this CLI is the whole agent surface.
|
||||
"workspace" (changes since you last heard, each once, with a
|
||||
"Workspace: ..." line in reply); exit 10 counts them as
|
||||
pendingWorkspace, and a change alone never ends a slice.
|
||||
Exit 0 may also carry "subagents" (a console setting, not typed
|
||||
by the person, with its "Subagents: ..." lines last in reply); a
|
||||
setting change alone never ends a slice either.
|
||||
chat --session <sid>
|
||||
Collect Quick questions and workspace changes now, never waiting,
|
||||
never touching card sends. Exit 0 = { chat, workspace, reply,
|
||||
terminalLine }, 10 = none, 20 = server gone.
|
||||
Collect Quick questions, workspace changes and a Subagents
|
||||
setting change now, never waiting, never touching card sends.
|
||||
Exit 0 = { chat, workspace, subagents?, reply, terminalLine },
|
||||
10 = none, 20 = server gone.
|
||||
terminalLine is "→ Look at the web console: <url>": end your terminal
|
||||
messages with it during a console session.
|
||||
keep --session <sid> --upload <path> --name <name> --spec specs/<idea> [--from <file>]
|
||||
|
||||
@@ -25,6 +25,7 @@ import { fileURLToPath } from "node:url";
|
||||
import { CHAT_LIMIT } from "./public/chat.js";
|
||||
import { DOC_TYPES } from "./public/answers.js";
|
||||
import { defaultName } from "./public/workspace.js";
|
||||
import { checkHelpers, cleanSetting, defaultSetting, offered } from "./public/subagents.js";
|
||||
|
||||
export const HERE = path.dirname(fileURLToPath(import.meta.url));
|
||||
export const PUBLIC_DIR = path.join(HERE, "public");
|
||||
@@ -491,9 +492,16 @@ export async function removeSessions(sessionsDir, sids) {
|
||||
}
|
||||
|
||||
// The console folder's own files that no sweep may ever remove: the person's
|
||||
// looks, the folders remembered per project and spec, the pointer to this
|
||||
// console's directory, and the cached release check.
|
||||
export const PROTECTED_CONSOLE_FILES = new Set(["looks.json", "workspaces.json", "console-dir", "update-check.json"]);
|
||||
// looks, the folders remembered per project and spec, the Subagents switch
|
||||
// saved per project and workflow, the pointer to this console's directory,
|
||||
// and the cached release check.
|
||||
export const PROTECTED_CONSOLE_FILES = new Set([
|
||||
"looks.json",
|
||||
"workspaces.json",
|
||||
"subagents.json",
|
||||
"console-dir",
|
||||
"update-check.json",
|
||||
]);
|
||||
|
||||
function isScratchName(name) {
|
||||
return (
|
||||
@@ -1142,6 +1150,19 @@ const DOC_DEFAULTS = { version: 1, stale: false, blocks: [] };
|
||||
// Blocks merge by id like docs do, so a patch that only settles a block's
|
||||
// state keeps its text. Blocks left out of the patch stay as they are.
|
||||
function mergeDocs(current, patchList) {
|
||||
// A doc's version only moves forward. One going back is a stale or copied
|
||||
// payload (last phase's progress script, say), and the page would quietly
|
||||
// show the old content under the new run's name.
|
||||
for (const entry of patchList) {
|
||||
if (!isPlainObject(entry) || typeof entry.version !== "number") continue;
|
||||
const prev = (current || []).find((d) => d && d.id === entry.id);
|
||||
if (prev && typeof prev.version === "number" && entry.version < prev.version) {
|
||||
throw new Error(
|
||||
`doc "${entry.id}" is at version ${prev.version} on the page; this patch sends version ${entry.version}. ` +
|
||||
"Versions only go up: bump it, and check the payload is the current one."
|
||||
);
|
||||
}
|
||||
}
|
||||
const merged = mergeKeyed(current, patchList, "id", DOC_DEFAULTS, "docs");
|
||||
for (const entry of patchList) {
|
||||
if (!Array.isArray(entry.blocks)) continue;
|
||||
@@ -1184,6 +1205,13 @@ export function applyPatch(state, patch) {
|
||||
if (!Array.isArray(v)) throw new Error('"topics" must be an array');
|
||||
next.topics = mergeKeyed(next.topics, v, "id", {}, "topics");
|
||||
break;
|
||||
case "helpers":
|
||||
// The agent's report of its helpers, for the page's Subagents tab.
|
||||
// Only `post` writes it; the server's /submit never touches it.
|
||||
if (!Array.isArray(v)) throw new Error('"helpers" must be an array');
|
||||
if (!v.every(isPlainObject)) throw new Error('"helpers" entries must be objects, each { id, title, ask, state }');
|
||||
next.helpers = mergeKeyed(next.helpers, v, "id", {}, "helpers");
|
||||
break;
|
||||
case "docs":
|
||||
if (!Array.isArray(v)) throw new Error('"docs" must be an array');
|
||||
next.docs = mergeDocs(next.docs, v);
|
||||
@@ -1478,6 +1506,20 @@ export function validate(state) {
|
||||
JSON.stringify(state.menu || {});
|
||||
problems.push(...proseProblems(prose));
|
||||
|
||||
// The agent's report of its helpers: the shape the page draws from
|
||||
// (subagents.js), then the same prose scan as everything else it writes.
|
||||
if (state.helpers != null) {
|
||||
problems.push(...checkHelpers(state.helpers));
|
||||
for (const helper of Array.isArray(state.helpers) ? state.helpers : []) {
|
||||
if (!isPlainObject(helper)) continue;
|
||||
for (const field of ["title", "ask", "result"]) {
|
||||
if (typeof helper[field] === "string") {
|
||||
problems.push(...proseProblems(helper[field], `helper "${helper.id}" ${field}`));
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
return problems;
|
||||
}
|
||||
|
||||
@@ -1507,7 +1549,8 @@ export function blankState({ sid, workflow, title, project, specDir }) {
|
||||
* A resume that passes through the dashboard (a finished skill going back to
|
||||
* it, or a launch from its menu) is a new skill taking the page over, so it
|
||||
* starts from a blank page: the last skill's questions, sections, docs,
|
||||
* headline and ending are its record on disk, not the next skill's opening.
|
||||
* helpers, headline and ending are its record on disk, not the next skill's
|
||||
* opening.
|
||||
* Only the session's identity carries across. `workspace.json`,
|
||||
* `ledger.ndjson` and the cursors live beside `state.json`, so the workspace
|
||||
* and the meter outlive every hop.
|
||||
@@ -1534,6 +1577,8 @@ export function switchWorkflow(state, { workflow, title, specDir }) {
|
||||
// workspace.json the server. Folders, version, change log, missing, remote.
|
||||
// ledger.ndjson console.mjs. Append-only meter events and folder issues.
|
||||
// workspace-cursor.json console.mjs. The last workspace version handed to the agent.
|
||||
// subagents-setting.json the server. The Subagents switch for this session, with its revision.
|
||||
// subagents-cursor.json console.mjs. The last Subagents revision and state handed to the agent.
|
||||
export const CHAT_FILE = "chat.ndjson";
|
||||
export const CHAT_CURSOR_FILE = "chat-cursor.json";
|
||||
export const WORKSPACE_FILE = "workspace.json";
|
||||
@@ -1989,6 +2034,98 @@ export function pendingWorkspaceChanges(dir) {
|
||||
return (readWorkspace(dir)?.changes || []).filter((c) => c.version > cursor);
|
||||
}
|
||||
|
||||
/* ------------------------------------------------------ the Subagents switch */
|
||||
|
||||
// The person's Subagents switch, remembered per project folder and workflow:
|
||||
//
|
||||
// { "<folded project path>": { "<workflow>": { on, instruction, max } } }
|
||||
//
|
||||
// Keyed with foldKey(), as workspaces.json is. `instruction: null` is the
|
||||
// workflow's shipped default.
|
||||
export const SUBAGENTS_FILE = path.join(HOME_DIR, "subagents.json");
|
||||
const SUBAGENTS_LOCK = "subagents.json.lock";
|
||||
|
||||
function readSubagentStore() {
|
||||
const saved = readJson(SUBAGENTS_FILE, null);
|
||||
return saved && typeof saved === "object" && !Array.isArray(saved) ? saved : {};
|
||||
}
|
||||
|
||||
// The saved `{ on, instruction, max }` for this folder and workflow, or the
|
||||
// default's when nothing (or something malformed) is saved.
|
||||
export function subagentStoreEntry(worktree, workflow) {
|
||||
const { on, instruction, max } = defaultSetting(workflow);
|
||||
const project = offered(workflow) ? readSubagentStore()[foldKey(worktree)] : null;
|
||||
const saved = project && typeof project === "object" ? cleanSetting(project[workflow]) : null;
|
||||
return saved && !saved.error ? saved : { on, instruction, max };
|
||||
}
|
||||
|
||||
// Single-writer rule: only server.mjs may call this.
|
||||
export function saveSubagentStoreEntry(worktree, workflow, value) {
|
||||
ensureDir(path.dirname(SUBAGENTS_FILE));
|
||||
withStateLock(
|
||||
path.dirname(SUBAGENTS_FILE),
|
||||
() => {
|
||||
const store = readSubagentStore();
|
||||
const key = foldKey(worktree);
|
||||
const project = store[key] && typeof store[key] === "object" ? store[key] : {};
|
||||
store[key] = { ...project, [workflow]: { on: value.on, instruction: value.instruction, max: value.max } };
|
||||
writeJsonAtomic(SUBAGENTS_FILE, store);
|
||||
},
|
||||
SUBAGENTS_LOCK
|
||||
);
|
||||
}
|
||||
|
||||
export const SUBAGENTS_SETTING_FILE = "subagents-setting.json";
|
||||
|
||||
const isCount = (n) => Number.isInteger(n) && n >= 0;
|
||||
|
||||
// This session's switch, `{ workflow, on, instruction, max, revision }`, or
|
||||
// null when there is none or it is malformed.
|
||||
export function readSubagentSetting(dir) {
|
||||
const s = readJson(path.join(dir, SUBAGENTS_SETTING_FILE), null);
|
||||
if (!s || typeof s !== "object") return null;
|
||||
if (typeof s.workflow !== "string" || typeof s.on !== "boolean" || !Number.isInteger(s.max) || !isCount(s.revision)) return null;
|
||||
return s;
|
||||
}
|
||||
|
||||
// Single-writer rule: only server.mjs may call this. The revision never goes
|
||||
// backwards within a session.
|
||||
export function writeSubagentSetting(dir, setting) {
|
||||
const previous = readSubagentSetting(dir);
|
||||
const revision = Math.max(previous ? previous.revision : 0, setting.revision);
|
||||
return writeJsonAtomic(path.join(dir, SUBAGENTS_SETTING_FILE), { ...setting, revision });
|
||||
}
|
||||
|
||||
export const SUBAGENTS_CURSOR_FILE = "subagents-cursor.json";
|
||||
const CURSOR_STATES = new Set(["none", "on", "off"]);
|
||||
|
||||
// What the agent was last told: `{ revision, state }`.
|
||||
export function readSubagentCursor(dir) {
|
||||
const saved = readJson(path.join(dir, SUBAGENTS_CURSOR_FILE), null);
|
||||
if (!saved || !isCount(saved.revision) || !CURSOR_STATES.has(saved.state)) return { revision: 0, state: "none" };
|
||||
return { revision: saved.revision, state: saved.state };
|
||||
}
|
||||
|
||||
// Single-writer rule: only console.mjs may call this. Never backwards, like
|
||||
// writeWorkspaceCursor(): a killed `wait` may repeat a change, never skip one.
|
||||
export function writeSubagentCursor(dir, cursor) {
|
||||
const old = readSubagentCursor(dir);
|
||||
const next = cursor.revision < old.revision ? old : { revision: cursor.revision, state: cursor.state };
|
||||
writeJsonAtomic(path.join(dir, SUBAGENTS_CURSOR_FILE), next);
|
||||
}
|
||||
|
||||
// The one place the cursor may go back: `open`, which starts a fresh agent.
|
||||
export function resetSubagentCursor(dir) {
|
||||
writeJsonAtomic(path.join(dir, SUBAGENTS_CURSOR_FILE), { revision: 0, state: "none" });
|
||||
}
|
||||
|
||||
// The `caps` of the last `open` event: what the agent's console copy can do.
|
||||
export function latestOpenCaps(dir) {
|
||||
const opens = readJsonLines(path.join(dir, "events.ndjson")).filter((e) => e.type === "open");
|
||||
const last = opens[opens.length - 1];
|
||||
return last && Array.isArray(last.caps) ? last.caps : [];
|
||||
}
|
||||
|
||||
/**
|
||||
* Flag the case where the link cannot be opened by the person it is for.
|
||||
*
|
||||
|
||||
@@ -208,6 +208,26 @@ body {
|
||||
.stop-btn:hover:not(:disabled) { color: var(--warn); border-color: var(--warn); }
|
||||
.brief-btn:hover:not(:disabled) { color: var(--accent); border-color: var(--accent-line); }
|
||||
|
||||
/* Subagents: an orchestrator and its helpers. Unlit is a hollow outline in
|
||||
the quiet ink; lit fills the nodes with the highlight color. */
|
||||
.subagents-btn { border-color: var(--rule-2); color: var(--ink-2); display: inline-flex; align-items: center; justify-content: center; }
|
||||
.btn.subagents-btn { padding: 0 6px; align-self: stretch; }
|
||||
.subagents-btn[hidden] { display: none; }
|
||||
.subagents-btn svg { width: 16px; height: 16px; display: block; }
|
||||
.subagents-btn .sa-link { fill: none; stroke: var(--ink-2); stroke-width: 1.2; stroke-linecap: round; }
|
||||
.subagents-btn .sa-hub { fill: none; stroke: var(--ink-2); stroke-width: 1.4; }
|
||||
.subagents-btn .sa-node { fill: none; stroke: var(--ink-2); stroke-width: 1.2; }
|
||||
.subagents-btn[aria-pressed="true"] .sa-hub,
|
||||
.subagents-btn[aria-pressed="true"] .sa-node { fill: var(--accent); stroke: var(--accent); }
|
||||
.subagents-btn[aria-pressed="true"] .sa-link { stroke: var(--accent); }
|
||||
.subagents-btn:hover:not(:disabled) { color: var(--accent); border-color: var(--accent-line); }
|
||||
.subagents-btn:hover:not(:disabled) .sa-link,
|
||||
.subagents-btn:hover:not(:disabled) .sa-hub,
|
||||
.subagents-btn:hover:not(:disabled) .sa-node { stroke: var(--accent); }
|
||||
.subagents-btn:disabled .sa-link,
|
||||
.subagents-btn:disabled .sa-hub,
|
||||
.subagents-btn:disabled .sa-node { stroke: var(--ink-3); fill: none; }
|
||||
|
||||
.ident { display: flex; align-items: baseline; gap: 12px; min-width: 0; }
|
||||
|
||||
/* The session meter: a ring that fills with the points and a few words, in
|
||||
@@ -1430,6 +1450,30 @@ h1 {
|
||||
.pill.done { background: var(--ok-soft); color: var(--ok); }
|
||||
.pill.staged { background: var(--stage-soft); color: var(--stage); }
|
||||
|
||||
/* The Subagents tab: one row per reported helper, newest state in a pill. */
|
||||
.sa-card h2 { margin: 0 0 6px; }
|
||||
.sa-card > .help { margin: 0 0 16px; }
|
||||
.sa-alone { margin: 0; color: var(--ink-2); }
|
||||
.sa-list { list-style: none; margin: 0; padding: 0; display: grid; gap: 10px; }
|
||||
.sa-row { border: 1px solid var(--rule); border-radius: 8px; background: var(--panel-2); padding: 12px 14px; }
|
||||
.sa-head { display: flex; align-items: center; justify-content: space-between; gap: 10px; }
|
||||
.sa-title { min-width: 0; overflow-wrap: anywhere; }
|
||||
.sa-ask {
|
||||
margin: 4px 0 0; color: var(--ink-2); font-size: 13.5px;
|
||||
display: -webkit-box; -webkit-box-orient: vertical; -webkit-line-clamp: 2; line-clamp: 2; overflow: hidden;
|
||||
}
|
||||
.sa-result { margin: 8px 0 0; padding-top: 8px; border-top: 1px solid var(--rule); font-size: 13.5px; }
|
||||
.sa-pill { display: inline-flex; align-items: center; gap: 6px; flex: none; }
|
||||
.sa-pill.is-running { background: var(--accent-soft); color: var(--accent); border-color: var(--accent-line); }
|
||||
.sa-pill.is-done { background: var(--ok-soft); color: var(--ok); }
|
||||
.sa-pill.is-failed { background: var(--warn-soft); color: var(--warn); }
|
||||
.sa-pill .spinner.tiny { width: 10px; height: 10px; }
|
||||
/* The dialog's number box, themed like the page's other inputs. */
|
||||
.subagents input[type="number"] {
|
||||
width: 5em; font: inherit; color: var(--ink); background: var(--panel-2);
|
||||
border: 1px solid var(--rule-2); border-radius: 6px; padding: 4px 8px;
|
||||
}
|
||||
|
||||
/* ------------------------------------------------------ settled answer */
|
||||
|
||||
.answered {
|
||||
@@ -1971,6 +2015,8 @@ h4.md-h, h5.md-h, h6.md-h { font-size: 15px; }
|
||||
cursor: pointer;
|
||||
}
|
||||
.footer-where:hover { text-decoration: underline; }
|
||||
/* The project name, in the person's highlight color. */
|
||||
.where-project { color: var(--accent); font-weight: 600; }
|
||||
/* A folder is missing or the agent could not read one: the dialog says which. */
|
||||
.where-alert {
|
||||
display: inline-block; width: 7px; height: 7px; margin-left: 6px;
|
||||
|
||||
@@ -103,6 +103,15 @@ import { FOOTER_TIERS, footerLabel, nameProblem } from "./workspace.js";
|
||||
import { RED_BANNER } from "./meter.js";
|
||||
import { applyMention, matchNames, mentionAt } from "./mentions.js";
|
||||
import { faviconState, setFavicon } from "./favicon.js";
|
||||
import {
|
||||
CHECKIN_LINE,
|
||||
PATHFINDER_RESEARCH_LINE,
|
||||
defaultInstruction,
|
||||
helperRows,
|
||||
showSwitch,
|
||||
showTab,
|
||||
switchLabel,
|
||||
} from "./subagents.js";
|
||||
|
||||
const $ = (id) => document.getElementById(id);
|
||||
|
||||
@@ -530,6 +539,9 @@ let meterFrame = null;
|
||||
// The frame's update ({ installed, latest }), present only when a newer
|
||||
// release is out; null otherwise.
|
||||
let updateFrame = null;
|
||||
// The frame's Subagents switch ({ offered, supported, on, instruction, max,
|
||||
// revision }), or null before a server that sends it.
|
||||
let subagentsFrame = null;
|
||||
let chatDot = false;
|
||||
let chatSending = false;
|
||||
let chatResetting = false;
|
||||
@@ -880,6 +892,8 @@ function adopt(body) {
|
||||
if (body.meter) meterFrame = body.meter;
|
||||
// Always replaced: an absent key means no update.
|
||||
updateFrame = body.update || null;
|
||||
// Always replaced too: an older server sends none, and then there is no switch.
|
||||
subagentsFrame = body.subagents || null;
|
||||
lastContact = Date.now();
|
||||
if (gone) {
|
||||
gone = false;
|
||||
@@ -1301,6 +1315,7 @@ function render() {
|
||||
renderChrome();
|
||||
renderStatus();
|
||||
renderBriefButton();
|
||||
renderSubagentsButton();
|
||||
renderStopButton();
|
||||
renderHomeButton();
|
||||
tabAdded = renderViews();
|
||||
@@ -1566,7 +1581,7 @@ function renderChrome() {
|
||||
renderMeter();
|
||||
$("title").textContent = S.title || "Session";
|
||||
$("badge").textContent = workflowLabel(S.workflow);
|
||||
document.title = (S.title || "Session") + " · #" + String(S.sid || "").slice(-6) + " · Plan2Code";
|
||||
renderTabTitle();
|
||||
|
||||
const h = S.headline || {};
|
||||
// On a finished session an open item is frozen: the send on it counts as
|
||||
@@ -1835,6 +1850,69 @@ function renderBriefButton() {
|
||||
if (offer) btn.disabled = gone || pendingResult;
|
||||
}
|
||||
|
||||
// Shown only where the skill opts in and the agent's console copy can deliver
|
||||
// it. Lit while helpers are on; a click opens the dialog, never toggles.
|
||||
function renderSubagentsButton() {
|
||||
const btn = $("btn-subagents");
|
||||
const offer = showSwitch(subagentsFrame);
|
||||
btn.hidden = !offer;
|
||||
if (!offer) return;
|
||||
const label = switchLabel(subagentsFrame);
|
||||
btn.setAttribute("aria-pressed", String(Boolean(subagentsFrame.on)));
|
||||
btn.title = label;
|
||||
btn.setAttribute("aria-label", label);
|
||||
btn.disabled = gone;
|
||||
}
|
||||
|
||||
// The Subagents dialog, filled from the frame each time it opens. A null
|
||||
// instruction is the shipped default, shown as its text so it can be edited.
|
||||
function openSubagents() {
|
||||
if (!showSwitch(subagentsFrame)) return;
|
||||
const on = Boolean(subagentsFrame.on);
|
||||
for (const radio of document.querySelectorAll('input[name="subagents-on"]')) {
|
||||
radio.checked = radio.value === (on ? "on" : "off");
|
||||
}
|
||||
$("subagents-instruction").value = subagentsFrame.instruction ?? defaultInstruction(S.workflow);
|
||||
$("subagents-max").value = String(subagentsFrame.max);
|
||||
$("subagents-checkin").textContent = CHECKIN_LINE;
|
||||
const research = $("subagents-research");
|
||||
research.textContent = PATHFINDER_RESEARCH_LINE;
|
||||
research.hidden = S.workflow !== "pathfinder";
|
||||
$("subagents-status").textContent = "";
|
||||
$("subagents-save").disabled = false;
|
||||
$("subagents-modal").showModal();
|
||||
const checked = document.querySelector('input[name="subagents-on"]:checked');
|
||||
if (checked) checked.focus();
|
||||
}
|
||||
|
||||
const SUBAGENTS_ERRORS = {
|
||||
max: "Pick a number from 1 to 20.",
|
||||
"too-long": "The instruction is over 2,000 characters.",
|
||||
"not-offered": "This skill doesn't use helpers.",
|
||||
bad: "That didn't save. Try again.",
|
||||
};
|
||||
const SUBAGENTS_LOST = "Lost contact with Plan2Code. Try again once it's back.";
|
||||
|
||||
async function saveSubagents() {
|
||||
const save = $("subagents-save");
|
||||
const status = $("subagents-status");
|
||||
const picked = document.querySelector('input[name="subagents-on"]:checked');
|
||||
const text = $("subagents-instruction").value.trim();
|
||||
// The shipped default is stored as null, so a later release's wording
|
||||
// reaches everyone who never changed it.
|
||||
const instruction = text === defaultInstruction(S.workflow) ? null : text;
|
||||
const body = { on: Boolean(picked && picked.value === "on"), instruction, max: Number($("subagents-max").value) };
|
||||
save.disabled = true;
|
||||
status.textContent = "";
|
||||
const res = await postJson("/subagents", body);
|
||||
save.disabled = false;
|
||||
// The next state frame redraws the button.
|
||||
if (res.status === 200) return $("subagents-modal").close();
|
||||
if (res.status === 400) status.textContent = SUBAGENTS_ERRORS[res.body && res.body.error] || SUBAGENTS_ERRORS.bad;
|
||||
else if (res.status === 403 || res.status === 0) status.textContent = SUBAGENTS_LOST;
|
||||
else status.textContent = SUBAGENTS_ERRORS.bad;
|
||||
}
|
||||
|
||||
function renderViews() {
|
||||
const nav = $("views");
|
||||
nav.replaceChildren();
|
||||
@@ -1850,6 +1928,14 @@ function renderViews() {
|
||||
if (hasOverview) tabs.push({ id: "overview", label: "Overview", count: 0 });
|
||||
else if (view === "overview") view = "questions";
|
||||
for (const d of docs()) tabs.push({ id: "doc:" + d.id, label: d.title || "Document", count: 0 });
|
||||
// The helpers the agent reported, from the first one on; cleared by a
|
||||
// dashboard hop, which sends the person home like the Overview tab does.
|
||||
if (showTab(subagentsFrame, S.helpers)) {
|
||||
// From the rows the tab draws, so the badge never counts helpers the
|
||||
// working-alone note hides.
|
||||
const running = helperRows(S.helpers).rows.filter((r) => r.state === "running").length;
|
||||
tabs.push({ id: "subagents", label: "Subagents", count: running });
|
||||
} else if (view === "subagents") view = "questions";
|
||||
// Always last, on every workflow and after a finish: the Quick question chat.
|
||||
// The ring left of "Ask" shows exactly when the conversation's own ring does:
|
||||
// a question the agent picked up and has not answered yet.
|
||||
@@ -2130,6 +2216,7 @@ function paintMain(main) {
|
||||
if (view.startsWith("doc:")) return renderDoc(main, view.slice(4));
|
||||
if (view === "overview") return renderOverview(main);
|
||||
if (view === "ask") return renderAsk(main);
|
||||
if (view === "subagents") return renderSubagents(main);
|
||||
|
||||
// The session's own page, reached from the PAUSED / SESSION ENDED item at
|
||||
// the top of the rail. The hand-off lives here alone now, rather than
|
||||
@@ -4774,6 +4861,42 @@ function renderOverview(main) {
|
||||
main.appendChild(box);
|
||||
}
|
||||
|
||||
// The helpers the agent reported, as it last posted them. Everything here is
|
||||
// the agent's text, so it goes in as text, never as markup.
|
||||
function renderSubagents(main) {
|
||||
const card = el("section", "card sa-card");
|
||||
card.appendChild(el("h2", null, "Subagents"));
|
||||
card.appendChild(el("p", "help", CHECKIN_LINE));
|
||||
const { alone, rows } = helperRows(S.helpers);
|
||||
if (alone) {
|
||||
card.appendChild(
|
||||
el("p", "sa-alone", "Working alone: your agent has no way to start helpers here, so it is doing this skill's work itself.")
|
||||
);
|
||||
main.appendChild(card);
|
||||
return;
|
||||
}
|
||||
const list = el("ul", "sa-list");
|
||||
for (const row of rows) {
|
||||
const item = el("li", "sa-row");
|
||||
const head = el("div", "sa-head");
|
||||
head.appendChild(el("strong", "sa-title", row.title));
|
||||
const pill = el("span", "pill sa-pill is-" + row.state);
|
||||
if (row.state === "running") {
|
||||
const spin = el("span", "spinner tiny");
|
||||
spin.setAttribute("aria-hidden", "true");
|
||||
pill.appendChild(spin);
|
||||
}
|
||||
pill.appendChild(document.createTextNode(row.stateLabel));
|
||||
head.appendChild(pill);
|
||||
item.appendChild(head);
|
||||
item.appendChild(el("p", "sa-ask", row.ask));
|
||||
if (row.result) item.appendChild(el("p", "sa-result", row.result));
|
||||
list.appendChild(item);
|
||||
}
|
||||
card.appendChild(list);
|
||||
main.appendChild(card);
|
||||
}
|
||||
|
||||
/* ---------------------------------------------------------------- ask */
|
||||
|
||||
// The frame's chat block, with `offline` worked out now rather than when the
|
||||
@@ -5956,10 +6079,30 @@ const workspaceFolders = () => (wsFrame && Array.isArray(wsFrame.folders) ? wsFr
|
||||
// session opened before the server wrote `worktree` has nothing to show, so
|
||||
// the slot stays hidden. The footer renders on every tick, so the DOM is only
|
||||
// touched when the labels change, or when a resize clears the key.
|
||||
// The project's name: the workspace's original folder, or the session's
|
||||
// worktree folder before a frame carries the workspace.
|
||||
function projectName() {
|
||||
const folders = workspaceFolders();
|
||||
if (folders.length && folders[0].name) return folders[0].name;
|
||||
const path = (S && S.worktree) || "";
|
||||
return path ? path.split(/[\\/]/).filter(Boolean).pop() || path : "";
|
||||
}
|
||||
|
||||
// The browser tab's title, led by the project so tabs from different
|
||||
// projects are told apart. Called from the chrome and the footer, since the
|
||||
// workspace frame can arrive after either.
|
||||
function renderTabTitle() {
|
||||
if (!S) return;
|
||||
const name = projectName();
|
||||
document.title =
|
||||
(name ? name + " · " : "") + (S.title || "Session") + " · #" + String(S.sid || "").slice(-6) + " · Plan2Code";
|
||||
}
|
||||
|
||||
function renderWhere() {
|
||||
const b = $("footer-where");
|
||||
const folders = workspaceFolders();
|
||||
const path = S.worktree || "";
|
||||
renderTabTitle();
|
||||
const alert = Boolean(folders.length && ((wsFrame.missing || []).length || (wsFrame.issues || []).length));
|
||||
const labels = folders.length
|
||||
? Array.from({ length: FOOTER_TIERS }, (_, tier) => footerLabel({ folders, branch: S.branch }, tier))
|
||||
@@ -5972,7 +6115,16 @@ function renderWhere() {
|
||||
let label = labels[0];
|
||||
for (const text of labels) {
|
||||
label = text;
|
||||
b.textContent = text;
|
||||
// The project name takes the highlight color, so several consoles side by
|
||||
// side tell apart at a glance; the rest of the label stays quiet.
|
||||
const name = projectName();
|
||||
b.textContent = "";
|
||||
if (name && text.startsWith(name)) {
|
||||
b.appendChild(el("span", "where-project", name));
|
||||
b.appendChild(document.createTextNode(text.slice(name.length)));
|
||||
} else {
|
||||
b.textContent = text;
|
||||
}
|
||||
if (alert) {
|
||||
const dot = el("span", "where-alert");
|
||||
dot.setAttribute("aria-hidden", "true");
|
||||
@@ -7197,6 +7349,7 @@ function lightDismiss(dlg) {
|
||||
});
|
||||
}
|
||||
lightDismiss($("looks-modal"));
|
||||
lightDismiss($("subagents-modal"));
|
||||
lightDismiss($("help-modal"));
|
||||
lightDismiss($("workspace-modal"));
|
||||
lightDismiss($("welcome-modal"));
|
||||
@@ -7499,6 +7652,13 @@ $("cleanup-scan").addEventListener("click", scanCleanup);
|
||||
$("cleanup-delete").addEventListener("click", deleteCleanup);
|
||||
|
||||
$("btn-brief").addEventListener("click", openBrief);
|
||||
$("btn-subagents").addEventListener("click", openSubagents);
|
||||
$("subagents-default").addEventListener("click", () => {
|
||||
$("subagents-instruction").value = defaultInstruction(S.workflow);
|
||||
});
|
||||
$("subagents-save").addEventListener("click", saveSubagents);
|
||||
$("subagents-cancel").addEventListener("click", () => $("subagents-modal").close());
|
||||
$("subagents-modal").addEventListener("close", () => $("btn-subagents").focus());
|
||||
$("brief-cancel").addEventListener("click", () => $("brief-modal").close());
|
||||
$("brief-go").addEventListener("click", sendBrief);
|
||||
for (const radio of document.querySelectorAll('input[name="brief-range"]')) {
|
||||
|
||||
@@ -19,6 +19,7 @@ export const HELP_TABS = Object.freeze([
|
||||
tab("dashboard", "The dashboard", true),
|
||||
tab("meter", "Session meter", false),
|
||||
tab("build", "Watching a build", false),
|
||||
tab("subagents", "Helpers (subagents)", false),
|
||||
tab("ask", "Ask a quick question", false),
|
||||
tab("finishing", "Stopping and finishing", false),
|
||||
tab("stuck", "When something looks stuck", true),
|
||||
@@ -39,6 +40,7 @@ export function helpTabFor({ view, dashboard, gone, adrift, finished, workflow,
|
||||
if (gone || adrift) return "stuck";
|
||||
if (workspace) return "workspace";
|
||||
if (v === "ask") return "ask";
|
||||
if (v === "subagents") return "subagents";
|
||||
if (dashboard && meterRed) return "meter";
|
||||
if (dashboard) return "dashboard";
|
||||
if (v === "overview" || v.startsWith("doc:")) return "docs";
|
||||
|
||||
@@ -21,6 +21,7 @@
|
||||
<link rel="modulepreload" href="/starters.js" />
|
||||
<link rel="modulepreload" href="/workspace.js" />
|
||||
<link rel="modulepreload" href="/meter.js" />
|
||||
<link rel="modulepreload" href="/subagents.js" />
|
||||
<link rel="modulepreload" href="/mentions.js" />
|
||||
<link rel="modulepreload" href="/favicon.js" />
|
||||
<link rel="modulepreload" href="/vendor/marked.esm.js" />
|
||||
@@ -172,6 +173,18 @@
|
||||
<button type="button" class="btn ghost small brief-btn" id="btn-brief" hidden>
|
||||
Write a brief
|
||||
</button>
|
||||
<!-- Subagents: opted-in skills only. Lit while helpers are on; a click
|
||||
opens the Subagents dialog and never toggles them itself. -->
|
||||
<button type="button" class="btn ghost small subagents-btn" id="btn-subagents" aria-pressed="false" hidden>
|
||||
<!-- An orchestrator and its helpers: one larger node linked to three smaller ones. -->
|
||||
<svg viewBox="0 0 16 16" aria-hidden="true" focusable="false">
|
||||
<path class="sa-link" d="M6.9 6.6L10.9 3.9M7.4 8h3.5M6.9 9.4l4 2.7" />
|
||||
<circle cx="4.6" cy="8" r="2.6" class="sa-hub" />
|
||||
<circle cx="12.4" cy="3" r="1.5" class="sa-node" />
|
||||
<circle cx="12.4" cy="8" r="1.5" class="sa-node" />
|
||||
<circle cx="12.4" cy="13" r="1.5" class="sa-node" />
|
||||
</svg>
|
||||
</button>
|
||||
</div>
|
||||
<div class="views-group">
|
||||
<span class="views-arrow" aria-hidden="true">
|
||||
@@ -580,6 +593,13 @@
|
||||
<rect x="3" y="9" width="18" height="6" rx="3" />
|
||||
<path d="M6 12h7" />
|
||||
</symbol>
|
||||
<symbol id="hi-subagents" viewBox="0 0 24 24" fill="none">
|
||||
<circle cx="7" cy="12" r="3.5" />
|
||||
<circle cx="18" cy="5" r="2" />
|
||||
<circle cx="18" cy="12" r="2" />
|
||||
<circle cx="18" cy="19" r="2" />
|
||||
<path d="M10 10l6-4M10.5 12H16M10 14l6 4" />
|
||||
</symbol>
|
||||
<symbol id="hi-ask" viewBox="0 0 24 24" fill="none">
|
||||
<path d="M4 5h16v11H10l-4 4v-4H4z" />
|
||||
<path d="M8 9.5h8M8 12.5h5" />
|
||||
@@ -1477,7 +1497,61 @@
|
||||
</p>
|
||||
</section>
|
||||
|
||||
<!-- Tab 12: Ask a quick question -->
|
||||
<!-- Tab 12: Helpers (subagents) -->
|
||||
<section class="help-panel" data-tab="subagents">
|
||||
<h3>Helpers (subagents)</h3>
|
||||
<p>
|
||||
On a build, a review and Pathfinder, Plan2Code can hand independent
|
||||
pieces of work to helpers (subagents) while it keeps the conversation
|
||||
with you. The <strong>Subagents</strong> button in the top bar, after
|
||||
Stop session, is lit while helpers are on.
|
||||
</p>
|
||||
<h4>The switch</h4>
|
||||
<ul>
|
||||
<li>
|
||||
Clicking the button opens the <strong>Subagents</strong> dialog; it
|
||||
never switches helpers on or off by itself. Pick <strong>Use
|
||||
helpers</strong> or <strong>Work alone</strong>, edit the instruction
|
||||
Plan2Code follows (<strong>Reset to default</strong> puts the
|
||||
shipped one back), and say how many may run at once.
|
||||
</li>
|
||||
<li>
|
||||
It is off by default and saved for this project and this skill, so
|
||||
the next session of the same skill here starts the same way.
|
||||
</li>
|
||||
<li>
|
||||
The change reaches Plan2Code at its next check-in, as a setting,
|
||||
not as something you typed. How many helpers it can really start is
|
||||
up to your agent; some have no helpers at all.
|
||||
</li>
|
||||
<li>The button only appears on skills that use helpers, and only when Plan2Code can pass the setting on.</li>
|
||||
</ul>
|
||||
<h4>The Subagents tab</h4>
|
||||
<ul>
|
||||
<li>
|
||||
With the first helper, a <strong>Subagents</strong> tab appears before
|
||||
Ask: one row each, with what it was asked, whether it is running, done
|
||||
or failed, and a one-line result at the end. The number on the tab is
|
||||
how many are still running.
|
||||
</li>
|
||||
<li>
|
||||
Helpers report through Plan2Code, so the rows change at its
|
||||
check-ins, not live. The page cannot stop a helper; ask Plan2Code
|
||||
on the Ask tab if one should stop.
|
||||
</li>
|
||||
<li>
|
||||
<strong>Working alone</strong> means your agent has no way to start
|
||||
helpers here, so it is doing the work itself.
|
||||
</li>
|
||||
<li>
|
||||
Pathfinder always uses helpers for its research questions, whatever
|
||||
the switch says, and they show here too.
|
||||
</li>
|
||||
<li>The tab clears when you go back to the dashboard.</li>
|
||||
</ul>
|
||||
</section>
|
||||
|
||||
<!-- Tab 13: Ask a quick question -->
|
||||
<section class="help-panel" data-tab="ask">
|
||||
<h3>Ask a quick question</h3>
|
||||
<p class="help-lead">
|
||||
@@ -1568,7 +1642,7 @@
|
||||
</p>
|
||||
</section>
|
||||
|
||||
<!-- Tab 13: Stopping and finishing -->
|
||||
<!-- Tab 14: Stopping and finishing -->
|
||||
<section class="help-panel" data-tab="finishing">
|
||||
<h3>Stopping and finishing</h3>
|
||||
<p class="help-lead">
|
||||
@@ -1650,7 +1724,7 @@
|
||||
</p>
|
||||
</section>
|
||||
|
||||
<!-- Tab 14: When something looks stuck -->
|
||||
<!-- Tab 15: When something looks stuck -->
|
||||
<section class="help-panel" data-tab="stuck">
|
||||
<h3>When something looks stuck</h3>
|
||||
<p class="help-lead">
|
||||
@@ -1772,7 +1846,7 @@
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<!-- Tab 15: Keyboard and preferences -->
|
||||
<!-- Tab 16: Keyboard and preferences -->
|
||||
<section class="help-panel" data-tab="prefs">
|
||||
<h3>Keyboard and preferences</h3>
|
||||
<p class="help-lead">
|
||||
@@ -1888,7 +1962,7 @@
|
||||
</ul>
|
||||
</section>
|
||||
|
||||
<!-- Tab 16: Privacy and where things are saved -->
|
||||
<!-- Tab 17: Privacy and where things are saved -->
|
||||
<section class="help-panel" data-tab="privacy">
|
||||
<h3>Privacy and where things are saved</h3>
|
||||
<p class="help-lead">
|
||||
@@ -1925,7 +1999,11 @@
|
||||
</li>
|
||||
<li>
|
||||
your role, theme, colors, card width and sounds, in
|
||||
<code>looks.json</code>.
|
||||
<code>looks.json</code>;
|
||||
</li>
|
||||
<li>
|
||||
your Subagents switch for each project and skill, in
|
||||
<code>subagents.json</code>.
|
||||
</li>
|
||||
</ul>
|
||||
<p>
|
||||
@@ -2039,6 +2117,46 @@
|
||||
</div>
|
||||
</dialog>
|
||||
|
||||
<!-- Subagents: the switch for this skill, filled from the frame's
|
||||
`subagents` by app.js and saved through POST /subagents. It borrows
|
||||
the User Preferences dialog's classes, so it needs no dialog styles of
|
||||
its own, only a themed number box. -->
|
||||
<dialog class="modal looks subagents" id="subagents-modal" aria-labelledby="subagents-title">
|
||||
<h2 id="subagents-title">Subagents</h2>
|
||||
<p class="modal-blurb">
|
||||
Let Plan2Code hand independent work to helpers in this skill. Saved for this
|
||||
project and this skill.
|
||||
</p>
|
||||
<fieldset class="modal-ranges looks-row">
|
||||
<legend>Helpers</legend>
|
||||
<label><input type="radio" name="subagents-on" value="on" /> <span>Use helpers</span></label>
|
||||
<label><input type="radio" name="subagents-on" value="off" checked /> <span>Work alone</span></label>
|
||||
</fieldset>
|
||||
<fieldset class="modal-ranges">
|
||||
<legend>Instruction</legend>
|
||||
<textarea id="subagents-instruction" rows="4" maxlength="2000" aria-label="Instruction"></textarea>
|
||||
<div class="models-actions">
|
||||
<button type="button" class="btn small ghost" id="subagents-default">Reset to default</button>
|
||||
<span class="help">Passed to the agent as written, at its next check-in.</span>
|
||||
</div>
|
||||
</fieldset>
|
||||
<fieldset class="modal-ranges">
|
||||
<legend>At most</legend>
|
||||
<label>
|
||||
<input type="number" id="subagents-max" min="1" max="20" step="1" aria-label="At most this many helpers at once" />
|
||||
<span>helpers at once</span>
|
||||
</label>
|
||||
<p class="help">Advisory: your agent's own limit still applies.</p>
|
||||
</fieldset>
|
||||
<p class="help" id="subagents-checkin"></p>
|
||||
<p class="help" id="subagents-research" hidden></p>
|
||||
<p class="help" id="subagents-status" role="status"></p>
|
||||
<div class="modal-actions">
|
||||
<button type="button" class="btn ghost" id="subagents-cancel">Cancel</button>
|
||||
<button type="button" class="btn primary" id="subagents-save">Save</button>
|
||||
</div>
|
||||
</dialog>
|
||||
|
||||
<!-- The Workspace: the folder this session started in plus any added as
|
||||
context. The list is drawn by app.js from the frame's `workspace`;
|
||||
every change goes through the server's /workspace routes. -->
|
||||
|
||||
@@ -0,0 +1,223 @@
|
||||
// Plan2Code Web Console - the Subagents switch's opt-in table, wording and checks.
|
||||
//
|
||||
// The source of truth for which workflows offer the switch, the instruction
|
||||
// each one ships with, the fixed frame every "on" block carries, the exact
|
||||
// lines the agent reads at a pickup (blockFor()), and the house rules for the
|
||||
// helpers an agent reports back (checkHelper()). No DOM access at module scope
|
||||
// and no imports: the server, console.mjs, the page and `node --test` all
|
||||
// import this file.
|
||||
|
||||
// The one place a skill opts in (FR-1). Wording is behaviour-level and names
|
||||
// no harness tool, so any agent can follow it or harmlessly ignore it.
|
||||
export const SUBAGENT_WORKFLOWS = Object.freeze({
|
||||
implement: Object.freeze({
|
||||
instruction:
|
||||
"Hand independent tasks in a phase to helpers: tasks that touch different files and do not depend on each other. Keep tasks that share files, the phase's tests and the sign-off with you.",
|
||||
}),
|
||||
"implement-review": Object.freeze({
|
||||
instruction:
|
||||
"Hand independent tasks in a phase to helpers: tasks that touch different files and do not depend on each other. Keep tasks that share files, the phase's tests and the sign-off with you.",
|
||||
}),
|
||||
"quick-task": Object.freeze({
|
||||
instruction:
|
||||
"Use helpers for side lookups, such as reading unfamiliar code or checking documentation, while you make the change yourself.",
|
||||
}),
|
||||
review: Object.freeze({
|
||||
instruction:
|
||||
"Split the review across helpers by area (for example correctness, tests and security), then merge and de-duplicate their findings yourself before you report.",
|
||||
}),
|
||||
pathfinder: Object.freeze({
|
||||
instruction:
|
||||
"Use helpers for codebase recon, sketches and lookups beside the conversation. Keep every question for the person with you.",
|
||||
}),
|
||||
});
|
||||
|
||||
export function offered(workflow) {
|
||||
return typeof workflow === "string" && Object.prototype.hasOwnProperty.call(SUBAGENT_WORKFLOWS, workflow);
|
||||
}
|
||||
|
||||
export const MAX_MIN = 1;
|
||||
export const MAX_MAX = 20;
|
||||
export const DEFAULT_MAX = 3;
|
||||
export const INSTRUCTION_MAX_CHARS = 2000;
|
||||
export const HELPER_TITLE_MAX = 80;
|
||||
export const HELPER_ASK_MAX = 400;
|
||||
export const HELPER_RESULT_MAX = 200;
|
||||
export const HELPER_STATES = Object.freeze(["running", "done", "failed"]);
|
||||
|
||||
/* ------------------------------------------------------------- settings */
|
||||
|
||||
export function defaultInstruction(workflow) {
|
||||
return offered(workflow) ? SUBAGENT_WORKFLOWS[workflow].instruction : "";
|
||||
}
|
||||
|
||||
// The person's own text when they wrote some, else the workflow's default.
|
||||
export function effectiveInstruction(setting) {
|
||||
const own = setting && typeof setting.instruction === "string" ? setting.instruction.trim() : "";
|
||||
return own || defaultInstruction(setting && setting.workflow);
|
||||
}
|
||||
|
||||
export function defaultSetting(workflow) {
|
||||
return { workflow, on: false, instruction: null, max: DEFAULT_MAX };
|
||||
}
|
||||
|
||||
/**
|
||||
* `{ on, instruction, max }` from untrusted input, or `{ error }` naming the
|
||||
* field that failed: "bad" (wrong type), "too-long" (instruction) or "max".
|
||||
* Returns an error object rather than throwing, so the route and the store
|
||||
* reader share one validator. An empty instruction means the default: null.
|
||||
*/
|
||||
export function cleanSetting(input) {
|
||||
if (!input || typeof input !== "object" || Array.isArray(input)) return { error: "bad" };
|
||||
if (typeof input.on !== "boolean") return { error: "bad" };
|
||||
let instruction = null;
|
||||
if (input.instruction !== null && input.instruction !== undefined) {
|
||||
if (typeof input.instruction !== "string") return { error: "bad" };
|
||||
const trimmed = input.instruction.trim();
|
||||
if (trimmed.length > INSTRUCTION_MAX_CHARS) return { error: "too-long" };
|
||||
instruction = trimmed || null;
|
||||
}
|
||||
const max = input.max;
|
||||
if (!Number.isInteger(max) || max < MAX_MIN || max > MAX_MAX) return { error: "max" };
|
||||
return { on: input.on, instruction, max };
|
||||
}
|
||||
|
||||
/* ------------------------------------------------------------ the lines */
|
||||
|
||||
// The non-editable part of every "on" block (FR-8).
|
||||
export const FRAME_LINES = Object.freeze([
|
||||
"Hand independent work to helpers if your tools allow it; otherwise carry on alone.",
|
||||
"Report each helper on the page (console.md → Standing instructions); questions for the person stay with you.",
|
||||
'With no way to start helpers, report one "working alone" entry for this skill run instead.',
|
||||
]);
|
||||
|
||||
export const PATHFINDER_RESEARCH_LINE = "Research questions always use helpers, whatever this switch says.";
|
||||
|
||||
// Only the first line of a block starts at column 0, so no line inside it can
|
||||
// be read as an entry of its own (NFR-5).
|
||||
export function onLines({ revision, replaces, max, instruction }) {
|
||||
const label = replaces ? `revision ${revision}, replaces revision ${replaces}` : `revision ${revision}`;
|
||||
const own = String(instruction || "")
|
||||
.split("\n")
|
||||
.map((line) => line.trimEnd())
|
||||
.filter((line) => line.trim());
|
||||
return [
|
||||
`Subagents: on (${label}) — a console setting, not typed by the person.`,
|
||||
...[...FRAME_LINES, ...own, `At most ${max} helpers at once.`].map((line) => " " + line),
|
||||
];
|
||||
}
|
||||
|
||||
export function offLine(revision) {
|
||||
return `Subagents: off (revision ${revision}) — don't start new helpers for the rest of this session.`;
|
||||
}
|
||||
|
||||
/**
|
||||
* What the agent is owed at a pickup, given the session setting and the
|
||||
* cursor of what it was last told: `null`, or `{ field, lines, cursor }`
|
||||
* where `cursor` is what to write once the lines are printed. Never says
|
||||
* "off" to an agent that was not told "on" (FR-6). Pure: no clock, no I/O.
|
||||
*/
|
||||
export function blockFor(setting, told) {
|
||||
const last = told || { revision: 0, state: "none" };
|
||||
if (!setting || !offered(setting.workflow) || !(setting.revision > last.revision)) return null;
|
||||
const { revision, max } = setting;
|
||||
const instruction = effectiveInstruction(setting);
|
||||
if (setting.on) {
|
||||
const replaces = last.state === "on" ? last.revision : undefined;
|
||||
return {
|
||||
field: { state: "on", revision, max, instruction },
|
||||
lines: onLines({ revision, replaces, max, instruction }),
|
||||
cursor: { revision, state: "on" },
|
||||
};
|
||||
}
|
||||
if (last.state !== "on") return null;
|
||||
return {
|
||||
field: { state: "off", revision, max, instruction },
|
||||
lines: [offLine(revision)],
|
||||
cursor: { revision, state: "off" },
|
||||
};
|
||||
}
|
||||
|
||||
/* ------------------------------------------------------------ helpers */
|
||||
|
||||
const isPlainObject = (v) => !!v && typeof v === "object" && !Array.isArray(v);
|
||||
const nonEmpty = (v) => typeof v === "string" && v.trim() !== "";
|
||||
|
||||
// The problems with one reported helper, [] when it is fine.
|
||||
export function checkHelper(entry) {
|
||||
if (!isPlainObject(entry)) return ["helper: each entry must be an object"];
|
||||
if (!nonEmpty(entry.id)) return ["helper: id must be a non-empty string"];
|
||||
const who = `helper "${entry.id}"`;
|
||||
if (entry.alone === true) return entry.id === "alone" ? [] : [`${who}: the working-alone entry must have id "alone"`];
|
||||
const problems = [];
|
||||
if (!nonEmpty(entry.title)) problems.push(`${who}: title must be a non-empty string`);
|
||||
else if (entry.title.length > HELPER_TITLE_MAX) problems.push(`${who}: title must be at most ${HELPER_TITLE_MAX} characters`);
|
||||
if (!nonEmpty(entry.ask)) problems.push(`${who}: ask must be a non-empty string`);
|
||||
else if (entry.ask.length > HELPER_ASK_MAX) problems.push(`${who}: ask must be at most ${HELPER_ASK_MAX} characters`);
|
||||
if (!HELPER_STATES.includes(entry.state)) problems.push(`${who}: state must be running, done or failed`);
|
||||
if (entry.result !== undefined) {
|
||||
if (typeof entry.result !== "string") problems.push(`${who}: result must be a string`);
|
||||
else if (entry.result.length > HELPER_RESULT_MAX) problems.push(`${who}: result must be at most ${HELPER_RESULT_MAX} characters`);
|
||||
}
|
||||
return problems;
|
||||
}
|
||||
|
||||
// The problems with a whole merged list.
|
||||
export function checkHelpers(list) {
|
||||
if (!Array.isArray(list)) return ["helpers must be an array"];
|
||||
const problems = [];
|
||||
const seen = new Set();
|
||||
let alone = 0;
|
||||
for (const entry of list) {
|
||||
if (isPlainObject(entry) && nonEmpty(entry.id)) {
|
||||
if (seen.has(entry.id)) problems.push(`helper "${entry.id}": duplicate id`);
|
||||
seen.add(entry.id);
|
||||
if (entry.alone === true && ++alone === 2) problems.push(`helper "${entry.id}": only one working-alone entry is allowed`);
|
||||
}
|
||||
problems.push(...checkHelper(entry));
|
||||
}
|
||||
return problems;
|
||||
}
|
||||
|
||||
/* ------------------------------------------------------------ the page */
|
||||
|
||||
// The page's rules for the button, the modal and the tab, kept here so they
|
||||
// are tested without a browser. `frame` is the state frame's `subagents`
|
||||
// block; app.js only renders what these say.
|
||||
|
||||
export const CHECKIN_LINE = "Helpers report through Plan2Code, so their progress shows here at its check-ins, not live.";
|
||||
|
||||
const STATE_LABELS = Object.freeze({ running: "Running", done: "Done", failed: "Failed" });
|
||||
|
||||
// The switch shows only where the skill opts in AND the agent's console copy
|
||||
// said it can deliver it (FR-3).
|
||||
export function showSwitch(frame) {
|
||||
return Boolean(frame && frame.offered && frame.supported);
|
||||
}
|
||||
|
||||
// The button's tooltip and accessible name (FR-2).
|
||||
export function switchLabel(frame) {
|
||||
return frame && frame.on ? "Subagents: on" : "Subagents: off";
|
||||
}
|
||||
|
||||
// What the Subagents tab draws: the working-alone note, or one row per helper
|
||||
// in the order the agent reported them. A result shows once the helper ended.
|
||||
export function helperRows(helpers) {
|
||||
const list = Array.isArray(helpers) ? helpers.filter(isPlainObject) : [];
|
||||
if (list.some((h) => h.alone === true)) return { alone: true, rows: [] };
|
||||
const rows = list.map(({ id, title, ask, state, result }) => ({
|
||||
id,
|
||||
title,
|
||||
ask,
|
||||
state,
|
||||
stateLabel: STATE_LABELS[state] || STATE_LABELS.running,
|
||||
...((state === "done" || state === "failed") && typeof result === "string" && result ? { result } : {}),
|
||||
}));
|
||||
return { alone: false, rows };
|
||||
}
|
||||
|
||||
// Never an empty tab. Independent of on / off, so Pathfinder's research
|
||||
// helpers show even with the switch off (FR-11, FR-12).
|
||||
export function showTab(frame, helpers) {
|
||||
return showSwitch(frame) && Array.isArray(helpers) && helpers.length > 0;
|
||||
}
|
||||
@@ -25,6 +25,7 @@ import {
|
||||
LOOKS_FILE,
|
||||
PUBLIC_DIR,
|
||||
SHIPPED_MODELS_FILE,
|
||||
SUBAGENTS_SETTING_FILE,
|
||||
UPDATE_CHECK_FILE,
|
||||
USER_MODELS_FILE,
|
||||
WORKSPACE_FILE,
|
||||
@@ -38,6 +39,7 @@ import {
|
||||
fileStamp,
|
||||
handleFile,
|
||||
initialWorkspace,
|
||||
latestOpenCaps,
|
||||
nowIso,
|
||||
parseArgs,
|
||||
pendingChatCount,
|
||||
@@ -46,20 +48,25 @@ import {
|
||||
readJson,
|
||||
readLedger,
|
||||
readOverview,
|
||||
readSubagentSetting,
|
||||
readWorkspace,
|
||||
rememberWorkspace,
|
||||
rememberedWorkspace,
|
||||
removeCleanup,
|
||||
remoteWarning,
|
||||
saveSubagentStoreEntry,
|
||||
specKey,
|
||||
subagentStoreEntry,
|
||||
typedCount,
|
||||
withStateLock,
|
||||
writeJsonAtomic,
|
||||
writeSubagentSetting,
|
||||
writeWorkspace,
|
||||
} from "./lib.mjs";
|
||||
import { DOC_TYPES, MAX_ATTACHMENTS, MAX_DOC_BYTES, docExt, workflowLabel, workflowTitle } from "./public/answers.js";
|
||||
import { CHAT_LIMIT, CHAT_MAX_CHARS, chatOffline } from "./public/chat.js";
|
||||
import { meterView } from "./public/meter.js";
|
||||
import { cleanSetting, defaultSetting, offered } from "./public/subagents.js";
|
||||
import { ACCENTS, DEFAULT_ACCENT, DEFAULT_CARD_WIDTH, cardWidth } from "./public/palette.js";
|
||||
import { defaultName, freeName, nameProblem } from "./public/workspace.js";
|
||||
import { checkForUpdate } from "./update-check.mjs";
|
||||
@@ -212,6 +219,7 @@ const SERVABLE = new Set([
|
||||
"starters.js",
|
||||
"workspace.js",
|
||||
"meter.js",
|
||||
"subagents.js",
|
||||
"mentions.js",
|
||||
"favicon.js",
|
||||
"start-stop.mp3",
|
||||
@@ -601,6 +609,48 @@ function ensureConversation(state) {
|
||||
if (entry) appendEvent(DIR, { type: "chat-reset", reason: entry.reason });
|
||||
}
|
||||
|
||||
/* ------------------------------------------------------------ subagents */
|
||||
|
||||
// subagents-setting.json has one writer, this server, and the agent hears of
|
||||
// it only through what console.mjs reads there; events.ndjson's latest `open`
|
||||
// says whether the agent's console copy can carry it. Both re-read only when
|
||||
// their file has moved.
|
||||
const SUBAGENTS_SETTING_PATH = path.join(DIR, SUBAGENTS_SETTING_FILE);
|
||||
const EVENTS_PATH = path.join(DIR, "events.ndjson");
|
||||
|
||||
let subagentSettingSeen = { stamp: null, setting: null };
|
||||
function subagentSettingNow() {
|
||||
const stamp = fileStamp(SUBAGENTS_SETTING_PATH);
|
||||
if (stamp !== subagentSettingSeen.stamp) subagentSettingSeen = { stamp, setting: readSubagentSetting(DIR) };
|
||||
return subagentSettingSeen.setting;
|
||||
}
|
||||
|
||||
let capsSeen = { stamp: null, caps: [] };
|
||||
function openCapsNow() {
|
||||
const stamp = fileStamp(EVENTS_PATH);
|
||||
if (stamp !== capsSeen.stamp) capsSeen = { stamp, caps: latestOpenCaps(DIR) };
|
||||
return capsSeen.caps;
|
||||
}
|
||||
|
||||
const sameSetting = (a, b) => a.workflow === b.workflow && a.on === b.on && a.instruction === b.instruction && a.max === b.max;
|
||||
|
||||
/**
|
||||
* Turn the per-project store into this session's setting, for the workflow
|
||||
* the session is in now. The only place that happens (FR-7): a session an
|
||||
* older server ran has no setting file, so nothing is ever injected into it.
|
||||
* A record that already matches is left alone, revision and all, so a
|
||||
* restart alone never re-tells the agent anything.
|
||||
*/
|
||||
function syncSubagentSetting(state) {
|
||||
if (!state || typeof state.workflow !== "string") return;
|
||||
const { workflow } = state;
|
||||
const { on, instruction, max } = offered(workflow) ? subagentStoreEntry(sessionWorktree(), workflow) : defaultSetting(workflow);
|
||||
const target = { workflow, on, instruction, max };
|
||||
const current = readSubagentSetting(DIR);
|
||||
if (current && sameSetting(current, target)) return;
|
||||
writeSubagentSetting(DIR, { ...target, revision: (current ? current.revision : 0) + 1 });
|
||||
}
|
||||
|
||||
// What the page needs to draw itself, in the shape of the SSE state frame.
|
||||
// `have` names that exact view, for the page to hand back when it opens its
|
||||
// stream (see /events).
|
||||
@@ -615,20 +665,33 @@ function stateFrame(state) {
|
||||
chat: { ...chatForFrame(chatEntries(), state), pickedUp: chatPickedUp(), offline: chatOfflineNow(state) },
|
||||
workspace: workspaceView(),
|
||||
meter: meterView(ledgerEntries()),
|
||||
subagents: subagentsView(state),
|
||||
...(updateInfo ? { update: updateInfo } : {}),
|
||||
have: haveKey(),
|
||||
};
|
||||
}
|
||||
|
||||
// The page shows the switch only when `offered && supported` (FR-3); the
|
||||
// frame says both and leaves combining them to the page. `instruction: null`
|
||||
// is the shipped default, which the page reads from subagents.js itself.
|
||||
function subagentsView(state) {
|
||||
const workflow = state && state.workflow;
|
||||
const { on, instruction, max, revision } = subagentSettingNow() || { ...defaultSetting(workflow), revision: 0 };
|
||||
return { offered: offered(workflow), supported: openCapsNow().includes("subagents"), on, instruction, max, revision };
|
||||
}
|
||||
|
||||
function haveKey() {
|
||||
const { pending, stop } = resultFlags();
|
||||
chatEntries();
|
||||
chatPickedUp();
|
||||
workspaceNow();
|
||||
ledgerEntries();
|
||||
subagentSettingNow();
|
||||
openCapsNow();
|
||||
return (
|
||||
`${STARTED}.${rev}.${pending ? 1 : 0}${stop ? 1 : 0}.${chatSeen.stamp || ""}.${cursorSeen.stamp || ""}` +
|
||||
`.${workspaceSeen.stamp || ""}.${ledgerSeen.stamp || ""}.${updateInfo ? updateInfo.latest : ""}`
|
||||
`.${workspaceSeen.stamp || ""}.${ledgerSeen.stamp || ""}.${updateInfo ? updateInfo.latest : ""}` +
|
||||
`.${subagentSettingSeen.stamp || ""}.${capsSeen.stamp || ""}`
|
||||
);
|
||||
}
|
||||
|
||||
@@ -1172,6 +1235,39 @@ const server = http.createServer((req, res) => {
|
||||
});
|
||||
}
|
||||
|
||||
// The Subagents switch for the session's workflow. Saved per project folder
|
||||
// for the next session, and applied to this one with a bumped revision, which
|
||||
// is what console.mjs hands the agent at its next pickup. Never blocked by,
|
||||
// and never blocking, a card send.
|
||||
if (pathname === "/subagents" && req.method === "POST") {
|
||||
if (!originOk(req, port)) return json(res, 403, { error: "bad origin" });
|
||||
return readBody(req, (err, body) => {
|
||||
if (err) return json(res, err.tooBig ? 413 : 400, { error: err.tooBig ? "too large" : "body must be JSON" });
|
||||
const state = readState();
|
||||
if (!state || !offered(state.workflow)) return json(res, 400, { error: "not-offered" });
|
||||
const clean = cleanSetting(body);
|
||||
if (clean.error) return json(res, 400, { error: clean.error });
|
||||
const { on, instruction, max } = clean;
|
||||
const current = readSubagentSetting(DIR);
|
||||
const next = { workflow: state.workflow, on, instruction, max };
|
||||
// The store is per project, so another session may have moved it since
|
||||
// this one synced: it always takes the person's latest pick. Only a
|
||||
// real change to this session's setting bumps what the agent hears.
|
||||
const unchanged = Boolean(current && sameSetting(current, next));
|
||||
try {
|
||||
saveSubagentStoreEntry(sessionWorktree(), state.workflow, { on, instruction, max });
|
||||
if (!unchanged) writeSubagentSetting(DIR, { ...next, revision: (current ? current.revision : 0) + 1 });
|
||||
} catch (e) {
|
||||
return json(res, 500, { error: String(e.message) });
|
||||
}
|
||||
if (unchanged) return json(res, 200, { ok: true, setting: current });
|
||||
const setting = readSubagentSetting(DIR);
|
||||
appendEvent(DIR, { type: "subagents", on, revision: setting.revision });
|
||||
pushState();
|
||||
return json(res, 200, { ok: true, setting });
|
||||
});
|
||||
}
|
||||
|
||||
// The launcher's model menu: what ships (read-only here) and what the user added.
|
||||
if (pathname === "/models" && req.method === "GET") {
|
||||
const saved = readJson(USER_MODELS_FILE, null) || {};
|
||||
@@ -1400,6 +1496,9 @@ const server = http.createServer((req, res) => {
|
||||
try {
|
||||
ensureConversation(written.state);
|
||||
} catch {}
|
||||
try {
|
||||
syncSubagentSetting(written.state);
|
||||
} catch {}
|
||||
}
|
||||
}
|
||||
// Name the items that went. A page with OTHER answers staged should drop
|
||||
@@ -1726,6 +1825,9 @@ function checkState() {
|
||||
try {
|
||||
ensureConversation(parsed);
|
||||
} catch {}
|
||||
try {
|
||||
syncSubagentSetting(parsed);
|
||||
} catch {}
|
||||
try {
|
||||
followSpecDir(parsed);
|
||||
} catch {}
|
||||
@@ -1900,6 +2002,9 @@ function onListening(port) {
|
||||
try {
|
||||
bootWorkspace();
|
||||
} catch {}
|
||||
try {
|
||||
syncSubagentSetting(readState());
|
||||
} catch {}
|
||||
process.stdout.write(JSON.stringify({ type: "ready", url, port, sid: SID }) + "\n");
|
||||
try {
|
||||
startUpdateCheck();
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "Plan2Code",
|
||||
"version": "2.4.2",
|
||||
"version": "2.5.0",
|
||||
"description": "A structured 4-step workflow methodology for AI-assisted software development",
|
||||
"keywords": [
|
||||
"ai",
|
||||
@@ -17,6 +17,6 @@
|
||||
"url": "https://github.com/jparkerweb/plan2code"
|
||||
},
|
||||
"homepage": "https://github.com/jparkerweb/plan2code",
|
||||
"releaseDate": "2026-10-05",
|
||||
"releaseDate": "2026-10-06",
|
||||
"mode": "utility"
|
||||
}
|
||||
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "Plan2Code",
|
||||
"version": "2.4.2",
|
||||
"version": "2.5.0",
|
||||
"description": "A structured 4-step workflow methodology for AI-assisted software development",
|
||||
"keywords": [
|
||||
"ai",
|
||||
@@ -17,6 +17,6 @@
|
||||
"url": "https://github.com/jparkerweb/plan2code"
|
||||
},
|
||||
"homepage": "https://github.com/jparkerweb/plan2code",
|
||||
"releaseDate": "2026-10-05",
|
||||
"releaseDate": "2026-10-06",
|
||||
"mode": "utility"
|
||||
}
|
||||
@@ -64,6 +64,13 @@ progress bar is the first thing someone watching a build looks at. The session
|
||||
meter counts the build's tasks from `cleared` as it rises, so keep it current,
|
||||
and start every phase (a second one in the same run too) at `"cleared": 0`.
|
||||
|
||||
`"version": 1` is for the first phase of a session only. A doc's version
|
||||
never goes back (console.md → House rules, rule 9), so a later phase in the
|
||||
same session reposts `phase` and `phasefile` at one more than the version the
|
||||
page holds, with the new phase's title and content. The same goes for
|
||||
`report` at sign-off and `review` in a mid-session review: version 1 the
|
||||
first time, then up from wherever the page has it.
|
||||
|
||||
`phasefile` is the whole `phase-X.md`, verbatim from disk, as its own tab —
|
||||
the person can read the prerequisites and task specs while you build. Re-post
|
||||
it whenever the file changes, which is every task: the checkbox write that
|
||||
@@ -111,6 +118,12 @@ printed), never into the project or into `~/.plan2code/console/` directly:
|
||||
- Do not call `wait` while building. There is nothing to collect, and the page
|
||||
holds anything the person sends until you next look.
|
||||
|
||||
A build may receive a `Subagents:` standing instruction, on `open` output or a
|
||||
`chat` check between tasks. Follow console.md → Standing instructions for
|
||||
handing independent tasks to helpers and reporting them as `helpers`. Keep the
|
||||
per-task progress posts, the checkbox writes, the chat checks and the sign-off
|
||||
with you.
|
||||
|
||||
### Quick questions between tasks
|
||||
|
||||
The person can ask a Quick question on the Ask tab at any point in a build
|
||||
@@ -195,7 +208,8 @@ only ever be offered once nothing could come of it:
|
||||
`reply` carries `Approve this phase: approved`, which is the terminal's
|
||||
`approved`. If the note that came with an approval asks for a change, treat it
|
||||
as "describe any issues": do the change first and ask again. `changes` means
|
||||
exactly what it says: address it, bump the report's version, and reopen the
|
||||
exactly what it says: address it, bump the report's version (a later phase's
|
||||
report starts above the last one's, too), and reopen the
|
||||
item (`"status": "reopened"`) with a reply in its `thread`. `review` is the
|
||||
person asking for the code review before they approve anything — see "The
|
||||
review, mid-session" below.
|
||||
|
||||
@@ -170,7 +170,7 @@ so even a kill at the worst possible moment costs you a repeat, never an answer.
|
||||
|
||||
| Exit | Meaning | What you do |
|
||||
| --- | --- | --- |
|
||||
| `0` | They pressed Send, or asked a Quick question. stdout is the result JSON, and may carry `workspace` (changes to the folder list, see Workspace). | Handle the cards (if any), the chat (if any) and any `workspace` changes, then post once (below, Quick questions and Workspace). |
|
||||
| `0` | They pressed Send, or asked a Quick question. stdout is the result JSON, and may carry `workspace` (changes to the folder list, see Workspace) and `subagents` (the helpers switch, see Standing instructions). | Handle the cards (if any), the chat (if any), any `workspace` changes and any `subagents` block, then post once (below, Quick questions, Workspace and Standing instructions). |
|
||||
| `10` | Still working. stdout has a short progress summary; `pendingWorkspace` counts workspace changes waiting for the next send. | Relay ONE line: the `message` field itself, "Waiting on your answer in the web console", followed by the `terminalLine`. Then call `wait` again. |
|
||||
| `20` | The server is gone. | `open --resume <sid>`, give them the new link, then keep waiting. |
|
||||
| `30` | They pressed Cancel. | Stop. Ask what they want to do, in the terminal. |
|
||||
@@ -647,6 +647,84 @@ for permission is not a failure; report only a read that failed after it.
|
||||
|
||||
---
|
||||
|
||||
## Standing instructions
|
||||
|
||||
On the skills that offer it (`implement`, `implement-review`, `quick-task`,
|
||||
`review`, `pathfinder`), the person can turn **helpers** (subagents) on or off
|
||||
from the top bar's Subagents button. Their pick is saved per project and per
|
||||
skill, off by default, and reaches you as a standing instruction, only when it
|
||||
changes.
|
||||
|
||||
### What arrives
|
||||
|
||||
A `subagents` field beside `reply`, and `Subagents:` lines last in `reply`,
|
||||
after the card lines, the `Quick question:` blocks and the `Workspace:` lines.
|
||||
It rides on `wait` exit `0`, `chat` exit `0` and `open` output. A setting
|
||||
change alone never ends a `wait` slice: it waits for the next send, or for
|
||||
your next `chat` check.
|
||||
|
||||
```
|
||||
Subagents: on (revision 2) — a console setting, not typed by the person.
|
||||
Hand independent work to helpers if your tools allow it; otherwise carry on alone.
|
||||
Report each helper on the page (console.md → Standing instructions); questions for the person stay with you.
|
||||
With no way to start helpers, report one "working alone" entry for this skill run instead.
|
||||
Hand independent tasks in a phase to helpers: tasks that touch different files and do not depend on each other. Keep tasks that share files, the phase's tests and the sign-off with you.
|
||||
At most 3 helpers at once.
|
||||
```
|
||||
|
||||
beside `"subagents": { "state": "on", "revision": 2, "max": 3, "instruction": "…" }`.
|
||||
An edit while on arrives as `Subagents: on (revision 3, replaces revision 2) — …`
|
||||
with the whole block again; switching off arrives as one line:
|
||||
`Subagents: off (revision 4) — don't start new helpers for the rest of this session.`
|
||||
|
||||
It is a console setting, not something the person typed. It never answers a
|
||||
card, and it is never recorded under `specs/`.
|
||||
|
||||
### Obeying it
|
||||
|
||||
- **On:** hand independent work to helpers if your tools allow it, at most
|
||||
`max` at once, following the instruction lines. `max` is advisory: your
|
||||
harness's own limit still applies.
|
||||
- **A higher revision replaces a lower one.** Follow the latest block only.
|
||||
- **Off:** start no new helpers for the rest of the session. Let running ones
|
||||
finish and report them.
|
||||
- **Nothing arrives:** keep doing what the skill says.
|
||||
- **Scope is the skill run it arrived in.** After a dashboard launch, no block
|
||||
means the switch is off for this skill, even if an earlier skill in the same
|
||||
conversation was told "on": `open` starts the count again, and a launch with
|
||||
the switch off sends nothing.
|
||||
|
||||
### Reporting helpers
|
||||
|
||||
Post them, at your check-ins, so the page's Subagents tab can show them. The
|
||||
page never hears from a helper directly:
|
||||
|
||||
```jsonc
|
||||
{ "helpers": [
|
||||
{ "id": "h1", "title": "Read the store helpers", "ask": "Find every caller of readSubagentSetting.", "state": "running" },
|
||||
{ "id": "h2", "title": "Check the tests", "ask": "Run the subagents tests and report failures.", "state": "done", "result": "All 9 pass." }
|
||||
] }
|
||||
```
|
||||
|
||||
- `id` (non-empty), `title` (at most 80 characters), `ask` (at most 400) and
|
||||
`state` (`running`, `done` or `failed`) are required; `result` (at most 200)
|
||||
is the one line you add once a helper ends.
|
||||
- Merged by `id`: post a helper again with its new `state` and `result` and it
|
||||
updates in place. `"helpers": null` clears the list. A dashboard hop clears it
|
||||
too; a resume into the same skill keeps it.
|
||||
- One post per change worth seeing, not a stream.
|
||||
- Questions for the person stay with you, never with a helper: most harnesses
|
||||
give helpers no way to ask, and an answer only reaches the agent holding the
|
||||
session.
|
||||
- **No way to start helpers?** Post one `{ "id": "alone", "alone": true }`
|
||||
entry for the skill run instead. The tab then says you are working alone.
|
||||
- **Pathfinder:** research questions always use helpers and are always
|
||||
reported, whatever the switch says. The switch governs recon, sketches and
|
||||
lookups beside the conversation.
|
||||
- Helpers add no session meter points. Post no `run` for them.
|
||||
|
||||
---
|
||||
|
||||
## Launches (dashboard only)
|
||||
|
||||
A `dashboard` session is not a conversation: the page draws a menu of every
|
||||
@@ -763,7 +841,10 @@ commands follow the pipeline: the sign-off's is
|
||||
|
||||
### Review (`review`)
|
||||
|
||||
Scope questions up front, then the findings report as a doc (`id: "report"`),
|
||||
Scope questions up front — run standalone with nothing named, the first is
|
||||
a `choice`, "What should I review?", built from a quick scan (branch changes,
|
||||
uncommitted changes, specs, files you name; each option with its size),
|
||||
never an assumed target; a build's review skips it (`building.md`). Then the findings report as a doc (`id: "report"`),
|
||||
then the pick-what-gets-fixed menu as a `multi` or `choice` keyed by finding
|
||||
id, carrying `"doc": "report"` so the card links straight to the findings.
|
||||
Settle that item (`"status": "answered"` plus the `answer` they sent) in
|
||||
@@ -797,6 +878,8 @@ that is what the person is there to download. The finish carries no
|
||||
- Chart Step 8's research subagents must all report back before the
|
||||
finish (Finishing → Nothing of yours may still be running); the finish
|
||||
body then names what each one found.
|
||||
- Report every research subagent as a helper, whatever the Subagents switch
|
||||
says (Standing instructions → Reporting helpers).
|
||||
- At every session end, post `finish` (headline, `body`, and Form A's command as
|
||||
`command`) BEFORE `stop`. Someone who spent the session in the browser never
|
||||
sees the Trail Footer, and without this their last screen promises a question
|
||||
@@ -1146,6 +1229,16 @@ A patch that breaks one of these is rejected with exit `3` and a message:
|
||||
(Session meter) and a non-empty `id`; a `folderIssue` needs non-empty
|
||||
`name` and `reason` strings, and `hint`, when present, is one too. Rules 4
|
||||
and 5 cover `reason` and `hint`.
|
||||
8. **`helpers` entries are well formed** (Standing instructions → Reporting
|
||||
helpers): an array of objects, each with a unique `id`, a `title`, an `ask`
|
||||
and a known `state` within their limits, plus at most one `alone` entry.
|
||||
Rules 4 and 5 cover `title`, `ask` and `result`.
|
||||
9. **A doc's `version` never goes back.** Sending a known doc a lower
|
||||
`version` than the page holds is refused: it is almost always a stale or
|
||||
copied payload. The same version again is fine, and a dashboard hop starts
|
||||
every doc fresh. Anything else reusing a doc id in the same session (a
|
||||
build's second phase, a second report or review) continues from the
|
||||
version the page holds.
|
||||
|
||||
These are workflow rules you already follow. The server just makes them checkable.
|
||||
|
||||
@@ -1167,7 +1260,9 @@ cannot see them, and the moment it says the session ended, the person is
|
||||
free to close that terminal and kill them mid-write. While you wait, post
|
||||
`{"agent":{"status":"working","activity":"Researching 3 questions (1 of 3 back)"}}`
|
||||
and update the count as each returns. Never write a `finish.body` that says
|
||||
work "is running in the background" or "will finish on its own".
|
||||
work "is running in the background" or "will finish on its own". Mark every
|
||||
reported helper `done` or `failed` before the finish, so the Subagents tab
|
||||
never ends on a row still running.
|
||||
|
||||
### 1. Post the finish
|
||||
|
||||
|
||||
@@ -64,6 +64,8 @@ import {
|
||||
readChat,
|
||||
readJson,
|
||||
readLedger,
|
||||
readSubagentCursor,
|
||||
readSubagentSetting,
|
||||
readWorkspace,
|
||||
reapHandles,
|
||||
rememberedWorkspace,
|
||||
@@ -71,6 +73,7 @@ import {
|
||||
removeScratch,
|
||||
removeSessions,
|
||||
repoRoots,
|
||||
resetSubagentCursor,
|
||||
scanProject,
|
||||
SESSION_MAX_AGE_MS,
|
||||
sessionDir,
|
||||
@@ -88,9 +91,11 @@ import {
|
||||
workspaceForAgent,
|
||||
writeCursor,
|
||||
writeJsonAtomic,
|
||||
writeSubagentCursor,
|
||||
writeWorkspaceCursor,
|
||||
} from "./lib.mjs";
|
||||
import { RUN_EVENTS, TASK_EVENTS, MAX_TASKS, isTaskCount, progressEntry } from "./public/meter.js";
|
||||
import { blockFor, offered } from "./public/subagents.js";
|
||||
import { changeLine } from "./public/workspace.js";
|
||||
|
||||
// Mirrors the server's absolute lifetime cap: a handle older than this cannot
|
||||
@@ -310,7 +315,11 @@ async function cmdOpen() {
|
||||
die(`could not write the session state: ${written ? written.error : "unknown"}`, 1);
|
||||
}
|
||||
state = written.state;
|
||||
appendEvent(dir, { type: "open", resumed: Boolean(args.resume || args.session), carried });
|
||||
appendEvent(dir, { type: "open", resumed: Boolean(args.resume || args.session), carried, caps: ["subagents"] });
|
||||
// A new agent conversation has been told nothing yet (FR-6).
|
||||
try {
|
||||
resetSubagentCursor(dir);
|
||||
} catch {}
|
||||
trace("open: state written");
|
||||
|
||||
// Dashboard launches are recorded too (they score nothing), so the folder
|
||||
@@ -337,9 +346,18 @@ async function cmdOpen() {
|
||||
removeScratch(HOME_DIR, sweptScratch).catch(() => {});
|
||||
};
|
||||
|
||||
// A standing instruction the new agent is owed, as `subagents` and a
|
||||
// `reply` holding only its lines; neither key when nothing is owed.
|
||||
const subagentsOwed = () => {
|
||||
awaitSubagentSync(dir, state.workflow);
|
||||
const [out, cursor] = withSubagents(dir, { reply: "" });
|
||||
return [out.subagents ? out : {}, cursor];
|
||||
};
|
||||
|
||||
// Reuse a live server if one is already serving this session.
|
||||
if (existing && (await reusable)) {
|
||||
if (!args["no-open"]) openBrowser(existing.url);
|
||||
const [owed, subCursor] = subagentsOwed();
|
||||
print({
|
||||
ok: true,
|
||||
sid,
|
||||
@@ -349,9 +367,11 @@ async function cmdOpen() {
|
||||
pendingResult: carried,
|
||||
terminalLine: terminalLine(existing.url),
|
||||
workspace,
|
||||
...owed,
|
||||
...swept,
|
||||
...remoteWarning(),
|
||||
});
|
||||
advanceSubagents(dir, subCursor);
|
||||
sweep();
|
||||
return;
|
||||
}
|
||||
@@ -384,6 +404,7 @@ async function cmdOpen() {
|
||||
const notes = [];
|
||||
if (remote.note) notes.push(remote.note);
|
||||
if (carried) notes.push("Answers are already waiting. Run `wait` to collect them.");
|
||||
const [owed, subCursor] = subagentsOwed();
|
||||
print({
|
||||
ok: true,
|
||||
sid,
|
||||
@@ -394,10 +415,12 @@ async function cmdOpen() {
|
||||
pendingResult: carried,
|
||||
terminalLine: terminalLine(handle.url),
|
||||
workspace,
|
||||
...owed,
|
||||
...swept,
|
||||
...(remote.remote ? { remote: remote.remote } : {}),
|
||||
...(notes.length ? { note: notes.join(" ") } : {}),
|
||||
});
|
||||
advanceSubagents(dir, subCursor);
|
||||
// After the print, never before it: the page and the link wait for nothing.
|
||||
sweep();
|
||||
}
|
||||
@@ -774,7 +797,7 @@ function serverGone(sid) {
|
||||
|
||||
// Quick questions and nothing else: an ordinary exit 0 with no card actions.
|
||||
function deliverChat(dir, sid, entries, url) {
|
||||
const [out, changes] = withWorkspace(dir, {
|
||||
const [withWs, changes] = withWorkspace(dir, {
|
||||
type: "chat",
|
||||
at: nowIso(),
|
||||
sid,
|
||||
@@ -782,9 +805,11 @@ function deliverChat(dir, sid, entries, url) {
|
||||
chat: entries,
|
||||
reply: chatReplyLines(entries),
|
||||
});
|
||||
const [out, subCursor] = withSubagents(dir, withWs);
|
||||
print({ ...out, ...(url ? { terminalLine: terminalLine(url) } : {}) });
|
||||
advanceCursor(dir, entries);
|
||||
advanceWorkspace(dir, changes);
|
||||
advanceSubagents(dir, subCursor);
|
||||
process.exitCode = 0;
|
||||
}
|
||||
|
||||
@@ -806,6 +831,52 @@ function advanceWorkspace(dir, changes) {
|
||||
} catch {}
|
||||
}
|
||||
|
||||
// The server rewrites the session's setting for a new workflow only once its
|
||||
// watcher sees the state `open` just wrote, so a launch or hop that read the
|
||||
// file at once would find the old workflow's and owe the agent nothing until
|
||||
// its next pickup. Give the server a moment to catch up instead, never
|
||||
// writing the file ourselves (FR-7). A session with no setting file at all is
|
||||
// an older server, which never writes one: a short look, not the full wait.
|
||||
const SUBAGENT_SYNC_WAIT_MS = 1500;
|
||||
const SUBAGENT_SYNC_MISSING_MS = 250;
|
||||
function awaitSubagentSync(dir, workflow) {
|
||||
if (!offered(workflow)) return;
|
||||
const start = Date.now();
|
||||
for (;;) {
|
||||
const setting = readSubagentSetting(dir);
|
||||
if (setting && setting.workflow === workflow) return;
|
||||
const budget = setting ? SUBAGENT_SYNC_WAIT_MS : SUBAGENT_SYNC_MISSING_MS;
|
||||
if (Date.now() - start >= budget) return;
|
||||
sleepSync(25);
|
||||
}
|
||||
}
|
||||
|
||||
// The Subagents switch the agent is owed, added to what it is about to read:
|
||||
// the setting as `subagents`, and its lines last in `reply`, after card lines,
|
||||
// Quick questions and Workspace lines (FR-9). Read from the session's own
|
||||
// setting file only, which only the server writes (FR-7). A setting for
|
||||
// another workflow is the server not having caught up with a hop yet: it
|
||||
// rides on the next pickup instead.
|
||||
function withSubagents(dir, out) {
|
||||
const setting = readSubagentSetting(dir);
|
||||
if (!setting) return [out, null];
|
||||
const workflow = (readJson(path.join(dir, "state.json")) || {}).workflow;
|
||||
if (setting.workflow !== workflow) return [out, null];
|
||||
const block = blockFor(setting, readSubagentCursor(dir));
|
||||
if (!block) return [out, null];
|
||||
const reply = [out.reply, ...block.lines].filter(Boolean).join("\n");
|
||||
return [{ ...out, subagents: block.field, reply }, block.cursor];
|
||||
}
|
||||
|
||||
// After the print, like advanceWorkspace(): a kill in between repeats the
|
||||
// block at the next pickup, never loses it.
|
||||
function advanceSubagents(dir, cursor) {
|
||||
if (!cursor) return;
|
||||
try {
|
||||
writeSubagentCursor(dir, cursor);
|
||||
} catch {}
|
||||
}
|
||||
|
||||
// Print first, then this, exactly as consume() stamps a result: a kill in
|
||||
// between can only hand the same chat over again, and collectChat() drops
|
||||
// anything that already has a reply.
|
||||
@@ -832,15 +903,17 @@ async function cmdChat() {
|
||||
}
|
||||
const entries = deliverableChat(collectChat(dir, readJson(path.join(dir, "state.json")) || {}));
|
||||
const changes = pendingWorkspaceChanges(dir);
|
||||
if (!entries.length && !changes.length) {
|
||||
const reply = [chatReplyLines(entries), ...changes.map(changeLine)].filter(Boolean).join("\n");
|
||||
const [out, subCursor] = withSubagents(dir, { chat: entries, workspace: changes, reply });
|
||||
if (!entries.length && !changes.length && !subCursor) {
|
||||
print({ chat: [] });
|
||||
process.exitCode = 10;
|
||||
return;
|
||||
}
|
||||
const reply = [chatReplyLines(entries), ...changes.map(changeLine)].filter(Boolean).join("\n");
|
||||
print({ chat: entries, workspace: changes, reply, terminalLine: terminalLine(handle.url) });
|
||||
print({ ...out, terminalLine: terminalLine(handle.url) });
|
||||
advanceCursor(dir, entries);
|
||||
advanceWorkspace(dir, changes);
|
||||
advanceSubagents(dir, subCursor);
|
||||
process.exitCode = 0;
|
||||
}
|
||||
|
||||
@@ -865,7 +938,8 @@ function consume(dir, resultPath, result, url, chat = []) {
|
||||
// never on result.json itself.
|
||||
const withChat = { ...collected, chat };
|
||||
if (chat.length) withChat.reply = [collected.reply, chatReplyLines(chat)].filter(Boolean).join("\n");
|
||||
const [out, changes] = withWorkspace(dir, withChat);
|
||||
const [withWs, changes] = withWorkspace(dir, withChat);
|
||||
const [out, subCursor] = withSubagents(dir, withWs);
|
||||
print(url ? { ...out, terminalLine: terminalLine(url) } : out);
|
||||
try {
|
||||
writeJsonAtomic(resultPath, collected);
|
||||
@@ -874,6 +948,7 @@ function consume(dir, resultPath, result, url, chat = []) {
|
||||
ledgerAnswers(dir, result);
|
||||
advanceCursor(dir, chat);
|
||||
advanceWorkspace(dir, changes);
|
||||
advanceSubagents(dir, subCursor);
|
||||
process.exitCode = result.type === "cancel" ? 30 : 0;
|
||||
}
|
||||
|
||||
@@ -986,12 +1061,18 @@ port, and the filesystem as transport; this CLI is the whole agent surface.
|
||||
path, description?, original? }], missing? }, the folders this
|
||||
console session reads as context, addressed as @name. The list is
|
||||
remembered per folder and spec in workspaces.json beside looks.json.
|
||||
May also print subagents: { state, revision, max, instruction } and
|
||||
a reply holding only its "Subagents: ..." lines, when a standing
|
||||
instruction (the page's Subagents switch) is owed to you.
|
||||
post --session <sid> --file <patch.json>
|
||||
Merge a patch into the session. Prints terminalLine while the
|
||||
server is live. Exit 3 = rejected; stderr says why. A patch may
|
||||
carry run: { event, id, tasks? } (session meter points) and folderIssue:
|
||||
{ name, reason, hint? } (a workspace folder you could not read);
|
||||
both go to the ledger, never into the state.
|
||||
both go to the ledger, never into the state. A patch may also
|
||||
carry helpers: [{ id, title, ask, state, result? }] or one
|
||||
{ id: "alone", alone: true }, merged by id, for the Subagents tab
|
||||
(see console.md → Standing instructions).
|
||||
wait --session <sid> [--seconds <N>]
|
||||
A bounded wait slice, sized below your shell timeout. Exit 0 = the
|
||||
result is on stdout, 10 = still waiting ("Waiting on your answer
|
||||
@@ -1002,10 +1083,14 @@ port, and the filesystem as transport; this CLI is the whole agent surface.
|
||||
"workspace" (changes since you last heard, each once, with a
|
||||
"Workspace: ..." line in reply); exit 10 counts them as
|
||||
pendingWorkspace, and a change alone never ends a slice.
|
||||
Exit 0 may also carry "subagents" (a console setting, not typed
|
||||
by the person, with its "Subagents: ..." lines last in reply); a
|
||||
setting change alone never ends a slice either.
|
||||
chat --session <sid>
|
||||
Collect Quick questions and workspace changes now, never waiting,
|
||||
never touching card sends. Exit 0 = { chat, workspace, reply,
|
||||
terminalLine }, 10 = none, 20 = server gone.
|
||||
Collect Quick questions, workspace changes and a Subagents
|
||||
setting change now, never waiting, never touching card sends.
|
||||
Exit 0 = { chat, workspace, subagents?, reply, terminalLine },
|
||||
10 = none, 20 = server gone.
|
||||
terminalLine is "→ Look at the web console: <url>": end your terminal
|
||||
messages with it during a console session.
|
||||
keep --session <sid> --upload <path> --name <name> --spec specs/<idea> [--from <file>]
|
||||
|
||||
@@ -25,6 +25,7 @@ import { fileURLToPath } from "node:url";
|
||||
import { CHAT_LIMIT } from "./public/chat.js";
|
||||
import { DOC_TYPES } from "./public/answers.js";
|
||||
import { defaultName } from "./public/workspace.js";
|
||||
import { checkHelpers, cleanSetting, defaultSetting, offered } from "./public/subagents.js";
|
||||
|
||||
export const HERE = path.dirname(fileURLToPath(import.meta.url));
|
||||
export const PUBLIC_DIR = path.join(HERE, "public");
|
||||
@@ -491,9 +492,16 @@ export async function removeSessions(sessionsDir, sids) {
|
||||
}
|
||||
|
||||
// The console folder's own files that no sweep may ever remove: the person's
|
||||
// looks, the folders remembered per project and spec, the pointer to this
|
||||
// console's directory, and the cached release check.
|
||||
export const PROTECTED_CONSOLE_FILES = new Set(["looks.json", "workspaces.json", "console-dir", "update-check.json"]);
|
||||
// looks, the folders remembered per project and spec, the Subagents switch
|
||||
// saved per project and workflow, the pointer to this console's directory,
|
||||
// and the cached release check.
|
||||
export const PROTECTED_CONSOLE_FILES = new Set([
|
||||
"looks.json",
|
||||
"workspaces.json",
|
||||
"subagents.json",
|
||||
"console-dir",
|
||||
"update-check.json",
|
||||
]);
|
||||
|
||||
function isScratchName(name) {
|
||||
return (
|
||||
@@ -1142,6 +1150,19 @@ const DOC_DEFAULTS = { version: 1, stale: false, blocks: [] };
|
||||
// Blocks merge by id like docs do, so a patch that only settles a block's
|
||||
// state keeps its text. Blocks left out of the patch stay as they are.
|
||||
function mergeDocs(current, patchList) {
|
||||
// A doc's version only moves forward. One going back is a stale or copied
|
||||
// payload (last phase's progress script, say), and the page would quietly
|
||||
// show the old content under the new run's name.
|
||||
for (const entry of patchList) {
|
||||
if (!isPlainObject(entry) || typeof entry.version !== "number") continue;
|
||||
const prev = (current || []).find((d) => d && d.id === entry.id);
|
||||
if (prev && typeof prev.version === "number" && entry.version < prev.version) {
|
||||
throw new Error(
|
||||
`doc "${entry.id}" is at version ${prev.version} on the page; this patch sends version ${entry.version}. ` +
|
||||
"Versions only go up: bump it, and check the payload is the current one."
|
||||
);
|
||||
}
|
||||
}
|
||||
const merged = mergeKeyed(current, patchList, "id", DOC_DEFAULTS, "docs");
|
||||
for (const entry of patchList) {
|
||||
if (!Array.isArray(entry.blocks)) continue;
|
||||
@@ -1184,6 +1205,13 @@ export function applyPatch(state, patch) {
|
||||
if (!Array.isArray(v)) throw new Error('"topics" must be an array');
|
||||
next.topics = mergeKeyed(next.topics, v, "id", {}, "topics");
|
||||
break;
|
||||
case "helpers":
|
||||
// The agent's report of its helpers, for the page's Subagents tab.
|
||||
// Only `post` writes it; the server's /submit never touches it.
|
||||
if (!Array.isArray(v)) throw new Error('"helpers" must be an array');
|
||||
if (!v.every(isPlainObject)) throw new Error('"helpers" entries must be objects, each { id, title, ask, state }');
|
||||
next.helpers = mergeKeyed(next.helpers, v, "id", {}, "helpers");
|
||||
break;
|
||||
case "docs":
|
||||
if (!Array.isArray(v)) throw new Error('"docs" must be an array');
|
||||
next.docs = mergeDocs(next.docs, v);
|
||||
@@ -1478,6 +1506,20 @@ export function validate(state) {
|
||||
JSON.stringify(state.menu || {});
|
||||
problems.push(...proseProblems(prose));
|
||||
|
||||
// The agent's report of its helpers: the shape the page draws from
|
||||
// (subagents.js), then the same prose scan as everything else it writes.
|
||||
if (state.helpers != null) {
|
||||
problems.push(...checkHelpers(state.helpers));
|
||||
for (const helper of Array.isArray(state.helpers) ? state.helpers : []) {
|
||||
if (!isPlainObject(helper)) continue;
|
||||
for (const field of ["title", "ask", "result"]) {
|
||||
if (typeof helper[field] === "string") {
|
||||
problems.push(...proseProblems(helper[field], `helper "${helper.id}" ${field}`));
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
return problems;
|
||||
}
|
||||
|
||||
@@ -1507,7 +1549,8 @@ export function blankState({ sid, workflow, title, project, specDir }) {
|
||||
* A resume that passes through the dashboard (a finished skill going back to
|
||||
* it, or a launch from its menu) is a new skill taking the page over, so it
|
||||
* starts from a blank page: the last skill's questions, sections, docs,
|
||||
* headline and ending are its record on disk, not the next skill's opening.
|
||||
* helpers, headline and ending are its record on disk, not the next skill's
|
||||
* opening.
|
||||
* Only the session's identity carries across. `workspace.json`,
|
||||
* `ledger.ndjson` and the cursors live beside `state.json`, so the workspace
|
||||
* and the meter outlive every hop.
|
||||
@@ -1534,6 +1577,8 @@ export function switchWorkflow(state, { workflow, title, specDir }) {
|
||||
// workspace.json the server. Folders, version, change log, missing, remote.
|
||||
// ledger.ndjson console.mjs. Append-only meter events and folder issues.
|
||||
// workspace-cursor.json console.mjs. The last workspace version handed to the agent.
|
||||
// subagents-setting.json the server. The Subagents switch for this session, with its revision.
|
||||
// subagents-cursor.json console.mjs. The last Subagents revision and state handed to the agent.
|
||||
export const CHAT_FILE = "chat.ndjson";
|
||||
export const CHAT_CURSOR_FILE = "chat-cursor.json";
|
||||
export const WORKSPACE_FILE = "workspace.json";
|
||||
@@ -1989,6 +2034,98 @@ export function pendingWorkspaceChanges(dir) {
|
||||
return (readWorkspace(dir)?.changes || []).filter((c) => c.version > cursor);
|
||||
}
|
||||
|
||||
/* ------------------------------------------------------ the Subagents switch */
|
||||
|
||||
// The person's Subagents switch, remembered per project folder and workflow:
|
||||
//
|
||||
// { "<folded project path>": { "<workflow>": { on, instruction, max } } }
|
||||
//
|
||||
// Keyed with foldKey(), as workspaces.json is. `instruction: null` is the
|
||||
// workflow's shipped default.
|
||||
export const SUBAGENTS_FILE = path.join(HOME_DIR, "subagents.json");
|
||||
const SUBAGENTS_LOCK = "subagents.json.lock";
|
||||
|
||||
function readSubagentStore() {
|
||||
const saved = readJson(SUBAGENTS_FILE, null);
|
||||
return saved && typeof saved === "object" && !Array.isArray(saved) ? saved : {};
|
||||
}
|
||||
|
||||
// The saved `{ on, instruction, max }` for this folder and workflow, or the
|
||||
// default's when nothing (or something malformed) is saved.
|
||||
export function subagentStoreEntry(worktree, workflow) {
|
||||
const { on, instruction, max } = defaultSetting(workflow);
|
||||
const project = offered(workflow) ? readSubagentStore()[foldKey(worktree)] : null;
|
||||
const saved = project && typeof project === "object" ? cleanSetting(project[workflow]) : null;
|
||||
return saved && !saved.error ? saved : { on, instruction, max };
|
||||
}
|
||||
|
||||
// Single-writer rule: only server.mjs may call this.
|
||||
export function saveSubagentStoreEntry(worktree, workflow, value) {
|
||||
ensureDir(path.dirname(SUBAGENTS_FILE));
|
||||
withStateLock(
|
||||
path.dirname(SUBAGENTS_FILE),
|
||||
() => {
|
||||
const store = readSubagentStore();
|
||||
const key = foldKey(worktree);
|
||||
const project = store[key] && typeof store[key] === "object" ? store[key] : {};
|
||||
store[key] = { ...project, [workflow]: { on: value.on, instruction: value.instruction, max: value.max } };
|
||||
writeJsonAtomic(SUBAGENTS_FILE, store);
|
||||
},
|
||||
SUBAGENTS_LOCK
|
||||
);
|
||||
}
|
||||
|
||||
export const SUBAGENTS_SETTING_FILE = "subagents-setting.json";
|
||||
|
||||
const isCount = (n) => Number.isInteger(n) && n >= 0;
|
||||
|
||||
// This session's switch, `{ workflow, on, instruction, max, revision }`, or
|
||||
// null when there is none or it is malformed.
|
||||
export function readSubagentSetting(dir) {
|
||||
const s = readJson(path.join(dir, SUBAGENTS_SETTING_FILE), null);
|
||||
if (!s || typeof s !== "object") return null;
|
||||
if (typeof s.workflow !== "string" || typeof s.on !== "boolean" || !Number.isInteger(s.max) || !isCount(s.revision)) return null;
|
||||
return s;
|
||||
}
|
||||
|
||||
// Single-writer rule: only server.mjs may call this. The revision never goes
|
||||
// backwards within a session.
|
||||
export function writeSubagentSetting(dir, setting) {
|
||||
const previous = readSubagentSetting(dir);
|
||||
const revision = Math.max(previous ? previous.revision : 0, setting.revision);
|
||||
return writeJsonAtomic(path.join(dir, SUBAGENTS_SETTING_FILE), { ...setting, revision });
|
||||
}
|
||||
|
||||
export const SUBAGENTS_CURSOR_FILE = "subagents-cursor.json";
|
||||
const CURSOR_STATES = new Set(["none", "on", "off"]);
|
||||
|
||||
// What the agent was last told: `{ revision, state }`.
|
||||
export function readSubagentCursor(dir) {
|
||||
const saved = readJson(path.join(dir, SUBAGENTS_CURSOR_FILE), null);
|
||||
if (!saved || !isCount(saved.revision) || !CURSOR_STATES.has(saved.state)) return { revision: 0, state: "none" };
|
||||
return { revision: saved.revision, state: saved.state };
|
||||
}
|
||||
|
||||
// Single-writer rule: only console.mjs may call this. Never backwards, like
|
||||
// writeWorkspaceCursor(): a killed `wait` may repeat a change, never skip one.
|
||||
export function writeSubagentCursor(dir, cursor) {
|
||||
const old = readSubagentCursor(dir);
|
||||
const next = cursor.revision < old.revision ? old : { revision: cursor.revision, state: cursor.state };
|
||||
writeJsonAtomic(path.join(dir, SUBAGENTS_CURSOR_FILE), next);
|
||||
}
|
||||
|
||||
// The one place the cursor may go back: `open`, which starts a fresh agent.
|
||||
export function resetSubagentCursor(dir) {
|
||||
writeJsonAtomic(path.join(dir, SUBAGENTS_CURSOR_FILE), { revision: 0, state: "none" });
|
||||
}
|
||||
|
||||
// The `caps` of the last `open` event: what the agent's console copy can do.
|
||||
export function latestOpenCaps(dir) {
|
||||
const opens = readJsonLines(path.join(dir, "events.ndjson")).filter((e) => e.type === "open");
|
||||
const last = opens[opens.length - 1];
|
||||
return last && Array.isArray(last.caps) ? last.caps : [];
|
||||
}
|
||||
|
||||
/**
|
||||
* Flag the case where the link cannot be opened by the person it is for.
|
||||
*
|
||||
|
||||
@@ -208,6 +208,26 @@ body {
|
||||
.stop-btn:hover:not(:disabled) { color: var(--warn); border-color: var(--warn); }
|
||||
.brief-btn:hover:not(:disabled) { color: var(--accent); border-color: var(--accent-line); }
|
||||
|
||||
/* Subagents: an orchestrator and its helpers. Unlit is a hollow outline in
|
||||
the quiet ink; lit fills the nodes with the highlight color. */
|
||||
.subagents-btn { border-color: var(--rule-2); color: var(--ink-2); display: inline-flex; align-items: center; justify-content: center; }
|
||||
.btn.subagents-btn { padding: 0 6px; align-self: stretch; }
|
||||
.subagents-btn[hidden] { display: none; }
|
||||
.subagents-btn svg { width: 16px; height: 16px; display: block; }
|
||||
.subagents-btn .sa-link { fill: none; stroke: var(--ink-2); stroke-width: 1.2; stroke-linecap: round; }
|
||||
.subagents-btn .sa-hub { fill: none; stroke: var(--ink-2); stroke-width: 1.4; }
|
||||
.subagents-btn .sa-node { fill: none; stroke: var(--ink-2); stroke-width: 1.2; }
|
||||
.subagents-btn[aria-pressed="true"] .sa-hub,
|
||||
.subagents-btn[aria-pressed="true"] .sa-node { fill: var(--accent); stroke: var(--accent); }
|
||||
.subagents-btn[aria-pressed="true"] .sa-link { stroke: var(--accent); }
|
||||
.subagents-btn:hover:not(:disabled) { color: var(--accent); border-color: var(--accent-line); }
|
||||
.subagents-btn:hover:not(:disabled) .sa-link,
|
||||
.subagents-btn:hover:not(:disabled) .sa-hub,
|
||||
.subagents-btn:hover:not(:disabled) .sa-node { stroke: var(--accent); }
|
||||
.subagents-btn:disabled .sa-link,
|
||||
.subagents-btn:disabled .sa-hub,
|
||||
.subagents-btn:disabled .sa-node { stroke: var(--ink-3); fill: none; }
|
||||
|
||||
.ident { display: flex; align-items: baseline; gap: 12px; min-width: 0; }
|
||||
|
||||
/* The session meter: a ring that fills with the points and a few words, in
|
||||
@@ -1430,6 +1450,30 @@ h1 {
|
||||
.pill.done { background: var(--ok-soft); color: var(--ok); }
|
||||
.pill.staged { background: var(--stage-soft); color: var(--stage); }
|
||||
|
||||
/* The Subagents tab: one row per reported helper, newest state in a pill. */
|
||||
.sa-card h2 { margin: 0 0 6px; }
|
||||
.sa-card > .help { margin: 0 0 16px; }
|
||||
.sa-alone { margin: 0; color: var(--ink-2); }
|
||||
.sa-list { list-style: none; margin: 0; padding: 0; display: grid; gap: 10px; }
|
||||
.sa-row { border: 1px solid var(--rule); border-radius: 8px; background: var(--panel-2); padding: 12px 14px; }
|
||||
.sa-head { display: flex; align-items: center; justify-content: space-between; gap: 10px; }
|
||||
.sa-title { min-width: 0; overflow-wrap: anywhere; }
|
||||
.sa-ask {
|
||||
margin: 4px 0 0; color: var(--ink-2); font-size: 13.5px;
|
||||
display: -webkit-box; -webkit-box-orient: vertical; -webkit-line-clamp: 2; line-clamp: 2; overflow: hidden;
|
||||
}
|
||||
.sa-result { margin: 8px 0 0; padding-top: 8px; border-top: 1px solid var(--rule); font-size: 13.5px; }
|
||||
.sa-pill { display: inline-flex; align-items: center; gap: 6px; flex: none; }
|
||||
.sa-pill.is-running { background: var(--accent-soft); color: var(--accent); border-color: var(--accent-line); }
|
||||
.sa-pill.is-done { background: var(--ok-soft); color: var(--ok); }
|
||||
.sa-pill.is-failed { background: var(--warn-soft); color: var(--warn); }
|
||||
.sa-pill .spinner.tiny { width: 10px; height: 10px; }
|
||||
/* The dialog's number box, themed like the page's other inputs. */
|
||||
.subagents input[type="number"] {
|
||||
width: 5em; font: inherit; color: var(--ink); background: var(--panel-2);
|
||||
border: 1px solid var(--rule-2); border-radius: 6px; padding: 4px 8px;
|
||||
}
|
||||
|
||||
/* ------------------------------------------------------ settled answer */
|
||||
|
||||
.answered {
|
||||
@@ -1971,6 +2015,8 @@ h4.md-h, h5.md-h, h6.md-h { font-size: 15px; }
|
||||
cursor: pointer;
|
||||
}
|
||||
.footer-where:hover { text-decoration: underline; }
|
||||
/* The project name, in the person's highlight color. */
|
||||
.where-project { color: var(--accent); font-weight: 600; }
|
||||
/* A folder is missing or the agent could not read one: the dialog says which. */
|
||||
.where-alert {
|
||||
display: inline-block; width: 7px; height: 7px; margin-left: 6px;
|
||||
|
||||
@@ -103,6 +103,15 @@ import { FOOTER_TIERS, footerLabel, nameProblem } from "./workspace.js";
|
||||
import { RED_BANNER } from "./meter.js";
|
||||
import { applyMention, matchNames, mentionAt } from "./mentions.js";
|
||||
import { faviconState, setFavicon } from "./favicon.js";
|
||||
import {
|
||||
CHECKIN_LINE,
|
||||
PATHFINDER_RESEARCH_LINE,
|
||||
defaultInstruction,
|
||||
helperRows,
|
||||
showSwitch,
|
||||
showTab,
|
||||
switchLabel,
|
||||
} from "./subagents.js";
|
||||
|
||||
const $ = (id) => document.getElementById(id);
|
||||
|
||||
@@ -530,6 +539,9 @@ let meterFrame = null;
|
||||
// The frame's update ({ installed, latest }), present only when a newer
|
||||
// release is out; null otherwise.
|
||||
let updateFrame = null;
|
||||
// The frame's Subagents switch ({ offered, supported, on, instruction, max,
|
||||
// revision }), or null before a server that sends it.
|
||||
let subagentsFrame = null;
|
||||
let chatDot = false;
|
||||
let chatSending = false;
|
||||
let chatResetting = false;
|
||||
@@ -880,6 +892,8 @@ function adopt(body) {
|
||||
if (body.meter) meterFrame = body.meter;
|
||||
// Always replaced: an absent key means no update.
|
||||
updateFrame = body.update || null;
|
||||
// Always replaced too: an older server sends none, and then there is no switch.
|
||||
subagentsFrame = body.subagents || null;
|
||||
lastContact = Date.now();
|
||||
if (gone) {
|
||||
gone = false;
|
||||
@@ -1301,6 +1315,7 @@ function render() {
|
||||
renderChrome();
|
||||
renderStatus();
|
||||
renderBriefButton();
|
||||
renderSubagentsButton();
|
||||
renderStopButton();
|
||||
renderHomeButton();
|
||||
tabAdded = renderViews();
|
||||
@@ -1566,7 +1581,7 @@ function renderChrome() {
|
||||
renderMeter();
|
||||
$("title").textContent = S.title || "Session";
|
||||
$("badge").textContent = workflowLabel(S.workflow);
|
||||
document.title = (S.title || "Session") + " · #" + String(S.sid || "").slice(-6) + " · Plan2Code";
|
||||
renderTabTitle();
|
||||
|
||||
const h = S.headline || {};
|
||||
// On a finished session an open item is frozen: the send on it counts as
|
||||
@@ -1835,6 +1850,69 @@ function renderBriefButton() {
|
||||
if (offer) btn.disabled = gone || pendingResult;
|
||||
}
|
||||
|
||||
// Shown only where the skill opts in and the agent's console copy can deliver
|
||||
// it. Lit while helpers are on; a click opens the dialog, never toggles.
|
||||
function renderSubagentsButton() {
|
||||
const btn = $("btn-subagents");
|
||||
const offer = showSwitch(subagentsFrame);
|
||||
btn.hidden = !offer;
|
||||
if (!offer) return;
|
||||
const label = switchLabel(subagentsFrame);
|
||||
btn.setAttribute("aria-pressed", String(Boolean(subagentsFrame.on)));
|
||||
btn.title = label;
|
||||
btn.setAttribute("aria-label", label);
|
||||
btn.disabled = gone;
|
||||
}
|
||||
|
||||
// The Subagents dialog, filled from the frame each time it opens. A null
|
||||
// instruction is the shipped default, shown as its text so it can be edited.
|
||||
function openSubagents() {
|
||||
if (!showSwitch(subagentsFrame)) return;
|
||||
const on = Boolean(subagentsFrame.on);
|
||||
for (const radio of document.querySelectorAll('input[name="subagents-on"]')) {
|
||||
radio.checked = radio.value === (on ? "on" : "off");
|
||||
}
|
||||
$("subagents-instruction").value = subagentsFrame.instruction ?? defaultInstruction(S.workflow);
|
||||
$("subagents-max").value = String(subagentsFrame.max);
|
||||
$("subagents-checkin").textContent = CHECKIN_LINE;
|
||||
const research = $("subagents-research");
|
||||
research.textContent = PATHFINDER_RESEARCH_LINE;
|
||||
research.hidden = S.workflow !== "pathfinder";
|
||||
$("subagents-status").textContent = "";
|
||||
$("subagents-save").disabled = false;
|
||||
$("subagents-modal").showModal();
|
||||
const checked = document.querySelector('input[name="subagents-on"]:checked');
|
||||
if (checked) checked.focus();
|
||||
}
|
||||
|
||||
const SUBAGENTS_ERRORS = {
|
||||
max: "Pick a number from 1 to 20.",
|
||||
"too-long": "The instruction is over 2,000 characters.",
|
||||
"not-offered": "This skill doesn't use helpers.",
|
||||
bad: "That didn't save. Try again.",
|
||||
};
|
||||
const SUBAGENTS_LOST = "Lost contact with Plan2Code. Try again once it's back.";
|
||||
|
||||
async function saveSubagents() {
|
||||
const save = $("subagents-save");
|
||||
const status = $("subagents-status");
|
||||
const picked = document.querySelector('input[name="subagents-on"]:checked');
|
||||
const text = $("subagents-instruction").value.trim();
|
||||
// The shipped default is stored as null, so a later release's wording
|
||||
// reaches everyone who never changed it.
|
||||
const instruction = text === defaultInstruction(S.workflow) ? null : text;
|
||||
const body = { on: Boolean(picked && picked.value === "on"), instruction, max: Number($("subagents-max").value) };
|
||||
save.disabled = true;
|
||||
status.textContent = "";
|
||||
const res = await postJson("/subagents", body);
|
||||
save.disabled = false;
|
||||
// The next state frame redraws the button.
|
||||
if (res.status === 200) return $("subagents-modal").close();
|
||||
if (res.status === 400) status.textContent = SUBAGENTS_ERRORS[res.body && res.body.error] || SUBAGENTS_ERRORS.bad;
|
||||
else if (res.status === 403 || res.status === 0) status.textContent = SUBAGENTS_LOST;
|
||||
else status.textContent = SUBAGENTS_ERRORS.bad;
|
||||
}
|
||||
|
||||
function renderViews() {
|
||||
const nav = $("views");
|
||||
nav.replaceChildren();
|
||||
@@ -1850,6 +1928,14 @@ function renderViews() {
|
||||
if (hasOverview) tabs.push({ id: "overview", label: "Overview", count: 0 });
|
||||
else if (view === "overview") view = "questions";
|
||||
for (const d of docs()) tabs.push({ id: "doc:" + d.id, label: d.title || "Document", count: 0 });
|
||||
// The helpers the agent reported, from the first one on; cleared by a
|
||||
// dashboard hop, which sends the person home like the Overview tab does.
|
||||
if (showTab(subagentsFrame, S.helpers)) {
|
||||
// From the rows the tab draws, so the badge never counts helpers the
|
||||
// working-alone note hides.
|
||||
const running = helperRows(S.helpers).rows.filter((r) => r.state === "running").length;
|
||||
tabs.push({ id: "subagents", label: "Subagents", count: running });
|
||||
} else if (view === "subagents") view = "questions";
|
||||
// Always last, on every workflow and after a finish: the Quick question chat.
|
||||
// The ring left of "Ask" shows exactly when the conversation's own ring does:
|
||||
// a question the agent picked up and has not answered yet.
|
||||
@@ -2130,6 +2216,7 @@ function paintMain(main) {
|
||||
if (view.startsWith("doc:")) return renderDoc(main, view.slice(4));
|
||||
if (view === "overview") return renderOverview(main);
|
||||
if (view === "ask") return renderAsk(main);
|
||||
if (view === "subagents") return renderSubagents(main);
|
||||
|
||||
// The session's own page, reached from the PAUSED / SESSION ENDED item at
|
||||
// the top of the rail. The hand-off lives here alone now, rather than
|
||||
@@ -4774,6 +4861,42 @@ function renderOverview(main) {
|
||||
main.appendChild(box);
|
||||
}
|
||||
|
||||
// The helpers the agent reported, as it last posted them. Everything here is
|
||||
// the agent's text, so it goes in as text, never as markup.
|
||||
function renderSubagents(main) {
|
||||
const card = el("section", "card sa-card");
|
||||
card.appendChild(el("h2", null, "Subagents"));
|
||||
card.appendChild(el("p", "help", CHECKIN_LINE));
|
||||
const { alone, rows } = helperRows(S.helpers);
|
||||
if (alone) {
|
||||
card.appendChild(
|
||||
el("p", "sa-alone", "Working alone: your agent has no way to start helpers here, so it is doing this skill's work itself.")
|
||||
);
|
||||
main.appendChild(card);
|
||||
return;
|
||||
}
|
||||
const list = el("ul", "sa-list");
|
||||
for (const row of rows) {
|
||||
const item = el("li", "sa-row");
|
||||
const head = el("div", "sa-head");
|
||||
head.appendChild(el("strong", "sa-title", row.title));
|
||||
const pill = el("span", "pill sa-pill is-" + row.state);
|
||||
if (row.state === "running") {
|
||||
const spin = el("span", "spinner tiny");
|
||||
spin.setAttribute("aria-hidden", "true");
|
||||
pill.appendChild(spin);
|
||||
}
|
||||
pill.appendChild(document.createTextNode(row.stateLabel));
|
||||
head.appendChild(pill);
|
||||
item.appendChild(head);
|
||||
item.appendChild(el("p", "sa-ask", row.ask));
|
||||
if (row.result) item.appendChild(el("p", "sa-result", row.result));
|
||||
list.appendChild(item);
|
||||
}
|
||||
card.appendChild(list);
|
||||
main.appendChild(card);
|
||||
}
|
||||
|
||||
/* ---------------------------------------------------------------- ask */
|
||||
|
||||
// The frame's chat block, with `offline` worked out now rather than when the
|
||||
@@ -5956,10 +6079,30 @@ const workspaceFolders = () => (wsFrame && Array.isArray(wsFrame.folders) ? wsFr
|
||||
// session opened before the server wrote `worktree` has nothing to show, so
|
||||
// the slot stays hidden. The footer renders on every tick, so the DOM is only
|
||||
// touched when the labels change, or when a resize clears the key.
|
||||
// The project's name: the workspace's original folder, or the session's
|
||||
// worktree folder before a frame carries the workspace.
|
||||
function projectName() {
|
||||
const folders = workspaceFolders();
|
||||
if (folders.length && folders[0].name) return folders[0].name;
|
||||
const path = (S && S.worktree) || "";
|
||||
return path ? path.split(/[\\/]/).filter(Boolean).pop() || path : "";
|
||||
}
|
||||
|
||||
// The browser tab's title, led by the project so tabs from different
|
||||
// projects are told apart. Called from the chrome and the footer, since the
|
||||
// workspace frame can arrive after either.
|
||||
function renderTabTitle() {
|
||||
if (!S) return;
|
||||
const name = projectName();
|
||||
document.title =
|
||||
(name ? name + " · " : "") + (S.title || "Session") + " · #" + String(S.sid || "").slice(-6) + " · Plan2Code";
|
||||
}
|
||||
|
||||
function renderWhere() {
|
||||
const b = $("footer-where");
|
||||
const folders = workspaceFolders();
|
||||
const path = S.worktree || "";
|
||||
renderTabTitle();
|
||||
const alert = Boolean(folders.length && ((wsFrame.missing || []).length || (wsFrame.issues || []).length));
|
||||
const labels = folders.length
|
||||
? Array.from({ length: FOOTER_TIERS }, (_, tier) => footerLabel({ folders, branch: S.branch }, tier))
|
||||
@@ -5972,7 +6115,16 @@ function renderWhere() {
|
||||
let label = labels[0];
|
||||
for (const text of labels) {
|
||||
label = text;
|
||||
b.textContent = text;
|
||||
// The project name takes the highlight color, so several consoles side by
|
||||
// side tell apart at a glance; the rest of the label stays quiet.
|
||||
const name = projectName();
|
||||
b.textContent = "";
|
||||
if (name && text.startsWith(name)) {
|
||||
b.appendChild(el("span", "where-project", name));
|
||||
b.appendChild(document.createTextNode(text.slice(name.length)));
|
||||
} else {
|
||||
b.textContent = text;
|
||||
}
|
||||
if (alert) {
|
||||
const dot = el("span", "where-alert");
|
||||
dot.setAttribute("aria-hidden", "true");
|
||||
@@ -7197,6 +7349,7 @@ function lightDismiss(dlg) {
|
||||
});
|
||||
}
|
||||
lightDismiss($("looks-modal"));
|
||||
lightDismiss($("subagents-modal"));
|
||||
lightDismiss($("help-modal"));
|
||||
lightDismiss($("workspace-modal"));
|
||||
lightDismiss($("welcome-modal"));
|
||||
@@ -7499,6 +7652,13 @@ $("cleanup-scan").addEventListener("click", scanCleanup);
|
||||
$("cleanup-delete").addEventListener("click", deleteCleanup);
|
||||
|
||||
$("btn-brief").addEventListener("click", openBrief);
|
||||
$("btn-subagents").addEventListener("click", openSubagents);
|
||||
$("subagents-default").addEventListener("click", () => {
|
||||
$("subagents-instruction").value = defaultInstruction(S.workflow);
|
||||
});
|
||||
$("subagents-save").addEventListener("click", saveSubagents);
|
||||
$("subagents-cancel").addEventListener("click", () => $("subagents-modal").close());
|
||||
$("subagents-modal").addEventListener("close", () => $("btn-subagents").focus());
|
||||
$("brief-cancel").addEventListener("click", () => $("brief-modal").close());
|
||||
$("brief-go").addEventListener("click", sendBrief);
|
||||
for (const radio of document.querySelectorAll('input[name="brief-range"]')) {
|
||||
|
||||
@@ -19,6 +19,7 @@ export const HELP_TABS = Object.freeze([
|
||||
tab("dashboard", "The dashboard", true),
|
||||
tab("meter", "Session meter", false),
|
||||
tab("build", "Watching a build", false),
|
||||
tab("subagents", "Helpers (subagents)", false),
|
||||
tab("ask", "Ask a quick question", false),
|
||||
tab("finishing", "Stopping and finishing", false),
|
||||
tab("stuck", "When something looks stuck", true),
|
||||
@@ -39,6 +40,7 @@ export function helpTabFor({ view, dashboard, gone, adrift, finished, workflow,
|
||||
if (gone || adrift) return "stuck";
|
||||
if (workspace) return "workspace";
|
||||
if (v === "ask") return "ask";
|
||||
if (v === "subagents") return "subagents";
|
||||
if (dashboard && meterRed) return "meter";
|
||||
if (dashboard) return "dashboard";
|
||||
if (v === "overview" || v.startsWith("doc:")) return "docs";
|
||||
|
||||
@@ -21,6 +21,7 @@
|
||||
<link rel="modulepreload" href="/starters.js" />
|
||||
<link rel="modulepreload" href="/workspace.js" />
|
||||
<link rel="modulepreload" href="/meter.js" />
|
||||
<link rel="modulepreload" href="/subagents.js" />
|
||||
<link rel="modulepreload" href="/mentions.js" />
|
||||
<link rel="modulepreload" href="/favicon.js" />
|
||||
<link rel="modulepreload" href="/vendor/marked.esm.js" />
|
||||
@@ -172,6 +173,18 @@
|
||||
<button type="button" class="btn ghost small brief-btn" id="btn-brief" hidden>
|
||||
Write a brief
|
||||
</button>
|
||||
<!-- Subagents: opted-in skills only. Lit while helpers are on; a click
|
||||
opens the Subagents dialog and never toggles them itself. -->
|
||||
<button type="button" class="btn ghost small subagents-btn" id="btn-subagents" aria-pressed="false" hidden>
|
||||
<!-- An orchestrator and its helpers: one larger node linked to three smaller ones. -->
|
||||
<svg viewBox="0 0 16 16" aria-hidden="true" focusable="false">
|
||||
<path class="sa-link" d="M6.9 6.6L10.9 3.9M7.4 8h3.5M6.9 9.4l4 2.7" />
|
||||
<circle cx="4.6" cy="8" r="2.6" class="sa-hub" />
|
||||
<circle cx="12.4" cy="3" r="1.5" class="sa-node" />
|
||||
<circle cx="12.4" cy="8" r="1.5" class="sa-node" />
|
||||
<circle cx="12.4" cy="13" r="1.5" class="sa-node" />
|
||||
</svg>
|
||||
</button>
|
||||
</div>
|
||||
<div class="views-group">
|
||||
<span class="views-arrow" aria-hidden="true">
|
||||
@@ -580,6 +593,13 @@
|
||||
<rect x="3" y="9" width="18" height="6" rx="3" />
|
||||
<path d="M6 12h7" />
|
||||
</symbol>
|
||||
<symbol id="hi-subagents" viewBox="0 0 24 24" fill="none">
|
||||
<circle cx="7" cy="12" r="3.5" />
|
||||
<circle cx="18" cy="5" r="2" />
|
||||
<circle cx="18" cy="12" r="2" />
|
||||
<circle cx="18" cy="19" r="2" />
|
||||
<path d="M10 10l6-4M10.5 12H16M10 14l6 4" />
|
||||
</symbol>
|
||||
<symbol id="hi-ask" viewBox="0 0 24 24" fill="none">
|
||||
<path d="M4 5h16v11H10l-4 4v-4H4z" />
|
||||
<path d="M8 9.5h8M8 12.5h5" />
|
||||
@@ -1477,7 +1497,61 @@
|
||||
</p>
|
||||
</section>
|
||||
|
||||
<!-- Tab 12: Ask a quick question -->
|
||||
<!-- Tab 12: Helpers (subagents) -->
|
||||
<section class="help-panel" data-tab="subagents">
|
||||
<h3>Helpers (subagents)</h3>
|
||||
<p>
|
||||
On a build, a review and Pathfinder, Plan2Code can hand independent
|
||||
pieces of work to helpers (subagents) while it keeps the conversation
|
||||
with you. The <strong>Subagents</strong> button in the top bar, after
|
||||
Stop session, is lit while helpers are on.
|
||||
</p>
|
||||
<h4>The switch</h4>
|
||||
<ul>
|
||||
<li>
|
||||
Clicking the button opens the <strong>Subagents</strong> dialog; it
|
||||
never switches helpers on or off by itself. Pick <strong>Use
|
||||
helpers</strong> or <strong>Work alone</strong>, edit the instruction
|
||||
Plan2Code follows (<strong>Reset to default</strong> puts the
|
||||
shipped one back), and say how many may run at once.
|
||||
</li>
|
||||
<li>
|
||||
It is off by default and saved for this project and this skill, so
|
||||
the next session of the same skill here starts the same way.
|
||||
</li>
|
||||
<li>
|
||||
The change reaches Plan2Code at its next check-in, as a setting,
|
||||
not as something you typed. How many helpers it can really start is
|
||||
up to your agent; some have no helpers at all.
|
||||
</li>
|
||||
<li>The button only appears on skills that use helpers, and only when Plan2Code can pass the setting on.</li>
|
||||
</ul>
|
||||
<h4>The Subagents tab</h4>
|
||||
<ul>
|
||||
<li>
|
||||
With the first helper, a <strong>Subagents</strong> tab appears before
|
||||
Ask: one row each, with what it was asked, whether it is running, done
|
||||
or failed, and a one-line result at the end. The number on the tab is
|
||||
how many are still running.
|
||||
</li>
|
||||
<li>
|
||||
Helpers report through Plan2Code, so the rows change at its
|
||||
check-ins, not live. The page cannot stop a helper; ask Plan2Code
|
||||
on the Ask tab if one should stop.
|
||||
</li>
|
||||
<li>
|
||||
<strong>Working alone</strong> means your agent has no way to start
|
||||
helpers here, so it is doing the work itself.
|
||||
</li>
|
||||
<li>
|
||||
Pathfinder always uses helpers for its research questions, whatever
|
||||
the switch says, and they show here too.
|
||||
</li>
|
||||
<li>The tab clears when you go back to the dashboard.</li>
|
||||
</ul>
|
||||
</section>
|
||||
|
||||
<!-- Tab 13: Ask a quick question -->
|
||||
<section class="help-panel" data-tab="ask">
|
||||
<h3>Ask a quick question</h3>
|
||||
<p class="help-lead">
|
||||
@@ -1568,7 +1642,7 @@
|
||||
</p>
|
||||
</section>
|
||||
|
||||
<!-- Tab 13: Stopping and finishing -->
|
||||
<!-- Tab 14: Stopping and finishing -->
|
||||
<section class="help-panel" data-tab="finishing">
|
||||
<h3>Stopping and finishing</h3>
|
||||
<p class="help-lead">
|
||||
@@ -1650,7 +1724,7 @@
|
||||
</p>
|
||||
</section>
|
||||
|
||||
<!-- Tab 14: When something looks stuck -->
|
||||
<!-- Tab 15: When something looks stuck -->
|
||||
<section class="help-panel" data-tab="stuck">
|
||||
<h3>When something looks stuck</h3>
|
||||
<p class="help-lead">
|
||||
@@ -1772,7 +1846,7 @@
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<!-- Tab 15: Keyboard and preferences -->
|
||||
<!-- Tab 16: Keyboard and preferences -->
|
||||
<section class="help-panel" data-tab="prefs">
|
||||
<h3>Keyboard and preferences</h3>
|
||||
<p class="help-lead">
|
||||
@@ -1888,7 +1962,7 @@
|
||||
</ul>
|
||||
</section>
|
||||
|
||||
<!-- Tab 16: Privacy and where things are saved -->
|
||||
<!-- Tab 17: Privacy and where things are saved -->
|
||||
<section class="help-panel" data-tab="privacy">
|
||||
<h3>Privacy and where things are saved</h3>
|
||||
<p class="help-lead">
|
||||
@@ -1925,7 +1999,11 @@
|
||||
</li>
|
||||
<li>
|
||||
your role, theme, colors, card width and sounds, in
|
||||
<code>looks.json</code>.
|
||||
<code>looks.json</code>;
|
||||
</li>
|
||||
<li>
|
||||
your Subagents switch for each project and skill, in
|
||||
<code>subagents.json</code>.
|
||||
</li>
|
||||
</ul>
|
||||
<p>
|
||||
@@ -2039,6 +2117,46 @@
|
||||
</div>
|
||||
</dialog>
|
||||
|
||||
<!-- Subagents: the switch for this skill, filled from the frame's
|
||||
`subagents` by app.js and saved through POST /subagents. It borrows
|
||||
the User Preferences dialog's classes, so it needs no dialog styles of
|
||||
its own, only a themed number box. -->
|
||||
<dialog class="modal looks subagents" id="subagents-modal" aria-labelledby="subagents-title">
|
||||
<h2 id="subagents-title">Subagents</h2>
|
||||
<p class="modal-blurb">
|
||||
Let Plan2Code hand independent work to helpers in this skill. Saved for this
|
||||
project and this skill.
|
||||
</p>
|
||||
<fieldset class="modal-ranges looks-row">
|
||||
<legend>Helpers</legend>
|
||||
<label><input type="radio" name="subagents-on" value="on" /> <span>Use helpers</span></label>
|
||||
<label><input type="radio" name="subagents-on" value="off" checked /> <span>Work alone</span></label>
|
||||
</fieldset>
|
||||
<fieldset class="modal-ranges">
|
||||
<legend>Instruction</legend>
|
||||
<textarea id="subagents-instruction" rows="4" maxlength="2000" aria-label="Instruction"></textarea>
|
||||
<div class="models-actions">
|
||||
<button type="button" class="btn small ghost" id="subagents-default">Reset to default</button>
|
||||
<span class="help">Passed to the agent as written, at its next check-in.</span>
|
||||
</div>
|
||||
</fieldset>
|
||||
<fieldset class="modal-ranges">
|
||||
<legend>At most</legend>
|
||||
<label>
|
||||
<input type="number" id="subagents-max" min="1" max="20" step="1" aria-label="At most this many helpers at once" />
|
||||
<span>helpers at once</span>
|
||||
</label>
|
||||
<p class="help">Advisory: your agent's own limit still applies.</p>
|
||||
</fieldset>
|
||||
<p class="help" id="subagents-checkin"></p>
|
||||
<p class="help" id="subagents-research" hidden></p>
|
||||
<p class="help" id="subagents-status" role="status"></p>
|
||||
<div class="modal-actions">
|
||||
<button type="button" class="btn ghost" id="subagents-cancel">Cancel</button>
|
||||
<button type="button" class="btn primary" id="subagents-save">Save</button>
|
||||
</div>
|
||||
</dialog>
|
||||
|
||||
<!-- The Workspace: the folder this session started in plus any added as
|
||||
context. The list is drawn by app.js from the frame's `workspace`;
|
||||
every change goes through the server's /workspace routes. -->
|
||||
|
||||
@@ -0,0 +1,223 @@
|
||||
// Plan2Code Web Console - the Subagents switch's opt-in table, wording and checks.
|
||||
//
|
||||
// The source of truth for which workflows offer the switch, the instruction
|
||||
// each one ships with, the fixed frame every "on" block carries, the exact
|
||||
// lines the agent reads at a pickup (blockFor()), and the house rules for the
|
||||
// helpers an agent reports back (checkHelper()). No DOM access at module scope
|
||||
// and no imports: the server, console.mjs, the page and `node --test` all
|
||||
// import this file.
|
||||
|
||||
// The one place a skill opts in (FR-1). Wording is behaviour-level and names
|
||||
// no harness tool, so any agent can follow it or harmlessly ignore it.
|
||||
export const SUBAGENT_WORKFLOWS = Object.freeze({
|
||||
implement: Object.freeze({
|
||||
instruction:
|
||||
"Hand independent tasks in a phase to helpers: tasks that touch different files and do not depend on each other. Keep tasks that share files, the phase's tests and the sign-off with you.",
|
||||
}),
|
||||
"implement-review": Object.freeze({
|
||||
instruction:
|
||||
"Hand independent tasks in a phase to helpers: tasks that touch different files and do not depend on each other. Keep tasks that share files, the phase's tests and the sign-off with you.",
|
||||
}),
|
||||
"quick-task": Object.freeze({
|
||||
instruction:
|
||||
"Use helpers for side lookups, such as reading unfamiliar code or checking documentation, while you make the change yourself.",
|
||||
}),
|
||||
review: Object.freeze({
|
||||
instruction:
|
||||
"Split the review across helpers by area (for example correctness, tests and security), then merge and de-duplicate their findings yourself before you report.",
|
||||
}),
|
||||
pathfinder: Object.freeze({
|
||||
instruction:
|
||||
"Use helpers for codebase recon, sketches and lookups beside the conversation. Keep every question for the person with you.",
|
||||
}),
|
||||
});
|
||||
|
||||
export function offered(workflow) {
|
||||
return typeof workflow === "string" && Object.prototype.hasOwnProperty.call(SUBAGENT_WORKFLOWS, workflow);
|
||||
}
|
||||
|
||||
export const MAX_MIN = 1;
|
||||
export const MAX_MAX = 20;
|
||||
export const DEFAULT_MAX = 3;
|
||||
export const INSTRUCTION_MAX_CHARS = 2000;
|
||||
export const HELPER_TITLE_MAX = 80;
|
||||
export const HELPER_ASK_MAX = 400;
|
||||
export const HELPER_RESULT_MAX = 200;
|
||||
export const HELPER_STATES = Object.freeze(["running", "done", "failed"]);
|
||||
|
||||
/* ------------------------------------------------------------- settings */
|
||||
|
||||
export function defaultInstruction(workflow) {
|
||||
return offered(workflow) ? SUBAGENT_WORKFLOWS[workflow].instruction : "";
|
||||
}
|
||||
|
||||
// The person's own text when they wrote some, else the workflow's default.
|
||||
export function effectiveInstruction(setting) {
|
||||
const own = setting && typeof setting.instruction === "string" ? setting.instruction.trim() : "";
|
||||
return own || defaultInstruction(setting && setting.workflow);
|
||||
}
|
||||
|
||||
export function defaultSetting(workflow) {
|
||||
return { workflow, on: false, instruction: null, max: DEFAULT_MAX };
|
||||
}
|
||||
|
||||
/**
|
||||
* `{ on, instruction, max }` from untrusted input, or `{ error }` naming the
|
||||
* field that failed: "bad" (wrong type), "too-long" (instruction) or "max".
|
||||
* Returns an error object rather than throwing, so the route and the store
|
||||
* reader share one validator. An empty instruction means the default: null.
|
||||
*/
|
||||
export function cleanSetting(input) {
|
||||
if (!input || typeof input !== "object" || Array.isArray(input)) return { error: "bad" };
|
||||
if (typeof input.on !== "boolean") return { error: "bad" };
|
||||
let instruction = null;
|
||||
if (input.instruction !== null && input.instruction !== undefined) {
|
||||
if (typeof input.instruction !== "string") return { error: "bad" };
|
||||
const trimmed = input.instruction.trim();
|
||||
if (trimmed.length > INSTRUCTION_MAX_CHARS) return { error: "too-long" };
|
||||
instruction = trimmed || null;
|
||||
}
|
||||
const max = input.max;
|
||||
if (!Number.isInteger(max) || max < MAX_MIN || max > MAX_MAX) return { error: "max" };
|
||||
return { on: input.on, instruction, max };
|
||||
}
|
||||
|
||||
/* ------------------------------------------------------------ the lines */
|
||||
|
||||
// The non-editable part of every "on" block (FR-8).
|
||||
export const FRAME_LINES = Object.freeze([
|
||||
"Hand independent work to helpers if your tools allow it; otherwise carry on alone.",
|
||||
"Report each helper on the page (console.md → Standing instructions); questions for the person stay with you.",
|
||||
'With no way to start helpers, report one "working alone" entry for this skill run instead.',
|
||||
]);
|
||||
|
||||
export const PATHFINDER_RESEARCH_LINE = "Research questions always use helpers, whatever this switch says.";
|
||||
|
||||
// Only the first line of a block starts at column 0, so no line inside it can
|
||||
// be read as an entry of its own (NFR-5).
|
||||
export function onLines({ revision, replaces, max, instruction }) {
|
||||
const label = replaces ? `revision ${revision}, replaces revision ${replaces}` : `revision ${revision}`;
|
||||
const own = String(instruction || "")
|
||||
.split("\n")
|
||||
.map((line) => line.trimEnd())
|
||||
.filter((line) => line.trim());
|
||||
return [
|
||||
`Subagents: on (${label}) — a console setting, not typed by the person.`,
|
||||
...[...FRAME_LINES, ...own, `At most ${max} helpers at once.`].map((line) => " " + line),
|
||||
];
|
||||
}
|
||||
|
||||
export function offLine(revision) {
|
||||
return `Subagents: off (revision ${revision}) — don't start new helpers for the rest of this session.`;
|
||||
}
|
||||
|
||||
/**
|
||||
* What the agent is owed at a pickup, given the session setting and the
|
||||
* cursor of what it was last told: `null`, or `{ field, lines, cursor }`
|
||||
* where `cursor` is what to write once the lines are printed. Never says
|
||||
* "off" to an agent that was not told "on" (FR-6). Pure: no clock, no I/O.
|
||||
*/
|
||||
export function blockFor(setting, told) {
|
||||
const last = told || { revision: 0, state: "none" };
|
||||
if (!setting || !offered(setting.workflow) || !(setting.revision > last.revision)) return null;
|
||||
const { revision, max } = setting;
|
||||
const instruction = effectiveInstruction(setting);
|
||||
if (setting.on) {
|
||||
const replaces = last.state === "on" ? last.revision : undefined;
|
||||
return {
|
||||
field: { state: "on", revision, max, instruction },
|
||||
lines: onLines({ revision, replaces, max, instruction }),
|
||||
cursor: { revision, state: "on" },
|
||||
};
|
||||
}
|
||||
if (last.state !== "on") return null;
|
||||
return {
|
||||
field: { state: "off", revision, max, instruction },
|
||||
lines: [offLine(revision)],
|
||||
cursor: { revision, state: "off" },
|
||||
};
|
||||
}
|
||||
|
||||
/* ------------------------------------------------------------ helpers */
|
||||
|
||||
const isPlainObject = (v) => !!v && typeof v === "object" && !Array.isArray(v);
|
||||
const nonEmpty = (v) => typeof v === "string" && v.trim() !== "";
|
||||
|
||||
// The problems with one reported helper, [] when it is fine.
|
||||
export function checkHelper(entry) {
|
||||
if (!isPlainObject(entry)) return ["helper: each entry must be an object"];
|
||||
if (!nonEmpty(entry.id)) return ["helper: id must be a non-empty string"];
|
||||
const who = `helper "${entry.id}"`;
|
||||
if (entry.alone === true) return entry.id === "alone" ? [] : [`${who}: the working-alone entry must have id "alone"`];
|
||||
const problems = [];
|
||||
if (!nonEmpty(entry.title)) problems.push(`${who}: title must be a non-empty string`);
|
||||
else if (entry.title.length > HELPER_TITLE_MAX) problems.push(`${who}: title must be at most ${HELPER_TITLE_MAX} characters`);
|
||||
if (!nonEmpty(entry.ask)) problems.push(`${who}: ask must be a non-empty string`);
|
||||
else if (entry.ask.length > HELPER_ASK_MAX) problems.push(`${who}: ask must be at most ${HELPER_ASK_MAX} characters`);
|
||||
if (!HELPER_STATES.includes(entry.state)) problems.push(`${who}: state must be running, done or failed`);
|
||||
if (entry.result !== undefined) {
|
||||
if (typeof entry.result !== "string") problems.push(`${who}: result must be a string`);
|
||||
else if (entry.result.length > HELPER_RESULT_MAX) problems.push(`${who}: result must be at most ${HELPER_RESULT_MAX} characters`);
|
||||
}
|
||||
return problems;
|
||||
}
|
||||
|
||||
// The problems with a whole merged list.
|
||||
export function checkHelpers(list) {
|
||||
if (!Array.isArray(list)) return ["helpers must be an array"];
|
||||
const problems = [];
|
||||
const seen = new Set();
|
||||
let alone = 0;
|
||||
for (const entry of list) {
|
||||
if (isPlainObject(entry) && nonEmpty(entry.id)) {
|
||||
if (seen.has(entry.id)) problems.push(`helper "${entry.id}": duplicate id`);
|
||||
seen.add(entry.id);
|
||||
if (entry.alone === true && ++alone === 2) problems.push(`helper "${entry.id}": only one working-alone entry is allowed`);
|
||||
}
|
||||
problems.push(...checkHelper(entry));
|
||||
}
|
||||
return problems;
|
||||
}
|
||||
|
||||
/* ------------------------------------------------------------ the page */
|
||||
|
||||
// The page's rules for the button, the modal and the tab, kept here so they
|
||||
// are tested without a browser. `frame` is the state frame's `subagents`
|
||||
// block; app.js only renders what these say.
|
||||
|
||||
export const CHECKIN_LINE = "Helpers report through Plan2Code, so their progress shows here at its check-ins, not live.";
|
||||
|
||||
const STATE_LABELS = Object.freeze({ running: "Running", done: "Done", failed: "Failed" });
|
||||
|
||||
// The switch shows only where the skill opts in AND the agent's console copy
|
||||
// said it can deliver it (FR-3).
|
||||
export function showSwitch(frame) {
|
||||
return Boolean(frame && frame.offered && frame.supported);
|
||||
}
|
||||
|
||||
// The button's tooltip and accessible name (FR-2).
|
||||
export function switchLabel(frame) {
|
||||
return frame && frame.on ? "Subagents: on" : "Subagents: off";
|
||||
}
|
||||
|
||||
// What the Subagents tab draws: the working-alone note, or one row per helper
|
||||
// in the order the agent reported them. A result shows once the helper ended.
|
||||
export function helperRows(helpers) {
|
||||
const list = Array.isArray(helpers) ? helpers.filter(isPlainObject) : [];
|
||||
if (list.some((h) => h.alone === true)) return { alone: true, rows: [] };
|
||||
const rows = list.map(({ id, title, ask, state, result }) => ({
|
||||
id,
|
||||
title,
|
||||
ask,
|
||||
state,
|
||||
stateLabel: STATE_LABELS[state] || STATE_LABELS.running,
|
||||
...((state === "done" || state === "failed") && typeof result === "string" && result ? { result } : {}),
|
||||
}));
|
||||
return { alone: false, rows };
|
||||
}
|
||||
|
||||
// Never an empty tab. Independent of on / off, so Pathfinder's research
|
||||
// helpers show even with the switch off (FR-11, FR-12).
|
||||
export function showTab(frame, helpers) {
|
||||
return showSwitch(frame) && Array.isArray(helpers) && helpers.length > 0;
|
||||
}
|
||||
@@ -25,6 +25,7 @@ import {
|
||||
LOOKS_FILE,
|
||||
PUBLIC_DIR,
|
||||
SHIPPED_MODELS_FILE,
|
||||
SUBAGENTS_SETTING_FILE,
|
||||
UPDATE_CHECK_FILE,
|
||||
USER_MODELS_FILE,
|
||||
WORKSPACE_FILE,
|
||||
@@ -38,6 +39,7 @@ import {
|
||||
fileStamp,
|
||||
handleFile,
|
||||
initialWorkspace,
|
||||
latestOpenCaps,
|
||||
nowIso,
|
||||
parseArgs,
|
||||
pendingChatCount,
|
||||
@@ -46,20 +48,25 @@ import {
|
||||
readJson,
|
||||
readLedger,
|
||||
readOverview,
|
||||
readSubagentSetting,
|
||||
readWorkspace,
|
||||
rememberWorkspace,
|
||||
rememberedWorkspace,
|
||||
removeCleanup,
|
||||
remoteWarning,
|
||||
saveSubagentStoreEntry,
|
||||
specKey,
|
||||
subagentStoreEntry,
|
||||
typedCount,
|
||||
withStateLock,
|
||||
writeJsonAtomic,
|
||||
writeSubagentSetting,
|
||||
writeWorkspace,
|
||||
} from "./lib.mjs";
|
||||
import { DOC_TYPES, MAX_ATTACHMENTS, MAX_DOC_BYTES, docExt, workflowLabel, workflowTitle } from "./public/answers.js";
|
||||
import { CHAT_LIMIT, CHAT_MAX_CHARS, chatOffline } from "./public/chat.js";
|
||||
import { meterView } from "./public/meter.js";
|
||||
import { cleanSetting, defaultSetting, offered } from "./public/subagents.js";
|
||||
import { ACCENTS, DEFAULT_ACCENT, DEFAULT_CARD_WIDTH, cardWidth } from "./public/palette.js";
|
||||
import { defaultName, freeName, nameProblem } from "./public/workspace.js";
|
||||
import { checkForUpdate } from "./update-check.mjs";
|
||||
@@ -212,6 +219,7 @@ const SERVABLE = new Set([
|
||||
"starters.js",
|
||||
"workspace.js",
|
||||
"meter.js",
|
||||
"subagents.js",
|
||||
"mentions.js",
|
||||
"favicon.js",
|
||||
"start-stop.mp3",
|
||||
@@ -601,6 +609,48 @@ function ensureConversation(state) {
|
||||
if (entry) appendEvent(DIR, { type: "chat-reset", reason: entry.reason });
|
||||
}
|
||||
|
||||
/* ------------------------------------------------------------ subagents */
|
||||
|
||||
// subagents-setting.json has one writer, this server, and the agent hears of
|
||||
// it only through what console.mjs reads there; events.ndjson's latest `open`
|
||||
// says whether the agent's console copy can carry it. Both re-read only when
|
||||
// their file has moved.
|
||||
const SUBAGENTS_SETTING_PATH = path.join(DIR, SUBAGENTS_SETTING_FILE);
|
||||
const EVENTS_PATH = path.join(DIR, "events.ndjson");
|
||||
|
||||
let subagentSettingSeen = { stamp: null, setting: null };
|
||||
function subagentSettingNow() {
|
||||
const stamp = fileStamp(SUBAGENTS_SETTING_PATH);
|
||||
if (stamp !== subagentSettingSeen.stamp) subagentSettingSeen = { stamp, setting: readSubagentSetting(DIR) };
|
||||
return subagentSettingSeen.setting;
|
||||
}
|
||||
|
||||
let capsSeen = { stamp: null, caps: [] };
|
||||
function openCapsNow() {
|
||||
const stamp = fileStamp(EVENTS_PATH);
|
||||
if (stamp !== capsSeen.stamp) capsSeen = { stamp, caps: latestOpenCaps(DIR) };
|
||||
return capsSeen.caps;
|
||||
}
|
||||
|
||||
const sameSetting = (a, b) => a.workflow === b.workflow && a.on === b.on && a.instruction === b.instruction && a.max === b.max;
|
||||
|
||||
/**
|
||||
* Turn the per-project store into this session's setting, for the workflow
|
||||
* the session is in now. The only place that happens (FR-7): a session an
|
||||
* older server ran has no setting file, so nothing is ever injected into it.
|
||||
* A record that already matches is left alone, revision and all, so a
|
||||
* restart alone never re-tells the agent anything.
|
||||
*/
|
||||
function syncSubagentSetting(state) {
|
||||
if (!state || typeof state.workflow !== "string") return;
|
||||
const { workflow } = state;
|
||||
const { on, instruction, max } = offered(workflow) ? subagentStoreEntry(sessionWorktree(), workflow) : defaultSetting(workflow);
|
||||
const target = { workflow, on, instruction, max };
|
||||
const current = readSubagentSetting(DIR);
|
||||
if (current && sameSetting(current, target)) return;
|
||||
writeSubagentSetting(DIR, { ...target, revision: (current ? current.revision : 0) + 1 });
|
||||
}
|
||||
|
||||
// What the page needs to draw itself, in the shape of the SSE state frame.
|
||||
// `have` names that exact view, for the page to hand back when it opens its
|
||||
// stream (see /events).
|
||||
@@ -615,20 +665,33 @@ function stateFrame(state) {
|
||||
chat: { ...chatForFrame(chatEntries(), state), pickedUp: chatPickedUp(), offline: chatOfflineNow(state) },
|
||||
workspace: workspaceView(),
|
||||
meter: meterView(ledgerEntries()),
|
||||
subagents: subagentsView(state),
|
||||
...(updateInfo ? { update: updateInfo } : {}),
|
||||
have: haveKey(),
|
||||
};
|
||||
}
|
||||
|
||||
// The page shows the switch only when `offered && supported` (FR-3); the
|
||||
// frame says both and leaves combining them to the page. `instruction: null`
|
||||
// is the shipped default, which the page reads from subagents.js itself.
|
||||
function subagentsView(state) {
|
||||
const workflow = state && state.workflow;
|
||||
const { on, instruction, max, revision } = subagentSettingNow() || { ...defaultSetting(workflow), revision: 0 };
|
||||
return { offered: offered(workflow), supported: openCapsNow().includes("subagents"), on, instruction, max, revision };
|
||||
}
|
||||
|
||||
function haveKey() {
|
||||
const { pending, stop } = resultFlags();
|
||||
chatEntries();
|
||||
chatPickedUp();
|
||||
workspaceNow();
|
||||
ledgerEntries();
|
||||
subagentSettingNow();
|
||||
openCapsNow();
|
||||
return (
|
||||
`${STARTED}.${rev}.${pending ? 1 : 0}${stop ? 1 : 0}.${chatSeen.stamp || ""}.${cursorSeen.stamp || ""}` +
|
||||
`.${workspaceSeen.stamp || ""}.${ledgerSeen.stamp || ""}.${updateInfo ? updateInfo.latest : ""}`
|
||||
`.${workspaceSeen.stamp || ""}.${ledgerSeen.stamp || ""}.${updateInfo ? updateInfo.latest : ""}` +
|
||||
`.${subagentSettingSeen.stamp || ""}.${capsSeen.stamp || ""}`
|
||||
);
|
||||
}
|
||||
|
||||
@@ -1172,6 +1235,39 @@ const server = http.createServer((req, res) => {
|
||||
});
|
||||
}
|
||||
|
||||
// The Subagents switch for the session's workflow. Saved per project folder
|
||||
// for the next session, and applied to this one with a bumped revision, which
|
||||
// is what console.mjs hands the agent at its next pickup. Never blocked by,
|
||||
// and never blocking, a card send.
|
||||
if (pathname === "/subagents" && req.method === "POST") {
|
||||
if (!originOk(req, port)) return json(res, 403, { error: "bad origin" });
|
||||
return readBody(req, (err, body) => {
|
||||
if (err) return json(res, err.tooBig ? 413 : 400, { error: err.tooBig ? "too large" : "body must be JSON" });
|
||||
const state = readState();
|
||||
if (!state || !offered(state.workflow)) return json(res, 400, { error: "not-offered" });
|
||||
const clean = cleanSetting(body);
|
||||
if (clean.error) return json(res, 400, { error: clean.error });
|
||||
const { on, instruction, max } = clean;
|
||||
const current = readSubagentSetting(DIR);
|
||||
const next = { workflow: state.workflow, on, instruction, max };
|
||||
// The store is per project, so another session may have moved it since
|
||||
// this one synced: it always takes the person's latest pick. Only a
|
||||
// real change to this session's setting bumps what the agent hears.
|
||||
const unchanged = Boolean(current && sameSetting(current, next));
|
||||
try {
|
||||
saveSubagentStoreEntry(sessionWorktree(), state.workflow, { on, instruction, max });
|
||||
if (!unchanged) writeSubagentSetting(DIR, { ...next, revision: (current ? current.revision : 0) + 1 });
|
||||
} catch (e) {
|
||||
return json(res, 500, { error: String(e.message) });
|
||||
}
|
||||
if (unchanged) return json(res, 200, { ok: true, setting: current });
|
||||
const setting = readSubagentSetting(DIR);
|
||||
appendEvent(DIR, { type: "subagents", on, revision: setting.revision });
|
||||
pushState();
|
||||
return json(res, 200, { ok: true, setting });
|
||||
});
|
||||
}
|
||||
|
||||
// The launcher's model menu: what ships (read-only here) and what the user added.
|
||||
if (pathname === "/models" && req.method === "GET") {
|
||||
const saved = readJson(USER_MODELS_FILE, null) || {};
|
||||
@@ -1400,6 +1496,9 @@ const server = http.createServer((req, res) => {
|
||||
try {
|
||||
ensureConversation(written.state);
|
||||
} catch {}
|
||||
try {
|
||||
syncSubagentSetting(written.state);
|
||||
} catch {}
|
||||
}
|
||||
}
|
||||
// Name the items that went. A page with OTHER answers staged should drop
|
||||
@@ -1726,6 +1825,9 @@ function checkState() {
|
||||
try {
|
||||
ensureConversation(parsed);
|
||||
} catch {}
|
||||
try {
|
||||
syncSubagentSetting(parsed);
|
||||
} catch {}
|
||||
try {
|
||||
followSpecDir(parsed);
|
||||
} catch {}
|
||||
@@ -1900,6 +2002,9 @@ function onListening(port) {
|
||||
try {
|
||||
bootWorkspace();
|
||||
} catch {}
|
||||
try {
|
||||
syncSubagentSetting(readState());
|
||||
} catch {}
|
||||
process.stdout.write(JSON.stringify({ type: "ready", url, port, sid: SID }) + "\n");
|
||||
try {
|
||||
startUpdateCheck();
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "Plan2Code",
|
||||
"version": "2.4.2",
|
||||
"version": "2.5.0",
|
||||
"description": "A structured 4-step workflow methodology for AI-assisted software development",
|
||||
"keywords": [
|
||||
"ai",
|
||||
@@ -17,6 +17,6 @@
|
||||
"url": "https://github.com/jparkerweb/plan2code"
|
||||
},
|
||||
"homepage": "https://github.com/jparkerweb/plan2code",
|
||||
"releaseDate": "2026-10-05",
|
||||
"releaseDate": "2026-10-06",
|
||||
"mode": "utility"
|
||||
}
|
||||
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "Plan2Code",
|
||||
"version": "2.4.2",
|
||||
"version": "2.5.0",
|
||||
"description": "A structured 4-step workflow methodology for AI-assisted software development",
|
||||
"keywords": [
|
||||
"ai",
|
||||
@@ -17,6 +17,6 @@
|
||||
"url": "https://github.com/jparkerweb/plan2code"
|
||||
},
|
||||
"homepage": "https://github.com/jparkerweb/plan2code",
|
||||
"releaseDate": "2026-10-05",
|
||||
"releaseDate": "2026-10-06",
|
||||
"mode": "utility"
|
||||
}
|
||||
@@ -64,6 +64,13 @@ progress bar is the first thing someone watching a build looks at. The session
|
||||
meter counts the build's tasks from `cleared` as it rises, so keep it current,
|
||||
and start every phase (a second one in the same run too) at `"cleared": 0`.
|
||||
|
||||
`"version": 1` is for the first phase of a session only. A doc's version
|
||||
never goes back (console.md → House rules, rule 9), so a later phase in the
|
||||
same session reposts `phase` and `phasefile` at one more than the version the
|
||||
page holds, with the new phase's title and content. The same goes for
|
||||
`report` at sign-off and `review` in a mid-session review: version 1 the
|
||||
first time, then up from wherever the page has it.
|
||||
|
||||
`phasefile` is the whole `phase-X.md`, verbatim from disk, as its own tab —
|
||||
the person can read the prerequisites and task specs while you build. Re-post
|
||||
it whenever the file changes, which is every task: the checkbox write that
|
||||
@@ -111,6 +118,12 @@ printed), never into the project or into `~/.plan2code/console/` directly:
|
||||
- Do not call `wait` while building. There is nothing to collect, and the page
|
||||
holds anything the person sends until you next look.
|
||||
|
||||
A build may receive a `Subagents:` standing instruction, on `open` output or a
|
||||
`chat` check between tasks. Follow console.md → Standing instructions for
|
||||
handing independent tasks to helpers and reporting them as `helpers`. Keep the
|
||||
per-task progress posts, the checkbox writes, the chat checks and the sign-off
|
||||
with you.
|
||||
|
||||
### Quick questions between tasks
|
||||
|
||||
The person can ask a Quick question on the Ask tab at any point in a build
|
||||
@@ -195,7 +208,8 @@ only ever be offered once nothing could come of it:
|
||||
`reply` carries `Approve this phase: approved`, which is the terminal's
|
||||
`approved`. If the note that came with an approval asks for a change, treat it
|
||||
as "describe any issues": do the change first and ask again. `changes` means
|
||||
exactly what it says: address it, bump the report's version, and reopen the
|
||||
exactly what it says: address it, bump the report's version (a later phase's
|
||||
report starts above the last one's, too), and reopen the
|
||||
item (`"status": "reopened"`) with a reply in its `thread`. `review` is the
|
||||
person asking for the code review before they approve anything — see "The
|
||||
review, mid-session" below.
|
||||
|
||||
@@ -170,7 +170,7 @@ so even a kill at the worst possible moment costs you a repeat, never an answer.
|
||||
|
||||
| Exit | Meaning | What you do |
|
||||
| --- | --- | --- |
|
||||
| `0` | They pressed Send, or asked a Quick question. stdout is the result JSON, and may carry `workspace` (changes to the folder list, see Workspace). | Handle the cards (if any), the chat (if any) and any `workspace` changes, then post once (below, Quick questions and Workspace). |
|
||||
| `0` | They pressed Send, or asked a Quick question. stdout is the result JSON, and may carry `workspace` (changes to the folder list, see Workspace) and `subagents` (the helpers switch, see Standing instructions). | Handle the cards (if any), the chat (if any), any `workspace` changes and any `subagents` block, then post once (below, Quick questions, Workspace and Standing instructions). |
|
||||
| `10` | Still working. stdout has a short progress summary; `pendingWorkspace` counts workspace changes waiting for the next send. | Relay ONE line: the `message` field itself, "Waiting on your answer in the web console", followed by the `terminalLine`. Then call `wait` again. |
|
||||
| `20` | The server is gone. | `open --resume <sid>`, give them the new link, then keep waiting. |
|
||||
| `30` | They pressed Cancel. | Stop. Ask what they want to do, in the terminal. |
|
||||
@@ -647,6 +647,84 @@ for permission is not a failure; report only a read that failed after it.
|
||||
|
||||
---
|
||||
|
||||
## Standing instructions
|
||||
|
||||
On the skills that offer it (`implement`, `implement-review`, `quick-task`,
|
||||
`review`, `pathfinder`), the person can turn **helpers** (subagents) on or off
|
||||
from the top bar's Subagents button. Their pick is saved per project and per
|
||||
skill, off by default, and reaches you as a standing instruction, only when it
|
||||
changes.
|
||||
|
||||
### What arrives
|
||||
|
||||
A `subagents` field beside `reply`, and `Subagents:` lines last in `reply`,
|
||||
after the card lines, the `Quick question:` blocks and the `Workspace:` lines.
|
||||
It rides on `wait` exit `0`, `chat` exit `0` and `open` output. A setting
|
||||
change alone never ends a `wait` slice: it waits for the next send, or for
|
||||
your next `chat` check.
|
||||
|
||||
```
|
||||
Subagents: on (revision 2) — a console setting, not typed by the person.
|
||||
Hand independent work to helpers if your tools allow it; otherwise carry on alone.
|
||||
Report each helper on the page (console.md → Standing instructions); questions for the person stay with you.
|
||||
With no way to start helpers, report one "working alone" entry for this skill run instead.
|
||||
Hand independent tasks in a phase to helpers: tasks that touch different files and do not depend on each other. Keep tasks that share files, the phase's tests and the sign-off with you.
|
||||
At most 3 helpers at once.
|
||||
```
|
||||
|
||||
beside `"subagents": { "state": "on", "revision": 2, "max": 3, "instruction": "…" }`.
|
||||
An edit while on arrives as `Subagents: on (revision 3, replaces revision 2) — …`
|
||||
with the whole block again; switching off arrives as one line:
|
||||
`Subagents: off (revision 4) — don't start new helpers for the rest of this session.`
|
||||
|
||||
It is a console setting, not something the person typed. It never answers a
|
||||
card, and it is never recorded under `specs/`.
|
||||
|
||||
### Obeying it
|
||||
|
||||
- **On:** hand independent work to helpers if your tools allow it, at most
|
||||
`max` at once, following the instruction lines. `max` is advisory: your
|
||||
harness's own limit still applies.
|
||||
- **A higher revision replaces a lower one.** Follow the latest block only.
|
||||
- **Off:** start no new helpers for the rest of the session. Let running ones
|
||||
finish and report them.
|
||||
- **Nothing arrives:** keep doing what the skill says.
|
||||
- **Scope is the skill run it arrived in.** After a dashboard launch, no block
|
||||
means the switch is off for this skill, even if an earlier skill in the same
|
||||
conversation was told "on": `open` starts the count again, and a launch with
|
||||
the switch off sends nothing.
|
||||
|
||||
### Reporting helpers
|
||||
|
||||
Post them, at your check-ins, so the page's Subagents tab can show them. The
|
||||
page never hears from a helper directly:
|
||||
|
||||
```jsonc
|
||||
{ "helpers": [
|
||||
{ "id": "h1", "title": "Read the store helpers", "ask": "Find every caller of readSubagentSetting.", "state": "running" },
|
||||
{ "id": "h2", "title": "Check the tests", "ask": "Run the subagents tests and report failures.", "state": "done", "result": "All 9 pass." }
|
||||
] }
|
||||
```
|
||||
|
||||
- `id` (non-empty), `title` (at most 80 characters), `ask` (at most 400) and
|
||||
`state` (`running`, `done` or `failed`) are required; `result` (at most 200)
|
||||
is the one line you add once a helper ends.
|
||||
- Merged by `id`: post a helper again with its new `state` and `result` and it
|
||||
updates in place. `"helpers": null` clears the list. A dashboard hop clears it
|
||||
too; a resume into the same skill keeps it.
|
||||
- One post per change worth seeing, not a stream.
|
||||
- Questions for the person stay with you, never with a helper: most harnesses
|
||||
give helpers no way to ask, and an answer only reaches the agent holding the
|
||||
session.
|
||||
- **No way to start helpers?** Post one `{ "id": "alone", "alone": true }`
|
||||
entry for the skill run instead. The tab then says you are working alone.
|
||||
- **Pathfinder:** research questions always use helpers and are always
|
||||
reported, whatever the switch says. The switch governs recon, sketches and
|
||||
lookups beside the conversation.
|
||||
- Helpers add no session meter points. Post no `run` for them.
|
||||
|
||||
---
|
||||
|
||||
## Launches (dashboard only)
|
||||
|
||||
A `dashboard` session is not a conversation: the page draws a menu of every
|
||||
@@ -763,7 +841,10 @@ commands follow the pipeline: the sign-off's is
|
||||
|
||||
### Review (`review`)
|
||||
|
||||
Scope questions up front, then the findings report as a doc (`id: "report"`),
|
||||
Scope questions up front — run standalone with nothing named, the first is
|
||||
a `choice`, "What should I review?", built from a quick scan (branch changes,
|
||||
uncommitted changes, specs, files you name; each option with its size),
|
||||
never an assumed target; a build's review skips it (`building.md`). Then the findings report as a doc (`id: "report"`),
|
||||
then the pick-what-gets-fixed menu as a `multi` or `choice` keyed by finding
|
||||
id, carrying `"doc": "report"` so the card links straight to the findings.
|
||||
Settle that item (`"status": "answered"` plus the `answer` they sent) in
|
||||
@@ -797,6 +878,8 @@ that is what the person is there to download. The finish carries no
|
||||
- Chart Step 8's research subagents must all report back before the
|
||||
finish (Finishing → Nothing of yours may still be running); the finish
|
||||
body then names what each one found.
|
||||
- Report every research subagent as a helper, whatever the Subagents switch
|
||||
says (Standing instructions → Reporting helpers).
|
||||
- At every session end, post `finish` (headline, `body`, and Form A's command as
|
||||
`command`) BEFORE `stop`. Someone who spent the session in the browser never
|
||||
sees the Trail Footer, and without this their last screen promises a question
|
||||
@@ -1146,6 +1229,16 @@ A patch that breaks one of these is rejected with exit `3` and a message:
|
||||
(Session meter) and a non-empty `id`; a `folderIssue` needs non-empty
|
||||
`name` and `reason` strings, and `hint`, when present, is one too. Rules 4
|
||||
and 5 cover `reason` and `hint`.
|
||||
8. **`helpers` entries are well formed** (Standing instructions → Reporting
|
||||
helpers): an array of objects, each with a unique `id`, a `title`, an `ask`
|
||||
and a known `state` within their limits, plus at most one `alone` entry.
|
||||
Rules 4 and 5 cover `title`, `ask` and `result`.
|
||||
9. **A doc's `version` never goes back.** Sending a known doc a lower
|
||||
`version` than the page holds is refused: it is almost always a stale or
|
||||
copied payload. The same version again is fine, and a dashboard hop starts
|
||||
every doc fresh. Anything else reusing a doc id in the same session (a
|
||||
build's second phase, a second report or review) continues from the
|
||||
version the page holds.
|
||||
|
||||
These are workflow rules you already follow. The server just makes them checkable.
|
||||
|
||||
@@ -1167,7 +1260,9 @@ cannot see them, and the moment it says the session ended, the person is
|
||||
free to close that terminal and kill them mid-write. While you wait, post
|
||||
`{"agent":{"status":"working","activity":"Researching 3 questions (1 of 3 back)"}}`
|
||||
and update the count as each returns. Never write a `finish.body` that says
|
||||
work "is running in the background" or "will finish on its own".
|
||||
work "is running in the background" or "will finish on its own". Mark every
|
||||
reported helper `done` or `failed` before the finish, so the Subagents tab
|
||||
never ends on a row still running.
|
||||
|
||||
### 1. Post the finish
|
||||
|
||||
|
||||
@@ -64,6 +64,8 @@ import {
|
||||
readChat,
|
||||
readJson,
|
||||
readLedger,
|
||||
readSubagentCursor,
|
||||
readSubagentSetting,
|
||||
readWorkspace,
|
||||
reapHandles,
|
||||
rememberedWorkspace,
|
||||
@@ -71,6 +73,7 @@ import {
|
||||
removeScratch,
|
||||
removeSessions,
|
||||
repoRoots,
|
||||
resetSubagentCursor,
|
||||
scanProject,
|
||||
SESSION_MAX_AGE_MS,
|
||||
sessionDir,
|
||||
@@ -88,9 +91,11 @@ import {
|
||||
workspaceForAgent,
|
||||
writeCursor,
|
||||
writeJsonAtomic,
|
||||
writeSubagentCursor,
|
||||
writeWorkspaceCursor,
|
||||
} from "./lib.mjs";
|
||||
import { RUN_EVENTS, TASK_EVENTS, MAX_TASKS, isTaskCount, progressEntry } from "./public/meter.js";
|
||||
import { blockFor, offered } from "./public/subagents.js";
|
||||
import { changeLine } from "./public/workspace.js";
|
||||
|
||||
// Mirrors the server's absolute lifetime cap: a handle older than this cannot
|
||||
@@ -310,7 +315,11 @@ async function cmdOpen() {
|
||||
die(`could not write the session state: ${written ? written.error : "unknown"}`, 1);
|
||||
}
|
||||
state = written.state;
|
||||
appendEvent(dir, { type: "open", resumed: Boolean(args.resume || args.session), carried });
|
||||
appendEvent(dir, { type: "open", resumed: Boolean(args.resume || args.session), carried, caps: ["subagents"] });
|
||||
// A new agent conversation has been told nothing yet (FR-6).
|
||||
try {
|
||||
resetSubagentCursor(dir);
|
||||
} catch {}
|
||||
trace("open: state written");
|
||||
|
||||
// Dashboard launches are recorded too (they score nothing), so the folder
|
||||
@@ -337,9 +346,18 @@ async function cmdOpen() {
|
||||
removeScratch(HOME_DIR, sweptScratch).catch(() => {});
|
||||
};
|
||||
|
||||
// A standing instruction the new agent is owed, as `subagents` and a
|
||||
// `reply` holding only its lines; neither key when nothing is owed.
|
||||
const subagentsOwed = () => {
|
||||
awaitSubagentSync(dir, state.workflow);
|
||||
const [out, cursor] = withSubagents(dir, { reply: "" });
|
||||
return [out.subagents ? out : {}, cursor];
|
||||
};
|
||||
|
||||
// Reuse a live server if one is already serving this session.
|
||||
if (existing && (await reusable)) {
|
||||
if (!args["no-open"]) openBrowser(existing.url);
|
||||
const [owed, subCursor] = subagentsOwed();
|
||||
print({
|
||||
ok: true,
|
||||
sid,
|
||||
@@ -349,9 +367,11 @@ async function cmdOpen() {
|
||||
pendingResult: carried,
|
||||
terminalLine: terminalLine(existing.url),
|
||||
workspace,
|
||||
...owed,
|
||||
...swept,
|
||||
...remoteWarning(),
|
||||
});
|
||||
advanceSubagents(dir, subCursor);
|
||||
sweep();
|
||||
return;
|
||||
}
|
||||
@@ -384,6 +404,7 @@ async function cmdOpen() {
|
||||
const notes = [];
|
||||
if (remote.note) notes.push(remote.note);
|
||||
if (carried) notes.push("Answers are already waiting. Run `wait` to collect them.");
|
||||
const [owed, subCursor] = subagentsOwed();
|
||||
print({
|
||||
ok: true,
|
||||
sid,
|
||||
@@ -394,10 +415,12 @@ async function cmdOpen() {
|
||||
pendingResult: carried,
|
||||
terminalLine: terminalLine(handle.url),
|
||||
workspace,
|
||||
...owed,
|
||||
...swept,
|
||||
...(remote.remote ? { remote: remote.remote } : {}),
|
||||
...(notes.length ? { note: notes.join(" ") } : {}),
|
||||
});
|
||||
advanceSubagents(dir, subCursor);
|
||||
// After the print, never before it: the page and the link wait for nothing.
|
||||
sweep();
|
||||
}
|
||||
@@ -774,7 +797,7 @@ function serverGone(sid) {
|
||||
|
||||
// Quick questions and nothing else: an ordinary exit 0 with no card actions.
|
||||
function deliverChat(dir, sid, entries, url) {
|
||||
const [out, changes] = withWorkspace(dir, {
|
||||
const [withWs, changes] = withWorkspace(dir, {
|
||||
type: "chat",
|
||||
at: nowIso(),
|
||||
sid,
|
||||
@@ -782,9 +805,11 @@ function deliverChat(dir, sid, entries, url) {
|
||||
chat: entries,
|
||||
reply: chatReplyLines(entries),
|
||||
});
|
||||
const [out, subCursor] = withSubagents(dir, withWs);
|
||||
print({ ...out, ...(url ? { terminalLine: terminalLine(url) } : {}) });
|
||||
advanceCursor(dir, entries);
|
||||
advanceWorkspace(dir, changes);
|
||||
advanceSubagents(dir, subCursor);
|
||||
process.exitCode = 0;
|
||||
}
|
||||
|
||||
@@ -806,6 +831,52 @@ function advanceWorkspace(dir, changes) {
|
||||
} catch {}
|
||||
}
|
||||
|
||||
// The server rewrites the session's setting for a new workflow only once its
|
||||
// watcher sees the state `open` just wrote, so a launch or hop that read the
|
||||
// file at once would find the old workflow's and owe the agent nothing until
|
||||
// its next pickup. Give the server a moment to catch up instead, never
|
||||
// writing the file ourselves (FR-7). A session with no setting file at all is
|
||||
// an older server, which never writes one: a short look, not the full wait.
|
||||
const SUBAGENT_SYNC_WAIT_MS = 1500;
|
||||
const SUBAGENT_SYNC_MISSING_MS = 250;
|
||||
function awaitSubagentSync(dir, workflow) {
|
||||
if (!offered(workflow)) return;
|
||||
const start = Date.now();
|
||||
for (;;) {
|
||||
const setting = readSubagentSetting(dir);
|
||||
if (setting && setting.workflow === workflow) return;
|
||||
const budget = setting ? SUBAGENT_SYNC_WAIT_MS : SUBAGENT_SYNC_MISSING_MS;
|
||||
if (Date.now() - start >= budget) return;
|
||||
sleepSync(25);
|
||||
}
|
||||
}
|
||||
|
||||
// The Subagents switch the agent is owed, added to what it is about to read:
|
||||
// the setting as `subagents`, and its lines last in `reply`, after card lines,
|
||||
// Quick questions and Workspace lines (FR-9). Read from the session's own
|
||||
// setting file only, which only the server writes (FR-7). A setting for
|
||||
// another workflow is the server not having caught up with a hop yet: it
|
||||
// rides on the next pickup instead.
|
||||
function withSubagents(dir, out) {
|
||||
const setting = readSubagentSetting(dir);
|
||||
if (!setting) return [out, null];
|
||||
const workflow = (readJson(path.join(dir, "state.json")) || {}).workflow;
|
||||
if (setting.workflow !== workflow) return [out, null];
|
||||
const block = blockFor(setting, readSubagentCursor(dir));
|
||||
if (!block) return [out, null];
|
||||
const reply = [out.reply, ...block.lines].filter(Boolean).join("\n");
|
||||
return [{ ...out, subagents: block.field, reply }, block.cursor];
|
||||
}
|
||||
|
||||
// After the print, like advanceWorkspace(): a kill in between repeats the
|
||||
// block at the next pickup, never loses it.
|
||||
function advanceSubagents(dir, cursor) {
|
||||
if (!cursor) return;
|
||||
try {
|
||||
writeSubagentCursor(dir, cursor);
|
||||
} catch {}
|
||||
}
|
||||
|
||||
// Print first, then this, exactly as consume() stamps a result: a kill in
|
||||
// between can only hand the same chat over again, and collectChat() drops
|
||||
// anything that already has a reply.
|
||||
@@ -832,15 +903,17 @@ async function cmdChat() {
|
||||
}
|
||||
const entries = deliverableChat(collectChat(dir, readJson(path.join(dir, "state.json")) || {}));
|
||||
const changes = pendingWorkspaceChanges(dir);
|
||||
if (!entries.length && !changes.length) {
|
||||
const reply = [chatReplyLines(entries), ...changes.map(changeLine)].filter(Boolean).join("\n");
|
||||
const [out, subCursor] = withSubagents(dir, { chat: entries, workspace: changes, reply });
|
||||
if (!entries.length && !changes.length && !subCursor) {
|
||||
print({ chat: [] });
|
||||
process.exitCode = 10;
|
||||
return;
|
||||
}
|
||||
const reply = [chatReplyLines(entries), ...changes.map(changeLine)].filter(Boolean).join("\n");
|
||||
print({ chat: entries, workspace: changes, reply, terminalLine: terminalLine(handle.url) });
|
||||
print({ ...out, terminalLine: terminalLine(handle.url) });
|
||||
advanceCursor(dir, entries);
|
||||
advanceWorkspace(dir, changes);
|
||||
advanceSubagents(dir, subCursor);
|
||||
process.exitCode = 0;
|
||||
}
|
||||
|
||||
@@ -865,7 +938,8 @@ function consume(dir, resultPath, result, url, chat = []) {
|
||||
// never on result.json itself.
|
||||
const withChat = { ...collected, chat };
|
||||
if (chat.length) withChat.reply = [collected.reply, chatReplyLines(chat)].filter(Boolean).join("\n");
|
||||
const [out, changes] = withWorkspace(dir, withChat);
|
||||
const [withWs, changes] = withWorkspace(dir, withChat);
|
||||
const [out, subCursor] = withSubagents(dir, withWs);
|
||||
print(url ? { ...out, terminalLine: terminalLine(url) } : out);
|
||||
try {
|
||||
writeJsonAtomic(resultPath, collected);
|
||||
@@ -874,6 +948,7 @@ function consume(dir, resultPath, result, url, chat = []) {
|
||||
ledgerAnswers(dir, result);
|
||||
advanceCursor(dir, chat);
|
||||
advanceWorkspace(dir, changes);
|
||||
advanceSubagents(dir, subCursor);
|
||||
process.exitCode = result.type === "cancel" ? 30 : 0;
|
||||
}
|
||||
|
||||
@@ -986,12 +1061,18 @@ port, and the filesystem as transport; this CLI is the whole agent surface.
|
||||
path, description?, original? }], missing? }, the folders this
|
||||
console session reads as context, addressed as @name. The list is
|
||||
remembered per folder and spec in workspaces.json beside looks.json.
|
||||
May also print subagents: { state, revision, max, instruction } and
|
||||
a reply holding only its "Subagents: ..." lines, when a standing
|
||||
instruction (the page's Subagents switch) is owed to you.
|
||||
post --session <sid> --file <patch.json>
|
||||
Merge a patch into the session. Prints terminalLine while the
|
||||
server is live. Exit 3 = rejected; stderr says why. A patch may
|
||||
carry run: { event, id, tasks? } (session meter points) and folderIssue:
|
||||
{ name, reason, hint? } (a workspace folder you could not read);
|
||||
both go to the ledger, never into the state.
|
||||
both go to the ledger, never into the state. A patch may also
|
||||
carry helpers: [{ id, title, ask, state, result? }] or one
|
||||
{ id: "alone", alone: true }, merged by id, for the Subagents tab
|
||||
(see console.md → Standing instructions).
|
||||
wait --session <sid> [--seconds <N>]
|
||||
A bounded wait slice, sized below your shell timeout. Exit 0 = the
|
||||
result is on stdout, 10 = still waiting ("Waiting on your answer
|
||||
@@ -1002,10 +1083,14 @@ port, and the filesystem as transport; this CLI is the whole agent surface.
|
||||
"workspace" (changes since you last heard, each once, with a
|
||||
"Workspace: ..." line in reply); exit 10 counts them as
|
||||
pendingWorkspace, and a change alone never ends a slice.
|
||||
Exit 0 may also carry "subagents" (a console setting, not typed
|
||||
by the person, with its "Subagents: ..." lines last in reply); a
|
||||
setting change alone never ends a slice either.
|
||||
chat --session <sid>
|
||||
Collect Quick questions and workspace changes now, never waiting,
|
||||
never touching card sends. Exit 0 = { chat, workspace, reply,
|
||||
terminalLine }, 10 = none, 20 = server gone.
|
||||
Collect Quick questions, workspace changes and a Subagents
|
||||
setting change now, never waiting, never touching card sends.
|
||||
Exit 0 = { chat, workspace, subagents?, reply, terminalLine },
|
||||
10 = none, 20 = server gone.
|
||||
terminalLine is "→ Look at the web console: <url>": end your terminal
|
||||
messages with it during a console session.
|
||||
keep --session <sid> --upload <path> --name <name> --spec specs/<idea> [--from <file>]
|
||||
|
||||
@@ -25,6 +25,7 @@ import { fileURLToPath } from "node:url";
|
||||
import { CHAT_LIMIT } from "./public/chat.js";
|
||||
import { DOC_TYPES } from "./public/answers.js";
|
||||
import { defaultName } from "./public/workspace.js";
|
||||
import { checkHelpers, cleanSetting, defaultSetting, offered } from "./public/subagents.js";
|
||||
|
||||
export const HERE = path.dirname(fileURLToPath(import.meta.url));
|
||||
export const PUBLIC_DIR = path.join(HERE, "public");
|
||||
@@ -491,9 +492,16 @@ export async function removeSessions(sessionsDir, sids) {
|
||||
}
|
||||
|
||||
// The console folder's own files that no sweep may ever remove: the person's
|
||||
// looks, the folders remembered per project and spec, the pointer to this
|
||||
// console's directory, and the cached release check.
|
||||
export const PROTECTED_CONSOLE_FILES = new Set(["looks.json", "workspaces.json", "console-dir", "update-check.json"]);
|
||||
// looks, the folders remembered per project and spec, the Subagents switch
|
||||
// saved per project and workflow, the pointer to this console's directory,
|
||||
// and the cached release check.
|
||||
export const PROTECTED_CONSOLE_FILES = new Set([
|
||||
"looks.json",
|
||||
"workspaces.json",
|
||||
"subagents.json",
|
||||
"console-dir",
|
||||
"update-check.json",
|
||||
]);
|
||||
|
||||
function isScratchName(name) {
|
||||
return (
|
||||
@@ -1142,6 +1150,19 @@ const DOC_DEFAULTS = { version: 1, stale: false, blocks: [] };
|
||||
// Blocks merge by id like docs do, so a patch that only settles a block's
|
||||
// state keeps its text. Blocks left out of the patch stay as they are.
|
||||
function mergeDocs(current, patchList) {
|
||||
// A doc's version only moves forward. One going back is a stale or copied
|
||||
// payload (last phase's progress script, say), and the page would quietly
|
||||
// show the old content under the new run's name.
|
||||
for (const entry of patchList) {
|
||||
if (!isPlainObject(entry) || typeof entry.version !== "number") continue;
|
||||
const prev = (current || []).find((d) => d && d.id === entry.id);
|
||||
if (prev && typeof prev.version === "number" && entry.version < prev.version) {
|
||||
throw new Error(
|
||||
`doc "${entry.id}" is at version ${prev.version} on the page; this patch sends version ${entry.version}. ` +
|
||||
"Versions only go up: bump it, and check the payload is the current one."
|
||||
);
|
||||
}
|
||||
}
|
||||
const merged = mergeKeyed(current, patchList, "id", DOC_DEFAULTS, "docs");
|
||||
for (const entry of patchList) {
|
||||
if (!Array.isArray(entry.blocks)) continue;
|
||||
@@ -1184,6 +1205,13 @@ export function applyPatch(state, patch) {
|
||||
if (!Array.isArray(v)) throw new Error('"topics" must be an array');
|
||||
next.topics = mergeKeyed(next.topics, v, "id", {}, "topics");
|
||||
break;
|
||||
case "helpers":
|
||||
// The agent's report of its helpers, for the page's Subagents tab.
|
||||
// Only `post` writes it; the server's /submit never touches it.
|
||||
if (!Array.isArray(v)) throw new Error('"helpers" must be an array');
|
||||
if (!v.every(isPlainObject)) throw new Error('"helpers" entries must be objects, each { id, title, ask, state }');
|
||||
next.helpers = mergeKeyed(next.helpers, v, "id", {}, "helpers");
|
||||
break;
|
||||
case "docs":
|
||||
if (!Array.isArray(v)) throw new Error('"docs" must be an array');
|
||||
next.docs = mergeDocs(next.docs, v);
|
||||
@@ -1478,6 +1506,20 @@ export function validate(state) {
|
||||
JSON.stringify(state.menu || {});
|
||||
problems.push(...proseProblems(prose));
|
||||
|
||||
// The agent's report of its helpers: the shape the page draws from
|
||||
// (subagents.js), then the same prose scan as everything else it writes.
|
||||
if (state.helpers != null) {
|
||||
problems.push(...checkHelpers(state.helpers));
|
||||
for (const helper of Array.isArray(state.helpers) ? state.helpers : []) {
|
||||
if (!isPlainObject(helper)) continue;
|
||||
for (const field of ["title", "ask", "result"]) {
|
||||
if (typeof helper[field] === "string") {
|
||||
problems.push(...proseProblems(helper[field], `helper "${helper.id}" ${field}`));
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
return problems;
|
||||
}
|
||||
|
||||
@@ -1507,7 +1549,8 @@ export function blankState({ sid, workflow, title, project, specDir }) {
|
||||
* A resume that passes through the dashboard (a finished skill going back to
|
||||
* it, or a launch from its menu) is a new skill taking the page over, so it
|
||||
* starts from a blank page: the last skill's questions, sections, docs,
|
||||
* headline and ending are its record on disk, not the next skill's opening.
|
||||
* helpers, headline and ending are its record on disk, not the next skill's
|
||||
* opening.
|
||||
* Only the session's identity carries across. `workspace.json`,
|
||||
* `ledger.ndjson` and the cursors live beside `state.json`, so the workspace
|
||||
* and the meter outlive every hop.
|
||||
@@ -1534,6 +1577,8 @@ export function switchWorkflow(state, { workflow, title, specDir }) {
|
||||
// workspace.json the server. Folders, version, change log, missing, remote.
|
||||
// ledger.ndjson console.mjs. Append-only meter events and folder issues.
|
||||
// workspace-cursor.json console.mjs. The last workspace version handed to the agent.
|
||||
// subagents-setting.json the server. The Subagents switch for this session, with its revision.
|
||||
// subagents-cursor.json console.mjs. The last Subagents revision and state handed to the agent.
|
||||
export const CHAT_FILE = "chat.ndjson";
|
||||
export const CHAT_CURSOR_FILE = "chat-cursor.json";
|
||||
export const WORKSPACE_FILE = "workspace.json";
|
||||
@@ -1989,6 +2034,98 @@ export function pendingWorkspaceChanges(dir) {
|
||||
return (readWorkspace(dir)?.changes || []).filter((c) => c.version > cursor);
|
||||
}
|
||||
|
||||
/* ------------------------------------------------------ the Subagents switch */
|
||||
|
||||
// The person's Subagents switch, remembered per project folder and workflow:
|
||||
//
|
||||
// { "<folded project path>": { "<workflow>": { on, instruction, max } } }
|
||||
//
|
||||
// Keyed with foldKey(), as workspaces.json is. `instruction: null` is the
|
||||
// workflow's shipped default.
|
||||
export const SUBAGENTS_FILE = path.join(HOME_DIR, "subagents.json");
|
||||
const SUBAGENTS_LOCK = "subagents.json.lock";
|
||||
|
||||
function readSubagentStore() {
|
||||
const saved = readJson(SUBAGENTS_FILE, null);
|
||||
return saved && typeof saved === "object" && !Array.isArray(saved) ? saved : {};
|
||||
}
|
||||
|
||||
// The saved `{ on, instruction, max }` for this folder and workflow, or the
|
||||
// default's when nothing (or something malformed) is saved.
|
||||
export function subagentStoreEntry(worktree, workflow) {
|
||||
const { on, instruction, max } = defaultSetting(workflow);
|
||||
const project = offered(workflow) ? readSubagentStore()[foldKey(worktree)] : null;
|
||||
const saved = project && typeof project === "object" ? cleanSetting(project[workflow]) : null;
|
||||
return saved && !saved.error ? saved : { on, instruction, max };
|
||||
}
|
||||
|
||||
// Single-writer rule: only server.mjs may call this.
|
||||
export function saveSubagentStoreEntry(worktree, workflow, value) {
|
||||
ensureDir(path.dirname(SUBAGENTS_FILE));
|
||||
withStateLock(
|
||||
path.dirname(SUBAGENTS_FILE),
|
||||
() => {
|
||||
const store = readSubagentStore();
|
||||
const key = foldKey(worktree);
|
||||
const project = store[key] && typeof store[key] === "object" ? store[key] : {};
|
||||
store[key] = { ...project, [workflow]: { on: value.on, instruction: value.instruction, max: value.max } };
|
||||
writeJsonAtomic(SUBAGENTS_FILE, store);
|
||||
},
|
||||
SUBAGENTS_LOCK
|
||||
);
|
||||
}
|
||||
|
||||
export const SUBAGENTS_SETTING_FILE = "subagents-setting.json";
|
||||
|
||||
const isCount = (n) => Number.isInteger(n) && n >= 0;
|
||||
|
||||
// This session's switch, `{ workflow, on, instruction, max, revision }`, or
|
||||
// null when there is none or it is malformed.
|
||||
export function readSubagentSetting(dir) {
|
||||
const s = readJson(path.join(dir, SUBAGENTS_SETTING_FILE), null);
|
||||
if (!s || typeof s !== "object") return null;
|
||||
if (typeof s.workflow !== "string" || typeof s.on !== "boolean" || !Number.isInteger(s.max) || !isCount(s.revision)) return null;
|
||||
return s;
|
||||
}
|
||||
|
||||
// Single-writer rule: only server.mjs may call this. The revision never goes
|
||||
// backwards within a session.
|
||||
export function writeSubagentSetting(dir, setting) {
|
||||
const previous = readSubagentSetting(dir);
|
||||
const revision = Math.max(previous ? previous.revision : 0, setting.revision);
|
||||
return writeJsonAtomic(path.join(dir, SUBAGENTS_SETTING_FILE), { ...setting, revision });
|
||||
}
|
||||
|
||||
export const SUBAGENTS_CURSOR_FILE = "subagents-cursor.json";
|
||||
const CURSOR_STATES = new Set(["none", "on", "off"]);
|
||||
|
||||
// What the agent was last told: `{ revision, state }`.
|
||||
export function readSubagentCursor(dir) {
|
||||
const saved = readJson(path.join(dir, SUBAGENTS_CURSOR_FILE), null);
|
||||
if (!saved || !isCount(saved.revision) || !CURSOR_STATES.has(saved.state)) return { revision: 0, state: "none" };
|
||||
return { revision: saved.revision, state: saved.state };
|
||||
}
|
||||
|
||||
// Single-writer rule: only console.mjs may call this. Never backwards, like
|
||||
// writeWorkspaceCursor(): a killed `wait` may repeat a change, never skip one.
|
||||
export function writeSubagentCursor(dir, cursor) {
|
||||
const old = readSubagentCursor(dir);
|
||||
const next = cursor.revision < old.revision ? old : { revision: cursor.revision, state: cursor.state };
|
||||
writeJsonAtomic(path.join(dir, SUBAGENTS_CURSOR_FILE), next);
|
||||
}
|
||||
|
||||
// The one place the cursor may go back: `open`, which starts a fresh agent.
|
||||
export function resetSubagentCursor(dir) {
|
||||
writeJsonAtomic(path.join(dir, SUBAGENTS_CURSOR_FILE), { revision: 0, state: "none" });
|
||||
}
|
||||
|
||||
// The `caps` of the last `open` event: what the agent's console copy can do.
|
||||
export function latestOpenCaps(dir) {
|
||||
const opens = readJsonLines(path.join(dir, "events.ndjson")).filter((e) => e.type === "open");
|
||||
const last = opens[opens.length - 1];
|
||||
return last && Array.isArray(last.caps) ? last.caps : [];
|
||||
}
|
||||
|
||||
/**
|
||||
* Flag the case where the link cannot be opened by the person it is for.
|
||||
*
|
||||
|
||||
@@ -208,6 +208,26 @@ body {
|
||||
.stop-btn:hover:not(:disabled) { color: var(--warn); border-color: var(--warn); }
|
||||
.brief-btn:hover:not(:disabled) { color: var(--accent); border-color: var(--accent-line); }
|
||||
|
||||
/* Subagents: an orchestrator and its helpers. Unlit is a hollow outline in
|
||||
the quiet ink; lit fills the nodes with the highlight color. */
|
||||
.subagents-btn { border-color: var(--rule-2); color: var(--ink-2); display: inline-flex; align-items: center; justify-content: center; }
|
||||
.btn.subagents-btn { padding: 0 6px; align-self: stretch; }
|
||||
.subagents-btn[hidden] { display: none; }
|
||||
.subagents-btn svg { width: 16px; height: 16px; display: block; }
|
||||
.subagents-btn .sa-link { fill: none; stroke: var(--ink-2); stroke-width: 1.2; stroke-linecap: round; }
|
||||
.subagents-btn .sa-hub { fill: none; stroke: var(--ink-2); stroke-width: 1.4; }
|
||||
.subagents-btn .sa-node { fill: none; stroke: var(--ink-2); stroke-width: 1.2; }
|
||||
.subagents-btn[aria-pressed="true"] .sa-hub,
|
||||
.subagents-btn[aria-pressed="true"] .sa-node { fill: var(--accent); stroke: var(--accent); }
|
||||
.subagents-btn[aria-pressed="true"] .sa-link { stroke: var(--accent); }
|
||||
.subagents-btn:hover:not(:disabled) { color: var(--accent); border-color: var(--accent-line); }
|
||||
.subagents-btn:hover:not(:disabled) .sa-link,
|
||||
.subagents-btn:hover:not(:disabled) .sa-hub,
|
||||
.subagents-btn:hover:not(:disabled) .sa-node { stroke: var(--accent); }
|
||||
.subagents-btn:disabled .sa-link,
|
||||
.subagents-btn:disabled .sa-hub,
|
||||
.subagents-btn:disabled .sa-node { stroke: var(--ink-3); fill: none; }
|
||||
|
||||
.ident { display: flex; align-items: baseline; gap: 12px; min-width: 0; }
|
||||
|
||||
/* The session meter: a ring that fills with the points and a few words, in
|
||||
@@ -1430,6 +1450,30 @@ h1 {
|
||||
.pill.done { background: var(--ok-soft); color: var(--ok); }
|
||||
.pill.staged { background: var(--stage-soft); color: var(--stage); }
|
||||
|
||||
/* The Subagents tab: one row per reported helper, newest state in a pill. */
|
||||
.sa-card h2 { margin: 0 0 6px; }
|
||||
.sa-card > .help { margin: 0 0 16px; }
|
||||
.sa-alone { margin: 0; color: var(--ink-2); }
|
||||
.sa-list { list-style: none; margin: 0; padding: 0; display: grid; gap: 10px; }
|
||||
.sa-row { border: 1px solid var(--rule); border-radius: 8px; background: var(--panel-2); padding: 12px 14px; }
|
||||
.sa-head { display: flex; align-items: center; justify-content: space-between; gap: 10px; }
|
||||
.sa-title { min-width: 0; overflow-wrap: anywhere; }
|
||||
.sa-ask {
|
||||
margin: 4px 0 0; color: var(--ink-2); font-size: 13.5px;
|
||||
display: -webkit-box; -webkit-box-orient: vertical; -webkit-line-clamp: 2; line-clamp: 2; overflow: hidden;
|
||||
}
|
||||
.sa-result { margin: 8px 0 0; padding-top: 8px; border-top: 1px solid var(--rule); font-size: 13.5px; }
|
||||
.sa-pill { display: inline-flex; align-items: center; gap: 6px; flex: none; }
|
||||
.sa-pill.is-running { background: var(--accent-soft); color: var(--accent); border-color: var(--accent-line); }
|
||||
.sa-pill.is-done { background: var(--ok-soft); color: var(--ok); }
|
||||
.sa-pill.is-failed { background: var(--warn-soft); color: var(--warn); }
|
||||
.sa-pill .spinner.tiny { width: 10px; height: 10px; }
|
||||
/* The dialog's number box, themed like the page's other inputs. */
|
||||
.subagents input[type="number"] {
|
||||
width: 5em; font: inherit; color: var(--ink); background: var(--panel-2);
|
||||
border: 1px solid var(--rule-2); border-radius: 6px; padding: 4px 8px;
|
||||
}
|
||||
|
||||
/* ------------------------------------------------------ settled answer */
|
||||
|
||||
.answered {
|
||||
@@ -1971,6 +2015,8 @@ h4.md-h, h5.md-h, h6.md-h { font-size: 15px; }
|
||||
cursor: pointer;
|
||||
}
|
||||
.footer-where:hover { text-decoration: underline; }
|
||||
/* The project name, in the person's highlight color. */
|
||||
.where-project { color: var(--accent); font-weight: 600; }
|
||||
/* A folder is missing or the agent could not read one: the dialog says which. */
|
||||
.where-alert {
|
||||
display: inline-block; width: 7px; height: 7px; margin-left: 6px;
|
||||
|
||||
@@ -103,6 +103,15 @@ import { FOOTER_TIERS, footerLabel, nameProblem } from "./workspace.js";
|
||||
import { RED_BANNER } from "./meter.js";
|
||||
import { applyMention, matchNames, mentionAt } from "./mentions.js";
|
||||
import { faviconState, setFavicon } from "./favicon.js";
|
||||
import {
|
||||
CHECKIN_LINE,
|
||||
PATHFINDER_RESEARCH_LINE,
|
||||
defaultInstruction,
|
||||
helperRows,
|
||||
showSwitch,
|
||||
showTab,
|
||||
switchLabel,
|
||||
} from "./subagents.js";
|
||||
|
||||
const $ = (id) => document.getElementById(id);
|
||||
|
||||
@@ -530,6 +539,9 @@ let meterFrame = null;
|
||||
// The frame's update ({ installed, latest }), present only when a newer
|
||||
// release is out; null otherwise.
|
||||
let updateFrame = null;
|
||||
// The frame's Subagents switch ({ offered, supported, on, instruction, max,
|
||||
// revision }), or null before a server that sends it.
|
||||
let subagentsFrame = null;
|
||||
let chatDot = false;
|
||||
let chatSending = false;
|
||||
let chatResetting = false;
|
||||
@@ -880,6 +892,8 @@ function adopt(body) {
|
||||
if (body.meter) meterFrame = body.meter;
|
||||
// Always replaced: an absent key means no update.
|
||||
updateFrame = body.update || null;
|
||||
// Always replaced too: an older server sends none, and then there is no switch.
|
||||
subagentsFrame = body.subagents || null;
|
||||
lastContact = Date.now();
|
||||
if (gone) {
|
||||
gone = false;
|
||||
@@ -1301,6 +1315,7 @@ function render() {
|
||||
renderChrome();
|
||||
renderStatus();
|
||||
renderBriefButton();
|
||||
renderSubagentsButton();
|
||||
renderStopButton();
|
||||
renderHomeButton();
|
||||
tabAdded = renderViews();
|
||||
@@ -1566,7 +1581,7 @@ function renderChrome() {
|
||||
renderMeter();
|
||||
$("title").textContent = S.title || "Session";
|
||||
$("badge").textContent = workflowLabel(S.workflow);
|
||||
document.title = (S.title || "Session") + " · #" + String(S.sid || "").slice(-6) + " · Plan2Code";
|
||||
renderTabTitle();
|
||||
|
||||
const h = S.headline || {};
|
||||
// On a finished session an open item is frozen: the send on it counts as
|
||||
@@ -1835,6 +1850,69 @@ function renderBriefButton() {
|
||||
if (offer) btn.disabled = gone || pendingResult;
|
||||
}
|
||||
|
||||
// Shown only where the skill opts in and the agent's console copy can deliver
|
||||
// it. Lit while helpers are on; a click opens the dialog, never toggles.
|
||||
function renderSubagentsButton() {
|
||||
const btn = $("btn-subagents");
|
||||
const offer = showSwitch(subagentsFrame);
|
||||
btn.hidden = !offer;
|
||||
if (!offer) return;
|
||||
const label = switchLabel(subagentsFrame);
|
||||
btn.setAttribute("aria-pressed", String(Boolean(subagentsFrame.on)));
|
||||
btn.title = label;
|
||||
btn.setAttribute("aria-label", label);
|
||||
btn.disabled = gone;
|
||||
}
|
||||
|
||||
// The Subagents dialog, filled from the frame each time it opens. A null
|
||||
// instruction is the shipped default, shown as its text so it can be edited.
|
||||
function openSubagents() {
|
||||
if (!showSwitch(subagentsFrame)) return;
|
||||
const on = Boolean(subagentsFrame.on);
|
||||
for (const radio of document.querySelectorAll('input[name="subagents-on"]')) {
|
||||
radio.checked = radio.value === (on ? "on" : "off");
|
||||
}
|
||||
$("subagents-instruction").value = subagentsFrame.instruction ?? defaultInstruction(S.workflow);
|
||||
$("subagents-max").value = String(subagentsFrame.max);
|
||||
$("subagents-checkin").textContent = CHECKIN_LINE;
|
||||
const research = $("subagents-research");
|
||||
research.textContent = PATHFINDER_RESEARCH_LINE;
|
||||
research.hidden = S.workflow !== "pathfinder";
|
||||
$("subagents-status").textContent = "";
|
||||
$("subagents-save").disabled = false;
|
||||
$("subagents-modal").showModal();
|
||||
const checked = document.querySelector('input[name="subagents-on"]:checked');
|
||||
if (checked) checked.focus();
|
||||
}
|
||||
|
||||
const SUBAGENTS_ERRORS = {
|
||||
max: "Pick a number from 1 to 20.",
|
||||
"too-long": "The instruction is over 2,000 characters.",
|
||||
"not-offered": "This skill doesn't use helpers.",
|
||||
bad: "That didn't save. Try again.",
|
||||
};
|
||||
const SUBAGENTS_LOST = "Lost contact with Plan2Code. Try again once it's back.";
|
||||
|
||||
async function saveSubagents() {
|
||||
const save = $("subagents-save");
|
||||
const status = $("subagents-status");
|
||||
const picked = document.querySelector('input[name="subagents-on"]:checked');
|
||||
const text = $("subagents-instruction").value.trim();
|
||||
// The shipped default is stored as null, so a later release's wording
|
||||
// reaches everyone who never changed it.
|
||||
const instruction = text === defaultInstruction(S.workflow) ? null : text;
|
||||
const body = { on: Boolean(picked && picked.value === "on"), instruction, max: Number($("subagents-max").value) };
|
||||
save.disabled = true;
|
||||
status.textContent = "";
|
||||
const res = await postJson("/subagents", body);
|
||||
save.disabled = false;
|
||||
// The next state frame redraws the button.
|
||||
if (res.status === 200) return $("subagents-modal").close();
|
||||
if (res.status === 400) status.textContent = SUBAGENTS_ERRORS[res.body && res.body.error] || SUBAGENTS_ERRORS.bad;
|
||||
else if (res.status === 403 || res.status === 0) status.textContent = SUBAGENTS_LOST;
|
||||
else status.textContent = SUBAGENTS_ERRORS.bad;
|
||||
}
|
||||
|
||||
function renderViews() {
|
||||
const nav = $("views");
|
||||
nav.replaceChildren();
|
||||
@@ -1850,6 +1928,14 @@ function renderViews() {
|
||||
if (hasOverview) tabs.push({ id: "overview", label: "Overview", count: 0 });
|
||||
else if (view === "overview") view = "questions";
|
||||
for (const d of docs()) tabs.push({ id: "doc:" + d.id, label: d.title || "Document", count: 0 });
|
||||
// The helpers the agent reported, from the first one on; cleared by a
|
||||
// dashboard hop, which sends the person home like the Overview tab does.
|
||||
if (showTab(subagentsFrame, S.helpers)) {
|
||||
// From the rows the tab draws, so the badge never counts helpers the
|
||||
// working-alone note hides.
|
||||
const running = helperRows(S.helpers).rows.filter((r) => r.state === "running").length;
|
||||
tabs.push({ id: "subagents", label: "Subagents", count: running });
|
||||
} else if (view === "subagents") view = "questions";
|
||||
// Always last, on every workflow and after a finish: the Quick question chat.
|
||||
// The ring left of "Ask" shows exactly when the conversation's own ring does:
|
||||
// a question the agent picked up and has not answered yet.
|
||||
@@ -2130,6 +2216,7 @@ function paintMain(main) {
|
||||
if (view.startsWith("doc:")) return renderDoc(main, view.slice(4));
|
||||
if (view === "overview") return renderOverview(main);
|
||||
if (view === "ask") return renderAsk(main);
|
||||
if (view === "subagents") return renderSubagents(main);
|
||||
|
||||
// The session's own page, reached from the PAUSED / SESSION ENDED item at
|
||||
// the top of the rail. The hand-off lives here alone now, rather than
|
||||
@@ -4774,6 +4861,42 @@ function renderOverview(main) {
|
||||
main.appendChild(box);
|
||||
}
|
||||
|
||||
// The helpers the agent reported, as it last posted them. Everything here is
|
||||
// the agent's text, so it goes in as text, never as markup.
|
||||
function renderSubagents(main) {
|
||||
const card = el("section", "card sa-card");
|
||||
card.appendChild(el("h2", null, "Subagents"));
|
||||
card.appendChild(el("p", "help", CHECKIN_LINE));
|
||||
const { alone, rows } = helperRows(S.helpers);
|
||||
if (alone) {
|
||||
card.appendChild(
|
||||
el("p", "sa-alone", "Working alone: your agent has no way to start helpers here, so it is doing this skill's work itself.")
|
||||
);
|
||||
main.appendChild(card);
|
||||
return;
|
||||
}
|
||||
const list = el("ul", "sa-list");
|
||||
for (const row of rows) {
|
||||
const item = el("li", "sa-row");
|
||||
const head = el("div", "sa-head");
|
||||
head.appendChild(el("strong", "sa-title", row.title));
|
||||
const pill = el("span", "pill sa-pill is-" + row.state);
|
||||
if (row.state === "running") {
|
||||
const spin = el("span", "spinner tiny");
|
||||
spin.setAttribute("aria-hidden", "true");
|
||||
pill.appendChild(spin);
|
||||
}
|
||||
pill.appendChild(document.createTextNode(row.stateLabel));
|
||||
head.appendChild(pill);
|
||||
item.appendChild(head);
|
||||
item.appendChild(el("p", "sa-ask", row.ask));
|
||||
if (row.result) item.appendChild(el("p", "sa-result", row.result));
|
||||
list.appendChild(item);
|
||||
}
|
||||
card.appendChild(list);
|
||||
main.appendChild(card);
|
||||
}
|
||||
|
||||
/* ---------------------------------------------------------------- ask */
|
||||
|
||||
// The frame's chat block, with `offline` worked out now rather than when the
|
||||
@@ -5956,10 +6079,30 @@ const workspaceFolders = () => (wsFrame && Array.isArray(wsFrame.folders) ? wsFr
|
||||
// session opened before the server wrote `worktree` has nothing to show, so
|
||||
// the slot stays hidden. The footer renders on every tick, so the DOM is only
|
||||
// touched when the labels change, or when a resize clears the key.
|
||||
// The project's name: the workspace's original folder, or the session's
|
||||
// worktree folder before a frame carries the workspace.
|
||||
function projectName() {
|
||||
const folders = workspaceFolders();
|
||||
if (folders.length && folders[0].name) return folders[0].name;
|
||||
const path = (S && S.worktree) || "";
|
||||
return path ? path.split(/[\\/]/).filter(Boolean).pop() || path : "";
|
||||
}
|
||||
|
||||
// The browser tab's title, led by the project so tabs from different
|
||||
// projects are told apart. Called from the chrome and the footer, since the
|
||||
// workspace frame can arrive after either.
|
||||
function renderTabTitle() {
|
||||
if (!S) return;
|
||||
const name = projectName();
|
||||
document.title =
|
||||
(name ? name + " · " : "") + (S.title || "Session") + " · #" + String(S.sid || "").slice(-6) + " · Plan2Code";
|
||||
}
|
||||
|
||||
function renderWhere() {
|
||||
const b = $("footer-where");
|
||||
const folders = workspaceFolders();
|
||||
const path = S.worktree || "";
|
||||
renderTabTitle();
|
||||
const alert = Boolean(folders.length && ((wsFrame.missing || []).length || (wsFrame.issues || []).length));
|
||||
const labels = folders.length
|
||||
? Array.from({ length: FOOTER_TIERS }, (_, tier) => footerLabel({ folders, branch: S.branch }, tier))
|
||||
@@ -5972,7 +6115,16 @@ function renderWhere() {
|
||||
let label = labels[0];
|
||||
for (const text of labels) {
|
||||
label = text;
|
||||
b.textContent = text;
|
||||
// The project name takes the highlight color, so several consoles side by
|
||||
// side tell apart at a glance; the rest of the label stays quiet.
|
||||
const name = projectName();
|
||||
b.textContent = "";
|
||||
if (name && text.startsWith(name)) {
|
||||
b.appendChild(el("span", "where-project", name));
|
||||
b.appendChild(document.createTextNode(text.slice(name.length)));
|
||||
} else {
|
||||
b.textContent = text;
|
||||
}
|
||||
if (alert) {
|
||||
const dot = el("span", "where-alert");
|
||||
dot.setAttribute("aria-hidden", "true");
|
||||
@@ -7197,6 +7349,7 @@ function lightDismiss(dlg) {
|
||||
});
|
||||
}
|
||||
lightDismiss($("looks-modal"));
|
||||
lightDismiss($("subagents-modal"));
|
||||
lightDismiss($("help-modal"));
|
||||
lightDismiss($("workspace-modal"));
|
||||
lightDismiss($("welcome-modal"));
|
||||
@@ -7499,6 +7652,13 @@ $("cleanup-scan").addEventListener("click", scanCleanup);
|
||||
$("cleanup-delete").addEventListener("click", deleteCleanup);
|
||||
|
||||
$("btn-brief").addEventListener("click", openBrief);
|
||||
$("btn-subagents").addEventListener("click", openSubagents);
|
||||
$("subagents-default").addEventListener("click", () => {
|
||||
$("subagents-instruction").value = defaultInstruction(S.workflow);
|
||||
});
|
||||
$("subagents-save").addEventListener("click", saveSubagents);
|
||||
$("subagents-cancel").addEventListener("click", () => $("subagents-modal").close());
|
||||
$("subagents-modal").addEventListener("close", () => $("btn-subagents").focus());
|
||||
$("brief-cancel").addEventListener("click", () => $("brief-modal").close());
|
||||
$("brief-go").addEventListener("click", sendBrief);
|
||||
for (const radio of document.querySelectorAll('input[name="brief-range"]')) {
|
||||
|
||||
@@ -19,6 +19,7 @@ export const HELP_TABS = Object.freeze([
|
||||
tab("dashboard", "The dashboard", true),
|
||||
tab("meter", "Session meter", false),
|
||||
tab("build", "Watching a build", false),
|
||||
tab("subagents", "Helpers (subagents)", false),
|
||||
tab("ask", "Ask a quick question", false),
|
||||
tab("finishing", "Stopping and finishing", false),
|
||||
tab("stuck", "When something looks stuck", true),
|
||||
@@ -39,6 +40,7 @@ export function helpTabFor({ view, dashboard, gone, adrift, finished, workflow,
|
||||
if (gone || adrift) return "stuck";
|
||||
if (workspace) return "workspace";
|
||||
if (v === "ask") return "ask";
|
||||
if (v === "subagents") return "subagents";
|
||||
if (dashboard && meterRed) return "meter";
|
||||
if (dashboard) return "dashboard";
|
||||
if (v === "overview" || v.startsWith("doc:")) return "docs";
|
||||
|
||||
@@ -21,6 +21,7 @@
|
||||
<link rel="modulepreload" href="/starters.js" />
|
||||
<link rel="modulepreload" href="/workspace.js" />
|
||||
<link rel="modulepreload" href="/meter.js" />
|
||||
<link rel="modulepreload" href="/subagents.js" />
|
||||
<link rel="modulepreload" href="/mentions.js" />
|
||||
<link rel="modulepreload" href="/favicon.js" />
|
||||
<link rel="modulepreload" href="/vendor/marked.esm.js" />
|
||||
@@ -172,6 +173,18 @@
|
||||
<button type="button" class="btn ghost small brief-btn" id="btn-brief" hidden>
|
||||
Write a brief
|
||||
</button>
|
||||
<!-- Subagents: opted-in skills only. Lit while helpers are on; a click
|
||||
opens the Subagents dialog and never toggles them itself. -->
|
||||
<button type="button" class="btn ghost small subagents-btn" id="btn-subagents" aria-pressed="false" hidden>
|
||||
<!-- An orchestrator and its helpers: one larger node linked to three smaller ones. -->
|
||||
<svg viewBox="0 0 16 16" aria-hidden="true" focusable="false">
|
||||
<path class="sa-link" d="M6.9 6.6L10.9 3.9M7.4 8h3.5M6.9 9.4l4 2.7" />
|
||||
<circle cx="4.6" cy="8" r="2.6" class="sa-hub" />
|
||||
<circle cx="12.4" cy="3" r="1.5" class="sa-node" />
|
||||
<circle cx="12.4" cy="8" r="1.5" class="sa-node" />
|
||||
<circle cx="12.4" cy="13" r="1.5" class="sa-node" />
|
||||
</svg>
|
||||
</button>
|
||||
</div>
|
||||
<div class="views-group">
|
||||
<span class="views-arrow" aria-hidden="true">
|
||||
@@ -580,6 +593,13 @@
|
||||
<rect x="3" y="9" width="18" height="6" rx="3" />
|
||||
<path d="M6 12h7" />
|
||||
</symbol>
|
||||
<symbol id="hi-subagents" viewBox="0 0 24 24" fill="none">
|
||||
<circle cx="7" cy="12" r="3.5" />
|
||||
<circle cx="18" cy="5" r="2" />
|
||||
<circle cx="18" cy="12" r="2" />
|
||||
<circle cx="18" cy="19" r="2" />
|
||||
<path d="M10 10l6-4M10.5 12H16M10 14l6 4" />
|
||||
</symbol>
|
||||
<symbol id="hi-ask" viewBox="0 0 24 24" fill="none">
|
||||
<path d="M4 5h16v11H10l-4 4v-4H4z" />
|
||||
<path d="M8 9.5h8M8 12.5h5" />
|
||||
@@ -1477,7 +1497,61 @@
|
||||
</p>
|
||||
</section>
|
||||
|
||||
<!-- Tab 12: Ask a quick question -->
|
||||
<!-- Tab 12: Helpers (subagents) -->
|
||||
<section class="help-panel" data-tab="subagents">
|
||||
<h3>Helpers (subagents)</h3>
|
||||
<p>
|
||||
On a build, a review and Pathfinder, Plan2Code can hand independent
|
||||
pieces of work to helpers (subagents) while it keeps the conversation
|
||||
with you. The <strong>Subagents</strong> button in the top bar, after
|
||||
Stop session, is lit while helpers are on.
|
||||
</p>
|
||||
<h4>The switch</h4>
|
||||
<ul>
|
||||
<li>
|
||||
Clicking the button opens the <strong>Subagents</strong> dialog; it
|
||||
never switches helpers on or off by itself. Pick <strong>Use
|
||||
helpers</strong> or <strong>Work alone</strong>, edit the instruction
|
||||
Plan2Code follows (<strong>Reset to default</strong> puts the
|
||||
shipped one back), and say how many may run at once.
|
||||
</li>
|
||||
<li>
|
||||
It is off by default and saved for this project and this skill, so
|
||||
the next session of the same skill here starts the same way.
|
||||
</li>
|
||||
<li>
|
||||
The change reaches Plan2Code at its next check-in, as a setting,
|
||||
not as something you typed. How many helpers it can really start is
|
||||
up to your agent; some have no helpers at all.
|
||||
</li>
|
||||
<li>The button only appears on skills that use helpers, and only when Plan2Code can pass the setting on.</li>
|
||||
</ul>
|
||||
<h4>The Subagents tab</h4>
|
||||
<ul>
|
||||
<li>
|
||||
With the first helper, a <strong>Subagents</strong> tab appears before
|
||||
Ask: one row each, with what it was asked, whether it is running, done
|
||||
or failed, and a one-line result at the end. The number on the tab is
|
||||
how many are still running.
|
||||
</li>
|
||||
<li>
|
||||
Helpers report through Plan2Code, so the rows change at its
|
||||
check-ins, not live. The page cannot stop a helper; ask Plan2Code
|
||||
on the Ask tab if one should stop.
|
||||
</li>
|
||||
<li>
|
||||
<strong>Working alone</strong> means your agent has no way to start
|
||||
helpers here, so it is doing the work itself.
|
||||
</li>
|
||||
<li>
|
||||
Pathfinder always uses helpers for its research questions, whatever
|
||||
the switch says, and they show here too.
|
||||
</li>
|
||||
<li>The tab clears when you go back to the dashboard.</li>
|
||||
</ul>
|
||||
</section>
|
||||
|
||||
<!-- Tab 13: Ask a quick question -->
|
||||
<section class="help-panel" data-tab="ask">
|
||||
<h3>Ask a quick question</h3>
|
||||
<p class="help-lead">
|
||||
@@ -1568,7 +1642,7 @@
|
||||
</p>
|
||||
</section>
|
||||
|
||||
<!-- Tab 13: Stopping and finishing -->
|
||||
<!-- Tab 14: Stopping and finishing -->
|
||||
<section class="help-panel" data-tab="finishing">
|
||||
<h3>Stopping and finishing</h3>
|
||||
<p class="help-lead">
|
||||
@@ -1650,7 +1724,7 @@
|
||||
</p>
|
||||
</section>
|
||||
|
||||
<!-- Tab 14: When something looks stuck -->
|
||||
<!-- Tab 15: When something looks stuck -->
|
||||
<section class="help-panel" data-tab="stuck">
|
||||
<h3>When something looks stuck</h3>
|
||||
<p class="help-lead">
|
||||
@@ -1772,7 +1846,7 @@
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<!-- Tab 15: Keyboard and preferences -->
|
||||
<!-- Tab 16: Keyboard and preferences -->
|
||||
<section class="help-panel" data-tab="prefs">
|
||||
<h3>Keyboard and preferences</h3>
|
||||
<p class="help-lead">
|
||||
@@ -1888,7 +1962,7 @@
|
||||
</ul>
|
||||
</section>
|
||||
|
||||
<!-- Tab 16: Privacy and where things are saved -->
|
||||
<!-- Tab 17: Privacy and where things are saved -->
|
||||
<section class="help-panel" data-tab="privacy">
|
||||
<h3>Privacy and where things are saved</h3>
|
||||
<p class="help-lead">
|
||||
@@ -1925,7 +1999,11 @@
|
||||
</li>
|
||||
<li>
|
||||
your role, theme, colors, card width and sounds, in
|
||||
<code>looks.json</code>.
|
||||
<code>looks.json</code>;
|
||||
</li>
|
||||
<li>
|
||||
your Subagents switch for each project and skill, in
|
||||
<code>subagents.json</code>.
|
||||
</li>
|
||||
</ul>
|
||||
<p>
|
||||
@@ -2039,6 +2117,46 @@
|
||||
</div>
|
||||
</dialog>
|
||||
|
||||
<!-- Subagents: the switch for this skill, filled from the frame's
|
||||
`subagents` by app.js and saved through POST /subagents. It borrows
|
||||
the User Preferences dialog's classes, so it needs no dialog styles of
|
||||
its own, only a themed number box. -->
|
||||
<dialog class="modal looks subagents" id="subagents-modal" aria-labelledby="subagents-title">
|
||||
<h2 id="subagents-title">Subagents</h2>
|
||||
<p class="modal-blurb">
|
||||
Let Plan2Code hand independent work to helpers in this skill. Saved for this
|
||||
project and this skill.
|
||||
</p>
|
||||
<fieldset class="modal-ranges looks-row">
|
||||
<legend>Helpers</legend>
|
||||
<label><input type="radio" name="subagents-on" value="on" /> <span>Use helpers</span></label>
|
||||
<label><input type="radio" name="subagents-on" value="off" checked /> <span>Work alone</span></label>
|
||||
</fieldset>
|
||||
<fieldset class="modal-ranges">
|
||||
<legend>Instruction</legend>
|
||||
<textarea id="subagents-instruction" rows="4" maxlength="2000" aria-label="Instruction"></textarea>
|
||||
<div class="models-actions">
|
||||
<button type="button" class="btn small ghost" id="subagents-default">Reset to default</button>
|
||||
<span class="help">Passed to the agent as written, at its next check-in.</span>
|
||||
</div>
|
||||
</fieldset>
|
||||
<fieldset class="modal-ranges">
|
||||
<legend>At most</legend>
|
||||
<label>
|
||||
<input type="number" id="subagents-max" min="1" max="20" step="1" aria-label="At most this many helpers at once" />
|
||||
<span>helpers at once</span>
|
||||
</label>
|
||||
<p class="help">Advisory: your agent's own limit still applies.</p>
|
||||
</fieldset>
|
||||
<p class="help" id="subagents-checkin"></p>
|
||||
<p class="help" id="subagents-research" hidden></p>
|
||||
<p class="help" id="subagents-status" role="status"></p>
|
||||
<div class="modal-actions">
|
||||
<button type="button" class="btn ghost" id="subagents-cancel">Cancel</button>
|
||||
<button type="button" class="btn primary" id="subagents-save">Save</button>
|
||||
</div>
|
||||
</dialog>
|
||||
|
||||
<!-- The Workspace: the folder this session started in plus any added as
|
||||
context. The list is drawn by app.js from the frame's `workspace`;
|
||||
every change goes through the server's /workspace routes. -->
|
||||
|
||||
@@ -0,0 +1,223 @@
|
||||
// Plan2Code Web Console - the Subagents switch's opt-in table, wording and checks.
|
||||
//
|
||||
// The source of truth for which workflows offer the switch, the instruction
|
||||
// each one ships with, the fixed frame every "on" block carries, the exact
|
||||
// lines the agent reads at a pickup (blockFor()), and the house rules for the
|
||||
// helpers an agent reports back (checkHelper()). No DOM access at module scope
|
||||
// and no imports: the server, console.mjs, the page and `node --test` all
|
||||
// import this file.
|
||||
|
||||
// The one place a skill opts in (FR-1). Wording is behaviour-level and names
|
||||
// no harness tool, so any agent can follow it or harmlessly ignore it.
|
||||
export const SUBAGENT_WORKFLOWS = Object.freeze({
|
||||
implement: Object.freeze({
|
||||
instruction:
|
||||
"Hand independent tasks in a phase to helpers: tasks that touch different files and do not depend on each other. Keep tasks that share files, the phase's tests and the sign-off with you.",
|
||||
}),
|
||||
"implement-review": Object.freeze({
|
||||
instruction:
|
||||
"Hand independent tasks in a phase to helpers: tasks that touch different files and do not depend on each other. Keep tasks that share files, the phase's tests and the sign-off with you.",
|
||||
}),
|
||||
"quick-task": Object.freeze({
|
||||
instruction:
|
||||
"Use helpers for side lookups, such as reading unfamiliar code or checking documentation, while you make the change yourself.",
|
||||
}),
|
||||
review: Object.freeze({
|
||||
instruction:
|
||||
"Split the review across helpers by area (for example correctness, tests and security), then merge and de-duplicate their findings yourself before you report.",
|
||||
}),
|
||||
pathfinder: Object.freeze({
|
||||
instruction:
|
||||
"Use helpers for codebase recon, sketches and lookups beside the conversation. Keep every question for the person with you.",
|
||||
}),
|
||||
});
|
||||
|
||||
export function offered(workflow) {
|
||||
return typeof workflow === "string" && Object.prototype.hasOwnProperty.call(SUBAGENT_WORKFLOWS, workflow);
|
||||
}
|
||||
|
||||
export const MAX_MIN = 1;
|
||||
export const MAX_MAX = 20;
|
||||
export const DEFAULT_MAX = 3;
|
||||
export const INSTRUCTION_MAX_CHARS = 2000;
|
||||
export const HELPER_TITLE_MAX = 80;
|
||||
export const HELPER_ASK_MAX = 400;
|
||||
export const HELPER_RESULT_MAX = 200;
|
||||
export const HELPER_STATES = Object.freeze(["running", "done", "failed"]);
|
||||
|
||||
/* ------------------------------------------------------------- settings */
|
||||
|
||||
export function defaultInstruction(workflow) {
|
||||
return offered(workflow) ? SUBAGENT_WORKFLOWS[workflow].instruction : "";
|
||||
}
|
||||
|
||||
// The person's own text when they wrote some, else the workflow's default.
|
||||
export function effectiveInstruction(setting) {
|
||||
const own = setting && typeof setting.instruction === "string" ? setting.instruction.trim() : "";
|
||||
return own || defaultInstruction(setting && setting.workflow);
|
||||
}
|
||||
|
||||
export function defaultSetting(workflow) {
|
||||
return { workflow, on: false, instruction: null, max: DEFAULT_MAX };
|
||||
}
|
||||
|
||||
/**
|
||||
* `{ on, instruction, max }` from untrusted input, or `{ error }` naming the
|
||||
* field that failed: "bad" (wrong type), "too-long" (instruction) or "max".
|
||||
* Returns an error object rather than throwing, so the route and the store
|
||||
* reader share one validator. An empty instruction means the default: null.
|
||||
*/
|
||||
export function cleanSetting(input) {
|
||||
if (!input || typeof input !== "object" || Array.isArray(input)) return { error: "bad" };
|
||||
if (typeof input.on !== "boolean") return { error: "bad" };
|
||||
let instruction = null;
|
||||
if (input.instruction !== null && input.instruction !== undefined) {
|
||||
if (typeof input.instruction !== "string") return { error: "bad" };
|
||||
const trimmed = input.instruction.trim();
|
||||
if (trimmed.length > INSTRUCTION_MAX_CHARS) return { error: "too-long" };
|
||||
instruction = trimmed || null;
|
||||
}
|
||||
const max = input.max;
|
||||
if (!Number.isInteger(max) || max < MAX_MIN || max > MAX_MAX) return { error: "max" };
|
||||
return { on: input.on, instruction, max };
|
||||
}
|
||||
|
||||
/* ------------------------------------------------------------ the lines */
|
||||
|
||||
// The non-editable part of every "on" block (FR-8).
|
||||
export const FRAME_LINES = Object.freeze([
|
||||
"Hand independent work to helpers if your tools allow it; otherwise carry on alone.",
|
||||
"Report each helper on the page (console.md → Standing instructions); questions for the person stay with you.",
|
||||
'With no way to start helpers, report one "working alone" entry for this skill run instead.',
|
||||
]);
|
||||
|
||||
export const PATHFINDER_RESEARCH_LINE = "Research questions always use helpers, whatever this switch says.";
|
||||
|
||||
// Only the first line of a block starts at column 0, so no line inside it can
|
||||
// be read as an entry of its own (NFR-5).
|
||||
export function onLines({ revision, replaces, max, instruction }) {
|
||||
const label = replaces ? `revision ${revision}, replaces revision ${replaces}` : `revision ${revision}`;
|
||||
const own = String(instruction || "")
|
||||
.split("\n")
|
||||
.map((line) => line.trimEnd())
|
||||
.filter((line) => line.trim());
|
||||
return [
|
||||
`Subagents: on (${label}) — a console setting, not typed by the person.`,
|
||||
...[...FRAME_LINES, ...own, `At most ${max} helpers at once.`].map((line) => " " + line),
|
||||
];
|
||||
}
|
||||
|
||||
export function offLine(revision) {
|
||||
return `Subagents: off (revision ${revision}) — don't start new helpers for the rest of this session.`;
|
||||
}
|
||||
|
||||
/**
|
||||
* What the agent is owed at a pickup, given the session setting and the
|
||||
* cursor of what it was last told: `null`, or `{ field, lines, cursor }`
|
||||
* where `cursor` is what to write once the lines are printed. Never says
|
||||
* "off" to an agent that was not told "on" (FR-6). Pure: no clock, no I/O.
|
||||
*/
|
||||
export function blockFor(setting, told) {
|
||||
const last = told || { revision: 0, state: "none" };
|
||||
if (!setting || !offered(setting.workflow) || !(setting.revision > last.revision)) return null;
|
||||
const { revision, max } = setting;
|
||||
const instruction = effectiveInstruction(setting);
|
||||
if (setting.on) {
|
||||
const replaces = last.state === "on" ? last.revision : undefined;
|
||||
return {
|
||||
field: { state: "on", revision, max, instruction },
|
||||
lines: onLines({ revision, replaces, max, instruction }),
|
||||
cursor: { revision, state: "on" },
|
||||
};
|
||||
}
|
||||
if (last.state !== "on") return null;
|
||||
return {
|
||||
field: { state: "off", revision, max, instruction },
|
||||
lines: [offLine(revision)],
|
||||
cursor: { revision, state: "off" },
|
||||
};
|
||||
}
|
||||
|
||||
/* ------------------------------------------------------------ helpers */
|
||||
|
||||
const isPlainObject = (v) => !!v && typeof v === "object" && !Array.isArray(v);
|
||||
const nonEmpty = (v) => typeof v === "string" && v.trim() !== "";
|
||||
|
||||
// The problems with one reported helper, [] when it is fine.
|
||||
export function checkHelper(entry) {
|
||||
if (!isPlainObject(entry)) return ["helper: each entry must be an object"];
|
||||
if (!nonEmpty(entry.id)) return ["helper: id must be a non-empty string"];
|
||||
const who = `helper "${entry.id}"`;
|
||||
if (entry.alone === true) return entry.id === "alone" ? [] : [`${who}: the working-alone entry must have id "alone"`];
|
||||
const problems = [];
|
||||
if (!nonEmpty(entry.title)) problems.push(`${who}: title must be a non-empty string`);
|
||||
else if (entry.title.length > HELPER_TITLE_MAX) problems.push(`${who}: title must be at most ${HELPER_TITLE_MAX} characters`);
|
||||
if (!nonEmpty(entry.ask)) problems.push(`${who}: ask must be a non-empty string`);
|
||||
else if (entry.ask.length > HELPER_ASK_MAX) problems.push(`${who}: ask must be at most ${HELPER_ASK_MAX} characters`);
|
||||
if (!HELPER_STATES.includes(entry.state)) problems.push(`${who}: state must be running, done or failed`);
|
||||
if (entry.result !== undefined) {
|
||||
if (typeof entry.result !== "string") problems.push(`${who}: result must be a string`);
|
||||
else if (entry.result.length > HELPER_RESULT_MAX) problems.push(`${who}: result must be at most ${HELPER_RESULT_MAX} characters`);
|
||||
}
|
||||
return problems;
|
||||
}
|
||||
|
||||
// The problems with a whole merged list.
|
||||
export function checkHelpers(list) {
|
||||
if (!Array.isArray(list)) return ["helpers must be an array"];
|
||||
const problems = [];
|
||||
const seen = new Set();
|
||||
let alone = 0;
|
||||
for (const entry of list) {
|
||||
if (isPlainObject(entry) && nonEmpty(entry.id)) {
|
||||
if (seen.has(entry.id)) problems.push(`helper "${entry.id}": duplicate id`);
|
||||
seen.add(entry.id);
|
||||
if (entry.alone === true && ++alone === 2) problems.push(`helper "${entry.id}": only one working-alone entry is allowed`);
|
||||
}
|
||||
problems.push(...checkHelper(entry));
|
||||
}
|
||||
return problems;
|
||||
}
|
||||
|
||||
/* ------------------------------------------------------------ the page */
|
||||
|
||||
// The page's rules for the button, the modal and the tab, kept here so they
|
||||
// are tested without a browser. `frame` is the state frame's `subagents`
|
||||
// block; app.js only renders what these say.
|
||||
|
||||
export const CHECKIN_LINE = "Helpers report through Plan2Code, so their progress shows here at its check-ins, not live.";
|
||||
|
||||
const STATE_LABELS = Object.freeze({ running: "Running", done: "Done", failed: "Failed" });
|
||||
|
||||
// The switch shows only where the skill opts in AND the agent's console copy
|
||||
// said it can deliver it (FR-3).
|
||||
export function showSwitch(frame) {
|
||||
return Boolean(frame && frame.offered && frame.supported);
|
||||
}
|
||||
|
||||
// The button's tooltip and accessible name (FR-2).
|
||||
export function switchLabel(frame) {
|
||||
return frame && frame.on ? "Subagents: on" : "Subagents: off";
|
||||
}
|
||||
|
||||
// What the Subagents tab draws: the working-alone note, or one row per helper
|
||||
// in the order the agent reported them. A result shows once the helper ended.
|
||||
export function helperRows(helpers) {
|
||||
const list = Array.isArray(helpers) ? helpers.filter(isPlainObject) : [];
|
||||
if (list.some((h) => h.alone === true)) return { alone: true, rows: [] };
|
||||
const rows = list.map(({ id, title, ask, state, result }) => ({
|
||||
id,
|
||||
title,
|
||||
ask,
|
||||
state,
|
||||
stateLabel: STATE_LABELS[state] || STATE_LABELS.running,
|
||||
...((state === "done" || state === "failed") && typeof result === "string" && result ? { result } : {}),
|
||||
}));
|
||||
return { alone: false, rows };
|
||||
}
|
||||
|
||||
// Never an empty tab. Independent of on / off, so Pathfinder's research
|
||||
// helpers show even with the switch off (FR-11, FR-12).
|
||||
export function showTab(frame, helpers) {
|
||||
return showSwitch(frame) && Array.isArray(helpers) && helpers.length > 0;
|
||||
}
|
||||
@@ -25,6 +25,7 @@ import {
|
||||
LOOKS_FILE,
|
||||
PUBLIC_DIR,
|
||||
SHIPPED_MODELS_FILE,
|
||||
SUBAGENTS_SETTING_FILE,
|
||||
UPDATE_CHECK_FILE,
|
||||
USER_MODELS_FILE,
|
||||
WORKSPACE_FILE,
|
||||
@@ -38,6 +39,7 @@ import {
|
||||
fileStamp,
|
||||
handleFile,
|
||||
initialWorkspace,
|
||||
latestOpenCaps,
|
||||
nowIso,
|
||||
parseArgs,
|
||||
pendingChatCount,
|
||||
@@ -46,20 +48,25 @@ import {
|
||||
readJson,
|
||||
readLedger,
|
||||
readOverview,
|
||||
readSubagentSetting,
|
||||
readWorkspace,
|
||||
rememberWorkspace,
|
||||
rememberedWorkspace,
|
||||
removeCleanup,
|
||||
remoteWarning,
|
||||
saveSubagentStoreEntry,
|
||||
specKey,
|
||||
subagentStoreEntry,
|
||||
typedCount,
|
||||
withStateLock,
|
||||
writeJsonAtomic,
|
||||
writeSubagentSetting,
|
||||
writeWorkspace,
|
||||
} from "./lib.mjs";
|
||||
import { DOC_TYPES, MAX_ATTACHMENTS, MAX_DOC_BYTES, docExt, workflowLabel, workflowTitle } from "./public/answers.js";
|
||||
import { CHAT_LIMIT, CHAT_MAX_CHARS, chatOffline } from "./public/chat.js";
|
||||
import { meterView } from "./public/meter.js";
|
||||
import { cleanSetting, defaultSetting, offered } from "./public/subagents.js";
|
||||
import { ACCENTS, DEFAULT_ACCENT, DEFAULT_CARD_WIDTH, cardWidth } from "./public/palette.js";
|
||||
import { defaultName, freeName, nameProblem } from "./public/workspace.js";
|
||||
import { checkForUpdate } from "./update-check.mjs";
|
||||
@@ -212,6 +219,7 @@ const SERVABLE = new Set([
|
||||
"starters.js",
|
||||
"workspace.js",
|
||||
"meter.js",
|
||||
"subagents.js",
|
||||
"mentions.js",
|
||||
"favicon.js",
|
||||
"start-stop.mp3",
|
||||
@@ -601,6 +609,48 @@ function ensureConversation(state) {
|
||||
if (entry) appendEvent(DIR, { type: "chat-reset", reason: entry.reason });
|
||||
}
|
||||
|
||||
/* ------------------------------------------------------------ subagents */
|
||||
|
||||
// subagents-setting.json has one writer, this server, and the agent hears of
|
||||
// it only through what console.mjs reads there; events.ndjson's latest `open`
|
||||
// says whether the agent's console copy can carry it. Both re-read only when
|
||||
// their file has moved.
|
||||
const SUBAGENTS_SETTING_PATH = path.join(DIR, SUBAGENTS_SETTING_FILE);
|
||||
const EVENTS_PATH = path.join(DIR, "events.ndjson");
|
||||
|
||||
let subagentSettingSeen = { stamp: null, setting: null };
|
||||
function subagentSettingNow() {
|
||||
const stamp = fileStamp(SUBAGENTS_SETTING_PATH);
|
||||
if (stamp !== subagentSettingSeen.stamp) subagentSettingSeen = { stamp, setting: readSubagentSetting(DIR) };
|
||||
return subagentSettingSeen.setting;
|
||||
}
|
||||
|
||||
let capsSeen = { stamp: null, caps: [] };
|
||||
function openCapsNow() {
|
||||
const stamp = fileStamp(EVENTS_PATH);
|
||||
if (stamp !== capsSeen.stamp) capsSeen = { stamp, caps: latestOpenCaps(DIR) };
|
||||
return capsSeen.caps;
|
||||
}
|
||||
|
||||
const sameSetting = (a, b) => a.workflow === b.workflow && a.on === b.on && a.instruction === b.instruction && a.max === b.max;
|
||||
|
||||
/**
|
||||
* Turn the per-project store into this session's setting, for the workflow
|
||||
* the session is in now. The only place that happens (FR-7): a session an
|
||||
* older server ran has no setting file, so nothing is ever injected into it.
|
||||
* A record that already matches is left alone, revision and all, so a
|
||||
* restart alone never re-tells the agent anything.
|
||||
*/
|
||||
function syncSubagentSetting(state) {
|
||||
if (!state || typeof state.workflow !== "string") return;
|
||||
const { workflow } = state;
|
||||
const { on, instruction, max } = offered(workflow) ? subagentStoreEntry(sessionWorktree(), workflow) : defaultSetting(workflow);
|
||||
const target = { workflow, on, instruction, max };
|
||||
const current = readSubagentSetting(DIR);
|
||||
if (current && sameSetting(current, target)) return;
|
||||
writeSubagentSetting(DIR, { ...target, revision: (current ? current.revision : 0) + 1 });
|
||||
}
|
||||
|
||||
// What the page needs to draw itself, in the shape of the SSE state frame.
|
||||
// `have` names that exact view, for the page to hand back when it opens its
|
||||
// stream (see /events).
|
||||
@@ -615,20 +665,33 @@ function stateFrame(state) {
|
||||
chat: { ...chatForFrame(chatEntries(), state), pickedUp: chatPickedUp(), offline: chatOfflineNow(state) },
|
||||
workspace: workspaceView(),
|
||||
meter: meterView(ledgerEntries()),
|
||||
subagents: subagentsView(state),
|
||||
...(updateInfo ? { update: updateInfo } : {}),
|
||||
have: haveKey(),
|
||||
};
|
||||
}
|
||||
|
||||
// The page shows the switch only when `offered && supported` (FR-3); the
|
||||
// frame says both and leaves combining them to the page. `instruction: null`
|
||||
// is the shipped default, which the page reads from subagents.js itself.
|
||||
function subagentsView(state) {
|
||||
const workflow = state && state.workflow;
|
||||
const { on, instruction, max, revision } = subagentSettingNow() || { ...defaultSetting(workflow), revision: 0 };
|
||||
return { offered: offered(workflow), supported: openCapsNow().includes("subagents"), on, instruction, max, revision };
|
||||
}
|
||||
|
||||
function haveKey() {
|
||||
const { pending, stop } = resultFlags();
|
||||
chatEntries();
|
||||
chatPickedUp();
|
||||
workspaceNow();
|
||||
ledgerEntries();
|
||||
subagentSettingNow();
|
||||
openCapsNow();
|
||||
return (
|
||||
`${STARTED}.${rev}.${pending ? 1 : 0}${stop ? 1 : 0}.${chatSeen.stamp || ""}.${cursorSeen.stamp || ""}` +
|
||||
`.${workspaceSeen.stamp || ""}.${ledgerSeen.stamp || ""}.${updateInfo ? updateInfo.latest : ""}`
|
||||
`.${workspaceSeen.stamp || ""}.${ledgerSeen.stamp || ""}.${updateInfo ? updateInfo.latest : ""}` +
|
||||
`.${subagentSettingSeen.stamp || ""}.${capsSeen.stamp || ""}`
|
||||
);
|
||||
}
|
||||
|
||||
@@ -1172,6 +1235,39 @@ const server = http.createServer((req, res) => {
|
||||
});
|
||||
}
|
||||
|
||||
// The Subagents switch for the session's workflow. Saved per project folder
|
||||
// for the next session, and applied to this one with a bumped revision, which
|
||||
// is what console.mjs hands the agent at its next pickup. Never blocked by,
|
||||
// and never blocking, a card send.
|
||||
if (pathname === "/subagents" && req.method === "POST") {
|
||||
if (!originOk(req, port)) return json(res, 403, { error: "bad origin" });
|
||||
return readBody(req, (err, body) => {
|
||||
if (err) return json(res, err.tooBig ? 413 : 400, { error: err.tooBig ? "too large" : "body must be JSON" });
|
||||
const state = readState();
|
||||
if (!state || !offered(state.workflow)) return json(res, 400, { error: "not-offered" });
|
||||
const clean = cleanSetting(body);
|
||||
if (clean.error) return json(res, 400, { error: clean.error });
|
||||
const { on, instruction, max } = clean;
|
||||
const current = readSubagentSetting(DIR);
|
||||
const next = { workflow: state.workflow, on, instruction, max };
|
||||
// The store is per project, so another session may have moved it since
|
||||
// this one synced: it always takes the person's latest pick. Only a
|
||||
// real change to this session's setting bumps what the agent hears.
|
||||
const unchanged = Boolean(current && sameSetting(current, next));
|
||||
try {
|
||||
saveSubagentStoreEntry(sessionWorktree(), state.workflow, { on, instruction, max });
|
||||
if (!unchanged) writeSubagentSetting(DIR, { ...next, revision: (current ? current.revision : 0) + 1 });
|
||||
} catch (e) {
|
||||
return json(res, 500, { error: String(e.message) });
|
||||
}
|
||||
if (unchanged) return json(res, 200, { ok: true, setting: current });
|
||||
const setting = readSubagentSetting(DIR);
|
||||
appendEvent(DIR, { type: "subagents", on, revision: setting.revision });
|
||||
pushState();
|
||||
return json(res, 200, { ok: true, setting });
|
||||
});
|
||||
}
|
||||
|
||||
// The launcher's model menu: what ships (read-only here) and what the user added.
|
||||
if (pathname === "/models" && req.method === "GET") {
|
||||
const saved = readJson(USER_MODELS_FILE, null) || {};
|
||||
@@ -1400,6 +1496,9 @@ const server = http.createServer((req, res) => {
|
||||
try {
|
||||
ensureConversation(written.state);
|
||||
} catch {}
|
||||
try {
|
||||
syncSubagentSetting(written.state);
|
||||
} catch {}
|
||||
}
|
||||
}
|
||||
// Name the items that went. A page with OTHER answers staged should drop
|
||||
@@ -1726,6 +1825,9 @@ function checkState() {
|
||||
try {
|
||||
ensureConversation(parsed);
|
||||
} catch {}
|
||||
try {
|
||||
syncSubagentSetting(parsed);
|
||||
} catch {}
|
||||
try {
|
||||
followSpecDir(parsed);
|
||||
} catch {}
|
||||
@@ -1900,6 +2002,9 @@ function onListening(port) {
|
||||
try {
|
||||
bootWorkspace();
|
||||
} catch {}
|
||||
try {
|
||||
syncSubagentSetting(readState());
|
||||
} catch {}
|
||||
process.stdout.write(JSON.stringify({ type: "ready", url, port, sid: SID }) + "\n");
|
||||
try {
|
||||
startUpdateCheck();
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "Plan2Code",
|
||||
"version": "2.4.2",
|
||||
"version": "2.5.0",
|
||||
"description": "A structured 4-step workflow methodology for AI-assisted software development",
|
||||
"keywords": [
|
||||
"ai",
|
||||
@@ -17,6 +17,6 @@
|
||||
"url": "https://github.com/jparkerweb/plan2code"
|
||||
},
|
||||
"homepage": "https://github.com/jparkerweb/plan2code",
|
||||
"releaseDate": "2026-10-05",
|
||||
"releaseDate": "2026-10-06",
|
||||
"mode": "utility"
|
||||
}
|
||||
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "Plan2Code",
|
||||
"version": "2.4.2",
|
||||
"version": "2.5.0",
|
||||
"description": "A structured 4-step workflow methodology for AI-assisted software development",
|
||||
"keywords": [
|
||||
"ai",
|
||||
@@ -17,6 +17,6 @@
|
||||
"url": "https://github.com/jparkerweb/plan2code"
|
||||
},
|
||||
"homepage": "https://github.com/jparkerweb/plan2code",
|
||||
"releaseDate": "2026-10-05",
|
||||
"releaseDate": "2026-10-06",
|
||||
"mode": "utility"
|
||||
}
|
||||
@@ -39,10 +39,10 @@ Three levels -- auto-detected, always respect explicit user override:
|
||||
| Scope | Trigger | Reviews |
|
||||
|-------|---------|---------|
|
||||
| **Focused** | User names files/functions, or conversation work detected | Specified files only |
|
||||
| **Branch** | "review my changes" or no context available | Branch changes vs main |
|
||||
| **Branch** | "review my changes", or picked when asked | Branch changes vs main |
|
||||
| **Full** | "full review" or names a subsystem | Entire codebase/subsystem |
|
||||
|
||||
**Detection:** 1) User prompt wins. 2) Conversation context = `focused`. 3) Fallback = `branch`. Ambiguous? Ask.
|
||||
**Detection:** 1) User prompt wins. 2) Conversation context = `focused`. 3) Scope already decided by a host workflow (a build's review, `building.md`) = use it. 4) Standalone with nothing named = scan, then ask (Step 1). Never default to `branch` silently. Ambiguous? Ask.
|
||||
|
||||
**Thoroughness:** Scope controls WHAT is reviewed, not HOW DEEPLY. Every review is thorough.
|
||||
|
||||
@@ -52,7 +52,7 @@ Three levels -- auto-detected, always respect explicit user override:
|
||||
|
||||
## Process
|
||||
|
||||
**Pre-flight:** Check AGENTS.md — use conventions if found, note if missing. Determine review target from user prompt or conversation context. If neither provides clear signal, use `ask_user_question` — never guess.
|
||||
**Pre-flight:** Check AGENTS.md — use conventions if found, note if missing. Determine review target from user prompt or conversation context. If neither provides clear signal, scan and use `ask_user_question` (Step 1) — never guess.
|
||||
|
||||
**Reference files:** Companion files loaded via Read directives. Fallback rules inline if unavailable.
|
||||
|
||||
@@ -62,7 +62,8 @@ Three levels -- auto-detected, always respect explicit user override:
|
||||
|
||||
1. **User prompt** — use it.
|
||||
2. **Conversation context** — recent work? Those artifacts. Scope: `focused`.
|
||||
3. **Git fallback** — run `review-scope.mjs`. It compares the branch with its base (`main`, else `master`; `--base` overrides; `base` says which it used) and adds staged, unstaged and untracked changes: `files` (status, lines), `counts`, `commits`, `mix`, `batchByRisk`. `empty: true`? Ask user. Exit 3 `no-base` (no `main` or `master`, or no such `--base`)? Rerun with `--base <trunk>`, asking the user which branch is the trunk if unclear. Exit 3 `not-a-repo`? Ask user which files to review.
|
||||
3. **Standalone, nothing named** — do not assume a target. Do a quick scan (no file reading): `review-scope.mjs`, `specs.mjs list`, recent commits. Then ask what to review (`ask_user_question`; a `choice` on the console, scope questions up front), offering only options the scan supports, each with its size: the branch's changes vs base (files, ~lines, `commits`), uncommitted changes only (when any), a spec/plan under `specs/` (when any), a named subsystem or full codebase, or specific files/folders (free text via Other). Recommend the likeliest first. Nothing found (`empty: true`, no specs)? Ask for files or a subsystem. Use the answer as the scope, then continue.
|
||||
4. **Scan details** — `review-scope.mjs` compares the branch with its base (`main`, else `master`; `--base` overrides; `base` says which it used) and adds staged, unstaged and untracked changes: `files` (status, lines), `counts`, `commits`, `mix`, `batchByRisk`. `empty: true`? Ask user. Exit 3 `no-base` (no `main` or `master`, or no such `--base`)? Rerun with `--base <trunk>`, asking the user which branch is the trunk if unclear. Exit 3 `not-a-repo`? Ask user which files to review.
|
||||
|
||||
**Classify review type** from context (auto-detect; use `ask_user_question` only if ambiguous):
|
||||
|
||||
|
||||
@@ -64,6 +64,13 @@ progress bar is the first thing someone watching a build looks at. The session
|
||||
meter counts the build's tasks from `cleared` as it rises, so keep it current,
|
||||
and start every phase (a second one in the same run too) at `"cleared": 0`.
|
||||
|
||||
`"version": 1` is for the first phase of a session only. A doc's version
|
||||
never goes back (console.md → House rules, rule 9), so a later phase in the
|
||||
same session reposts `phase` and `phasefile` at one more than the version the
|
||||
page holds, with the new phase's title and content. The same goes for
|
||||
`report` at sign-off and `review` in a mid-session review: version 1 the
|
||||
first time, then up from wherever the page has it.
|
||||
|
||||
`phasefile` is the whole `phase-X.md`, verbatim from disk, as its own tab —
|
||||
the person can read the prerequisites and task specs while you build. Re-post
|
||||
it whenever the file changes, which is every task: the checkbox write that
|
||||
@@ -111,6 +118,12 @@ printed), never into the project or into `~/.plan2code/console/` directly:
|
||||
- Do not call `wait` while building. There is nothing to collect, and the page
|
||||
holds anything the person sends until you next look.
|
||||
|
||||
A build may receive a `Subagents:` standing instruction, on `open` output or a
|
||||
`chat` check between tasks. Follow console.md → Standing instructions for
|
||||
handing independent tasks to helpers and reporting them as `helpers`. Keep the
|
||||
per-task progress posts, the checkbox writes, the chat checks and the sign-off
|
||||
with you.
|
||||
|
||||
### Quick questions between tasks
|
||||
|
||||
The person can ask a Quick question on the Ask tab at any point in a build
|
||||
@@ -195,7 +208,8 @@ only ever be offered once nothing could come of it:
|
||||
`reply` carries `Approve this phase: approved`, which is the terminal's
|
||||
`approved`. If the note that came with an approval asks for a change, treat it
|
||||
as "describe any issues": do the change first and ask again. `changes` means
|
||||
exactly what it says: address it, bump the report's version, and reopen the
|
||||
exactly what it says: address it, bump the report's version (a later phase's
|
||||
report starts above the last one's, too), and reopen the
|
||||
item (`"status": "reopened"`) with a reply in its `thread`. `review` is the
|
||||
person asking for the code review before they approve anything — see "The
|
||||
review, mid-session" below.
|
||||
|
||||
@@ -170,7 +170,7 @@ so even a kill at the worst possible moment costs you a repeat, never an answer.
|
||||
|
||||
| Exit | Meaning | What you do |
|
||||
| --- | --- | --- |
|
||||
| `0` | They pressed Send, or asked a Quick question. stdout is the result JSON, and may carry `workspace` (changes to the folder list, see Workspace). | Handle the cards (if any), the chat (if any) and any `workspace` changes, then post once (below, Quick questions and Workspace). |
|
||||
| `0` | They pressed Send, or asked a Quick question. stdout is the result JSON, and may carry `workspace` (changes to the folder list, see Workspace) and `subagents` (the helpers switch, see Standing instructions). | Handle the cards (if any), the chat (if any), any `workspace` changes and any `subagents` block, then post once (below, Quick questions, Workspace and Standing instructions). |
|
||||
| `10` | Still working. stdout has a short progress summary; `pendingWorkspace` counts workspace changes waiting for the next send. | Relay ONE line: the `message` field itself, "Waiting on your answer in the web console", followed by the `terminalLine`. Then call `wait` again. |
|
||||
| `20` | The server is gone. | `open --resume <sid>`, give them the new link, then keep waiting. |
|
||||
| `30` | They pressed Cancel. | Stop. Ask what they want to do, in the terminal. |
|
||||
@@ -647,6 +647,84 @@ for permission is not a failure; report only a read that failed after it.
|
||||
|
||||
---
|
||||
|
||||
## Standing instructions
|
||||
|
||||
On the skills that offer it (`implement`, `implement-review`, `quick-task`,
|
||||
`review`, `pathfinder`), the person can turn **helpers** (subagents) on or off
|
||||
from the top bar's Subagents button. Their pick is saved per project and per
|
||||
skill, off by default, and reaches you as a standing instruction, only when it
|
||||
changes.
|
||||
|
||||
### What arrives
|
||||
|
||||
A `subagents` field beside `reply`, and `Subagents:` lines last in `reply`,
|
||||
after the card lines, the `Quick question:` blocks and the `Workspace:` lines.
|
||||
It rides on `wait` exit `0`, `chat` exit `0` and `open` output. A setting
|
||||
change alone never ends a `wait` slice: it waits for the next send, or for
|
||||
your next `chat` check.
|
||||
|
||||
```
|
||||
Subagents: on (revision 2) — a console setting, not typed by the person.
|
||||
Hand independent work to helpers if your tools allow it; otherwise carry on alone.
|
||||
Report each helper on the page (console.md → Standing instructions); questions for the person stay with you.
|
||||
With no way to start helpers, report one "working alone" entry for this skill run instead.
|
||||
Hand independent tasks in a phase to helpers: tasks that touch different files and do not depend on each other. Keep tasks that share files, the phase's tests and the sign-off with you.
|
||||
At most 3 helpers at once.
|
||||
```
|
||||
|
||||
beside `"subagents": { "state": "on", "revision": 2, "max": 3, "instruction": "…" }`.
|
||||
An edit while on arrives as `Subagents: on (revision 3, replaces revision 2) — …`
|
||||
with the whole block again; switching off arrives as one line:
|
||||
`Subagents: off (revision 4) — don't start new helpers for the rest of this session.`
|
||||
|
||||
It is a console setting, not something the person typed. It never answers a
|
||||
card, and it is never recorded under `specs/`.
|
||||
|
||||
### Obeying it
|
||||
|
||||
- **On:** hand independent work to helpers if your tools allow it, at most
|
||||
`max` at once, following the instruction lines. `max` is advisory: your
|
||||
harness's own limit still applies.
|
||||
- **A higher revision replaces a lower one.** Follow the latest block only.
|
||||
- **Off:** start no new helpers for the rest of the session. Let running ones
|
||||
finish and report them.
|
||||
- **Nothing arrives:** keep doing what the skill says.
|
||||
- **Scope is the skill run it arrived in.** After a dashboard launch, no block
|
||||
means the switch is off for this skill, even if an earlier skill in the same
|
||||
conversation was told "on": `open` starts the count again, and a launch with
|
||||
the switch off sends nothing.
|
||||
|
||||
### Reporting helpers
|
||||
|
||||
Post them, at your check-ins, so the page's Subagents tab can show them. The
|
||||
page never hears from a helper directly:
|
||||
|
||||
```jsonc
|
||||
{ "helpers": [
|
||||
{ "id": "h1", "title": "Read the store helpers", "ask": "Find every caller of readSubagentSetting.", "state": "running" },
|
||||
{ "id": "h2", "title": "Check the tests", "ask": "Run the subagents tests and report failures.", "state": "done", "result": "All 9 pass." }
|
||||
] }
|
||||
```
|
||||
|
||||
- `id` (non-empty), `title` (at most 80 characters), `ask` (at most 400) and
|
||||
`state` (`running`, `done` or `failed`) are required; `result` (at most 200)
|
||||
is the one line you add once a helper ends.
|
||||
- Merged by `id`: post a helper again with its new `state` and `result` and it
|
||||
updates in place. `"helpers": null` clears the list. A dashboard hop clears it
|
||||
too; a resume into the same skill keeps it.
|
||||
- One post per change worth seeing, not a stream.
|
||||
- Questions for the person stay with you, never with a helper: most harnesses
|
||||
give helpers no way to ask, and an answer only reaches the agent holding the
|
||||
session.
|
||||
- **No way to start helpers?** Post one `{ "id": "alone", "alone": true }`
|
||||
entry for the skill run instead. The tab then says you are working alone.
|
||||
- **Pathfinder:** research questions always use helpers and are always
|
||||
reported, whatever the switch says. The switch governs recon, sketches and
|
||||
lookups beside the conversation.
|
||||
- Helpers add no session meter points. Post no `run` for them.
|
||||
|
||||
---
|
||||
|
||||
## Launches (dashboard only)
|
||||
|
||||
A `dashboard` session is not a conversation: the page draws a menu of every
|
||||
@@ -763,7 +841,10 @@ commands follow the pipeline: the sign-off's is
|
||||
|
||||
### Review (`review`)
|
||||
|
||||
Scope questions up front, then the findings report as a doc (`id: "report"`),
|
||||
Scope questions up front — run standalone with nothing named, the first is
|
||||
a `choice`, "What should I review?", built from a quick scan (branch changes,
|
||||
uncommitted changes, specs, files you name; each option with its size),
|
||||
never an assumed target; a build's review skips it (`building.md`). Then the findings report as a doc (`id: "report"`),
|
||||
then the pick-what-gets-fixed menu as a `multi` or `choice` keyed by finding
|
||||
id, carrying `"doc": "report"` so the card links straight to the findings.
|
||||
Settle that item (`"status": "answered"` plus the `answer` they sent) in
|
||||
@@ -797,6 +878,8 @@ that is what the person is there to download. The finish carries no
|
||||
- Chart Step 8's research subagents must all report back before the
|
||||
finish (Finishing → Nothing of yours may still be running); the finish
|
||||
body then names what each one found.
|
||||
- Report every research subagent as a helper, whatever the Subagents switch
|
||||
says (Standing instructions → Reporting helpers).
|
||||
- At every session end, post `finish` (headline, `body`, and Form A's command as
|
||||
`command`) BEFORE `stop`. Someone who spent the session in the browser never
|
||||
sees the Trail Footer, and without this their last screen promises a question
|
||||
@@ -1146,6 +1229,16 @@ A patch that breaks one of these is rejected with exit `3` and a message:
|
||||
(Session meter) and a non-empty `id`; a `folderIssue` needs non-empty
|
||||
`name` and `reason` strings, and `hint`, when present, is one too. Rules 4
|
||||
and 5 cover `reason` and `hint`.
|
||||
8. **`helpers` entries are well formed** (Standing instructions → Reporting
|
||||
helpers): an array of objects, each with a unique `id`, a `title`, an `ask`
|
||||
and a known `state` within their limits, plus at most one `alone` entry.
|
||||
Rules 4 and 5 cover `title`, `ask` and `result`.
|
||||
9. **A doc's `version` never goes back.** Sending a known doc a lower
|
||||
`version` than the page holds is refused: it is almost always a stale or
|
||||
copied payload. The same version again is fine, and a dashboard hop starts
|
||||
every doc fresh. Anything else reusing a doc id in the same session (a
|
||||
build's second phase, a second report or review) continues from the
|
||||
version the page holds.
|
||||
|
||||
These are workflow rules you already follow. The server just makes them checkable.
|
||||
|
||||
@@ -1167,7 +1260,9 @@ cannot see them, and the moment it says the session ended, the person is
|
||||
free to close that terminal and kill them mid-write. While you wait, post
|
||||
`{"agent":{"status":"working","activity":"Researching 3 questions (1 of 3 back)"}}`
|
||||
and update the count as each returns. Never write a `finish.body` that says
|
||||
work "is running in the background" or "will finish on its own".
|
||||
work "is running in the background" or "will finish on its own". Mark every
|
||||
reported helper `done` or `failed` before the finish, so the Subagents tab
|
||||
never ends on a row still running.
|
||||
|
||||
### 1. Post the finish
|
||||
|
||||
|
||||
@@ -64,6 +64,8 @@ import {
|
||||
readChat,
|
||||
readJson,
|
||||
readLedger,
|
||||
readSubagentCursor,
|
||||
readSubagentSetting,
|
||||
readWorkspace,
|
||||
reapHandles,
|
||||
rememberedWorkspace,
|
||||
@@ -71,6 +73,7 @@ import {
|
||||
removeScratch,
|
||||
removeSessions,
|
||||
repoRoots,
|
||||
resetSubagentCursor,
|
||||
scanProject,
|
||||
SESSION_MAX_AGE_MS,
|
||||
sessionDir,
|
||||
@@ -88,9 +91,11 @@ import {
|
||||
workspaceForAgent,
|
||||
writeCursor,
|
||||
writeJsonAtomic,
|
||||
writeSubagentCursor,
|
||||
writeWorkspaceCursor,
|
||||
} from "./lib.mjs";
|
||||
import { RUN_EVENTS, TASK_EVENTS, MAX_TASKS, isTaskCount, progressEntry } from "./public/meter.js";
|
||||
import { blockFor, offered } from "./public/subagents.js";
|
||||
import { changeLine } from "./public/workspace.js";
|
||||
|
||||
// Mirrors the server's absolute lifetime cap: a handle older than this cannot
|
||||
@@ -310,7 +315,11 @@ async function cmdOpen() {
|
||||
die(`could not write the session state: ${written ? written.error : "unknown"}`, 1);
|
||||
}
|
||||
state = written.state;
|
||||
appendEvent(dir, { type: "open", resumed: Boolean(args.resume || args.session), carried });
|
||||
appendEvent(dir, { type: "open", resumed: Boolean(args.resume || args.session), carried, caps: ["subagents"] });
|
||||
// A new agent conversation has been told nothing yet (FR-6).
|
||||
try {
|
||||
resetSubagentCursor(dir);
|
||||
} catch {}
|
||||
trace("open: state written");
|
||||
|
||||
// Dashboard launches are recorded too (they score nothing), so the folder
|
||||
@@ -337,9 +346,18 @@ async function cmdOpen() {
|
||||
removeScratch(HOME_DIR, sweptScratch).catch(() => {});
|
||||
};
|
||||
|
||||
// A standing instruction the new agent is owed, as `subagents` and a
|
||||
// `reply` holding only its lines; neither key when nothing is owed.
|
||||
const subagentsOwed = () => {
|
||||
awaitSubagentSync(dir, state.workflow);
|
||||
const [out, cursor] = withSubagents(dir, { reply: "" });
|
||||
return [out.subagents ? out : {}, cursor];
|
||||
};
|
||||
|
||||
// Reuse a live server if one is already serving this session.
|
||||
if (existing && (await reusable)) {
|
||||
if (!args["no-open"]) openBrowser(existing.url);
|
||||
const [owed, subCursor] = subagentsOwed();
|
||||
print({
|
||||
ok: true,
|
||||
sid,
|
||||
@@ -349,9 +367,11 @@ async function cmdOpen() {
|
||||
pendingResult: carried,
|
||||
terminalLine: terminalLine(existing.url),
|
||||
workspace,
|
||||
...owed,
|
||||
...swept,
|
||||
...remoteWarning(),
|
||||
});
|
||||
advanceSubagents(dir, subCursor);
|
||||
sweep();
|
||||
return;
|
||||
}
|
||||
@@ -384,6 +404,7 @@ async function cmdOpen() {
|
||||
const notes = [];
|
||||
if (remote.note) notes.push(remote.note);
|
||||
if (carried) notes.push("Answers are already waiting. Run `wait` to collect them.");
|
||||
const [owed, subCursor] = subagentsOwed();
|
||||
print({
|
||||
ok: true,
|
||||
sid,
|
||||
@@ -394,10 +415,12 @@ async function cmdOpen() {
|
||||
pendingResult: carried,
|
||||
terminalLine: terminalLine(handle.url),
|
||||
workspace,
|
||||
...owed,
|
||||
...swept,
|
||||
...(remote.remote ? { remote: remote.remote } : {}),
|
||||
...(notes.length ? { note: notes.join(" ") } : {}),
|
||||
});
|
||||
advanceSubagents(dir, subCursor);
|
||||
// After the print, never before it: the page and the link wait for nothing.
|
||||
sweep();
|
||||
}
|
||||
@@ -774,7 +797,7 @@ function serverGone(sid) {
|
||||
|
||||
// Quick questions and nothing else: an ordinary exit 0 with no card actions.
|
||||
function deliverChat(dir, sid, entries, url) {
|
||||
const [out, changes] = withWorkspace(dir, {
|
||||
const [withWs, changes] = withWorkspace(dir, {
|
||||
type: "chat",
|
||||
at: nowIso(),
|
||||
sid,
|
||||
@@ -782,9 +805,11 @@ function deliverChat(dir, sid, entries, url) {
|
||||
chat: entries,
|
||||
reply: chatReplyLines(entries),
|
||||
});
|
||||
const [out, subCursor] = withSubagents(dir, withWs);
|
||||
print({ ...out, ...(url ? { terminalLine: terminalLine(url) } : {}) });
|
||||
advanceCursor(dir, entries);
|
||||
advanceWorkspace(dir, changes);
|
||||
advanceSubagents(dir, subCursor);
|
||||
process.exitCode = 0;
|
||||
}
|
||||
|
||||
@@ -806,6 +831,52 @@ function advanceWorkspace(dir, changes) {
|
||||
} catch {}
|
||||
}
|
||||
|
||||
// The server rewrites the session's setting for a new workflow only once its
|
||||
// watcher sees the state `open` just wrote, so a launch or hop that read the
|
||||
// file at once would find the old workflow's and owe the agent nothing until
|
||||
// its next pickup. Give the server a moment to catch up instead, never
|
||||
// writing the file ourselves (FR-7). A session with no setting file at all is
|
||||
// an older server, which never writes one: a short look, not the full wait.
|
||||
const SUBAGENT_SYNC_WAIT_MS = 1500;
|
||||
const SUBAGENT_SYNC_MISSING_MS = 250;
|
||||
function awaitSubagentSync(dir, workflow) {
|
||||
if (!offered(workflow)) return;
|
||||
const start = Date.now();
|
||||
for (;;) {
|
||||
const setting = readSubagentSetting(dir);
|
||||
if (setting && setting.workflow === workflow) return;
|
||||
const budget = setting ? SUBAGENT_SYNC_WAIT_MS : SUBAGENT_SYNC_MISSING_MS;
|
||||
if (Date.now() - start >= budget) return;
|
||||
sleepSync(25);
|
||||
}
|
||||
}
|
||||
|
||||
// The Subagents switch the agent is owed, added to what it is about to read:
|
||||
// the setting as `subagents`, and its lines last in `reply`, after card lines,
|
||||
// Quick questions and Workspace lines (FR-9). Read from the session's own
|
||||
// setting file only, which only the server writes (FR-7). A setting for
|
||||
// another workflow is the server not having caught up with a hop yet: it
|
||||
// rides on the next pickup instead.
|
||||
function withSubagents(dir, out) {
|
||||
const setting = readSubagentSetting(dir);
|
||||
if (!setting) return [out, null];
|
||||
const workflow = (readJson(path.join(dir, "state.json")) || {}).workflow;
|
||||
if (setting.workflow !== workflow) return [out, null];
|
||||
const block = blockFor(setting, readSubagentCursor(dir));
|
||||
if (!block) return [out, null];
|
||||
const reply = [out.reply, ...block.lines].filter(Boolean).join("\n");
|
||||
return [{ ...out, subagents: block.field, reply }, block.cursor];
|
||||
}
|
||||
|
||||
// After the print, like advanceWorkspace(): a kill in between repeats the
|
||||
// block at the next pickup, never loses it.
|
||||
function advanceSubagents(dir, cursor) {
|
||||
if (!cursor) return;
|
||||
try {
|
||||
writeSubagentCursor(dir, cursor);
|
||||
} catch {}
|
||||
}
|
||||
|
||||
// Print first, then this, exactly as consume() stamps a result: a kill in
|
||||
// between can only hand the same chat over again, and collectChat() drops
|
||||
// anything that already has a reply.
|
||||
@@ -832,15 +903,17 @@ async function cmdChat() {
|
||||
}
|
||||
const entries = deliverableChat(collectChat(dir, readJson(path.join(dir, "state.json")) || {}));
|
||||
const changes = pendingWorkspaceChanges(dir);
|
||||
if (!entries.length && !changes.length) {
|
||||
const reply = [chatReplyLines(entries), ...changes.map(changeLine)].filter(Boolean).join("\n");
|
||||
const [out, subCursor] = withSubagents(dir, { chat: entries, workspace: changes, reply });
|
||||
if (!entries.length && !changes.length && !subCursor) {
|
||||
print({ chat: [] });
|
||||
process.exitCode = 10;
|
||||
return;
|
||||
}
|
||||
const reply = [chatReplyLines(entries), ...changes.map(changeLine)].filter(Boolean).join("\n");
|
||||
print({ chat: entries, workspace: changes, reply, terminalLine: terminalLine(handle.url) });
|
||||
print({ ...out, terminalLine: terminalLine(handle.url) });
|
||||
advanceCursor(dir, entries);
|
||||
advanceWorkspace(dir, changes);
|
||||
advanceSubagents(dir, subCursor);
|
||||
process.exitCode = 0;
|
||||
}
|
||||
|
||||
@@ -865,7 +938,8 @@ function consume(dir, resultPath, result, url, chat = []) {
|
||||
// never on result.json itself.
|
||||
const withChat = { ...collected, chat };
|
||||
if (chat.length) withChat.reply = [collected.reply, chatReplyLines(chat)].filter(Boolean).join("\n");
|
||||
const [out, changes] = withWorkspace(dir, withChat);
|
||||
const [withWs, changes] = withWorkspace(dir, withChat);
|
||||
const [out, subCursor] = withSubagents(dir, withWs);
|
||||
print(url ? { ...out, terminalLine: terminalLine(url) } : out);
|
||||
try {
|
||||
writeJsonAtomic(resultPath, collected);
|
||||
@@ -874,6 +948,7 @@ function consume(dir, resultPath, result, url, chat = []) {
|
||||
ledgerAnswers(dir, result);
|
||||
advanceCursor(dir, chat);
|
||||
advanceWorkspace(dir, changes);
|
||||
advanceSubagents(dir, subCursor);
|
||||
process.exitCode = result.type === "cancel" ? 30 : 0;
|
||||
}
|
||||
|
||||
@@ -986,12 +1061,18 @@ port, and the filesystem as transport; this CLI is the whole agent surface.
|
||||
path, description?, original? }], missing? }, the folders this
|
||||
console session reads as context, addressed as @name. The list is
|
||||
remembered per folder and spec in workspaces.json beside looks.json.
|
||||
May also print subagents: { state, revision, max, instruction } and
|
||||
a reply holding only its "Subagents: ..." lines, when a standing
|
||||
instruction (the page's Subagents switch) is owed to you.
|
||||
post --session <sid> --file <patch.json>
|
||||
Merge a patch into the session. Prints terminalLine while the
|
||||
server is live. Exit 3 = rejected; stderr says why. A patch may
|
||||
carry run: { event, id, tasks? } (session meter points) and folderIssue:
|
||||
{ name, reason, hint? } (a workspace folder you could not read);
|
||||
both go to the ledger, never into the state.
|
||||
both go to the ledger, never into the state. A patch may also
|
||||
carry helpers: [{ id, title, ask, state, result? }] or one
|
||||
{ id: "alone", alone: true }, merged by id, for the Subagents tab
|
||||
(see console.md → Standing instructions).
|
||||
wait --session <sid> [--seconds <N>]
|
||||
A bounded wait slice, sized below your shell timeout. Exit 0 = the
|
||||
result is on stdout, 10 = still waiting ("Waiting on your answer
|
||||
@@ -1002,10 +1083,14 @@ port, and the filesystem as transport; this CLI is the whole agent surface.
|
||||
"workspace" (changes since you last heard, each once, with a
|
||||
"Workspace: ..." line in reply); exit 10 counts them as
|
||||
pendingWorkspace, and a change alone never ends a slice.
|
||||
Exit 0 may also carry "subagents" (a console setting, not typed
|
||||
by the person, with its "Subagents: ..." lines last in reply); a
|
||||
setting change alone never ends a slice either.
|
||||
chat --session <sid>
|
||||
Collect Quick questions and workspace changes now, never waiting,
|
||||
never touching card sends. Exit 0 = { chat, workspace, reply,
|
||||
terminalLine }, 10 = none, 20 = server gone.
|
||||
Collect Quick questions, workspace changes and a Subagents
|
||||
setting change now, never waiting, never touching card sends.
|
||||
Exit 0 = { chat, workspace, subagents?, reply, terminalLine },
|
||||
10 = none, 20 = server gone.
|
||||
terminalLine is "→ Look at the web console: <url>": end your terminal
|
||||
messages with it during a console session.
|
||||
keep --session <sid> --upload <path> --name <name> --spec specs/<idea> [--from <file>]
|
||||
|
||||
@@ -25,6 +25,7 @@ import { fileURLToPath } from "node:url";
|
||||
import { CHAT_LIMIT } from "./public/chat.js";
|
||||
import { DOC_TYPES } from "./public/answers.js";
|
||||
import { defaultName } from "./public/workspace.js";
|
||||
import { checkHelpers, cleanSetting, defaultSetting, offered } from "./public/subagents.js";
|
||||
|
||||
export const HERE = path.dirname(fileURLToPath(import.meta.url));
|
||||
export const PUBLIC_DIR = path.join(HERE, "public");
|
||||
@@ -491,9 +492,16 @@ export async function removeSessions(sessionsDir, sids) {
|
||||
}
|
||||
|
||||
// The console folder's own files that no sweep may ever remove: the person's
|
||||
// looks, the folders remembered per project and spec, the pointer to this
|
||||
// console's directory, and the cached release check.
|
||||
export const PROTECTED_CONSOLE_FILES = new Set(["looks.json", "workspaces.json", "console-dir", "update-check.json"]);
|
||||
// looks, the folders remembered per project and spec, the Subagents switch
|
||||
// saved per project and workflow, the pointer to this console's directory,
|
||||
// and the cached release check.
|
||||
export const PROTECTED_CONSOLE_FILES = new Set([
|
||||
"looks.json",
|
||||
"workspaces.json",
|
||||
"subagents.json",
|
||||
"console-dir",
|
||||
"update-check.json",
|
||||
]);
|
||||
|
||||
function isScratchName(name) {
|
||||
return (
|
||||
@@ -1142,6 +1150,19 @@ const DOC_DEFAULTS = { version: 1, stale: false, blocks: [] };
|
||||
// Blocks merge by id like docs do, so a patch that only settles a block's
|
||||
// state keeps its text. Blocks left out of the patch stay as they are.
|
||||
function mergeDocs(current, patchList) {
|
||||
// A doc's version only moves forward. One going back is a stale or copied
|
||||
// payload (last phase's progress script, say), and the page would quietly
|
||||
// show the old content under the new run's name.
|
||||
for (const entry of patchList) {
|
||||
if (!isPlainObject(entry) || typeof entry.version !== "number") continue;
|
||||
const prev = (current || []).find((d) => d && d.id === entry.id);
|
||||
if (prev && typeof prev.version === "number" && entry.version < prev.version) {
|
||||
throw new Error(
|
||||
`doc "${entry.id}" is at version ${prev.version} on the page; this patch sends version ${entry.version}. ` +
|
||||
"Versions only go up: bump it, and check the payload is the current one."
|
||||
);
|
||||
}
|
||||
}
|
||||
const merged = mergeKeyed(current, patchList, "id", DOC_DEFAULTS, "docs");
|
||||
for (const entry of patchList) {
|
||||
if (!Array.isArray(entry.blocks)) continue;
|
||||
@@ -1184,6 +1205,13 @@ export function applyPatch(state, patch) {
|
||||
if (!Array.isArray(v)) throw new Error('"topics" must be an array');
|
||||
next.topics = mergeKeyed(next.topics, v, "id", {}, "topics");
|
||||
break;
|
||||
case "helpers":
|
||||
// The agent's report of its helpers, for the page's Subagents tab.
|
||||
// Only `post` writes it; the server's /submit never touches it.
|
||||
if (!Array.isArray(v)) throw new Error('"helpers" must be an array');
|
||||
if (!v.every(isPlainObject)) throw new Error('"helpers" entries must be objects, each { id, title, ask, state }');
|
||||
next.helpers = mergeKeyed(next.helpers, v, "id", {}, "helpers");
|
||||
break;
|
||||
case "docs":
|
||||
if (!Array.isArray(v)) throw new Error('"docs" must be an array');
|
||||
next.docs = mergeDocs(next.docs, v);
|
||||
@@ -1478,6 +1506,20 @@ export function validate(state) {
|
||||
JSON.stringify(state.menu || {});
|
||||
problems.push(...proseProblems(prose));
|
||||
|
||||
// The agent's report of its helpers: the shape the page draws from
|
||||
// (subagents.js), then the same prose scan as everything else it writes.
|
||||
if (state.helpers != null) {
|
||||
problems.push(...checkHelpers(state.helpers));
|
||||
for (const helper of Array.isArray(state.helpers) ? state.helpers : []) {
|
||||
if (!isPlainObject(helper)) continue;
|
||||
for (const field of ["title", "ask", "result"]) {
|
||||
if (typeof helper[field] === "string") {
|
||||
problems.push(...proseProblems(helper[field], `helper "${helper.id}" ${field}`));
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
return problems;
|
||||
}
|
||||
|
||||
@@ -1507,7 +1549,8 @@ export function blankState({ sid, workflow, title, project, specDir }) {
|
||||
* A resume that passes through the dashboard (a finished skill going back to
|
||||
* it, or a launch from its menu) is a new skill taking the page over, so it
|
||||
* starts from a blank page: the last skill's questions, sections, docs,
|
||||
* headline and ending are its record on disk, not the next skill's opening.
|
||||
* helpers, headline and ending are its record on disk, not the next skill's
|
||||
* opening.
|
||||
* Only the session's identity carries across. `workspace.json`,
|
||||
* `ledger.ndjson` and the cursors live beside `state.json`, so the workspace
|
||||
* and the meter outlive every hop.
|
||||
@@ -1534,6 +1577,8 @@ export function switchWorkflow(state, { workflow, title, specDir }) {
|
||||
// workspace.json the server. Folders, version, change log, missing, remote.
|
||||
// ledger.ndjson console.mjs. Append-only meter events and folder issues.
|
||||
// workspace-cursor.json console.mjs. The last workspace version handed to the agent.
|
||||
// subagents-setting.json the server. The Subagents switch for this session, with its revision.
|
||||
// subagents-cursor.json console.mjs. The last Subagents revision and state handed to the agent.
|
||||
export const CHAT_FILE = "chat.ndjson";
|
||||
export const CHAT_CURSOR_FILE = "chat-cursor.json";
|
||||
export const WORKSPACE_FILE = "workspace.json";
|
||||
@@ -1989,6 +2034,98 @@ export function pendingWorkspaceChanges(dir) {
|
||||
return (readWorkspace(dir)?.changes || []).filter((c) => c.version > cursor);
|
||||
}
|
||||
|
||||
/* ------------------------------------------------------ the Subagents switch */
|
||||
|
||||
// The person's Subagents switch, remembered per project folder and workflow:
|
||||
//
|
||||
// { "<folded project path>": { "<workflow>": { on, instruction, max } } }
|
||||
//
|
||||
// Keyed with foldKey(), as workspaces.json is. `instruction: null` is the
|
||||
// workflow's shipped default.
|
||||
export const SUBAGENTS_FILE = path.join(HOME_DIR, "subagents.json");
|
||||
const SUBAGENTS_LOCK = "subagents.json.lock";
|
||||
|
||||
function readSubagentStore() {
|
||||
const saved = readJson(SUBAGENTS_FILE, null);
|
||||
return saved && typeof saved === "object" && !Array.isArray(saved) ? saved : {};
|
||||
}
|
||||
|
||||
// The saved `{ on, instruction, max }` for this folder and workflow, or the
|
||||
// default's when nothing (or something malformed) is saved.
|
||||
export function subagentStoreEntry(worktree, workflow) {
|
||||
const { on, instruction, max } = defaultSetting(workflow);
|
||||
const project = offered(workflow) ? readSubagentStore()[foldKey(worktree)] : null;
|
||||
const saved = project && typeof project === "object" ? cleanSetting(project[workflow]) : null;
|
||||
return saved && !saved.error ? saved : { on, instruction, max };
|
||||
}
|
||||
|
||||
// Single-writer rule: only server.mjs may call this.
|
||||
export function saveSubagentStoreEntry(worktree, workflow, value) {
|
||||
ensureDir(path.dirname(SUBAGENTS_FILE));
|
||||
withStateLock(
|
||||
path.dirname(SUBAGENTS_FILE),
|
||||
() => {
|
||||
const store = readSubagentStore();
|
||||
const key = foldKey(worktree);
|
||||
const project = store[key] && typeof store[key] === "object" ? store[key] : {};
|
||||
store[key] = { ...project, [workflow]: { on: value.on, instruction: value.instruction, max: value.max } };
|
||||
writeJsonAtomic(SUBAGENTS_FILE, store);
|
||||
},
|
||||
SUBAGENTS_LOCK
|
||||
);
|
||||
}
|
||||
|
||||
export const SUBAGENTS_SETTING_FILE = "subagents-setting.json";
|
||||
|
||||
const isCount = (n) => Number.isInteger(n) && n >= 0;
|
||||
|
||||
// This session's switch, `{ workflow, on, instruction, max, revision }`, or
|
||||
// null when there is none or it is malformed.
|
||||
export function readSubagentSetting(dir) {
|
||||
const s = readJson(path.join(dir, SUBAGENTS_SETTING_FILE), null);
|
||||
if (!s || typeof s !== "object") return null;
|
||||
if (typeof s.workflow !== "string" || typeof s.on !== "boolean" || !Number.isInteger(s.max) || !isCount(s.revision)) return null;
|
||||
return s;
|
||||
}
|
||||
|
||||
// Single-writer rule: only server.mjs may call this. The revision never goes
|
||||
// backwards within a session.
|
||||
export function writeSubagentSetting(dir, setting) {
|
||||
const previous = readSubagentSetting(dir);
|
||||
const revision = Math.max(previous ? previous.revision : 0, setting.revision);
|
||||
return writeJsonAtomic(path.join(dir, SUBAGENTS_SETTING_FILE), { ...setting, revision });
|
||||
}
|
||||
|
||||
export const SUBAGENTS_CURSOR_FILE = "subagents-cursor.json";
|
||||
const CURSOR_STATES = new Set(["none", "on", "off"]);
|
||||
|
||||
// What the agent was last told: `{ revision, state }`.
|
||||
export function readSubagentCursor(dir) {
|
||||
const saved = readJson(path.join(dir, SUBAGENTS_CURSOR_FILE), null);
|
||||
if (!saved || !isCount(saved.revision) || !CURSOR_STATES.has(saved.state)) return { revision: 0, state: "none" };
|
||||
return { revision: saved.revision, state: saved.state };
|
||||
}
|
||||
|
||||
// Single-writer rule: only console.mjs may call this. Never backwards, like
|
||||
// writeWorkspaceCursor(): a killed `wait` may repeat a change, never skip one.
|
||||
export function writeSubagentCursor(dir, cursor) {
|
||||
const old = readSubagentCursor(dir);
|
||||
const next = cursor.revision < old.revision ? old : { revision: cursor.revision, state: cursor.state };
|
||||
writeJsonAtomic(path.join(dir, SUBAGENTS_CURSOR_FILE), next);
|
||||
}
|
||||
|
||||
// The one place the cursor may go back: `open`, which starts a fresh agent.
|
||||
export function resetSubagentCursor(dir) {
|
||||
writeJsonAtomic(path.join(dir, SUBAGENTS_CURSOR_FILE), { revision: 0, state: "none" });
|
||||
}
|
||||
|
||||
// The `caps` of the last `open` event: what the agent's console copy can do.
|
||||
export function latestOpenCaps(dir) {
|
||||
const opens = readJsonLines(path.join(dir, "events.ndjson")).filter((e) => e.type === "open");
|
||||
const last = opens[opens.length - 1];
|
||||
return last && Array.isArray(last.caps) ? last.caps : [];
|
||||
}
|
||||
|
||||
/**
|
||||
* Flag the case where the link cannot be opened by the person it is for.
|
||||
*
|
||||
|
||||
@@ -208,6 +208,26 @@ body {
|
||||
.stop-btn:hover:not(:disabled) { color: var(--warn); border-color: var(--warn); }
|
||||
.brief-btn:hover:not(:disabled) { color: var(--accent); border-color: var(--accent-line); }
|
||||
|
||||
/* Subagents: an orchestrator and its helpers. Unlit is a hollow outline in
|
||||
the quiet ink; lit fills the nodes with the highlight color. */
|
||||
.subagents-btn { border-color: var(--rule-2); color: var(--ink-2); display: inline-flex; align-items: center; justify-content: center; }
|
||||
.btn.subagents-btn { padding: 0 6px; align-self: stretch; }
|
||||
.subagents-btn[hidden] { display: none; }
|
||||
.subagents-btn svg { width: 16px; height: 16px; display: block; }
|
||||
.subagents-btn .sa-link { fill: none; stroke: var(--ink-2); stroke-width: 1.2; stroke-linecap: round; }
|
||||
.subagents-btn .sa-hub { fill: none; stroke: var(--ink-2); stroke-width: 1.4; }
|
||||
.subagents-btn .sa-node { fill: none; stroke: var(--ink-2); stroke-width: 1.2; }
|
||||
.subagents-btn[aria-pressed="true"] .sa-hub,
|
||||
.subagents-btn[aria-pressed="true"] .sa-node { fill: var(--accent); stroke: var(--accent); }
|
||||
.subagents-btn[aria-pressed="true"] .sa-link { stroke: var(--accent); }
|
||||
.subagents-btn:hover:not(:disabled) { color: var(--accent); border-color: var(--accent-line); }
|
||||
.subagents-btn:hover:not(:disabled) .sa-link,
|
||||
.subagents-btn:hover:not(:disabled) .sa-hub,
|
||||
.subagents-btn:hover:not(:disabled) .sa-node { stroke: var(--accent); }
|
||||
.subagents-btn:disabled .sa-link,
|
||||
.subagents-btn:disabled .sa-hub,
|
||||
.subagents-btn:disabled .sa-node { stroke: var(--ink-3); fill: none; }
|
||||
|
||||
.ident { display: flex; align-items: baseline; gap: 12px; min-width: 0; }
|
||||
|
||||
/* The session meter: a ring that fills with the points and a few words, in
|
||||
@@ -1430,6 +1450,30 @@ h1 {
|
||||
.pill.done { background: var(--ok-soft); color: var(--ok); }
|
||||
.pill.staged { background: var(--stage-soft); color: var(--stage); }
|
||||
|
||||
/* The Subagents tab: one row per reported helper, newest state in a pill. */
|
||||
.sa-card h2 { margin: 0 0 6px; }
|
||||
.sa-card > .help { margin: 0 0 16px; }
|
||||
.sa-alone { margin: 0; color: var(--ink-2); }
|
||||
.sa-list { list-style: none; margin: 0; padding: 0; display: grid; gap: 10px; }
|
||||
.sa-row { border: 1px solid var(--rule); border-radius: 8px; background: var(--panel-2); padding: 12px 14px; }
|
||||
.sa-head { display: flex; align-items: center; justify-content: space-between; gap: 10px; }
|
||||
.sa-title { min-width: 0; overflow-wrap: anywhere; }
|
||||
.sa-ask {
|
||||
margin: 4px 0 0; color: var(--ink-2); font-size: 13.5px;
|
||||
display: -webkit-box; -webkit-box-orient: vertical; -webkit-line-clamp: 2; line-clamp: 2; overflow: hidden;
|
||||
}
|
||||
.sa-result { margin: 8px 0 0; padding-top: 8px; border-top: 1px solid var(--rule); font-size: 13.5px; }
|
||||
.sa-pill { display: inline-flex; align-items: center; gap: 6px; flex: none; }
|
||||
.sa-pill.is-running { background: var(--accent-soft); color: var(--accent); border-color: var(--accent-line); }
|
||||
.sa-pill.is-done { background: var(--ok-soft); color: var(--ok); }
|
||||
.sa-pill.is-failed { background: var(--warn-soft); color: var(--warn); }
|
||||
.sa-pill .spinner.tiny { width: 10px; height: 10px; }
|
||||
/* The dialog's number box, themed like the page's other inputs. */
|
||||
.subagents input[type="number"] {
|
||||
width: 5em; font: inherit; color: var(--ink); background: var(--panel-2);
|
||||
border: 1px solid var(--rule-2); border-radius: 6px; padding: 4px 8px;
|
||||
}
|
||||
|
||||
/* ------------------------------------------------------ settled answer */
|
||||
|
||||
.answered {
|
||||
@@ -1971,6 +2015,8 @@ h4.md-h, h5.md-h, h6.md-h { font-size: 15px; }
|
||||
cursor: pointer;
|
||||
}
|
||||
.footer-where:hover { text-decoration: underline; }
|
||||
/* The project name, in the person's highlight color. */
|
||||
.where-project { color: var(--accent); font-weight: 600; }
|
||||
/* A folder is missing or the agent could not read one: the dialog says which. */
|
||||
.where-alert {
|
||||
display: inline-block; width: 7px; height: 7px; margin-left: 6px;
|
||||
|
||||
@@ -103,6 +103,15 @@ import { FOOTER_TIERS, footerLabel, nameProblem } from "./workspace.js";
|
||||
import { RED_BANNER } from "./meter.js";
|
||||
import { applyMention, matchNames, mentionAt } from "./mentions.js";
|
||||
import { faviconState, setFavicon } from "./favicon.js";
|
||||
import {
|
||||
CHECKIN_LINE,
|
||||
PATHFINDER_RESEARCH_LINE,
|
||||
defaultInstruction,
|
||||
helperRows,
|
||||
showSwitch,
|
||||
showTab,
|
||||
switchLabel,
|
||||
} from "./subagents.js";
|
||||
|
||||
const $ = (id) => document.getElementById(id);
|
||||
|
||||
@@ -530,6 +539,9 @@ let meterFrame = null;
|
||||
// The frame's update ({ installed, latest }), present only when a newer
|
||||
// release is out; null otherwise.
|
||||
let updateFrame = null;
|
||||
// The frame's Subagents switch ({ offered, supported, on, instruction, max,
|
||||
// revision }), or null before a server that sends it.
|
||||
let subagentsFrame = null;
|
||||
let chatDot = false;
|
||||
let chatSending = false;
|
||||
let chatResetting = false;
|
||||
@@ -880,6 +892,8 @@ function adopt(body) {
|
||||
if (body.meter) meterFrame = body.meter;
|
||||
// Always replaced: an absent key means no update.
|
||||
updateFrame = body.update || null;
|
||||
// Always replaced too: an older server sends none, and then there is no switch.
|
||||
subagentsFrame = body.subagents || null;
|
||||
lastContact = Date.now();
|
||||
if (gone) {
|
||||
gone = false;
|
||||
@@ -1301,6 +1315,7 @@ function render() {
|
||||
renderChrome();
|
||||
renderStatus();
|
||||
renderBriefButton();
|
||||
renderSubagentsButton();
|
||||
renderStopButton();
|
||||
renderHomeButton();
|
||||
tabAdded = renderViews();
|
||||
@@ -1566,7 +1581,7 @@ function renderChrome() {
|
||||
renderMeter();
|
||||
$("title").textContent = S.title || "Session";
|
||||
$("badge").textContent = workflowLabel(S.workflow);
|
||||
document.title = (S.title || "Session") + " · #" + String(S.sid || "").slice(-6) + " · Plan2Code";
|
||||
renderTabTitle();
|
||||
|
||||
const h = S.headline || {};
|
||||
// On a finished session an open item is frozen: the send on it counts as
|
||||
@@ -1835,6 +1850,69 @@ function renderBriefButton() {
|
||||
if (offer) btn.disabled = gone || pendingResult;
|
||||
}
|
||||
|
||||
// Shown only where the skill opts in and the agent's console copy can deliver
|
||||
// it. Lit while helpers are on; a click opens the dialog, never toggles.
|
||||
function renderSubagentsButton() {
|
||||
const btn = $("btn-subagents");
|
||||
const offer = showSwitch(subagentsFrame);
|
||||
btn.hidden = !offer;
|
||||
if (!offer) return;
|
||||
const label = switchLabel(subagentsFrame);
|
||||
btn.setAttribute("aria-pressed", String(Boolean(subagentsFrame.on)));
|
||||
btn.title = label;
|
||||
btn.setAttribute("aria-label", label);
|
||||
btn.disabled = gone;
|
||||
}
|
||||
|
||||
// The Subagents dialog, filled from the frame each time it opens. A null
|
||||
// instruction is the shipped default, shown as its text so it can be edited.
|
||||
function openSubagents() {
|
||||
if (!showSwitch(subagentsFrame)) return;
|
||||
const on = Boolean(subagentsFrame.on);
|
||||
for (const radio of document.querySelectorAll('input[name="subagents-on"]')) {
|
||||
radio.checked = radio.value === (on ? "on" : "off");
|
||||
}
|
||||
$("subagents-instruction").value = subagentsFrame.instruction ?? defaultInstruction(S.workflow);
|
||||
$("subagents-max").value = String(subagentsFrame.max);
|
||||
$("subagents-checkin").textContent = CHECKIN_LINE;
|
||||
const research = $("subagents-research");
|
||||
research.textContent = PATHFINDER_RESEARCH_LINE;
|
||||
research.hidden = S.workflow !== "pathfinder";
|
||||
$("subagents-status").textContent = "";
|
||||
$("subagents-save").disabled = false;
|
||||
$("subagents-modal").showModal();
|
||||
const checked = document.querySelector('input[name="subagents-on"]:checked');
|
||||
if (checked) checked.focus();
|
||||
}
|
||||
|
||||
const SUBAGENTS_ERRORS = {
|
||||
max: "Pick a number from 1 to 20.",
|
||||
"too-long": "The instruction is over 2,000 characters.",
|
||||
"not-offered": "This skill doesn't use helpers.",
|
||||
bad: "That didn't save. Try again.",
|
||||
};
|
||||
const SUBAGENTS_LOST = "Lost contact with Plan2Code. Try again once it's back.";
|
||||
|
||||
async function saveSubagents() {
|
||||
const save = $("subagents-save");
|
||||
const status = $("subagents-status");
|
||||
const picked = document.querySelector('input[name="subagents-on"]:checked');
|
||||
const text = $("subagents-instruction").value.trim();
|
||||
// The shipped default is stored as null, so a later release's wording
|
||||
// reaches everyone who never changed it.
|
||||
const instruction = text === defaultInstruction(S.workflow) ? null : text;
|
||||
const body = { on: Boolean(picked && picked.value === "on"), instruction, max: Number($("subagents-max").value) };
|
||||
save.disabled = true;
|
||||
status.textContent = "";
|
||||
const res = await postJson("/subagents", body);
|
||||
save.disabled = false;
|
||||
// The next state frame redraws the button.
|
||||
if (res.status === 200) return $("subagents-modal").close();
|
||||
if (res.status === 400) status.textContent = SUBAGENTS_ERRORS[res.body && res.body.error] || SUBAGENTS_ERRORS.bad;
|
||||
else if (res.status === 403 || res.status === 0) status.textContent = SUBAGENTS_LOST;
|
||||
else status.textContent = SUBAGENTS_ERRORS.bad;
|
||||
}
|
||||
|
||||
function renderViews() {
|
||||
const nav = $("views");
|
||||
nav.replaceChildren();
|
||||
@@ -1850,6 +1928,14 @@ function renderViews() {
|
||||
if (hasOverview) tabs.push({ id: "overview", label: "Overview", count: 0 });
|
||||
else if (view === "overview") view = "questions";
|
||||
for (const d of docs()) tabs.push({ id: "doc:" + d.id, label: d.title || "Document", count: 0 });
|
||||
// The helpers the agent reported, from the first one on; cleared by a
|
||||
// dashboard hop, which sends the person home like the Overview tab does.
|
||||
if (showTab(subagentsFrame, S.helpers)) {
|
||||
// From the rows the tab draws, so the badge never counts helpers the
|
||||
// working-alone note hides.
|
||||
const running = helperRows(S.helpers).rows.filter((r) => r.state === "running").length;
|
||||
tabs.push({ id: "subagents", label: "Subagents", count: running });
|
||||
} else if (view === "subagents") view = "questions";
|
||||
// Always last, on every workflow and after a finish: the Quick question chat.
|
||||
// The ring left of "Ask" shows exactly when the conversation's own ring does:
|
||||
// a question the agent picked up and has not answered yet.
|
||||
@@ -2130,6 +2216,7 @@ function paintMain(main) {
|
||||
if (view.startsWith("doc:")) return renderDoc(main, view.slice(4));
|
||||
if (view === "overview") return renderOverview(main);
|
||||
if (view === "ask") return renderAsk(main);
|
||||
if (view === "subagents") return renderSubagents(main);
|
||||
|
||||
// The session's own page, reached from the PAUSED / SESSION ENDED item at
|
||||
// the top of the rail. The hand-off lives here alone now, rather than
|
||||
@@ -4774,6 +4861,42 @@ function renderOverview(main) {
|
||||
main.appendChild(box);
|
||||
}
|
||||
|
||||
// The helpers the agent reported, as it last posted them. Everything here is
|
||||
// the agent's text, so it goes in as text, never as markup.
|
||||
function renderSubagents(main) {
|
||||
const card = el("section", "card sa-card");
|
||||
card.appendChild(el("h2", null, "Subagents"));
|
||||
card.appendChild(el("p", "help", CHECKIN_LINE));
|
||||
const { alone, rows } = helperRows(S.helpers);
|
||||
if (alone) {
|
||||
card.appendChild(
|
||||
el("p", "sa-alone", "Working alone: your agent has no way to start helpers here, so it is doing this skill's work itself.")
|
||||
);
|
||||
main.appendChild(card);
|
||||
return;
|
||||
}
|
||||
const list = el("ul", "sa-list");
|
||||
for (const row of rows) {
|
||||
const item = el("li", "sa-row");
|
||||
const head = el("div", "sa-head");
|
||||
head.appendChild(el("strong", "sa-title", row.title));
|
||||
const pill = el("span", "pill sa-pill is-" + row.state);
|
||||
if (row.state === "running") {
|
||||
const spin = el("span", "spinner tiny");
|
||||
spin.setAttribute("aria-hidden", "true");
|
||||
pill.appendChild(spin);
|
||||
}
|
||||
pill.appendChild(document.createTextNode(row.stateLabel));
|
||||
head.appendChild(pill);
|
||||
item.appendChild(head);
|
||||
item.appendChild(el("p", "sa-ask", row.ask));
|
||||
if (row.result) item.appendChild(el("p", "sa-result", row.result));
|
||||
list.appendChild(item);
|
||||
}
|
||||
card.appendChild(list);
|
||||
main.appendChild(card);
|
||||
}
|
||||
|
||||
/* ---------------------------------------------------------------- ask */
|
||||
|
||||
// The frame's chat block, with `offline` worked out now rather than when the
|
||||
@@ -5956,10 +6079,30 @@ const workspaceFolders = () => (wsFrame && Array.isArray(wsFrame.folders) ? wsFr
|
||||
// session opened before the server wrote `worktree` has nothing to show, so
|
||||
// the slot stays hidden. The footer renders on every tick, so the DOM is only
|
||||
// touched when the labels change, or when a resize clears the key.
|
||||
// The project's name: the workspace's original folder, or the session's
|
||||
// worktree folder before a frame carries the workspace.
|
||||
function projectName() {
|
||||
const folders = workspaceFolders();
|
||||
if (folders.length && folders[0].name) return folders[0].name;
|
||||
const path = (S && S.worktree) || "";
|
||||
return path ? path.split(/[\\/]/).filter(Boolean).pop() || path : "";
|
||||
}
|
||||
|
||||
// The browser tab's title, led by the project so tabs from different
|
||||
// projects are told apart. Called from the chrome and the footer, since the
|
||||
// workspace frame can arrive after either.
|
||||
function renderTabTitle() {
|
||||
if (!S) return;
|
||||
const name = projectName();
|
||||
document.title =
|
||||
(name ? name + " · " : "") + (S.title || "Session") + " · #" + String(S.sid || "").slice(-6) + " · Plan2Code";
|
||||
}
|
||||
|
||||
function renderWhere() {
|
||||
const b = $("footer-where");
|
||||
const folders = workspaceFolders();
|
||||
const path = S.worktree || "";
|
||||
renderTabTitle();
|
||||
const alert = Boolean(folders.length && ((wsFrame.missing || []).length || (wsFrame.issues || []).length));
|
||||
const labels = folders.length
|
||||
? Array.from({ length: FOOTER_TIERS }, (_, tier) => footerLabel({ folders, branch: S.branch }, tier))
|
||||
@@ -5972,7 +6115,16 @@ function renderWhere() {
|
||||
let label = labels[0];
|
||||
for (const text of labels) {
|
||||
label = text;
|
||||
b.textContent = text;
|
||||
// The project name takes the highlight color, so several consoles side by
|
||||
// side tell apart at a glance; the rest of the label stays quiet.
|
||||
const name = projectName();
|
||||
b.textContent = "";
|
||||
if (name && text.startsWith(name)) {
|
||||
b.appendChild(el("span", "where-project", name));
|
||||
b.appendChild(document.createTextNode(text.slice(name.length)));
|
||||
} else {
|
||||
b.textContent = text;
|
||||
}
|
||||
if (alert) {
|
||||
const dot = el("span", "where-alert");
|
||||
dot.setAttribute("aria-hidden", "true");
|
||||
@@ -7197,6 +7349,7 @@ function lightDismiss(dlg) {
|
||||
});
|
||||
}
|
||||
lightDismiss($("looks-modal"));
|
||||
lightDismiss($("subagents-modal"));
|
||||
lightDismiss($("help-modal"));
|
||||
lightDismiss($("workspace-modal"));
|
||||
lightDismiss($("welcome-modal"));
|
||||
@@ -7499,6 +7652,13 @@ $("cleanup-scan").addEventListener("click", scanCleanup);
|
||||
$("cleanup-delete").addEventListener("click", deleteCleanup);
|
||||
|
||||
$("btn-brief").addEventListener("click", openBrief);
|
||||
$("btn-subagents").addEventListener("click", openSubagents);
|
||||
$("subagents-default").addEventListener("click", () => {
|
||||
$("subagents-instruction").value = defaultInstruction(S.workflow);
|
||||
});
|
||||
$("subagents-save").addEventListener("click", saveSubagents);
|
||||
$("subagents-cancel").addEventListener("click", () => $("subagents-modal").close());
|
||||
$("subagents-modal").addEventListener("close", () => $("btn-subagents").focus());
|
||||
$("brief-cancel").addEventListener("click", () => $("brief-modal").close());
|
||||
$("brief-go").addEventListener("click", sendBrief);
|
||||
for (const radio of document.querySelectorAll('input[name="brief-range"]')) {
|
||||
|
||||
@@ -19,6 +19,7 @@ export const HELP_TABS = Object.freeze([
|
||||
tab("dashboard", "The dashboard", true),
|
||||
tab("meter", "Session meter", false),
|
||||
tab("build", "Watching a build", false),
|
||||
tab("subagents", "Helpers (subagents)", false),
|
||||
tab("ask", "Ask a quick question", false),
|
||||
tab("finishing", "Stopping and finishing", false),
|
||||
tab("stuck", "When something looks stuck", true),
|
||||
@@ -39,6 +40,7 @@ export function helpTabFor({ view, dashboard, gone, adrift, finished, workflow,
|
||||
if (gone || adrift) return "stuck";
|
||||
if (workspace) return "workspace";
|
||||
if (v === "ask") return "ask";
|
||||
if (v === "subagents") return "subagents";
|
||||
if (dashboard && meterRed) return "meter";
|
||||
if (dashboard) return "dashboard";
|
||||
if (v === "overview" || v.startsWith("doc:")) return "docs";
|
||||
|
||||
@@ -21,6 +21,7 @@
|
||||
<link rel="modulepreload" href="/starters.js" />
|
||||
<link rel="modulepreload" href="/workspace.js" />
|
||||
<link rel="modulepreload" href="/meter.js" />
|
||||
<link rel="modulepreload" href="/subagents.js" />
|
||||
<link rel="modulepreload" href="/mentions.js" />
|
||||
<link rel="modulepreload" href="/favicon.js" />
|
||||
<link rel="modulepreload" href="/vendor/marked.esm.js" />
|
||||
@@ -172,6 +173,18 @@
|
||||
<button type="button" class="btn ghost small brief-btn" id="btn-brief" hidden>
|
||||
Write a brief
|
||||
</button>
|
||||
<!-- Subagents: opted-in skills only. Lit while helpers are on; a click
|
||||
opens the Subagents dialog and never toggles them itself. -->
|
||||
<button type="button" class="btn ghost small subagents-btn" id="btn-subagents" aria-pressed="false" hidden>
|
||||
<!-- An orchestrator and its helpers: one larger node linked to three smaller ones. -->
|
||||
<svg viewBox="0 0 16 16" aria-hidden="true" focusable="false">
|
||||
<path class="sa-link" d="M6.9 6.6L10.9 3.9M7.4 8h3.5M6.9 9.4l4 2.7" />
|
||||
<circle cx="4.6" cy="8" r="2.6" class="sa-hub" />
|
||||
<circle cx="12.4" cy="3" r="1.5" class="sa-node" />
|
||||
<circle cx="12.4" cy="8" r="1.5" class="sa-node" />
|
||||
<circle cx="12.4" cy="13" r="1.5" class="sa-node" />
|
||||
</svg>
|
||||
</button>
|
||||
</div>
|
||||
<div class="views-group">
|
||||
<span class="views-arrow" aria-hidden="true">
|
||||
@@ -580,6 +593,13 @@
|
||||
<rect x="3" y="9" width="18" height="6" rx="3" />
|
||||
<path d="M6 12h7" />
|
||||
</symbol>
|
||||
<symbol id="hi-subagents" viewBox="0 0 24 24" fill="none">
|
||||
<circle cx="7" cy="12" r="3.5" />
|
||||
<circle cx="18" cy="5" r="2" />
|
||||
<circle cx="18" cy="12" r="2" />
|
||||
<circle cx="18" cy="19" r="2" />
|
||||
<path d="M10 10l6-4M10.5 12H16M10 14l6 4" />
|
||||
</symbol>
|
||||
<symbol id="hi-ask" viewBox="0 0 24 24" fill="none">
|
||||
<path d="M4 5h16v11H10l-4 4v-4H4z" />
|
||||
<path d="M8 9.5h8M8 12.5h5" />
|
||||
@@ -1477,7 +1497,61 @@
|
||||
</p>
|
||||
</section>
|
||||
|
||||
<!-- Tab 12: Ask a quick question -->
|
||||
<!-- Tab 12: Helpers (subagents) -->
|
||||
<section class="help-panel" data-tab="subagents">
|
||||
<h3>Helpers (subagents)</h3>
|
||||
<p>
|
||||
On a build, a review and Pathfinder, Plan2Code can hand independent
|
||||
pieces of work to helpers (subagents) while it keeps the conversation
|
||||
with you. The <strong>Subagents</strong> button in the top bar, after
|
||||
Stop session, is lit while helpers are on.
|
||||
</p>
|
||||
<h4>The switch</h4>
|
||||
<ul>
|
||||
<li>
|
||||
Clicking the button opens the <strong>Subagents</strong> dialog; it
|
||||
never switches helpers on or off by itself. Pick <strong>Use
|
||||
helpers</strong> or <strong>Work alone</strong>, edit the instruction
|
||||
Plan2Code follows (<strong>Reset to default</strong> puts the
|
||||
shipped one back), and say how many may run at once.
|
||||
</li>
|
||||
<li>
|
||||
It is off by default and saved for this project and this skill, so
|
||||
the next session of the same skill here starts the same way.
|
||||
</li>
|
||||
<li>
|
||||
The change reaches Plan2Code at its next check-in, as a setting,
|
||||
not as something you typed. How many helpers it can really start is
|
||||
up to your agent; some have no helpers at all.
|
||||
</li>
|
||||
<li>The button only appears on skills that use helpers, and only when Plan2Code can pass the setting on.</li>
|
||||
</ul>
|
||||
<h4>The Subagents tab</h4>
|
||||
<ul>
|
||||
<li>
|
||||
With the first helper, a <strong>Subagents</strong> tab appears before
|
||||
Ask: one row each, with what it was asked, whether it is running, done
|
||||
or failed, and a one-line result at the end. The number on the tab is
|
||||
how many are still running.
|
||||
</li>
|
||||
<li>
|
||||
Helpers report through Plan2Code, so the rows change at its
|
||||
check-ins, not live. The page cannot stop a helper; ask Plan2Code
|
||||
on the Ask tab if one should stop.
|
||||
</li>
|
||||
<li>
|
||||
<strong>Working alone</strong> means your agent has no way to start
|
||||
helpers here, so it is doing the work itself.
|
||||
</li>
|
||||
<li>
|
||||
Pathfinder always uses helpers for its research questions, whatever
|
||||
the switch says, and they show here too.
|
||||
</li>
|
||||
<li>The tab clears when you go back to the dashboard.</li>
|
||||
</ul>
|
||||
</section>
|
||||
|
||||
<!-- Tab 13: Ask a quick question -->
|
||||
<section class="help-panel" data-tab="ask">
|
||||
<h3>Ask a quick question</h3>
|
||||
<p class="help-lead">
|
||||
@@ -1568,7 +1642,7 @@
|
||||
</p>
|
||||
</section>
|
||||
|
||||
<!-- Tab 13: Stopping and finishing -->
|
||||
<!-- Tab 14: Stopping and finishing -->
|
||||
<section class="help-panel" data-tab="finishing">
|
||||
<h3>Stopping and finishing</h3>
|
||||
<p class="help-lead">
|
||||
@@ -1650,7 +1724,7 @@
|
||||
</p>
|
||||
</section>
|
||||
|
||||
<!-- Tab 14: When something looks stuck -->
|
||||
<!-- Tab 15: When something looks stuck -->
|
||||
<section class="help-panel" data-tab="stuck">
|
||||
<h3>When something looks stuck</h3>
|
||||
<p class="help-lead">
|
||||
@@ -1772,7 +1846,7 @@
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<!-- Tab 15: Keyboard and preferences -->
|
||||
<!-- Tab 16: Keyboard and preferences -->
|
||||
<section class="help-panel" data-tab="prefs">
|
||||
<h3>Keyboard and preferences</h3>
|
||||
<p class="help-lead">
|
||||
@@ -1888,7 +1962,7 @@
|
||||
</ul>
|
||||
</section>
|
||||
|
||||
<!-- Tab 16: Privacy and where things are saved -->
|
||||
<!-- Tab 17: Privacy and where things are saved -->
|
||||
<section class="help-panel" data-tab="privacy">
|
||||
<h3>Privacy and where things are saved</h3>
|
||||
<p class="help-lead">
|
||||
@@ -1925,7 +1999,11 @@
|
||||
</li>
|
||||
<li>
|
||||
your role, theme, colors, card width and sounds, in
|
||||
<code>looks.json</code>.
|
||||
<code>looks.json</code>;
|
||||
</li>
|
||||
<li>
|
||||
your Subagents switch for each project and skill, in
|
||||
<code>subagents.json</code>.
|
||||
</li>
|
||||
</ul>
|
||||
<p>
|
||||
@@ -2039,6 +2117,46 @@
|
||||
</div>
|
||||
</dialog>
|
||||
|
||||
<!-- Subagents: the switch for this skill, filled from the frame's
|
||||
`subagents` by app.js and saved through POST /subagents. It borrows
|
||||
the User Preferences dialog's classes, so it needs no dialog styles of
|
||||
its own, only a themed number box. -->
|
||||
<dialog class="modal looks subagents" id="subagents-modal" aria-labelledby="subagents-title">
|
||||
<h2 id="subagents-title">Subagents</h2>
|
||||
<p class="modal-blurb">
|
||||
Let Plan2Code hand independent work to helpers in this skill. Saved for this
|
||||
project and this skill.
|
||||
</p>
|
||||
<fieldset class="modal-ranges looks-row">
|
||||
<legend>Helpers</legend>
|
||||
<label><input type="radio" name="subagents-on" value="on" /> <span>Use helpers</span></label>
|
||||
<label><input type="radio" name="subagents-on" value="off" checked /> <span>Work alone</span></label>
|
||||
</fieldset>
|
||||
<fieldset class="modal-ranges">
|
||||
<legend>Instruction</legend>
|
||||
<textarea id="subagents-instruction" rows="4" maxlength="2000" aria-label="Instruction"></textarea>
|
||||
<div class="models-actions">
|
||||
<button type="button" class="btn small ghost" id="subagents-default">Reset to default</button>
|
||||
<span class="help">Passed to the agent as written, at its next check-in.</span>
|
||||
</div>
|
||||
</fieldset>
|
||||
<fieldset class="modal-ranges">
|
||||
<legend>At most</legend>
|
||||
<label>
|
||||
<input type="number" id="subagents-max" min="1" max="20" step="1" aria-label="At most this many helpers at once" />
|
||||
<span>helpers at once</span>
|
||||
</label>
|
||||
<p class="help">Advisory: your agent's own limit still applies.</p>
|
||||
</fieldset>
|
||||
<p class="help" id="subagents-checkin"></p>
|
||||
<p class="help" id="subagents-research" hidden></p>
|
||||
<p class="help" id="subagents-status" role="status"></p>
|
||||
<div class="modal-actions">
|
||||
<button type="button" class="btn ghost" id="subagents-cancel">Cancel</button>
|
||||
<button type="button" class="btn primary" id="subagents-save">Save</button>
|
||||
</div>
|
||||
</dialog>
|
||||
|
||||
<!-- The Workspace: the folder this session started in plus any added as
|
||||
context. The list is drawn by app.js from the frame's `workspace`;
|
||||
every change goes through the server's /workspace routes. -->
|
||||
|
||||
@@ -0,0 +1,223 @@
|
||||
// Plan2Code Web Console - the Subagents switch's opt-in table, wording and checks.
|
||||
//
|
||||
// The source of truth for which workflows offer the switch, the instruction
|
||||
// each one ships with, the fixed frame every "on" block carries, the exact
|
||||
// lines the agent reads at a pickup (blockFor()), and the house rules for the
|
||||
// helpers an agent reports back (checkHelper()). No DOM access at module scope
|
||||
// and no imports: the server, console.mjs, the page and `node --test` all
|
||||
// import this file.
|
||||
|
||||
// The one place a skill opts in (FR-1). Wording is behaviour-level and names
|
||||
// no harness tool, so any agent can follow it or harmlessly ignore it.
|
||||
export const SUBAGENT_WORKFLOWS = Object.freeze({
|
||||
implement: Object.freeze({
|
||||
instruction:
|
||||
"Hand independent tasks in a phase to helpers: tasks that touch different files and do not depend on each other. Keep tasks that share files, the phase's tests and the sign-off with you.",
|
||||
}),
|
||||
"implement-review": Object.freeze({
|
||||
instruction:
|
||||
"Hand independent tasks in a phase to helpers: tasks that touch different files and do not depend on each other. Keep tasks that share files, the phase's tests and the sign-off with you.",
|
||||
}),
|
||||
"quick-task": Object.freeze({
|
||||
instruction:
|
||||
"Use helpers for side lookups, such as reading unfamiliar code or checking documentation, while you make the change yourself.",
|
||||
}),
|
||||
review: Object.freeze({
|
||||
instruction:
|
||||
"Split the review across helpers by area (for example correctness, tests and security), then merge and de-duplicate their findings yourself before you report.",
|
||||
}),
|
||||
pathfinder: Object.freeze({
|
||||
instruction:
|
||||
"Use helpers for codebase recon, sketches and lookups beside the conversation. Keep every question for the person with you.",
|
||||
}),
|
||||
});
|
||||
|
||||
export function offered(workflow) {
|
||||
return typeof workflow === "string" && Object.prototype.hasOwnProperty.call(SUBAGENT_WORKFLOWS, workflow);
|
||||
}
|
||||
|
||||
export const MAX_MIN = 1;
|
||||
export const MAX_MAX = 20;
|
||||
export const DEFAULT_MAX = 3;
|
||||
export const INSTRUCTION_MAX_CHARS = 2000;
|
||||
export const HELPER_TITLE_MAX = 80;
|
||||
export const HELPER_ASK_MAX = 400;
|
||||
export const HELPER_RESULT_MAX = 200;
|
||||
export const HELPER_STATES = Object.freeze(["running", "done", "failed"]);
|
||||
|
||||
/* ------------------------------------------------------------- settings */
|
||||
|
||||
export function defaultInstruction(workflow) {
|
||||
return offered(workflow) ? SUBAGENT_WORKFLOWS[workflow].instruction : "";
|
||||
}
|
||||
|
||||
// The person's own text when they wrote some, else the workflow's default.
|
||||
export function effectiveInstruction(setting) {
|
||||
const own = setting && typeof setting.instruction === "string" ? setting.instruction.trim() : "";
|
||||
return own || defaultInstruction(setting && setting.workflow);
|
||||
}
|
||||
|
||||
export function defaultSetting(workflow) {
|
||||
return { workflow, on: false, instruction: null, max: DEFAULT_MAX };
|
||||
}
|
||||
|
||||
/**
|
||||
* `{ on, instruction, max }` from untrusted input, or `{ error }` naming the
|
||||
* field that failed: "bad" (wrong type), "too-long" (instruction) or "max".
|
||||
* Returns an error object rather than throwing, so the route and the store
|
||||
* reader share one validator. An empty instruction means the default: null.
|
||||
*/
|
||||
export function cleanSetting(input) {
|
||||
if (!input || typeof input !== "object" || Array.isArray(input)) return { error: "bad" };
|
||||
if (typeof input.on !== "boolean") return { error: "bad" };
|
||||
let instruction = null;
|
||||
if (input.instruction !== null && input.instruction !== undefined) {
|
||||
if (typeof input.instruction !== "string") return { error: "bad" };
|
||||
const trimmed = input.instruction.trim();
|
||||
if (trimmed.length > INSTRUCTION_MAX_CHARS) return { error: "too-long" };
|
||||
instruction = trimmed || null;
|
||||
}
|
||||
const max = input.max;
|
||||
if (!Number.isInteger(max) || max < MAX_MIN || max > MAX_MAX) return { error: "max" };
|
||||
return { on: input.on, instruction, max };
|
||||
}
|
||||
|
||||
/* ------------------------------------------------------------ the lines */
|
||||
|
||||
// The non-editable part of every "on" block (FR-8).
|
||||
export const FRAME_LINES = Object.freeze([
|
||||
"Hand independent work to helpers if your tools allow it; otherwise carry on alone.",
|
||||
"Report each helper on the page (console.md → Standing instructions); questions for the person stay with you.",
|
||||
'With no way to start helpers, report one "working alone" entry for this skill run instead.',
|
||||
]);
|
||||
|
||||
export const PATHFINDER_RESEARCH_LINE = "Research questions always use helpers, whatever this switch says.";
|
||||
|
||||
// Only the first line of a block starts at column 0, so no line inside it can
|
||||
// be read as an entry of its own (NFR-5).
|
||||
export function onLines({ revision, replaces, max, instruction }) {
|
||||
const label = replaces ? `revision ${revision}, replaces revision ${replaces}` : `revision ${revision}`;
|
||||
const own = String(instruction || "")
|
||||
.split("\n")
|
||||
.map((line) => line.trimEnd())
|
||||
.filter((line) => line.trim());
|
||||
return [
|
||||
`Subagents: on (${label}) — a console setting, not typed by the person.`,
|
||||
...[...FRAME_LINES, ...own, `At most ${max} helpers at once.`].map((line) => " " + line),
|
||||
];
|
||||
}
|
||||
|
||||
export function offLine(revision) {
|
||||
return `Subagents: off (revision ${revision}) — don't start new helpers for the rest of this session.`;
|
||||
}
|
||||
|
||||
/**
|
||||
* What the agent is owed at a pickup, given the session setting and the
|
||||
* cursor of what it was last told: `null`, or `{ field, lines, cursor }`
|
||||
* where `cursor` is what to write once the lines are printed. Never says
|
||||
* "off" to an agent that was not told "on" (FR-6). Pure: no clock, no I/O.
|
||||
*/
|
||||
export function blockFor(setting, told) {
|
||||
const last = told || { revision: 0, state: "none" };
|
||||
if (!setting || !offered(setting.workflow) || !(setting.revision > last.revision)) return null;
|
||||
const { revision, max } = setting;
|
||||
const instruction = effectiveInstruction(setting);
|
||||
if (setting.on) {
|
||||
const replaces = last.state === "on" ? last.revision : undefined;
|
||||
return {
|
||||
field: { state: "on", revision, max, instruction },
|
||||
lines: onLines({ revision, replaces, max, instruction }),
|
||||
cursor: { revision, state: "on" },
|
||||
};
|
||||
}
|
||||
if (last.state !== "on") return null;
|
||||
return {
|
||||
field: { state: "off", revision, max, instruction },
|
||||
lines: [offLine(revision)],
|
||||
cursor: { revision, state: "off" },
|
||||
};
|
||||
}
|
||||
|
||||
/* ------------------------------------------------------------ helpers */
|
||||
|
||||
const isPlainObject = (v) => !!v && typeof v === "object" && !Array.isArray(v);
|
||||
const nonEmpty = (v) => typeof v === "string" && v.trim() !== "";
|
||||
|
||||
// The problems with one reported helper, [] when it is fine.
|
||||
export function checkHelper(entry) {
|
||||
if (!isPlainObject(entry)) return ["helper: each entry must be an object"];
|
||||
if (!nonEmpty(entry.id)) return ["helper: id must be a non-empty string"];
|
||||
const who = `helper "${entry.id}"`;
|
||||
if (entry.alone === true) return entry.id === "alone" ? [] : [`${who}: the working-alone entry must have id "alone"`];
|
||||
const problems = [];
|
||||
if (!nonEmpty(entry.title)) problems.push(`${who}: title must be a non-empty string`);
|
||||
else if (entry.title.length > HELPER_TITLE_MAX) problems.push(`${who}: title must be at most ${HELPER_TITLE_MAX} characters`);
|
||||
if (!nonEmpty(entry.ask)) problems.push(`${who}: ask must be a non-empty string`);
|
||||
else if (entry.ask.length > HELPER_ASK_MAX) problems.push(`${who}: ask must be at most ${HELPER_ASK_MAX} characters`);
|
||||
if (!HELPER_STATES.includes(entry.state)) problems.push(`${who}: state must be running, done or failed`);
|
||||
if (entry.result !== undefined) {
|
||||
if (typeof entry.result !== "string") problems.push(`${who}: result must be a string`);
|
||||
else if (entry.result.length > HELPER_RESULT_MAX) problems.push(`${who}: result must be at most ${HELPER_RESULT_MAX} characters`);
|
||||
}
|
||||
return problems;
|
||||
}
|
||||
|
||||
// The problems with a whole merged list.
|
||||
export function checkHelpers(list) {
|
||||
if (!Array.isArray(list)) return ["helpers must be an array"];
|
||||
const problems = [];
|
||||
const seen = new Set();
|
||||
let alone = 0;
|
||||
for (const entry of list) {
|
||||
if (isPlainObject(entry) && nonEmpty(entry.id)) {
|
||||
if (seen.has(entry.id)) problems.push(`helper "${entry.id}": duplicate id`);
|
||||
seen.add(entry.id);
|
||||
if (entry.alone === true && ++alone === 2) problems.push(`helper "${entry.id}": only one working-alone entry is allowed`);
|
||||
}
|
||||
problems.push(...checkHelper(entry));
|
||||
}
|
||||
return problems;
|
||||
}
|
||||
|
||||
/* ------------------------------------------------------------ the page */
|
||||
|
||||
// The page's rules for the button, the modal and the tab, kept here so they
|
||||
// are tested without a browser. `frame` is the state frame's `subagents`
|
||||
// block; app.js only renders what these say.
|
||||
|
||||
export const CHECKIN_LINE = "Helpers report through Plan2Code, so their progress shows here at its check-ins, not live.";
|
||||
|
||||
const STATE_LABELS = Object.freeze({ running: "Running", done: "Done", failed: "Failed" });
|
||||
|
||||
// The switch shows only where the skill opts in AND the agent's console copy
|
||||
// said it can deliver it (FR-3).
|
||||
export function showSwitch(frame) {
|
||||
return Boolean(frame && frame.offered && frame.supported);
|
||||
}
|
||||
|
||||
// The button's tooltip and accessible name (FR-2).
|
||||
export function switchLabel(frame) {
|
||||
return frame && frame.on ? "Subagents: on" : "Subagents: off";
|
||||
}
|
||||
|
||||
// What the Subagents tab draws: the working-alone note, or one row per helper
|
||||
// in the order the agent reported them. A result shows once the helper ended.
|
||||
export function helperRows(helpers) {
|
||||
const list = Array.isArray(helpers) ? helpers.filter(isPlainObject) : [];
|
||||
if (list.some((h) => h.alone === true)) return { alone: true, rows: [] };
|
||||
const rows = list.map(({ id, title, ask, state, result }) => ({
|
||||
id,
|
||||
title,
|
||||
ask,
|
||||
state,
|
||||
stateLabel: STATE_LABELS[state] || STATE_LABELS.running,
|
||||
...((state === "done" || state === "failed") && typeof result === "string" && result ? { result } : {}),
|
||||
}));
|
||||
return { alone: false, rows };
|
||||
}
|
||||
|
||||
// Never an empty tab. Independent of on / off, so Pathfinder's research
|
||||
// helpers show even with the switch off (FR-11, FR-12).
|
||||
export function showTab(frame, helpers) {
|
||||
return showSwitch(frame) && Array.isArray(helpers) && helpers.length > 0;
|
||||
}
|
||||
@@ -25,6 +25,7 @@ import {
|
||||
LOOKS_FILE,
|
||||
PUBLIC_DIR,
|
||||
SHIPPED_MODELS_FILE,
|
||||
SUBAGENTS_SETTING_FILE,
|
||||
UPDATE_CHECK_FILE,
|
||||
USER_MODELS_FILE,
|
||||
WORKSPACE_FILE,
|
||||
@@ -38,6 +39,7 @@ import {
|
||||
fileStamp,
|
||||
handleFile,
|
||||
initialWorkspace,
|
||||
latestOpenCaps,
|
||||
nowIso,
|
||||
parseArgs,
|
||||
pendingChatCount,
|
||||
@@ -46,20 +48,25 @@ import {
|
||||
readJson,
|
||||
readLedger,
|
||||
readOverview,
|
||||
readSubagentSetting,
|
||||
readWorkspace,
|
||||
rememberWorkspace,
|
||||
rememberedWorkspace,
|
||||
removeCleanup,
|
||||
remoteWarning,
|
||||
saveSubagentStoreEntry,
|
||||
specKey,
|
||||
subagentStoreEntry,
|
||||
typedCount,
|
||||
withStateLock,
|
||||
writeJsonAtomic,
|
||||
writeSubagentSetting,
|
||||
writeWorkspace,
|
||||
} from "./lib.mjs";
|
||||
import { DOC_TYPES, MAX_ATTACHMENTS, MAX_DOC_BYTES, docExt, workflowLabel, workflowTitle } from "./public/answers.js";
|
||||
import { CHAT_LIMIT, CHAT_MAX_CHARS, chatOffline } from "./public/chat.js";
|
||||
import { meterView } from "./public/meter.js";
|
||||
import { cleanSetting, defaultSetting, offered } from "./public/subagents.js";
|
||||
import { ACCENTS, DEFAULT_ACCENT, DEFAULT_CARD_WIDTH, cardWidth } from "./public/palette.js";
|
||||
import { defaultName, freeName, nameProblem } from "./public/workspace.js";
|
||||
import { checkForUpdate } from "./update-check.mjs";
|
||||
@@ -212,6 +219,7 @@ const SERVABLE = new Set([
|
||||
"starters.js",
|
||||
"workspace.js",
|
||||
"meter.js",
|
||||
"subagents.js",
|
||||
"mentions.js",
|
||||
"favicon.js",
|
||||
"start-stop.mp3",
|
||||
@@ -601,6 +609,48 @@ function ensureConversation(state) {
|
||||
if (entry) appendEvent(DIR, { type: "chat-reset", reason: entry.reason });
|
||||
}
|
||||
|
||||
/* ------------------------------------------------------------ subagents */
|
||||
|
||||
// subagents-setting.json has one writer, this server, and the agent hears of
|
||||
// it only through what console.mjs reads there; events.ndjson's latest `open`
|
||||
// says whether the agent's console copy can carry it. Both re-read only when
|
||||
// their file has moved.
|
||||
const SUBAGENTS_SETTING_PATH = path.join(DIR, SUBAGENTS_SETTING_FILE);
|
||||
const EVENTS_PATH = path.join(DIR, "events.ndjson");
|
||||
|
||||
let subagentSettingSeen = { stamp: null, setting: null };
|
||||
function subagentSettingNow() {
|
||||
const stamp = fileStamp(SUBAGENTS_SETTING_PATH);
|
||||
if (stamp !== subagentSettingSeen.stamp) subagentSettingSeen = { stamp, setting: readSubagentSetting(DIR) };
|
||||
return subagentSettingSeen.setting;
|
||||
}
|
||||
|
||||
let capsSeen = { stamp: null, caps: [] };
|
||||
function openCapsNow() {
|
||||
const stamp = fileStamp(EVENTS_PATH);
|
||||
if (stamp !== capsSeen.stamp) capsSeen = { stamp, caps: latestOpenCaps(DIR) };
|
||||
return capsSeen.caps;
|
||||
}
|
||||
|
||||
const sameSetting = (a, b) => a.workflow === b.workflow && a.on === b.on && a.instruction === b.instruction && a.max === b.max;
|
||||
|
||||
/**
|
||||
* Turn the per-project store into this session's setting, for the workflow
|
||||
* the session is in now. The only place that happens (FR-7): a session an
|
||||
* older server ran has no setting file, so nothing is ever injected into it.
|
||||
* A record that already matches is left alone, revision and all, so a
|
||||
* restart alone never re-tells the agent anything.
|
||||
*/
|
||||
function syncSubagentSetting(state) {
|
||||
if (!state || typeof state.workflow !== "string") return;
|
||||
const { workflow } = state;
|
||||
const { on, instruction, max } = offered(workflow) ? subagentStoreEntry(sessionWorktree(), workflow) : defaultSetting(workflow);
|
||||
const target = { workflow, on, instruction, max };
|
||||
const current = readSubagentSetting(DIR);
|
||||
if (current && sameSetting(current, target)) return;
|
||||
writeSubagentSetting(DIR, { ...target, revision: (current ? current.revision : 0) + 1 });
|
||||
}
|
||||
|
||||
// What the page needs to draw itself, in the shape of the SSE state frame.
|
||||
// `have` names that exact view, for the page to hand back when it opens its
|
||||
// stream (see /events).
|
||||
@@ -615,20 +665,33 @@ function stateFrame(state) {
|
||||
chat: { ...chatForFrame(chatEntries(), state), pickedUp: chatPickedUp(), offline: chatOfflineNow(state) },
|
||||
workspace: workspaceView(),
|
||||
meter: meterView(ledgerEntries()),
|
||||
subagents: subagentsView(state),
|
||||
...(updateInfo ? { update: updateInfo } : {}),
|
||||
have: haveKey(),
|
||||
};
|
||||
}
|
||||
|
||||
// The page shows the switch only when `offered && supported` (FR-3); the
|
||||
// frame says both and leaves combining them to the page. `instruction: null`
|
||||
// is the shipped default, which the page reads from subagents.js itself.
|
||||
function subagentsView(state) {
|
||||
const workflow = state && state.workflow;
|
||||
const { on, instruction, max, revision } = subagentSettingNow() || { ...defaultSetting(workflow), revision: 0 };
|
||||
return { offered: offered(workflow), supported: openCapsNow().includes("subagents"), on, instruction, max, revision };
|
||||
}
|
||||
|
||||
function haveKey() {
|
||||
const { pending, stop } = resultFlags();
|
||||
chatEntries();
|
||||
chatPickedUp();
|
||||
workspaceNow();
|
||||
ledgerEntries();
|
||||
subagentSettingNow();
|
||||
openCapsNow();
|
||||
return (
|
||||
`${STARTED}.${rev}.${pending ? 1 : 0}${stop ? 1 : 0}.${chatSeen.stamp || ""}.${cursorSeen.stamp || ""}` +
|
||||
`.${workspaceSeen.stamp || ""}.${ledgerSeen.stamp || ""}.${updateInfo ? updateInfo.latest : ""}`
|
||||
`.${workspaceSeen.stamp || ""}.${ledgerSeen.stamp || ""}.${updateInfo ? updateInfo.latest : ""}` +
|
||||
`.${subagentSettingSeen.stamp || ""}.${capsSeen.stamp || ""}`
|
||||
);
|
||||
}
|
||||
|
||||
@@ -1172,6 +1235,39 @@ const server = http.createServer((req, res) => {
|
||||
});
|
||||
}
|
||||
|
||||
// The Subagents switch for the session's workflow. Saved per project folder
|
||||
// for the next session, and applied to this one with a bumped revision, which
|
||||
// is what console.mjs hands the agent at its next pickup. Never blocked by,
|
||||
// and never blocking, a card send.
|
||||
if (pathname === "/subagents" && req.method === "POST") {
|
||||
if (!originOk(req, port)) return json(res, 403, { error: "bad origin" });
|
||||
return readBody(req, (err, body) => {
|
||||
if (err) return json(res, err.tooBig ? 413 : 400, { error: err.tooBig ? "too large" : "body must be JSON" });
|
||||
const state = readState();
|
||||
if (!state || !offered(state.workflow)) return json(res, 400, { error: "not-offered" });
|
||||
const clean = cleanSetting(body);
|
||||
if (clean.error) return json(res, 400, { error: clean.error });
|
||||
const { on, instruction, max } = clean;
|
||||
const current = readSubagentSetting(DIR);
|
||||
const next = { workflow: state.workflow, on, instruction, max };
|
||||
// The store is per project, so another session may have moved it since
|
||||
// this one synced: it always takes the person's latest pick. Only a
|
||||
// real change to this session's setting bumps what the agent hears.
|
||||
const unchanged = Boolean(current && sameSetting(current, next));
|
||||
try {
|
||||
saveSubagentStoreEntry(sessionWorktree(), state.workflow, { on, instruction, max });
|
||||
if (!unchanged) writeSubagentSetting(DIR, { ...next, revision: (current ? current.revision : 0) + 1 });
|
||||
} catch (e) {
|
||||
return json(res, 500, { error: String(e.message) });
|
||||
}
|
||||
if (unchanged) return json(res, 200, { ok: true, setting: current });
|
||||
const setting = readSubagentSetting(DIR);
|
||||
appendEvent(DIR, { type: "subagents", on, revision: setting.revision });
|
||||
pushState();
|
||||
return json(res, 200, { ok: true, setting });
|
||||
});
|
||||
}
|
||||
|
||||
// The launcher's model menu: what ships (read-only here) and what the user added.
|
||||
if (pathname === "/models" && req.method === "GET") {
|
||||
const saved = readJson(USER_MODELS_FILE, null) || {};
|
||||
@@ -1400,6 +1496,9 @@ const server = http.createServer((req, res) => {
|
||||
try {
|
||||
ensureConversation(written.state);
|
||||
} catch {}
|
||||
try {
|
||||
syncSubagentSetting(written.state);
|
||||
} catch {}
|
||||
}
|
||||
}
|
||||
// Name the items that went. A page with OTHER answers staged should drop
|
||||
@@ -1726,6 +1825,9 @@ function checkState() {
|
||||
try {
|
||||
ensureConversation(parsed);
|
||||
} catch {}
|
||||
try {
|
||||
syncSubagentSetting(parsed);
|
||||
} catch {}
|
||||
try {
|
||||
followSpecDir(parsed);
|
||||
} catch {}
|
||||
@@ -1900,6 +2002,9 @@ function onListening(port) {
|
||||
try {
|
||||
bootWorkspace();
|
||||
} catch {}
|
||||
try {
|
||||
syncSubagentSetting(readState());
|
||||
} catch {}
|
||||
process.stdout.write(JSON.stringify({ type: "ready", url, port, sid: SID }) + "\n");
|
||||
try {
|
||||
startUpdateCheck();
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "Plan2Code",
|
||||
"version": "2.4.2",
|
||||
"version": "2.5.0",
|
||||
"description": "A structured 4-step workflow methodology for AI-assisted software development",
|
||||
"keywords": [
|
||||
"ai",
|
||||
@@ -17,6 +17,6 @@
|
||||
"url": "https://github.com/jparkerweb/plan2code"
|
||||
},
|
||||
"homepage": "https://github.com/jparkerweb/plan2code",
|
||||
"releaseDate": "2026-10-05",
|
||||
"releaseDate": "2026-10-06",
|
||||
"mode": "utility"
|
||||
}
|
||||
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "Plan2Code",
|
||||
"version": "2.4.2",
|
||||
"version": "2.5.0",
|
||||
"description": "A structured 4-step workflow methodology for AI-assisted software development",
|
||||
"keywords": [
|
||||
"ai",
|
||||
@@ -17,6 +17,6 @@
|
||||
"url": "https://github.com/jparkerweb/plan2code"
|
||||
},
|
||||
"homepage": "https://github.com/jparkerweb/plan2code",
|
||||
"releaseDate": "2026-10-05",
|
||||
"releaseDate": "2026-10-06",
|
||||
"mode": "utility"
|
||||
}
|
||||
@@ -39,10 +39,10 @@ Three levels -- auto-detected, always respect explicit user override:
|
||||
| Scope | Trigger | Reviews |
|
||||
|-------|---------|---------|
|
||||
| **Focused** | User names files/functions, or conversation work detected | Specified files only |
|
||||
| **Branch** | "review my changes" or no context available | Branch changes vs main |
|
||||
| **Branch** | "review my changes", or picked when asked | Branch changes vs main |
|
||||
| **Full** | "full review" or names a subsystem | Entire codebase/subsystem |
|
||||
|
||||
**Detection:** 1) User prompt wins. 2) Conversation context = `focused`. 3) Fallback = `branch`. Ambiguous? Ask.
|
||||
**Detection:** 1) User prompt wins. 2) Conversation context = `focused`. 3) Scope already decided by a host workflow (a build's review, `building.md`) = use it. 4) Standalone with nothing named = scan, then ask (Step 1). Never default to `branch` silently. Ambiguous? Ask.
|
||||
|
||||
**Thoroughness:** Scope controls WHAT is reviewed, not HOW DEEPLY. Every review is thorough.
|
||||
|
||||
@@ -52,7 +52,7 @@ Three levels -- auto-detected, always respect explicit user override:
|
||||
|
||||
## Process
|
||||
|
||||
**Pre-flight:** Check AGENTS.md — use conventions if found, note if missing. Determine review target from user prompt or conversation context. If neither provides clear signal, use `ask_user_question` — never guess.
|
||||
**Pre-flight:** Check AGENTS.md — use conventions if found, note if missing. Determine review target from user prompt or conversation context. If neither provides clear signal, scan and use `ask_user_question` (Step 1) — never guess.
|
||||
|
||||
**Reference files:** Companion files loaded via Read directives. Fallback rules inline if unavailable.
|
||||
|
||||
@@ -62,7 +62,8 @@ Three levels -- auto-detected, always respect explicit user override:
|
||||
|
||||
1. **User prompt** — use it.
|
||||
2. **Conversation context** — recent work? Those artifacts. Scope: `focused`.
|
||||
3. **Git fallback** — run `review-scope.mjs`. It compares the branch with its base (`main`, else `master`; `--base` overrides; `base` says which it used) and adds staged, unstaged and untracked changes: `files` (status, lines), `counts`, `commits`, `mix`, `batchByRisk`. `empty: true`? Ask user. Exit 3 `no-base` (no `main` or `master`, or no such `--base`)? Rerun with `--base <trunk>`, asking the user which branch is the trunk if unclear. Exit 3 `not-a-repo`? Ask user which files to review.
|
||||
3. **Standalone, nothing named** — do not assume a target. Do a quick scan (no file reading): `review-scope.mjs`, `specs.mjs list`, recent commits. Then ask what to review (`ask_user_question`; a `choice` on the console, scope questions up front), offering only options the scan supports, each with its size: the branch's changes vs base (files, ~lines, `commits`), uncommitted changes only (when any), a spec/plan under `specs/` (when any), a named subsystem or full codebase, or specific files/folders (free text via Other). Recommend the likeliest first. Nothing found (`empty: true`, no specs)? Ask for files or a subsystem. Use the answer as the scope, then continue.
|
||||
4. **Scan details** — `review-scope.mjs` compares the branch with its base (`main`, else `master`; `--base` overrides; `base` says which it used) and adds staged, unstaged and untracked changes: `files` (status, lines), `counts`, `commits`, `mix`, `batchByRisk`. `empty: true`? Ask user. Exit 3 `no-base` (no `main` or `master`, or no such `--base`)? Rerun with `--base <trunk>`, asking the user which branch is the trunk if unclear. Exit 3 `not-a-repo`? Ask user which files to review.
|
||||
|
||||
**Classify review type** from context (auto-detect; use `ask_user_question` only if ambiguous):
|
||||
|
||||
|
||||
@@ -64,6 +64,13 @@ progress bar is the first thing someone watching a build looks at. The session
|
||||
meter counts the build's tasks from `cleared` as it rises, so keep it current,
|
||||
and start every phase (a second one in the same run too) at `"cleared": 0`.
|
||||
|
||||
`"version": 1` is for the first phase of a session only. A doc's version
|
||||
never goes back (console.md → House rules, rule 9), so a later phase in the
|
||||
same session reposts `phase` and `phasefile` at one more than the version the
|
||||
page holds, with the new phase's title and content. The same goes for
|
||||
`report` at sign-off and `review` in a mid-session review: version 1 the
|
||||
first time, then up from wherever the page has it.
|
||||
|
||||
`phasefile` is the whole `phase-X.md`, verbatim from disk, as its own tab —
|
||||
the person can read the prerequisites and task specs while you build. Re-post
|
||||
it whenever the file changes, which is every task: the checkbox write that
|
||||
@@ -111,6 +118,12 @@ printed), never into the project or into `~/.plan2code/console/` directly:
|
||||
- Do not call `wait` while building. There is nothing to collect, and the page
|
||||
holds anything the person sends until you next look.
|
||||
|
||||
A build may receive a `Subagents:` standing instruction, on `open` output or a
|
||||
`chat` check between tasks. Follow console.md → Standing instructions for
|
||||
handing independent tasks to helpers and reporting them as `helpers`. Keep the
|
||||
per-task progress posts, the checkbox writes, the chat checks and the sign-off
|
||||
with you.
|
||||
|
||||
### Quick questions between tasks
|
||||
|
||||
The person can ask a Quick question on the Ask tab at any point in a build
|
||||
@@ -195,7 +208,8 @@ only ever be offered once nothing could come of it:
|
||||
`reply` carries `Approve this phase: approved`, which is the terminal's
|
||||
`approved`. If the note that came with an approval asks for a change, treat it
|
||||
as "describe any issues": do the change first and ask again. `changes` means
|
||||
exactly what it says: address it, bump the report's version, and reopen the
|
||||
exactly what it says: address it, bump the report's version (a later phase's
|
||||
report starts above the last one's, too), and reopen the
|
||||
item (`"status": "reopened"`) with a reply in its `thread`. `review` is the
|
||||
person asking for the code review before they approve anything — see "The
|
||||
review, mid-session" below.
|
||||
|
||||
@@ -170,7 +170,7 @@ so even a kill at the worst possible moment costs you a repeat, never an answer.
|
||||
|
||||
| Exit | Meaning | What you do |
|
||||
| --- | --- | --- |
|
||||
| `0` | They pressed Send, or asked a Quick question. stdout is the result JSON, and may carry `workspace` (changes to the folder list, see Workspace). | Handle the cards (if any), the chat (if any) and any `workspace` changes, then post once (below, Quick questions and Workspace). |
|
||||
| `0` | They pressed Send, or asked a Quick question. stdout is the result JSON, and may carry `workspace` (changes to the folder list, see Workspace) and `subagents` (the helpers switch, see Standing instructions). | Handle the cards (if any), the chat (if any), any `workspace` changes and any `subagents` block, then post once (below, Quick questions, Workspace and Standing instructions). |
|
||||
| `10` | Still working. stdout has a short progress summary; `pendingWorkspace` counts workspace changes waiting for the next send. | Relay ONE line: the `message` field itself, "Waiting on your answer in the web console", followed by the `terminalLine`. Then call `wait` again. |
|
||||
| `20` | The server is gone. | `open --resume <sid>`, give them the new link, then keep waiting. |
|
||||
| `30` | They pressed Cancel. | Stop. Ask what they want to do, in the terminal. |
|
||||
@@ -647,6 +647,84 @@ for permission is not a failure; report only a read that failed after it.
|
||||
|
||||
---
|
||||
|
||||
## Standing instructions
|
||||
|
||||
On the skills that offer it (`implement`, `implement-review`, `quick-task`,
|
||||
`review`, `pathfinder`), the person can turn **helpers** (subagents) on or off
|
||||
from the top bar's Subagents button. Their pick is saved per project and per
|
||||
skill, off by default, and reaches you as a standing instruction, only when it
|
||||
changes.
|
||||
|
||||
### What arrives
|
||||
|
||||
A `subagents` field beside `reply`, and `Subagents:` lines last in `reply`,
|
||||
after the card lines, the `Quick question:` blocks and the `Workspace:` lines.
|
||||
It rides on `wait` exit `0`, `chat` exit `0` and `open` output. A setting
|
||||
change alone never ends a `wait` slice: it waits for the next send, or for
|
||||
your next `chat` check.
|
||||
|
||||
```
|
||||
Subagents: on (revision 2) — a console setting, not typed by the person.
|
||||
Hand independent work to helpers if your tools allow it; otherwise carry on alone.
|
||||
Report each helper on the page (console.md → Standing instructions); questions for the person stay with you.
|
||||
With no way to start helpers, report one "working alone" entry for this skill run instead.
|
||||
Hand independent tasks in a phase to helpers: tasks that touch different files and do not depend on each other. Keep tasks that share files, the phase's tests and the sign-off with you.
|
||||
At most 3 helpers at once.
|
||||
```
|
||||
|
||||
beside `"subagents": { "state": "on", "revision": 2, "max": 3, "instruction": "…" }`.
|
||||
An edit while on arrives as `Subagents: on (revision 3, replaces revision 2) — …`
|
||||
with the whole block again; switching off arrives as one line:
|
||||
`Subagents: off (revision 4) — don't start new helpers for the rest of this session.`
|
||||
|
||||
It is a console setting, not something the person typed. It never answers a
|
||||
card, and it is never recorded under `specs/`.
|
||||
|
||||
### Obeying it
|
||||
|
||||
- **On:** hand independent work to helpers if your tools allow it, at most
|
||||
`max` at once, following the instruction lines. `max` is advisory: your
|
||||
harness's own limit still applies.
|
||||
- **A higher revision replaces a lower one.** Follow the latest block only.
|
||||
- **Off:** start no new helpers for the rest of the session. Let running ones
|
||||
finish and report them.
|
||||
- **Nothing arrives:** keep doing what the skill says.
|
||||
- **Scope is the skill run it arrived in.** After a dashboard launch, no block
|
||||
means the switch is off for this skill, even if an earlier skill in the same
|
||||
conversation was told "on": `open` starts the count again, and a launch with
|
||||
the switch off sends nothing.
|
||||
|
||||
### Reporting helpers
|
||||
|
||||
Post them, at your check-ins, so the page's Subagents tab can show them. The
|
||||
page never hears from a helper directly:
|
||||
|
||||
```jsonc
|
||||
{ "helpers": [
|
||||
{ "id": "h1", "title": "Read the store helpers", "ask": "Find every caller of readSubagentSetting.", "state": "running" },
|
||||
{ "id": "h2", "title": "Check the tests", "ask": "Run the subagents tests and report failures.", "state": "done", "result": "All 9 pass." }
|
||||
] }
|
||||
```
|
||||
|
||||
- `id` (non-empty), `title` (at most 80 characters), `ask` (at most 400) and
|
||||
`state` (`running`, `done` or `failed`) are required; `result` (at most 200)
|
||||
is the one line you add once a helper ends.
|
||||
- Merged by `id`: post a helper again with its new `state` and `result` and it
|
||||
updates in place. `"helpers": null` clears the list. A dashboard hop clears it
|
||||
too; a resume into the same skill keeps it.
|
||||
- One post per change worth seeing, not a stream.
|
||||
- Questions for the person stay with you, never with a helper: most harnesses
|
||||
give helpers no way to ask, and an answer only reaches the agent holding the
|
||||
session.
|
||||
- **No way to start helpers?** Post one `{ "id": "alone", "alone": true }`
|
||||
entry for the skill run instead. The tab then says you are working alone.
|
||||
- **Pathfinder:** research questions always use helpers and are always
|
||||
reported, whatever the switch says. The switch governs recon, sketches and
|
||||
lookups beside the conversation.
|
||||
- Helpers add no session meter points. Post no `run` for them.
|
||||
|
||||
---
|
||||
|
||||
## Launches (dashboard only)
|
||||
|
||||
A `dashboard` session is not a conversation: the page draws a menu of every
|
||||
@@ -763,7 +841,10 @@ commands follow the pipeline: the sign-off's is
|
||||
|
||||
### Review (`review`)
|
||||
|
||||
Scope questions up front, then the findings report as a doc (`id: "report"`),
|
||||
Scope questions up front — run standalone with nothing named, the first is
|
||||
a `choice`, "What should I review?", built from a quick scan (branch changes,
|
||||
uncommitted changes, specs, files you name; each option with its size),
|
||||
never an assumed target; a build's review skips it (`building.md`). Then the findings report as a doc (`id: "report"`),
|
||||
then the pick-what-gets-fixed menu as a `multi` or `choice` keyed by finding
|
||||
id, carrying `"doc": "report"` so the card links straight to the findings.
|
||||
Settle that item (`"status": "answered"` plus the `answer` they sent) in
|
||||
@@ -797,6 +878,8 @@ that is what the person is there to download. The finish carries no
|
||||
- Chart Step 8's research subagents must all report back before the
|
||||
finish (Finishing → Nothing of yours may still be running); the finish
|
||||
body then names what each one found.
|
||||
- Report every research subagent as a helper, whatever the Subagents switch
|
||||
says (Standing instructions → Reporting helpers).
|
||||
- At every session end, post `finish` (headline, `body`, and Form A's command as
|
||||
`command`) BEFORE `stop`. Someone who spent the session in the browser never
|
||||
sees the Trail Footer, and without this their last screen promises a question
|
||||
@@ -1146,6 +1229,16 @@ A patch that breaks one of these is rejected with exit `3` and a message:
|
||||
(Session meter) and a non-empty `id`; a `folderIssue` needs non-empty
|
||||
`name` and `reason` strings, and `hint`, when present, is one too. Rules 4
|
||||
and 5 cover `reason` and `hint`.
|
||||
8. **`helpers` entries are well formed** (Standing instructions → Reporting
|
||||
helpers): an array of objects, each with a unique `id`, a `title`, an `ask`
|
||||
and a known `state` within their limits, plus at most one `alone` entry.
|
||||
Rules 4 and 5 cover `title`, `ask` and `result`.
|
||||
9. **A doc's `version` never goes back.** Sending a known doc a lower
|
||||
`version` than the page holds is refused: it is almost always a stale or
|
||||
copied payload. The same version again is fine, and a dashboard hop starts
|
||||
every doc fresh. Anything else reusing a doc id in the same session (a
|
||||
build's second phase, a second report or review) continues from the
|
||||
version the page holds.
|
||||
|
||||
These are workflow rules you already follow. The server just makes them checkable.
|
||||
|
||||
@@ -1167,7 +1260,9 @@ cannot see them, and the moment it says the session ended, the person is
|
||||
free to close that terminal and kill them mid-write. While you wait, post
|
||||
`{"agent":{"status":"working","activity":"Researching 3 questions (1 of 3 back)"}}`
|
||||
and update the count as each returns. Never write a `finish.body` that says
|
||||
work "is running in the background" or "will finish on its own".
|
||||
work "is running in the background" or "will finish on its own". Mark every
|
||||
reported helper `done` or `failed` before the finish, so the Subagents tab
|
||||
never ends on a row still running.
|
||||
|
||||
### 1. Post the finish
|
||||
|
||||
|
||||
@@ -64,6 +64,8 @@ import {
|
||||
readChat,
|
||||
readJson,
|
||||
readLedger,
|
||||
readSubagentCursor,
|
||||
readSubagentSetting,
|
||||
readWorkspace,
|
||||
reapHandles,
|
||||
rememberedWorkspace,
|
||||
@@ -71,6 +73,7 @@ import {
|
||||
removeScratch,
|
||||
removeSessions,
|
||||
repoRoots,
|
||||
resetSubagentCursor,
|
||||
scanProject,
|
||||
SESSION_MAX_AGE_MS,
|
||||
sessionDir,
|
||||
@@ -88,9 +91,11 @@ import {
|
||||
workspaceForAgent,
|
||||
writeCursor,
|
||||
writeJsonAtomic,
|
||||
writeSubagentCursor,
|
||||
writeWorkspaceCursor,
|
||||
} from "./lib.mjs";
|
||||
import { RUN_EVENTS, TASK_EVENTS, MAX_TASKS, isTaskCount, progressEntry } from "./public/meter.js";
|
||||
import { blockFor, offered } from "./public/subagents.js";
|
||||
import { changeLine } from "./public/workspace.js";
|
||||
|
||||
// Mirrors the server's absolute lifetime cap: a handle older than this cannot
|
||||
@@ -310,7 +315,11 @@ async function cmdOpen() {
|
||||
die(`could not write the session state: ${written ? written.error : "unknown"}`, 1);
|
||||
}
|
||||
state = written.state;
|
||||
appendEvent(dir, { type: "open", resumed: Boolean(args.resume || args.session), carried });
|
||||
appendEvent(dir, { type: "open", resumed: Boolean(args.resume || args.session), carried, caps: ["subagents"] });
|
||||
// A new agent conversation has been told nothing yet (FR-6).
|
||||
try {
|
||||
resetSubagentCursor(dir);
|
||||
} catch {}
|
||||
trace("open: state written");
|
||||
|
||||
// Dashboard launches are recorded too (they score nothing), so the folder
|
||||
@@ -337,9 +346,18 @@ async function cmdOpen() {
|
||||
removeScratch(HOME_DIR, sweptScratch).catch(() => {});
|
||||
};
|
||||
|
||||
// A standing instruction the new agent is owed, as `subagents` and a
|
||||
// `reply` holding only its lines; neither key when nothing is owed.
|
||||
const subagentsOwed = () => {
|
||||
awaitSubagentSync(dir, state.workflow);
|
||||
const [out, cursor] = withSubagents(dir, { reply: "" });
|
||||
return [out.subagents ? out : {}, cursor];
|
||||
};
|
||||
|
||||
// Reuse a live server if one is already serving this session.
|
||||
if (existing && (await reusable)) {
|
||||
if (!args["no-open"]) openBrowser(existing.url);
|
||||
const [owed, subCursor] = subagentsOwed();
|
||||
print({
|
||||
ok: true,
|
||||
sid,
|
||||
@@ -349,9 +367,11 @@ async function cmdOpen() {
|
||||
pendingResult: carried,
|
||||
terminalLine: terminalLine(existing.url),
|
||||
workspace,
|
||||
...owed,
|
||||
...swept,
|
||||
...remoteWarning(),
|
||||
});
|
||||
advanceSubagents(dir, subCursor);
|
||||
sweep();
|
||||
return;
|
||||
}
|
||||
@@ -384,6 +404,7 @@ async function cmdOpen() {
|
||||
const notes = [];
|
||||
if (remote.note) notes.push(remote.note);
|
||||
if (carried) notes.push("Answers are already waiting. Run `wait` to collect them.");
|
||||
const [owed, subCursor] = subagentsOwed();
|
||||
print({
|
||||
ok: true,
|
||||
sid,
|
||||
@@ -394,10 +415,12 @@ async function cmdOpen() {
|
||||
pendingResult: carried,
|
||||
terminalLine: terminalLine(handle.url),
|
||||
workspace,
|
||||
...owed,
|
||||
...swept,
|
||||
...(remote.remote ? { remote: remote.remote } : {}),
|
||||
...(notes.length ? { note: notes.join(" ") } : {}),
|
||||
});
|
||||
advanceSubagents(dir, subCursor);
|
||||
// After the print, never before it: the page and the link wait for nothing.
|
||||
sweep();
|
||||
}
|
||||
@@ -774,7 +797,7 @@ function serverGone(sid) {
|
||||
|
||||
// Quick questions and nothing else: an ordinary exit 0 with no card actions.
|
||||
function deliverChat(dir, sid, entries, url) {
|
||||
const [out, changes] = withWorkspace(dir, {
|
||||
const [withWs, changes] = withWorkspace(dir, {
|
||||
type: "chat",
|
||||
at: nowIso(),
|
||||
sid,
|
||||
@@ -782,9 +805,11 @@ function deliverChat(dir, sid, entries, url) {
|
||||
chat: entries,
|
||||
reply: chatReplyLines(entries),
|
||||
});
|
||||
const [out, subCursor] = withSubagents(dir, withWs);
|
||||
print({ ...out, ...(url ? { terminalLine: terminalLine(url) } : {}) });
|
||||
advanceCursor(dir, entries);
|
||||
advanceWorkspace(dir, changes);
|
||||
advanceSubagents(dir, subCursor);
|
||||
process.exitCode = 0;
|
||||
}
|
||||
|
||||
@@ -806,6 +831,52 @@ function advanceWorkspace(dir, changes) {
|
||||
} catch {}
|
||||
}
|
||||
|
||||
// The server rewrites the session's setting for a new workflow only once its
|
||||
// watcher sees the state `open` just wrote, so a launch or hop that read the
|
||||
// file at once would find the old workflow's and owe the agent nothing until
|
||||
// its next pickup. Give the server a moment to catch up instead, never
|
||||
// writing the file ourselves (FR-7). A session with no setting file at all is
|
||||
// an older server, which never writes one: a short look, not the full wait.
|
||||
const SUBAGENT_SYNC_WAIT_MS = 1500;
|
||||
const SUBAGENT_SYNC_MISSING_MS = 250;
|
||||
function awaitSubagentSync(dir, workflow) {
|
||||
if (!offered(workflow)) return;
|
||||
const start = Date.now();
|
||||
for (;;) {
|
||||
const setting = readSubagentSetting(dir);
|
||||
if (setting && setting.workflow === workflow) return;
|
||||
const budget = setting ? SUBAGENT_SYNC_WAIT_MS : SUBAGENT_SYNC_MISSING_MS;
|
||||
if (Date.now() - start >= budget) return;
|
||||
sleepSync(25);
|
||||
}
|
||||
}
|
||||
|
||||
// The Subagents switch the agent is owed, added to what it is about to read:
|
||||
// the setting as `subagents`, and its lines last in `reply`, after card lines,
|
||||
// Quick questions and Workspace lines (FR-9). Read from the session's own
|
||||
// setting file only, which only the server writes (FR-7). A setting for
|
||||
// another workflow is the server not having caught up with a hop yet: it
|
||||
// rides on the next pickup instead.
|
||||
function withSubagents(dir, out) {
|
||||
const setting = readSubagentSetting(dir);
|
||||
if (!setting) return [out, null];
|
||||
const workflow = (readJson(path.join(dir, "state.json")) || {}).workflow;
|
||||
if (setting.workflow !== workflow) return [out, null];
|
||||
const block = blockFor(setting, readSubagentCursor(dir));
|
||||
if (!block) return [out, null];
|
||||
const reply = [out.reply, ...block.lines].filter(Boolean).join("\n");
|
||||
return [{ ...out, subagents: block.field, reply }, block.cursor];
|
||||
}
|
||||
|
||||
// After the print, like advanceWorkspace(): a kill in between repeats the
|
||||
// block at the next pickup, never loses it.
|
||||
function advanceSubagents(dir, cursor) {
|
||||
if (!cursor) return;
|
||||
try {
|
||||
writeSubagentCursor(dir, cursor);
|
||||
} catch {}
|
||||
}
|
||||
|
||||
// Print first, then this, exactly as consume() stamps a result: a kill in
|
||||
// between can only hand the same chat over again, and collectChat() drops
|
||||
// anything that already has a reply.
|
||||
@@ -832,15 +903,17 @@ async function cmdChat() {
|
||||
}
|
||||
const entries = deliverableChat(collectChat(dir, readJson(path.join(dir, "state.json")) || {}));
|
||||
const changes = pendingWorkspaceChanges(dir);
|
||||
if (!entries.length && !changes.length) {
|
||||
const reply = [chatReplyLines(entries), ...changes.map(changeLine)].filter(Boolean).join("\n");
|
||||
const [out, subCursor] = withSubagents(dir, { chat: entries, workspace: changes, reply });
|
||||
if (!entries.length && !changes.length && !subCursor) {
|
||||
print({ chat: [] });
|
||||
process.exitCode = 10;
|
||||
return;
|
||||
}
|
||||
const reply = [chatReplyLines(entries), ...changes.map(changeLine)].filter(Boolean).join("\n");
|
||||
print({ chat: entries, workspace: changes, reply, terminalLine: terminalLine(handle.url) });
|
||||
print({ ...out, terminalLine: terminalLine(handle.url) });
|
||||
advanceCursor(dir, entries);
|
||||
advanceWorkspace(dir, changes);
|
||||
advanceSubagents(dir, subCursor);
|
||||
process.exitCode = 0;
|
||||
}
|
||||
|
||||
@@ -865,7 +938,8 @@ function consume(dir, resultPath, result, url, chat = []) {
|
||||
// never on result.json itself.
|
||||
const withChat = { ...collected, chat };
|
||||
if (chat.length) withChat.reply = [collected.reply, chatReplyLines(chat)].filter(Boolean).join("\n");
|
||||
const [out, changes] = withWorkspace(dir, withChat);
|
||||
const [withWs, changes] = withWorkspace(dir, withChat);
|
||||
const [out, subCursor] = withSubagents(dir, withWs);
|
||||
print(url ? { ...out, terminalLine: terminalLine(url) } : out);
|
||||
try {
|
||||
writeJsonAtomic(resultPath, collected);
|
||||
@@ -874,6 +948,7 @@ function consume(dir, resultPath, result, url, chat = []) {
|
||||
ledgerAnswers(dir, result);
|
||||
advanceCursor(dir, chat);
|
||||
advanceWorkspace(dir, changes);
|
||||
advanceSubagents(dir, subCursor);
|
||||
process.exitCode = result.type === "cancel" ? 30 : 0;
|
||||
}
|
||||
|
||||
@@ -986,12 +1061,18 @@ port, and the filesystem as transport; this CLI is the whole agent surface.
|
||||
path, description?, original? }], missing? }, the folders this
|
||||
console session reads as context, addressed as @name. The list is
|
||||
remembered per folder and spec in workspaces.json beside looks.json.
|
||||
May also print subagents: { state, revision, max, instruction } and
|
||||
a reply holding only its "Subagents: ..." lines, when a standing
|
||||
instruction (the page's Subagents switch) is owed to you.
|
||||
post --session <sid> --file <patch.json>
|
||||
Merge a patch into the session. Prints terminalLine while the
|
||||
server is live. Exit 3 = rejected; stderr says why. A patch may
|
||||
carry run: { event, id, tasks? } (session meter points) and folderIssue:
|
||||
{ name, reason, hint? } (a workspace folder you could not read);
|
||||
both go to the ledger, never into the state.
|
||||
both go to the ledger, never into the state. A patch may also
|
||||
carry helpers: [{ id, title, ask, state, result? }] or one
|
||||
{ id: "alone", alone: true }, merged by id, for the Subagents tab
|
||||
(see console.md → Standing instructions).
|
||||
wait --session <sid> [--seconds <N>]
|
||||
A bounded wait slice, sized below your shell timeout. Exit 0 = the
|
||||
result is on stdout, 10 = still waiting ("Waiting on your answer
|
||||
@@ -1002,10 +1083,14 @@ port, and the filesystem as transport; this CLI is the whole agent surface.
|
||||
"workspace" (changes since you last heard, each once, with a
|
||||
"Workspace: ..." line in reply); exit 10 counts them as
|
||||
pendingWorkspace, and a change alone never ends a slice.
|
||||
Exit 0 may also carry "subagents" (a console setting, not typed
|
||||
by the person, with its "Subagents: ..." lines last in reply); a
|
||||
setting change alone never ends a slice either.
|
||||
chat --session <sid>
|
||||
Collect Quick questions and workspace changes now, never waiting,
|
||||
never touching card sends. Exit 0 = { chat, workspace, reply,
|
||||
terminalLine }, 10 = none, 20 = server gone.
|
||||
Collect Quick questions, workspace changes and a Subagents
|
||||
setting change now, never waiting, never touching card sends.
|
||||
Exit 0 = { chat, workspace, subagents?, reply, terminalLine },
|
||||
10 = none, 20 = server gone.
|
||||
terminalLine is "→ Look at the web console: <url>": end your terminal
|
||||
messages with it during a console session.
|
||||
keep --session <sid> --upload <path> --name <name> --spec specs/<idea> [--from <file>]
|
||||
|
||||
@@ -25,6 +25,7 @@ import { fileURLToPath } from "node:url";
|
||||
import { CHAT_LIMIT } from "./public/chat.js";
|
||||
import { DOC_TYPES } from "./public/answers.js";
|
||||
import { defaultName } from "./public/workspace.js";
|
||||
import { checkHelpers, cleanSetting, defaultSetting, offered } from "./public/subagents.js";
|
||||
|
||||
export const HERE = path.dirname(fileURLToPath(import.meta.url));
|
||||
export const PUBLIC_DIR = path.join(HERE, "public");
|
||||
@@ -491,9 +492,16 @@ export async function removeSessions(sessionsDir, sids) {
|
||||
}
|
||||
|
||||
// The console folder's own files that no sweep may ever remove: the person's
|
||||
// looks, the folders remembered per project and spec, the pointer to this
|
||||
// console's directory, and the cached release check.
|
||||
export const PROTECTED_CONSOLE_FILES = new Set(["looks.json", "workspaces.json", "console-dir", "update-check.json"]);
|
||||
// looks, the folders remembered per project and spec, the Subagents switch
|
||||
// saved per project and workflow, the pointer to this console's directory,
|
||||
// and the cached release check.
|
||||
export const PROTECTED_CONSOLE_FILES = new Set([
|
||||
"looks.json",
|
||||
"workspaces.json",
|
||||
"subagents.json",
|
||||
"console-dir",
|
||||
"update-check.json",
|
||||
]);
|
||||
|
||||
function isScratchName(name) {
|
||||
return (
|
||||
@@ -1142,6 +1150,19 @@ const DOC_DEFAULTS = { version: 1, stale: false, blocks: [] };
|
||||
// Blocks merge by id like docs do, so a patch that only settles a block's
|
||||
// state keeps its text. Blocks left out of the patch stay as they are.
|
||||
function mergeDocs(current, patchList) {
|
||||
// A doc's version only moves forward. One going back is a stale or copied
|
||||
// payload (last phase's progress script, say), and the page would quietly
|
||||
// show the old content under the new run's name.
|
||||
for (const entry of patchList) {
|
||||
if (!isPlainObject(entry) || typeof entry.version !== "number") continue;
|
||||
const prev = (current || []).find((d) => d && d.id === entry.id);
|
||||
if (prev && typeof prev.version === "number" && entry.version < prev.version) {
|
||||
throw new Error(
|
||||
`doc "${entry.id}" is at version ${prev.version} on the page; this patch sends version ${entry.version}. ` +
|
||||
"Versions only go up: bump it, and check the payload is the current one."
|
||||
);
|
||||
}
|
||||
}
|
||||
const merged = mergeKeyed(current, patchList, "id", DOC_DEFAULTS, "docs");
|
||||
for (const entry of patchList) {
|
||||
if (!Array.isArray(entry.blocks)) continue;
|
||||
@@ -1184,6 +1205,13 @@ export function applyPatch(state, patch) {
|
||||
if (!Array.isArray(v)) throw new Error('"topics" must be an array');
|
||||
next.topics = mergeKeyed(next.topics, v, "id", {}, "topics");
|
||||
break;
|
||||
case "helpers":
|
||||
// The agent's report of its helpers, for the page's Subagents tab.
|
||||
// Only `post` writes it; the server's /submit never touches it.
|
||||
if (!Array.isArray(v)) throw new Error('"helpers" must be an array');
|
||||
if (!v.every(isPlainObject)) throw new Error('"helpers" entries must be objects, each { id, title, ask, state }');
|
||||
next.helpers = mergeKeyed(next.helpers, v, "id", {}, "helpers");
|
||||
break;
|
||||
case "docs":
|
||||
if (!Array.isArray(v)) throw new Error('"docs" must be an array');
|
||||
next.docs = mergeDocs(next.docs, v);
|
||||
@@ -1478,6 +1506,20 @@ export function validate(state) {
|
||||
JSON.stringify(state.menu || {});
|
||||
problems.push(...proseProblems(prose));
|
||||
|
||||
// The agent's report of its helpers: the shape the page draws from
|
||||
// (subagents.js), then the same prose scan as everything else it writes.
|
||||
if (state.helpers != null) {
|
||||
problems.push(...checkHelpers(state.helpers));
|
||||
for (const helper of Array.isArray(state.helpers) ? state.helpers : []) {
|
||||
if (!isPlainObject(helper)) continue;
|
||||
for (const field of ["title", "ask", "result"]) {
|
||||
if (typeof helper[field] === "string") {
|
||||
problems.push(...proseProblems(helper[field], `helper "${helper.id}" ${field}`));
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
return problems;
|
||||
}
|
||||
|
||||
@@ -1507,7 +1549,8 @@ export function blankState({ sid, workflow, title, project, specDir }) {
|
||||
* A resume that passes through the dashboard (a finished skill going back to
|
||||
* it, or a launch from its menu) is a new skill taking the page over, so it
|
||||
* starts from a blank page: the last skill's questions, sections, docs,
|
||||
* headline and ending are its record on disk, not the next skill's opening.
|
||||
* helpers, headline and ending are its record on disk, not the next skill's
|
||||
* opening.
|
||||
* Only the session's identity carries across. `workspace.json`,
|
||||
* `ledger.ndjson` and the cursors live beside `state.json`, so the workspace
|
||||
* and the meter outlive every hop.
|
||||
@@ -1534,6 +1577,8 @@ export function switchWorkflow(state, { workflow, title, specDir }) {
|
||||
// workspace.json the server. Folders, version, change log, missing, remote.
|
||||
// ledger.ndjson console.mjs. Append-only meter events and folder issues.
|
||||
// workspace-cursor.json console.mjs. The last workspace version handed to the agent.
|
||||
// subagents-setting.json the server. The Subagents switch for this session, with its revision.
|
||||
// subagents-cursor.json console.mjs. The last Subagents revision and state handed to the agent.
|
||||
export const CHAT_FILE = "chat.ndjson";
|
||||
export const CHAT_CURSOR_FILE = "chat-cursor.json";
|
||||
export const WORKSPACE_FILE = "workspace.json";
|
||||
@@ -1989,6 +2034,98 @@ export function pendingWorkspaceChanges(dir) {
|
||||
return (readWorkspace(dir)?.changes || []).filter((c) => c.version > cursor);
|
||||
}
|
||||
|
||||
/* ------------------------------------------------------ the Subagents switch */
|
||||
|
||||
// The person's Subagents switch, remembered per project folder and workflow:
|
||||
//
|
||||
// { "<folded project path>": { "<workflow>": { on, instruction, max } } }
|
||||
//
|
||||
// Keyed with foldKey(), as workspaces.json is. `instruction: null` is the
|
||||
// workflow's shipped default.
|
||||
export const SUBAGENTS_FILE = path.join(HOME_DIR, "subagents.json");
|
||||
const SUBAGENTS_LOCK = "subagents.json.lock";
|
||||
|
||||
function readSubagentStore() {
|
||||
const saved = readJson(SUBAGENTS_FILE, null);
|
||||
return saved && typeof saved === "object" && !Array.isArray(saved) ? saved : {};
|
||||
}
|
||||
|
||||
// The saved `{ on, instruction, max }` for this folder and workflow, or the
|
||||
// default's when nothing (or something malformed) is saved.
|
||||
export function subagentStoreEntry(worktree, workflow) {
|
||||
const { on, instruction, max } = defaultSetting(workflow);
|
||||
const project = offered(workflow) ? readSubagentStore()[foldKey(worktree)] : null;
|
||||
const saved = project && typeof project === "object" ? cleanSetting(project[workflow]) : null;
|
||||
return saved && !saved.error ? saved : { on, instruction, max };
|
||||
}
|
||||
|
||||
// Single-writer rule: only server.mjs may call this.
|
||||
export function saveSubagentStoreEntry(worktree, workflow, value) {
|
||||
ensureDir(path.dirname(SUBAGENTS_FILE));
|
||||
withStateLock(
|
||||
path.dirname(SUBAGENTS_FILE),
|
||||
() => {
|
||||
const store = readSubagentStore();
|
||||
const key = foldKey(worktree);
|
||||
const project = store[key] && typeof store[key] === "object" ? store[key] : {};
|
||||
store[key] = { ...project, [workflow]: { on: value.on, instruction: value.instruction, max: value.max } };
|
||||
writeJsonAtomic(SUBAGENTS_FILE, store);
|
||||
},
|
||||
SUBAGENTS_LOCK
|
||||
);
|
||||
}
|
||||
|
||||
export const SUBAGENTS_SETTING_FILE = "subagents-setting.json";
|
||||
|
||||
const isCount = (n) => Number.isInteger(n) && n >= 0;
|
||||
|
||||
// This session's switch, `{ workflow, on, instruction, max, revision }`, or
|
||||
// null when there is none or it is malformed.
|
||||
export function readSubagentSetting(dir) {
|
||||
const s = readJson(path.join(dir, SUBAGENTS_SETTING_FILE), null);
|
||||
if (!s || typeof s !== "object") return null;
|
||||
if (typeof s.workflow !== "string" || typeof s.on !== "boolean" || !Number.isInteger(s.max) || !isCount(s.revision)) return null;
|
||||
return s;
|
||||
}
|
||||
|
||||
// Single-writer rule: only server.mjs may call this. The revision never goes
|
||||
// backwards within a session.
|
||||
export function writeSubagentSetting(dir, setting) {
|
||||
const previous = readSubagentSetting(dir);
|
||||
const revision = Math.max(previous ? previous.revision : 0, setting.revision);
|
||||
return writeJsonAtomic(path.join(dir, SUBAGENTS_SETTING_FILE), { ...setting, revision });
|
||||
}
|
||||
|
||||
export const SUBAGENTS_CURSOR_FILE = "subagents-cursor.json";
|
||||
const CURSOR_STATES = new Set(["none", "on", "off"]);
|
||||
|
||||
// What the agent was last told: `{ revision, state }`.
|
||||
export function readSubagentCursor(dir) {
|
||||
const saved = readJson(path.join(dir, SUBAGENTS_CURSOR_FILE), null);
|
||||
if (!saved || !isCount(saved.revision) || !CURSOR_STATES.has(saved.state)) return { revision: 0, state: "none" };
|
||||
return { revision: saved.revision, state: saved.state };
|
||||
}
|
||||
|
||||
// Single-writer rule: only console.mjs may call this. Never backwards, like
|
||||
// writeWorkspaceCursor(): a killed `wait` may repeat a change, never skip one.
|
||||
export function writeSubagentCursor(dir, cursor) {
|
||||
const old = readSubagentCursor(dir);
|
||||
const next = cursor.revision < old.revision ? old : { revision: cursor.revision, state: cursor.state };
|
||||
writeJsonAtomic(path.join(dir, SUBAGENTS_CURSOR_FILE), next);
|
||||
}
|
||||
|
||||
// The one place the cursor may go back: `open`, which starts a fresh agent.
|
||||
export function resetSubagentCursor(dir) {
|
||||
writeJsonAtomic(path.join(dir, SUBAGENTS_CURSOR_FILE), { revision: 0, state: "none" });
|
||||
}
|
||||
|
||||
// The `caps` of the last `open` event: what the agent's console copy can do.
|
||||
export function latestOpenCaps(dir) {
|
||||
const opens = readJsonLines(path.join(dir, "events.ndjson")).filter((e) => e.type === "open");
|
||||
const last = opens[opens.length - 1];
|
||||
return last && Array.isArray(last.caps) ? last.caps : [];
|
||||
}
|
||||
|
||||
/**
|
||||
* Flag the case where the link cannot be opened by the person it is for.
|
||||
*
|
||||
|
||||
@@ -208,6 +208,26 @@ body {
|
||||
.stop-btn:hover:not(:disabled) { color: var(--warn); border-color: var(--warn); }
|
||||
.brief-btn:hover:not(:disabled) { color: var(--accent); border-color: var(--accent-line); }
|
||||
|
||||
/* Subagents: an orchestrator and its helpers. Unlit is a hollow outline in
|
||||
the quiet ink; lit fills the nodes with the highlight color. */
|
||||
.subagents-btn { border-color: var(--rule-2); color: var(--ink-2); display: inline-flex; align-items: center; justify-content: center; }
|
||||
.btn.subagents-btn { padding: 0 6px; align-self: stretch; }
|
||||
.subagents-btn[hidden] { display: none; }
|
||||
.subagents-btn svg { width: 16px; height: 16px; display: block; }
|
||||
.subagents-btn .sa-link { fill: none; stroke: var(--ink-2); stroke-width: 1.2; stroke-linecap: round; }
|
||||
.subagents-btn .sa-hub { fill: none; stroke: var(--ink-2); stroke-width: 1.4; }
|
||||
.subagents-btn .sa-node { fill: none; stroke: var(--ink-2); stroke-width: 1.2; }
|
||||
.subagents-btn[aria-pressed="true"] .sa-hub,
|
||||
.subagents-btn[aria-pressed="true"] .sa-node { fill: var(--accent); stroke: var(--accent); }
|
||||
.subagents-btn[aria-pressed="true"] .sa-link { stroke: var(--accent); }
|
||||
.subagents-btn:hover:not(:disabled) { color: var(--accent); border-color: var(--accent-line); }
|
||||
.subagents-btn:hover:not(:disabled) .sa-link,
|
||||
.subagents-btn:hover:not(:disabled) .sa-hub,
|
||||
.subagents-btn:hover:not(:disabled) .sa-node { stroke: var(--accent); }
|
||||
.subagents-btn:disabled .sa-link,
|
||||
.subagents-btn:disabled .sa-hub,
|
||||
.subagents-btn:disabled .sa-node { stroke: var(--ink-3); fill: none; }
|
||||
|
||||
.ident { display: flex; align-items: baseline; gap: 12px; min-width: 0; }
|
||||
|
||||
/* The session meter: a ring that fills with the points and a few words, in
|
||||
@@ -1430,6 +1450,30 @@ h1 {
|
||||
.pill.done { background: var(--ok-soft); color: var(--ok); }
|
||||
.pill.staged { background: var(--stage-soft); color: var(--stage); }
|
||||
|
||||
/* The Subagents tab: one row per reported helper, newest state in a pill. */
|
||||
.sa-card h2 { margin: 0 0 6px; }
|
||||
.sa-card > .help { margin: 0 0 16px; }
|
||||
.sa-alone { margin: 0; color: var(--ink-2); }
|
||||
.sa-list { list-style: none; margin: 0; padding: 0; display: grid; gap: 10px; }
|
||||
.sa-row { border: 1px solid var(--rule); border-radius: 8px; background: var(--panel-2); padding: 12px 14px; }
|
||||
.sa-head { display: flex; align-items: center; justify-content: space-between; gap: 10px; }
|
||||
.sa-title { min-width: 0; overflow-wrap: anywhere; }
|
||||
.sa-ask {
|
||||
margin: 4px 0 0; color: var(--ink-2); font-size: 13.5px;
|
||||
display: -webkit-box; -webkit-box-orient: vertical; -webkit-line-clamp: 2; line-clamp: 2; overflow: hidden;
|
||||
}
|
||||
.sa-result { margin: 8px 0 0; padding-top: 8px; border-top: 1px solid var(--rule); font-size: 13.5px; }
|
||||
.sa-pill { display: inline-flex; align-items: center; gap: 6px; flex: none; }
|
||||
.sa-pill.is-running { background: var(--accent-soft); color: var(--accent); border-color: var(--accent-line); }
|
||||
.sa-pill.is-done { background: var(--ok-soft); color: var(--ok); }
|
||||
.sa-pill.is-failed { background: var(--warn-soft); color: var(--warn); }
|
||||
.sa-pill .spinner.tiny { width: 10px; height: 10px; }
|
||||
/* The dialog's number box, themed like the page's other inputs. */
|
||||
.subagents input[type="number"] {
|
||||
width: 5em; font: inherit; color: var(--ink); background: var(--panel-2);
|
||||
border: 1px solid var(--rule-2); border-radius: 6px; padding: 4px 8px;
|
||||
}
|
||||
|
||||
/* ------------------------------------------------------ settled answer */
|
||||
|
||||
.answered {
|
||||
@@ -1971,6 +2015,8 @@ h4.md-h, h5.md-h, h6.md-h { font-size: 15px; }
|
||||
cursor: pointer;
|
||||
}
|
||||
.footer-where:hover { text-decoration: underline; }
|
||||
/* The project name, in the person's highlight color. */
|
||||
.where-project { color: var(--accent); font-weight: 600; }
|
||||
/* A folder is missing or the agent could not read one: the dialog says which. */
|
||||
.where-alert {
|
||||
display: inline-block; width: 7px; height: 7px; margin-left: 6px;
|
||||
|
||||
@@ -103,6 +103,15 @@ import { FOOTER_TIERS, footerLabel, nameProblem } from "./workspace.js";
|
||||
import { RED_BANNER } from "./meter.js";
|
||||
import { applyMention, matchNames, mentionAt } from "./mentions.js";
|
||||
import { faviconState, setFavicon } from "./favicon.js";
|
||||
import {
|
||||
CHECKIN_LINE,
|
||||
PATHFINDER_RESEARCH_LINE,
|
||||
defaultInstruction,
|
||||
helperRows,
|
||||
showSwitch,
|
||||
showTab,
|
||||
switchLabel,
|
||||
} from "./subagents.js";
|
||||
|
||||
const $ = (id) => document.getElementById(id);
|
||||
|
||||
@@ -530,6 +539,9 @@ let meterFrame = null;
|
||||
// The frame's update ({ installed, latest }), present only when a newer
|
||||
// release is out; null otherwise.
|
||||
let updateFrame = null;
|
||||
// The frame's Subagents switch ({ offered, supported, on, instruction, max,
|
||||
// revision }), or null before a server that sends it.
|
||||
let subagentsFrame = null;
|
||||
let chatDot = false;
|
||||
let chatSending = false;
|
||||
let chatResetting = false;
|
||||
@@ -880,6 +892,8 @@ function adopt(body) {
|
||||
if (body.meter) meterFrame = body.meter;
|
||||
// Always replaced: an absent key means no update.
|
||||
updateFrame = body.update || null;
|
||||
// Always replaced too: an older server sends none, and then there is no switch.
|
||||
subagentsFrame = body.subagents || null;
|
||||
lastContact = Date.now();
|
||||
if (gone) {
|
||||
gone = false;
|
||||
@@ -1301,6 +1315,7 @@ function render() {
|
||||
renderChrome();
|
||||
renderStatus();
|
||||
renderBriefButton();
|
||||
renderSubagentsButton();
|
||||
renderStopButton();
|
||||
renderHomeButton();
|
||||
tabAdded = renderViews();
|
||||
@@ -1566,7 +1581,7 @@ function renderChrome() {
|
||||
renderMeter();
|
||||
$("title").textContent = S.title || "Session";
|
||||
$("badge").textContent = workflowLabel(S.workflow);
|
||||
document.title = (S.title || "Session") + " · #" + String(S.sid || "").slice(-6) + " · Plan2Code";
|
||||
renderTabTitle();
|
||||
|
||||
const h = S.headline || {};
|
||||
// On a finished session an open item is frozen: the send on it counts as
|
||||
@@ -1835,6 +1850,69 @@ function renderBriefButton() {
|
||||
if (offer) btn.disabled = gone || pendingResult;
|
||||
}
|
||||
|
||||
// Shown only where the skill opts in and the agent's console copy can deliver
|
||||
// it. Lit while helpers are on; a click opens the dialog, never toggles.
|
||||
function renderSubagentsButton() {
|
||||
const btn = $("btn-subagents");
|
||||
const offer = showSwitch(subagentsFrame);
|
||||
btn.hidden = !offer;
|
||||
if (!offer) return;
|
||||
const label = switchLabel(subagentsFrame);
|
||||
btn.setAttribute("aria-pressed", String(Boolean(subagentsFrame.on)));
|
||||
btn.title = label;
|
||||
btn.setAttribute("aria-label", label);
|
||||
btn.disabled = gone;
|
||||
}
|
||||
|
||||
// The Subagents dialog, filled from the frame each time it opens. A null
|
||||
// instruction is the shipped default, shown as its text so it can be edited.
|
||||
function openSubagents() {
|
||||
if (!showSwitch(subagentsFrame)) return;
|
||||
const on = Boolean(subagentsFrame.on);
|
||||
for (const radio of document.querySelectorAll('input[name="subagents-on"]')) {
|
||||
radio.checked = radio.value === (on ? "on" : "off");
|
||||
}
|
||||
$("subagents-instruction").value = subagentsFrame.instruction ?? defaultInstruction(S.workflow);
|
||||
$("subagents-max").value = String(subagentsFrame.max);
|
||||
$("subagents-checkin").textContent = CHECKIN_LINE;
|
||||
const research = $("subagents-research");
|
||||
research.textContent = PATHFINDER_RESEARCH_LINE;
|
||||
research.hidden = S.workflow !== "pathfinder";
|
||||
$("subagents-status").textContent = "";
|
||||
$("subagents-save").disabled = false;
|
||||
$("subagents-modal").showModal();
|
||||
const checked = document.querySelector('input[name="subagents-on"]:checked');
|
||||
if (checked) checked.focus();
|
||||
}
|
||||
|
||||
const SUBAGENTS_ERRORS = {
|
||||
max: "Pick a number from 1 to 20.",
|
||||
"too-long": "The instruction is over 2,000 characters.",
|
||||
"not-offered": "This skill doesn't use helpers.",
|
||||
bad: "That didn't save. Try again.",
|
||||
};
|
||||
const SUBAGENTS_LOST = "Lost contact with Plan2Code. Try again once it's back.";
|
||||
|
||||
async function saveSubagents() {
|
||||
const save = $("subagents-save");
|
||||
const status = $("subagents-status");
|
||||
const picked = document.querySelector('input[name="subagents-on"]:checked');
|
||||
const text = $("subagents-instruction").value.trim();
|
||||
// The shipped default is stored as null, so a later release's wording
|
||||
// reaches everyone who never changed it.
|
||||
const instruction = text === defaultInstruction(S.workflow) ? null : text;
|
||||
const body = { on: Boolean(picked && picked.value === "on"), instruction, max: Number($("subagents-max").value) };
|
||||
save.disabled = true;
|
||||
status.textContent = "";
|
||||
const res = await postJson("/subagents", body);
|
||||
save.disabled = false;
|
||||
// The next state frame redraws the button.
|
||||
if (res.status === 200) return $("subagents-modal").close();
|
||||
if (res.status === 400) status.textContent = SUBAGENTS_ERRORS[res.body && res.body.error] || SUBAGENTS_ERRORS.bad;
|
||||
else if (res.status === 403 || res.status === 0) status.textContent = SUBAGENTS_LOST;
|
||||
else status.textContent = SUBAGENTS_ERRORS.bad;
|
||||
}
|
||||
|
||||
function renderViews() {
|
||||
const nav = $("views");
|
||||
nav.replaceChildren();
|
||||
@@ -1850,6 +1928,14 @@ function renderViews() {
|
||||
if (hasOverview) tabs.push({ id: "overview", label: "Overview", count: 0 });
|
||||
else if (view === "overview") view = "questions";
|
||||
for (const d of docs()) tabs.push({ id: "doc:" + d.id, label: d.title || "Document", count: 0 });
|
||||
// The helpers the agent reported, from the first one on; cleared by a
|
||||
// dashboard hop, which sends the person home like the Overview tab does.
|
||||
if (showTab(subagentsFrame, S.helpers)) {
|
||||
// From the rows the tab draws, so the badge never counts helpers the
|
||||
// working-alone note hides.
|
||||
const running = helperRows(S.helpers).rows.filter((r) => r.state === "running").length;
|
||||
tabs.push({ id: "subagents", label: "Subagents", count: running });
|
||||
} else if (view === "subagents") view = "questions";
|
||||
// Always last, on every workflow and after a finish: the Quick question chat.
|
||||
// The ring left of "Ask" shows exactly when the conversation's own ring does:
|
||||
// a question the agent picked up and has not answered yet.
|
||||
@@ -2130,6 +2216,7 @@ function paintMain(main) {
|
||||
if (view.startsWith("doc:")) return renderDoc(main, view.slice(4));
|
||||
if (view === "overview") return renderOverview(main);
|
||||
if (view === "ask") return renderAsk(main);
|
||||
if (view === "subagents") return renderSubagents(main);
|
||||
|
||||
// The session's own page, reached from the PAUSED / SESSION ENDED item at
|
||||
// the top of the rail. The hand-off lives here alone now, rather than
|
||||
@@ -4774,6 +4861,42 @@ function renderOverview(main) {
|
||||
main.appendChild(box);
|
||||
}
|
||||
|
||||
// The helpers the agent reported, as it last posted them. Everything here is
|
||||
// the agent's text, so it goes in as text, never as markup.
|
||||
function renderSubagents(main) {
|
||||
const card = el("section", "card sa-card");
|
||||
card.appendChild(el("h2", null, "Subagents"));
|
||||
card.appendChild(el("p", "help", CHECKIN_LINE));
|
||||
const { alone, rows } = helperRows(S.helpers);
|
||||
if (alone) {
|
||||
card.appendChild(
|
||||
el("p", "sa-alone", "Working alone: your agent has no way to start helpers here, so it is doing this skill's work itself.")
|
||||
);
|
||||
main.appendChild(card);
|
||||
return;
|
||||
}
|
||||
const list = el("ul", "sa-list");
|
||||
for (const row of rows) {
|
||||
const item = el("li", "sa-row");
|
||||
const head = el("div", "sa-head");
|
||||
head.appendChild(el("strong", "sa-title", row.title));
|
||||
const pill = el("span", "pill sa-pill is-" + row.state);
|
||||
if (row.state === "running") {
|
||||
const spin = el("span", "spinner tiny");
|
||||
spin.setAttribute("aria-hidden", "true");
|
||||
pill.appendChild(spin);
|
||||
}
|
||||
pill.appendChild(document.createTextNode(row.stateLabel));
|
||||
head.appendChild(pill);
|
||||
item.appendChild(head);
|
||||
item.appendChild(el("p", "sa-ask", row.ask));
|
||||
if (row.result) item.appendChild(el("p", "sa-result", row.result));
|
||||
list.appendChild(item);
|
||||
}
|
||||
card.appendChild(list);
|
||||
main.appendChild(card);
|
||||
}
|
||||
|
||||
/* ---------------------------------------------------------------- ask */
|
||||
|
||||
// The frame's chat block, with `offline` worked out now rather than when the
|
||||
@@ -5956,10 +6079,30 @@ const workspaceFolders = () => (wsFrame && Array.isArray(wsFrame.folders) ? wsFr
|
||||
// session opened before the server wrote `worktree` has nothing to show, so
|
||||
// the slot stays hidden. The footer renders on every tick, so the DOM is only
|
||||
// touched when the labels change, or when a resize clears the key.
|
||||
// The project's name: the workspace's original folder, or the session's
|
||||
// worktree folder before a frame carries the workspace.
|
||||
function projectName() {
|
||||
const folders = workspaceFolders();
|
||||
if (folders.length && folders[0].name) return folders[0].name;
|
||||
const path = (S && S.worktree) || "";
|
||||
return path ? path.split(/[\\/]/).filter(Boolean).pop() || path : "";
|
||||
}
|
||||
|
||||
// The browser tab's title, led by the project so tabs from different
|
||||
// projects are told apart. Called from the chrome and the footer, since the
|
||||
// workspace frame can arrive after either.
|
||||
function renderTabTitle() {
|
||||
if (!S) return;
|
||||
const name = projectName();
|
||||
document.title =
|
||||
(name ? name + " · " : "") + (S.title || "Session") + " · #" + String(S.sid || "").slice(-6) + " · Plan2Code";
|
||||
}
|
||||
|
||||
function renderWhere() {
|
||||
const b = $("footer-where");
|
||||
const folders = workspaceFolders();
|
||||
const path = S.worktree || "";
|
||||
renderTabTitle();
|
||||
const alert = Boolean(folders.length && ((wsFrame.missing || []).length || (wsFrame.issues || []).length));
|
||||
const labels = folders.length
|
||||
? Array.from({ length: FOOTER_TIERS }, (_, tier) => footerLabel({ folders, branch: S.branch }, tier))
|
||||
@@ -5972,7 +6115,16 @@ function renderWhere() {
|
||||
let label = labels[0];
|
||||
for (const text of labels) {
|
||||
label = text;
|
||||
b.textContent = text;
|
||||
// The project name takes the highlight color, so several consoles side by
|
||||
// side tell apart at a glance; the rest of the label stays quiet.
|
||||
const name = projectName();
|
||||
b.textContent = "";
|
||||
if (name && text.startsWith(name)) {
|
||||
b.appendChild(el("span", "where-project", name));
|
||||
b.appendChild(document.createTextNode(text.slice(name.length)));
|
||||
} else {
|
||||
b.textContent = text;
|
||||
}
|
||||
if (alert) {
|
||||
const dot = el("span", "where-alert");
|
||||
dot.setAttribute("aria-hidden", "true");
|
||||
@@ -7197,6 +7349,7 @@ function lightDismiss(dlg) {
|
||||
});
|
||||
}
|
||||
lightDismiss($("looks-modal"));
|
||||
lightDismiss($("subagents-modal"));
|
||||
lightDismiss($("help-modal"));
|
||||
lightDismiss($("workspace-modal"));
|
||||
lightDismiss($("welcome-modal"));
|
||||
@@ -7499,6 +7652,13 @@ $("cleanup-scan").addEventListener("click", scanCleanup);
|
||||
$("cleanup-delete").addEventListener("click", deleteCleanup);
|
||||
|
||||
$("btn-brief").addEventListener("click", openBrief);
|
||||
$("btn-subagents").addEventListener("click", openSubagents);
|
||||
$("subagents-default").addEventListener("click", () => {
|
||||
$("subagents-instruction").value = defaultInstruction(S.workflow);
|
||||
});
|
||||
$("subagents-save").addEventListener("click", saveSubagents);
|
||||
$("subagents-cancel").addEventListener("click", () => $("subagents-modal").close());
|
||||
$("subagents-modal").addEventListener("close", () => $("btn-subagents").focus());
|
||||
$("brief-cancel").addEventListener("click", () => $("brief-modal").close());
|
||||
$("brief-go").addEventListener("click", sendBrief);
|
||||
for (const radio of document.querySelectorAll('input[name="brief-range"]')) {
|
||||
|
||||
@@ -19,6 +19,7 @@ export const HELP_TABS = Object.freeze([
|
||||
tab("dashboard", "The dashboard", true),
|
||||
tab("meter", "Session meter", false),
|
||||
tab("build", "Watching a build", false),
|
||||
tab("subagents", "Helpers (subagents)", false),
|
||||
tab("ask", "Ask a quick question", false),
|
||||
tab("finishing", "Stopping and finishing", false),
|
||||
tab("stuck", "When something looks stuck", true),
|
||||
@@ -39,6 +40,7 @@ export function helpTabFor({ view, dashboard, gone, adrift, finished, workflow,
|
||||
if (gone || adrift) return "stuck";
|
||||
if (workspace) return "workspace";
|
||||
if (v === "ask") return "ask";
|
||||
if (v === "subagents") return "subagents";
|
||||
if (dashboard && meterRed) return "meter";
|
||||
if (dashboard) return "dashboard";
|
||||
if (v === "overview" || v.startsWith("doc:")) return "docs";
|
||||
|
||||
@@ -21,6 +21,7 @@
|
||||
<link rel="modulepreload" href="/starters.js" />
|
||||
<link rel="modulepreload" href="/workspace.js" />
|
||||
<link rel="modulepreload" href="/meter.js" />
|
||||
<link rel="modulepreload" href="/subagents.js" />
|
||||
<link rel="modulepreload" href="/mentions.js" />
|
||||
<link rel="modulepreload" href="/favicon.js" />
|
||||
<link rel="modulepreload" href="/vendor/marked.esm.js" />
|
||||
@@ -172,6 +173,18 @@
|
||||
<button type="button" class="btn ghost small brief-btn" id="btn-brief" hidden>
|
||||
Write a brief
|
||||
</button>
|
||||
<!-- Subagents: opted-in skills only. Lit while helpers are on; a click
|
||||
opens the Subagents dialog and never toggles them itself. -->
|
||||
<button type="button" class="btn ghost small subagents-btn" id="btn-subagents" aria-pressed="false" hidden>
|
||||
<!-- An orchestrator and its helpers: one larger node linked to three smaller ones. -->
|
||||
<svg viewBox="0 0 16 16" aria-hidden="true" focusable="false">
|
||||
<path class="sa-link" d="M6.9 6.6L10.9 3.9M7.4 8h3.5M6.9 9.4l4 2.7" />
|
||||
<circle cx="4.6" cy="8" r="2.6" class="sa-hub" />
|
||||
<circle cx="12.4" cy="3" r="1.5" class="sa-node" />
|
||||
<circle cx="12.4" cy="8" r="1.5" class="sa-node" />
|
||||
<circle cx="12.4" cy="13" r="1.5" class="sa-node" />
|
||||
</svg>
|
||||
</button>
|
||||
</div>
|
||||
<div class="views-group">
|
||||
<span class="views-arrow" aria-hidden="true">
|
||||
@@ -580,6 +593,13 @@
|
||||
<rect x="3" y="9" width="18" height="6" rx="3" />
|
||||
<path d="M6 12h7" />
|
||||
</symbol>
|
||||
<symbol id="hi-subagents" viewBox="0 0 24 24" fill="none">
|
||||
<circle cx="7" cy="12" r="3.5" />
|
||||
<circle cx="18" cy="5" r="2" />
|
||||
<circle cx="18" cy="12" r="2" />
|
||||
<circle cx="18" cy="19" r="2" />
|
||||
<path d="M10 10l6-4M10.5 12H16M10 14l6 4" />
|
||||
</symbol>
|
||||
<symbol id="hi-ask" viewBox="0 0 24 24" fill="none">
|
||||
<path d="M4 5h16v11H10l-4 4v-4H4z" />
|
||||
<path d="M8 9.5h8M8 12.5h5" />
|
||||
@@ -1477,7 +1497,61 @@
|
||||
</p>
|
||||
</section>
|
||||
|
||||
<!-- Tab 12: Ask a quick question -->
|
||||
<!-- Tab 12: Helpers (subagents) -->
|
||||
<section class="help-panel" data-tab="subagents">
|
||||
<h3>Helpers (subagents)</h3>
|
||||
<p>
|
||||
On a build, a review and Pathfinder, Plan2Code can hand independent
|
||||
pieces of work to helpers (subagents) while it keeps the conversation
|
||||
with you. The <strong>Subagents</strong> button in the top bar, after
|
||||
Stop session, is lit while helpers are on.
|
||||
</p>
|
||||
<h4>The switch</h4>
|
||||
<ul>
|
||||
<li>
|
||||
Clicking the button opens the <strong>Subagents</strong> dialog; it
|
||||
never switches helpers on or off by itself. Pick <strong>Use
|
||||
helpers</strong> or <strong>Work alone</strong>, edit the instruction
|
||||
Plan2Code follows (<strong>Reset to default</strong> puts the
|
||||
shipped one back), and say how many may run at once.
|
||||
</li>
|
||||
<li>
|
||||
It is off by default and saved for this project and this skill, so
|
||||
the next session of the same skill here starts the same way.
|
||||
</li>
|
||||
<li>
|
||||
The change reaches Plan2Code at its next check-in, as a setting,
|
||||
not as something you typed. How many helpers it can really start is
|
||||
up to your agent; some have no helpers at all.
|
||||
</li>
|
||||
<li>The button only appears on skills that use helpers, and only when Plan2Code can pass the setting on.</li>
|
||||
</ul>
|
||||
<h4>The Subagents tab</h4>
|
||||
<ul>
|
||||
<li>
|
||||
With the first helper, a <strong>Subagents</strong> tab appears before
|
||||
Ask: one row each, with what it was asked, whether it is running, done
|
||||
or failed, and a one-line result at the end. The number on the tab is
|
||||
how many are still running.
|
||||
</li>
|
||||
<li>
|
||||
Helpers report through Plan2Code, so the rows change at its
|
||||
check-ins, not live. The page cannot stop a helper; ask Plan2Code
|
||||
on the Ask tab if one should stop.
|
||||
</li>
|
||||
<li>
|
||||
<strong>Working alone</strong> means your agent has no way to start
|
||||
helpers here, so it is doing the work itself.
|
||||
</li>
|
||||
<li>
|
||||
Pathfinder always uses helpers for its research questions, whatever
|
||||
the switch says, and they show here too.
|
||||
</li>
|
||||
<li>The tab clears when you go back to the dashboard.</li>
|
||||
</ul>
|
||||
</section>
|
||||
|
||||
<!-- Tab 13: Ask a quick question -->
|
||||
<section class="help-panel" data-tab="ask">
|
||||
<h3>Ask a quick question</h3>
|
||||
<p class="help-lead">
|
||||
@@ -1568,7 +1642,7 @@
|
||||
</p>
|
||||
</section>
|
||||
|
||||
<!-- Tab 13: Stopping and finishing -->
|
||||
<!-- Tab 14: Stopping and finishing -->
|
||||
<section class="help-panel" data-tab="finishing">
|
||||
<h3>Stopping and finishing</h3>
|
||||
<p class="help-lead">
|
||||
@@ -1650,7 +1724,7 @@
|
||||
</p>
|
||||
</section>
|
||||
|
||||
<!-- Tab 14: When something looks stuck -->
|
||||
<!-- Tab 15: When something looks stuck -->
|
||||
<section class="help-panel" data-tab="stuck">
|
||||
<h3>When something looks stuck</h3>
|
||||
<p class="help-lead">
|
||||
@@ -1772,7 +1846,7 @@
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<!-- Tab 15: Keyboard and preferences -->
|
||||
<!-- Tab 16: Keyboard and preferences -->
|
||||
<section class="help-panel" data-tab="prefs">
|
||||
<h3>Keyboard and preferences</h3>
|
||||
<p class="help-lead">
|
||||
@@ -1888,7 +1962,7 @@
|
||||
</ul>
|
||||
</section>
|
||||
|
||||
<!-- Tab 16: Privacy and where things are saved -->
|
||||
<!-- Tab 17: Privacy and where things are saved -->
|
||||
<section class="help-panel" data-tab="privacy">
|
||||
<h3>Privacy and where things are saved</h3>
|
||||
<p class="help-lead">
|
||||
@@ -1925,7 +1999,11 @@
|
||||
</li>
|
||||
<li>
|
||||
your role, theme, colors, card width and sounds, in
|
||||
<code>looks.json</code>.
|
||||
<code>looks.json</code>;
|
||||
</li>
|
||||
<li>
|
||||
your Subagents switch for each project and skill, in
|
||||
<code>subagents.json</code>.
|
||||
</li>
|
||||
</ul>
|
||||
<p>
|
||||
@@ -2039,6 +2117,46 @@
|
||||
</div>
|
||||
</dialog>
|
||||
|
||||
<!-- Subagents: the switch for this skill, filled from the frame's
|
||||
`subagents` by app.js and saved through POST /subagents. It borrows
|
||||
the User Preferences dialog's classes, so it needs no dialog styles of
|
||||
its own, only a themed number box. -->
|
||||
<dialog class="modal looks subagents" id="subagents-modal" aria-labelledby="subagents-title">
|
||||
<h2 id="subagents-title">Subagents</h2>
|
||||
<p class="modal-blurb">
|
||||
Let Plan2Code hand independent work to helpers in this skill. Saved for this
|
||||
project and this skill.
|
||||
</p>
|
||||
<fieldset class="modal-ranges looks-row">
|
||||
<legend>Helpers</legend>
|
||||
<label><input type="radio" name="subagents-on" value="on" /> <span>Use helpers</span></label>
|
||||
<label><input type="radio" name="subagents-on" value="off" checked /> <span>Work alone</span></label>
|
||||
</fieldset>
|
||||
<fieldset class="modal-ranges">
|
||||
<legend>Instruction</legend>
|
||||
<textarea id="subagents-instruction" rows="4" maxlength="2000" aria-label="Instruction"></textarea>
|
||||
<div class="models-actions">
|
||||
<button type="button" class="btn small ghost" id="subagents-default">Reset to default</button>
|
||||
<span class="help">Passed to the agent as written, at its next check-in.</span>
|
||||
</div>
|
||||
</fieldset>
|
||||
<fieldset class="modal-ranges">
|
||||
<legend>At most</legend>
|
||||
<label>
|
||||
<input type="number" id="subagents-max" min="1" max="20" step="1" aria-label="At most this many helpers at once" />
|
||||
<span>helpers at once</span>
|
||||
</label>
|
||||
<p class="help">Advisory: your agent's own limit still applies.</p>
|
||||
</fieldset>
|
||||
<p class="help" id="subagents-checkin"></p>
|
||||
<p class="help" id="subagents-research" hidden></p>
|
||||
<p class="help" id="subagents-status" role="status"></p>
|
||||
<div class="modal-actions">
|
||||
<button type="button" class="btn ghost" id="subagents-cancel">Cancel</button>
|
||||
<button type="button" class="btn primary" id="subagents-save">Save</button>
|
||||
</div>
|
||||
</dialog>
|
||||
|
||||
<!-- The Workspace: the folder this session started in plus any added as
|
||||
context. The list is drawn by app.js from the frame's `workspace`;
|
||||
every change goes through the server's /workspace routes. -->
|
||||
|
||||
@@ -0,0 +1,223 @@
|
||||
// Plan2Code Web Console - the Subagents switch's opt-in table, wording and checks.
|
||||
//
|
||||
// The source of truth for which workflows offer the switch, the instruction
|
||||
// each one ships with, the fixed frame every "on" block carries, the exact
|
||||
// lines the agent reads at a pickup (blockFor()), and the house rules for the
|
||||
// helpers an agent reports back (checkHelper()). No DOM access at module scope
|
||||
// and no imports: the server, console.mjs, the page and `node --test` all
|
||||
// import this file.
|
||||
|
||||
// The one place a skill opts in (FR-1). Wording is behaviour-level and names
|
||||
// no harness tool, so any agent can follow it or harmlessly ignore it.
|
||||
export const SUBAGENT_WORKFLOWS = Object.freeze({
|
||||
implement: Object.freeze({
|
||||
instruction:
|
||||
"Hand independent tasks in a phase to helpers: tasks that touch different files and do not depend on each other. Keep tasks that share files, the phase's tests and the sign-off with you.",
|
||||
}),
|
||||
"implement-review": Object.freeze({
|
||||
instruction:
|
||||
"Hand independent tasks in a phase to helpers: tasks that touch different files and do not depend on each other. Keep tasks that share files, the phase's tests and the sign-off with you.",
|
||||
}),
|
||||
"quick-task": Object.freeze({
|
||||
instruction:
|
||||
"Use helpers for side lookups, such as reading unfamiliar code or checking documentation, while you make the change yourself.",
|
||||
}),
|
||||
review: Object.freeze({
|
||||
instruction:
|
||||
"Split the review across helpers by area (for example correctness, tests and security), then merge and de-duplicate their findings yourself before you report.",
|
||||
}),
|
||||
pathfinder: Object.freeze({
|
||||
instruction:
|
||||
"Use helpers for codebase recon, sketches and lookups beside the conversation. Keep every question for the person with you.",
|
||||
}),
|
||||
});
|
||||
|
||||
export function offered(workflow) {
|
||||
return typeof workflow === "string" && Object.prototype.hasOwnProperty.call(SUBAGENT_WORKFLOWS, workflow);
|
||||
}
|
||||
|
||||
export const MAX_MIN = 1;
|
||||
export const MAX_MAX = 20;
|
||||
export const DEFAULT_MAX = 3;
|
||||
export const INSTRUCTION_MAX_CHARS = 2000;
|
||||
export const HELPER_TITLE_MAX = 80;
|
||||
export const HELPER_ASK_MAX = 400;
|
||||
export const HELPER_RESULT_MAX = 200;
|
||||
export const HELPER_STATES = Object.freeze(["running", "done", "failed"]);
|
||||
|
||||
/* ------------------------------------------------------------- settings */
|
||||
|
||||
export function defaultInstruction(workflow) {
|
||||
return offered(workflow) ? SUBAGENT_WORKFLOWS[workflow].instruction : "";
|
||||
}
|
||||
|
||||
// The person's own text when they wrote some, else the workflow's default.
|
||||
export function effectiveInstruction(setting) {
|
||||
const own = setting && typeof setting.instruction === "string" ? setting.instruction.trim() : "";
|
||||
return own || defaultInstruction(setting && setting.workflow);
|
||||
}
|
||||
|
||||
export function defaultSetting(workflow) {
|
||||
return { workflow, on: false, instruction: null, max: DEFAULT_MAX };
|
||||
}
|
||||
|
||||
/**
|
||||
* `{ on, instruction, max }` from untrusted input, or `{ error }` naming the
|
||||
* field that failed: "bad" (wrong type), "too-long" (instruction) or "max".
|
||||
* Returns an error object rather than throwing, so the route and the store
|
||||
* reader share one validator. An empty instruction means the default: null.
|
||||
*/
|
||||
export function cleanSetting(input) {
|
||||
if (!input || typeof input !== "object" || Array.isArray(input)) return { error: "bad" };
|
||||
if (typeof input.on !== "boolean") return { error: "bad" };
|
||||
let instruction = null;
|
||||
if (input.instruction !== null && input.instruction !== undefined) {
|
||||
if (typeof input.instruction !== "string") return { error: "bad" };
|
||||
const trimmed = input.instruction.trim();
|
||||
if (trimmed.length > INSTRUCTION_MAX_CHARS) return { error: "too-long" };
|
||||
instruction = trimmed || null;
|
||||
}
|
||||
const max = input.max;
|
||||
if (!Number.isInteger(max) || max < MAX_MIN || max > MAX_MAX) return { error: "max" };
|
||||
return { on: input.on, instruction, max };
|
||||
}
|
||||
|
||||
/* ------------------------------------------------------------ the lines */
|
||||
|
||||
// The non-editable part of every "on" block (FR-8).
|
||||
export const FRAME_LINES = Object.freeze([
|
||||
"Hand independent work to helpers if your tools allow it; otherwise carry on alone.",
|
||||
"Report each helper on the page (console.md → Standing instructions); questions for the person stay with you.",
|
||||
'With no way to start helpers, report one "working alone" entry for this skill run instead.',
|
||||
]);
|
||||
|
||||
export const PATHFINDER_RESEARCH_LINE = "Research questions always use helpers, whatever this switch says.";
|
||||
|
||||
// Only the first line of a block starts at column 0, so no line inside it can
|
||||
// be read as an entry of its own (NFR-5).
|
||||
export function onLines({ revision, replaces, max, instruction }) {
|
||||
const label = replaces ? `revision ${revision}, replaces revision ${replaces}` : `revision ${revision}`;
|
||||
const own = String(instruction || "")
|
||||
.split("\n")
|
||||
.map((line) => line.trimEnd())
|
||||
.filter((line) => line.trim());
|
||||
return [
|
||||
`Subagents: on (${label}) — a console setting, not typed by the person.`,
|
||||
...[...FRAME_LINES, ...own, `At most ${max} helpers at once.`].map((line) => " " + line),
|
||||
];
|
||||
}
|
||||
|
||||
export function offLine(revision) {
|
||||
return `Subagents: off (revision ${revision}) — don't start new helpers for the rest of this session.`;
|
||||
}
|
||||
|
||||
/**
|
||||
* What the agent is owed at a pickup, given the session setting and the
|
||||
* cursor of what it was last told: `null`, or `{ field, lines, cursor }`
|
||||
* where `cursor` is what to write once the lines are printed. Never says
|
||||
* "off" to an agent that was not told "on" (FR-6). Pure: no clock, no I/O.
|
||||
*/
|
||||
export function blockFor(setting, told) {
|
||||
const last = told || { revision: 0, state: "none" };
|
||||
if (!setting || !offered(setting.workflow) || !(setting.revision > last.revision)) return null;
|
||||
const { revision, max } = setting;
|
||||
const instruction = effectiveInstruction(setting);
|
||||
if (setting.on) {
|
||||
const replaces = last.state === "on" ? last.revision : undefined;
|
||||
return {
|
||||
field: { state: "on", revision, max, instruction },
|
||||
lines: onLines({ revision, replaces, max, instruction }),
|
||||
cursor: { revision, state: "on" },
|
||||
};
|
||||
}
|
||||
if (last.state !== "on") return null;
|
||||
return {
|
||||
field: { state: "off", revision, max, instruction },
|
||||
lines: [offLine(revision)],
|
||||
cursor: { revision, state: "off" },
|
||||
};
|
||||
}
|
||||
|
||||
/* ------------------------------------------------------------ helpers */
|
||||
|
||||
const isPlainObject = (v) => !!v && typeof v === "object" && !Array.isArray(v);
|
||||
const nonEmpty = (v) => typeof v === "string" && v.trim() !== "";
|
||||
|
||||
// The problems with one reported helper, [] when it is fine.
|
||||
export function checkHelper(entry) {
|
||||
if (!isPlainObject(entry)) return ["helper: each entry must be an object"];
|
||||
if (!nonEmpty(entry.id)) return ["helper: id must be a non-empty string"];
|
||||
const who = `helper "${entry.id}"`;
|
||||
if (entry.alone === true) return entry.id === "alone" ? [] : [`${who}: the working-alone entry must have id "alone"`];
|
||||
const problems = [];
|
||||
if (!nonEmpty(entry.title)) problems.push(`${who}: title must be a non-empty string`);
|
||||
else if (entry.title.length > HELPER_TITLE_MAX) problems.push(`${who}: title must be at most ${HELPER_TITLE_MAX} characters`);
|
||||
if (!nonEmpty(entry.ask)) problems.push(`${who}: ask must be a non-empty string`);
|
||||
else if (entry.ask.length > HELPER_ASK_MAX) problems.push(`${who}: ask must be at most ${HELPER_ASK_MAX} characters`);
|
||||
if (!HELPER_STATES.includes(entry.state)) problems.push(`${who}: state must be running, done or failed`);
|
||||
if (entry.result !== undefined) {
|
||||
if (typeof entry.result !== "string") problems.push(`${who}: result must be a string`);
|
||||
else if (entry.result.length > HELPER_RESULT_MAX) problems.push(`${who}: result must be at most ${HELPER_RESULT_MAX} characters`);
|
||||
}
|
||||
return problems;
|
||||
}
|
||||
|
||||
// The problems with a whole merged list.
|
||||
export function checkHelpers(list) {
|
||||
if (!Array.isArray(list)) return ["helpers must be an array"];
|
||||
const problems = [];
|
||||
const seen = new Set();
|
||||
let alone = 0;
|
||||
for (const entry of list) {
|
||||
if (isPlainObject(entry) && nonEmpty(entry.id)) {
|
||||
if (seen.has(entry.id)) problems.push(`helper "${entry.id}": duplicate id`);
|
||||
seen.add(entry.id);
|
||||
if (entry.alone === true && ++alone === 2) problems.push(`helper "${entry.id}": only one working-alone entry is allowed`);
|
||||
}
|
||||
problems.push(...checkHelper(entry));
|
||||
}
|
||||
return problems;
|
||||
}
|
||||
|
||||
/* ------------------------------------------------------------ the page */
|
||||
|
||||
// The page's rules for the button, the modal and the tab, kept here so they
|
||||
// are tested without a browser. `frame` is the state frame's `subagents`
|
||||
// block; app.js only renders what these say.
|
||||
|
||||
export const CHECKIN_LINE = "Helpers report through Plan2Code, so their progress shows here at its check-ins, not live.";
|
||||
|
||||
const STATE_LABELS = Object.freeze({ running: "Running", done: "Done", failed: "Failed" });
|
||||
|
||||
// The switch shows only where the skill opts in AND the agent's console copy
|
||||
// said it can deliver it (FR-3).
|
||||
export function showSwitch(frame) {
|
||||
return Boolean(frame && frame.offered && frame.supported);
|
||||
}
|
||||
|
||||
// The button's tooltip and accessible name (FR-2).
|
||||
export function switchLabel(frame) {
|
||||
return frame && frame.on ? "Subagents: on" : "Subagents: off";
|
||||
}
|
||||
|
||||
// What the Subagents tab draws: the working-alone note, or one row per helper
|
||||
// in the order the agent reported them. A result shows once the helper ended.
|
||||
export function helperRows(helpers) {
|
||||
const list = Array.isArray(helpers) ? helpers.filter(isPlainObject) : [];
|
||||
if (list.some((h) => h.alone === true)) return { alone: true, rows: [] };
|
||||
const rows = list.map(({ id, title, ask, state, result }) => ({
|
||||
id,
|
||||
title,
|
||||
ask,
|
||||
state,
|
||||
stateLabel: STATE_LABELS[state] || STATE_LABELS.running,
|
||||
...((state === "done" || state === "failed") && typeof result === "string" && result ? { result } : {}),
|
||||
}));
|
||||
return { alone: false, rows };
|
||||
}
|
||||
|
||||
// Never an empty tab. Independent of on / off, so Pathfinder's research
|
||||
// helpers show even with the switch off (FR-11, FR-12).
|
||||
export function showTab(frame, helpers) {
|
||||
return showSwitch(frame) && Array.isArray(helpers) && helpers.length > 0;
|
||||
}
|
||||
@@ -25,6 +25,7 @@ import {
|
||||
LOOKS_FILE,
|
||||
PUBLIC_DIR,
|
||||
SHIPPED_MODELS_FILE,
|
||||
SUBAGENTS_SETTING_FILE,
|
||||
UPDATE_CHECK_FILE,
|
||||
USER_MODELS_FILE,
|
||||
WORKSPACE_FILE,
|
||||
@@ -38,6 +39,7 @@ import {
|
||||
fileStamp,
|
||||
handleFile,
|
||||
initialWorkspace,
|
||||
latestOpenCaps,
|
||||
nowIso,
|
||||
parseArgs,
|
||||
pendingChatCount,
|
||||
@@ -46,20 +48,25 @@ import {
|
||||
readJson,
|
||||
readLedger,
|
||||
readOverview,
|
||||
readSubagentSetting,
|
||||
readWorkspace,
|
||||
rememberWorkspace,
|
||||
rememberedWorkspace,
|
||||
removeCleanup,
|
||||
remoteWarning,
|
||||
saveSubagentStoreEntry,
|
||||
specKey,
|
||||
subagentStoreEntry,
|
||||
typedCount,
|
||||
withStateLock,
|
||||
writeJsonAtomic,
|
||||
writeSubagentSetting,
|
||||
writeWorkspace,
|
||||
} from "./lib.mjs";
|
||||
import { DOC_TYPES, MAX_ATTACHMENTS, MAX_DOC_BYTES, docExt, workflowLabel, workflowTitle } from "./public/answers.js";
|
||||
import { CHAT_LIMIT, CHAT_MAX_CHARS, chatOffline } from "./public/chat.js";
|
||||
import { meterView } from "./public/meter.js";
|
||||
import { cleanSetting, defaultSetting, offered } from "./public/subagents.js";
|
||||
import { ACCENTS, DEFAULT_ACCENT, DEFAULT_CARD_WIDTH, cardWidth } from "./public/palette.js";
|
||||
import { defaultName, freeName, nameProblem } from "./public/workspace.js";
|
||||
import { checkForUpdate } from "./update-check.mjs";
|
||||
@@ -212,6 +219,7 @@ const SERVABLE = new Set([
|
||||
"starters.js",
|
||||
"workspace.js",
|
||||
"meter.js",
|
||||
"subagents.js",
|
||||
"mentions.js",
|
||||
"favicon.js",
|
||||
"start-stop.mp3",
|
||||
@@ -601,6 +609,48 @@ function ensureConversation(state) {
|
||||
if (entry) appendEvent(DIR, { type: "chat-reset", reason: entry.reason });
|
||||
}
|
||||
|
||||
/* ------------------------------------------------------------ subagents */
|
||||
|
||||
// subagents-setting.json has one writer, this server, and the agent hears of
|
||||
// it only through what console.mjs reads there; events.ndjson's latest `open`
|
||||
// says whether the agent's console copy can carry it. Both re-read only when
|
||||
// their file has moved.
|
||||
const SUBAGENTS_SETTING_PATH = path.join(DIR, SUBAGENTS_SETTING_FILE);
|
||||
const EVENTS_PATH = path.join(DIR, "events.ndjson");
|
||||
|
||||
let subagentSettingSeen = { stamp: null, setting: null };
|
||||
function subagentSettingNow() {
|
||||
const stamp = fileStamp(SUBAGENTS_SETTING_PATH);
|
||||
if (stamp !== subagentSettingSeen.stamp) subagentSettingSeen = { stamp, setting: readSubagentSetting(DIR) };
|
||||
return subagentSettingSeen.setting;
|
||||
}
|
||||
|
||||
let capsSeen = { stamp: null, caps: [] };
|
||||
function openCapsNow() {
|
||||
const stamp = fileStamp(EVENTS_PATH);
|
||||
if (stamp !== capsSeen.stamp) capsSeen = { stamp, caps: latestOpenCaps(DIR) };
|
||||
return capsSeen.caps;
|
||||
}
|
||||
|
||||
const sameSetting = (a, b) => a.workflow === b.workflow && a.on === b.on && a.instruction === b.instruction && a.max === b.max;
|
||||
|
||||
/**
|
||||
* Turn the per-project store into this session's setting, for the workflow
|
||||
* the session is in now. The only place that happens (FR-7): a session an
|
||||
* older server ran has no setting file, so nothing is ever injected into it.
|
||||
* A record that already matches is left alone, revision and all, so a
|
||||
* restart alone never re-tells the agent anything.
|
||||
*/
|
||||
function syncSubagentSetting(state) {
|
||||
if (!state || typeof state.workflow !== "string") return;
|
||||
const { workflow } = state;
|
||||
const { on, instruction, max } = offered(workflow) ? subagentStoreEntry(sessionWorktree(), workflow) : defaultSetting(workflow);
|
||||
const target = { workflow, on, instruction, max };
|
||||
const current = readSubagentSetting(DIR);
|
||||
if (current && sameSetting(current, target)) return;
|
||||
writeSubagentSetting(DIR, { ...target, revision: (current ? current.revision : 0) + 1 });
|
||||
}
|
||||
|
||||
// What the page needs to draw itself, in the shape of the SSE state frame.
|
||||
// `have` names that exact view, for the page to hand back when it opens its
|
||||
// stream (see /events).
|
||||
@@ -615,20 +665,33 @@ function stateFrame(state) {
|
||||
chat: { ...chatForFrame(chatEntries(), state), pickedUp: chatPickedUp(), offline: chatOfflineNow(state) },
|
||||
workspace: workspaceView(),
|
||||
meter: meterView(ledgerEntries()),
|
||||
subagents: subagentsView(state),
|
||||
...(updateInfo ? { update: updateInfo } : {}),
|
||||
have: haveKey(),
|
||||
};
|
||||
}
|
||||
|
||||
// The page shows the switch only when `offered && supported` (FR-3); the
|
||||
// frame says both and leaves combining them to the page. `instruction: null`
|
||||
// is the shipped default, which the page reads from subagents.js itself.
|
||||
function subagentsView(state) {
|
||||
const workflow = state && state.workflow;
|
||||
const { on, instruction, max, revision } = subagentSettingNow() || { ...defaultSetting(workflow), revision: 0 };
|
||||
return { offered: offered(workflow), supported: openCapsNow().includes("subagents"), on, instruction, max, revision };
|
||||
}
|
||||
|
||||
function haveKey() {
|
||||
const { pending, stop } = resultFlags();
|
||||
chatEntries();
|
||||
chatPickedUp();
|
||||
workspaceNow();
|
||||
ledgerEntries();
|
||||
subagentSettingNow();
|
||||
openCapsNow();
|
||||
return (
|
||||
`${STARTED}.${rev}.${pending ? 1 : 0}${stop ? 1 : 0}.${chatSeen.stamp || ""}.${cursorSeen.stamp || ""}` +
|
||||
`.${workspaceSeen.stamp || ""}.${ledgerSeen.stamp || ""}.${updateInfo ? updateInfo.latest : ""}`
|
||||
`.${workspaceSeen.stamp || ""}.${ledgerSeen.stamp || ""}.${updateInfo ? updateInfo.latest : ""}` +
|
||||
`.${subagentSettingSeen.stamp || ""}.${capsSeen.stamp || ""}`
|
||||
);
|
||||
}
|
||||
|
||||
@@ -1172,6 +1235,39 @@ const server = http.createServer((req, res) => {
|
||||
});
|
||||
}
|
||||
|
||||
// The Subagents switch for the session's workflow. Saved per project folder
|
||||
// for the next session, and applied to this one with a bumped revision, which
|
||||
// is what console.mjs hands the agent at its next pickup. Never blocked by,
|
||||
// and never blocking, a card send.
|
||||
if (pathname === "/subagents" && req.method === "POST") {
|
||||
if (!originOk(req, port)) return json(res, 403, { error: "bad origin" });
|
||||
return readBody(req, (err, body) => {
|
||||
if (err) return json(res, err.tooBig ? 413 : 400, { error: err.tooBig ? "too large" : "body must be JSON" });
|
||||
const state = readState();
|
||||
if (!state || !offered(state.workflow)) return json(res, 400, { error: "not-offered" });
|
||||
const clean = cleanSetting(body);
|
||||
if (clean.error) return json(res, 400, { error: clean.error });
|
||||
const { on, instruction, max } = clean;
|
||||
const current = readSubagentSetting(DIR);
|
||||
const next = { workflow: state.workflow, on, instruction, max };
|
||||
// The store is per project, so another session may have moved it since
|
||||
// this one synced: it always takes the person's latest pick. Only a
|
||||
// real change to this session's setting bumps what the agent hears.
|
||||
const unchanged = Boolean(current && sameSetting(current, next));
|
||||
try {
|
||||
saveSubagentStoreEntry(sessionWorktree(), state.workflow, { on, instruction, max });
|
||||
if (!unchanged) writeSubagentSetting(DIR, { ...next, revision: (current ? current.revision : 0) + 1 });
|
||||
} catch (e) {
|
||||
return json(res, 500, { error: String(e.message) });
|
||||
}
|
||||
if (unchanged) return json(res, 200, { ok: true, setting: current });
|
||||
const setting = readSubagentSetting(DIR);
|
||||
appendEvent(DIR, { type: "subagents", on, revision: setting.revision });
|
||||
pushState();
|
||||
return json(res, 200, { ok: true, setting });
|
||||
});
|
||||
}
|
||||
|
||||
// The launcher's model menu: what ships (read-only here) and what the user added.
|
||||
if (pathname === "/models" && req.method === "GET") {
|
||||
const saved = readJson(USER_MODELS_FILE, null) || {};
|
||||
@@ -1400,6 +1496,9 @@ const server = http.createServer((req, res) => {
|
||||
try {
|
||||
ensureConversation(written.state);
|
||||
} catch {}
|
||||
try {
|
||||
syncSubagentSetting(written.state);
|
||||
} catch {}
|
||||
}
|
||||
}
|
||||
// Name the items that went. A page with OTHER answers staged should drop
|
||||
@@ -1726,6 +1825,9 @@ function checkState() {
|
||||
try {
|
||||
ensureConversation(parsed);
|
||||
} catch {}
|
||||
try {
|
||||
syncSubagentSetting(parsed);
|
||||
} catch {}
|
||||
try {
|
||||
followSpecDir(parsed);
|
||||
} catch {}
|
||||
@@ -1900,6 +2002,9 @@ function onListening(port) {
|
||||
try {
|
||||
bootWorkspace();
|
||||
} catch {}
|
||||
try {
|
||||
syncSubagentSetting(readState());
|
||||
} catch {}
|
||||
process.stdout.write(JSON.stringify({ type: "ready", url, port, sid: SID }) + "\n");
|
||||
try {
|
||||
startUpdateCheck();
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "Plan2Code",
|
||||
"version": "2.4.2",
|
||||
"version": "2.5.0",
|
||||
"description": "A structured 4-step workflow methodology for AI-assisted software development",
|
||||
"keywords": [
|
||||
"ai",
|
||||
@@ -17,6 +17,6 @@
|
||||
"url": "https://github.com/jparkerweb/plan2code"
|
||||
},
|
||||
"homepage": "https://github.com/jparkerweb/plan2code",
|
||||
"releaseDate": "2026-10-05",
|
||||
"releaseDate": "2026-10-06",
|
||||
"mode": "utility"
|
||||
}
|
||||
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "Plan2Code",
|
||||
"version": "2.4.2",
|
||||
"version": "2.5.0",
|
||||
"description": "A structured 4-step workflow methodology for AI-assisted software development",
|
||||
"keywords": [
|
||||
"ai",
|
||||
@@ -17,6 +17,6 @@
|
||||
"url": "https://github.com/jparkerweb/plan2code"
|
||||
},
|
||||
"homepage": "https://github.com/jparkerweb/plan2code",
|
||||
"releaseDate": "2026-10-05",
|
||||
"releaseDate": "2026-10-06",
|
||||
"mode": "utility"
|
||||
}
|
||||
@@ -64,6 +64,13 @@ progress bar is the first thing someone watching a build looks at. The session
|
||||
meter counts the build's tasks from `cleared` as it rises, so keep it current,
|
||||
and start every phase (a second one in the same run too) at `"cleared": 0`.
|
||||
|
||||
`"version": 1` is for the first phase of a session only. A doc's version
|
||||
never goes back (console.md → House rules, rule 9), so a later phase in the
|
||||
same session reposts `phase` and `phasefile` at one more than the version the
|
||||
page holds, with the new phase's title and content. The same goes for
|
||||
`report` at sign-off and `review` in a mid-session review: version 1 the
|
||||
first time, then up from wherever the page has it.
|
||||
|
||||
`phasefile` is the whole `phase-X.md`, verbatim from disk, as its own tab —
|
||||
the person can read the prerequisites and task specs while you build. Re-post
|
||||
it whenever the file changes, which is every task: the checkbox write that
|
||||
@@ -111,6 +118,12 @@ printed), never into the project or into `~/.plan2code/console/` directly:
|
||||
- Do not call `wait` while building. There is nothing to collect, and the page
|
||||
holds anything the person sends until you next look.
|
||||
|
||||
A build may receive a `Subagents:` standing instruction, on `open` output or a
|
||||
`chat` check between tasks. Follow console.md → Standing instructions for
|
||||
handing independent tasks to helpers and reporting them as `helpers`. Keep the
|
||||
per-task progress posts, the checkbox writes, the chat checks and the sign-off
|
||||
with you.
|
||||
|
||||
### Quick questions between tasks
|
||||
|
||||
The person can ask a Quick question on the Ask tab at any point in a build
|
||||
@@ -195,7 +208,8 @@ only ever be offered once nothing could come of it:
|
||||
`reply` carries `Approve this phase: approved`, which is the terminal's
|
||||
`approved`. If the note that came with an approval asks for a change, treat it
|
||||
as "describe any issues": do the change first and ask again. `changes` means
|
||||
exactly what it says: address it, bump the report's version, and reopen the
|
||||
exactly what it says: address it, bump the report's version (a later phase's
|
||||
report starts above the last one's, too), and reopen the
|
||||
item (`"status": "reopened"`) with a reply in its `thread`. `review` is the
|
||||
person asking for the code review before they approve anything — see "The
|
||||
review, mid-session" below.
|
||||
|
||||
@@ -170,7 +170,7 @@ so even a kill at the worst possible moment costs you a repeat, never an answer.
|
||||
|
||||
| Exit | Meaning | What you do |
|
||||
| --- | --- | --- |
|
||||
| `0` | They pressed Send, or asked a Quick question. stdout is the result JSON, and may carry `workspace` (changes to the folder list, see Workspace). | Handle the cards (if any), the chat (if any) and any `workspace` changes, then post once (below, Quick questions and Workspace). |
|
||||
| `0` | They pressed Send, or asked a Quick question. stdout is the result JSON, and may carry `workspace` (changes to the folder list, see Workspace) and `subagents` (the helpers switch, see Standing instructions). | Handle the cards (if any), the chat (if any), any `workspace` changes and any `subagents` block, then post once (below, Quick questions, Workspace and Standing instructions). |
|
||||
| `10` | Still working. stdout has a short progress summary; `pendingWorkspace` counts workspace changes waiting for the next send. | Relay ONE line: the `message` field itself, "Waiting on your answer in the web console", followed by the `terminalLine`. Then call `wait` again. |
|
||||
| `20` | The server is gone. | `open --resume <sid>`, give them the new link, then keep waiting. |
|
||||
| `30` | They pressed Cancel. | Stop. Ask what they want to do, in the terminal. |
|
||||
@@ -647,6 +647,84 @@ for permission is not a failure; report only a read that failed after it.
|
||||
|
||||
---
|
||||
|
||||
## Standing instructions
|
||||
|
||||
On the skills that offer it (`implement`, `implement-review`, `quick-task`,
|
||||
`review`, `pathfinder`), the person can turn **helpers** (subagents) on or off
|
||||
from the top bar's Subagents button. Their pick is saved per project and per
|
||||
skill, off by default, and reaches you as a standing instruction, only when it
|
||||
changes.
|
||||
|
||||
### What arrives
|
||||
|
||||
A `subagents` field beside `reply`, and `Subagents:` lines last in `reply`,
|
||||
after the card lines, the `Quick question:` blocks and the `Workspace:` lines.
|
||||
It rides on `wait` exit `0`, `chat` exit `0` and `open` output. A setting
|
||||
change alone never ends a `wait` slice: it waits for the next send, or for
|
||||
your next `chat` check.
|
||||
|
||||
```
|
||||
Subagents: on (revision 2) — a console setting, not typed by the person.
|
||||
Hand independent work to helpers if your tools allow it; otherwise carry on alone.
|
||||
Report each helper on the page (console.md → Standing instructions); questions for the person stay with you.
|
||||
With no way to start helpers, report one "working alone" entry for this skill run instead.
|
||||
Hand independent tasks in a phase to helpers: tasks that touch different files and do not depend on each other. Keep tasks that share files, the phase's tests and the sign-off with you.
|
||||
At most 3 helpers at once.
|
||||
```
|
||||
|
||||
beside `"subagents": { "state": "on", "revision": 2, "max": 3, "instruction": "…" }`.
|
||||
An edit while on arrives as `Subagents: on (revision 3, replaces revision 2) — …`
|
||||
with the whole block again; switching off arrives as one line:
|
||||
`Subagents: off (revision 4) — don't start new helpers for the rest of this session.`
|
||||
|
||||
It is a console setting, not something the person typed. It never answers a
|
||||
card, and it is never recorded under `specs/`.
|
||||
|
||||
### Obeying it
|
||||
|
||||
- **On:** hand independent work to helpers if your tools allow it, at most
|
||||
`max` at once, following the instruction lines. `max` is advisory: your
|
||||
harness's own limit still applies.
|
||||
- **A higher revision replaces a lower one.** Follow the latest block only.
|
||||
- **Off:** start no new helpers for the rest of the session. Let running ones
|
||||
finish and report them.
|
||||
- **Nothing arrives:** keep doing what the skill says.
|
||||
- **Scope is the skill run it arrived in.** After a dashboard launch, no block
|
||||
means the switch is off for this skill, even if an earlier skill in the same
|
||||
conversation was told "on": `open` starts the count again, and a launch with
|
||||
the switch off sends nothing.
|
||||
|
||||
### Reporting helpers
|
||||
|
||||
Post them, at your check-ins, so the page's Subagents tab can show them. The
|
||||
page never hears from a helper directly:
|
||||
|
||||
```jsonc
|
||||
{ "helpers": [
|
||||
{ "id": "h1", "title": "Read the store helpers", "ask": "Find every caller of readSubagentSetting.", "state": "running" },
|
||||
{ "id": "h2", "title": "Check the tests", "ask": "Run the subagents tests and report failures.", "state": "done", "result": "All 9 pass." }
|
||||
] }
|
||||
```
|
||||
|
||||
- `id` (non-empty), `title` (at most 80 characters), `ask` (at most 400) and
|
||||
`state` (`running`, `done` or `failed`) are required; `result` (at most 200)
|
||||
is the one line you add once a helper ends.
|
||||
- Merged by `id`: post a helper again with its new `state` and `result` and it
|
||||
updates in place. `"helpers": null` clears the list. A dashboard hop clears it
|
||||
too; a resume into the same skill keeps it.
|
||||
- One post per change worth seeing, not a stream.
|
||||
- Questions for the person stay with you, never with a helper: most harnesses
|
||||
give helpers no way to ask, and an answer only reaches the agent holding the
|
||||
session.
|
||||
- **No way to start helpers?** Post one `{ "id": "alone", "alone": true }`
|
||||
entry for the skill run instead. The tab then says you are working alone.
|
||||
- **Pathfinder:** research questions always use helpers and are always
|
||||
reported, whatever the switch says. The switch governs recon, sketches and
|
||||
lookups beside the conversation.
|
||||
- Helpers add no session meter points. Post no `run` for them.
|
||||
|
||||
---
|
||||
|
||||
## Launches (dashboard only)
|
||||
|
||||
A `dashboard` session is not a conversation: the page draws a menu of every
|
||||
@@ -763,7 +841,10 @@ commands follow the pipeline: the sign-off's is
|
||||
|
||||
### Review (`review`)
|
||||
|
||||
Scope questions up front, then the findings report as a doc (`id: "report"`),
|
||||
Scope questions up front — run standalone with nothing named, the first is
|
||||
a `choice`, "What should I review?", built from a quick scan (branch changes,
|
||||
uncommitted changes, specs, files you name; each option with its size),
|
||||
never an assumed target; a build's review skips it (`building.md`). Then the findings report as a doc (`id: "report"`),
|
||||
then the pick-what-gets-fixed menu as a `multi` or `choice` keyed by finding
|
||||
id, carrying `"doc": "report"` so the card links straight to the findings.
|
||||
Settle that item (`"status": "answered"` plus the `answer` they sent) in
|
||||
@@ -797,6 +878,8 @@ that is what the person is there to download. The finish carries no
|
||||
- Chart Step 8's research subagents must all report back before the
|
||||
finish (Finishing → Nothing of yours may still be running); the finish
|
||||
body then names what each one found.
|
||||
- Report every research subagent as a helper, whatever the Subagents switch
|
||||
says (Standing instructions → Reporting helpers).
|
||||
- At every session end, post `finish` (headline, `body`, and Form A's command as
|
||||
`command`) BEFORE `stop`. Someone who spent the session in the browser never
|
||||
sees the Trail Footer, and without this their last screen promises a question
|
||||
@@ -1146,6 +1229,16 @@ A patch that breaks one of these is rejected with exit `3` and a message:
|
||||
(Session meter) and a non-empty `id`; a `folderIssue` needs non-empty
|
||||
`name` and `reason` strings, and `hint`, when present, is one too. Rules 4
|
||||
and 5 cover `reason` and `hint`.
|
||||
8. **`helpers` entries are well formed** (Standing instructions → Reporting
|
||||
helpers): an array of objects, each with a unique `id`, a `title`, an `ask`
|
||||
and a known `state` within their limits, plus at most one `alone` entry.
|
||||
Rules 4 and 5 cover `title`, `ask` and `result`.
|
||||
9. **A doc's `version` never goes back.** Sending a known doc a lower
|
||||
`version` than the page holds is refused: it is almost always a stale or
|
||||
copied payload. The same version again is fine, and a dashboard hop starts
|
||||
every doc fresh. Anything else reusing a doc id in the same session (a
|
||||
build's second phase, a second report or review) continues from the
|
||||
version the page holds.
|
||||
|
||||
These are workflow rules you already follow. The server just makes them checkable.
|
||||
|
||||
@@ -1167,7 +1260,9 @@ cannot see them, and the moment it says the session ended, the person is
|
||||
free to close that terminal and kill them mid-write. While you wait, post
|
||||
`{"agent":{"status":"working","activity":"Researching 3 questions (1 of 3 back)"}}`
|
||||
and update the count as each returns. Never write a `finish.body` that says
|
||||
work "is running in the background" or "will finish on its own".
|
||||
work "is running in the background" or "will finish on its own". Mark every
|
||||
reported helper `done` or `failed` before the finish, so the Subagents tab
|
||||
never ends on a row still running.
|
||||
|
||||
### 1. Post the finish
|
||||
|
||||
|
||||
@@ -64,6 +64,8 @@ import {
|
||||
readChat,
|
||||
readJson,
|
||||
readLedger,
|
||||
readSubagentCursor,
|
||||
readSubagentSetting,
|
||||
readWorkspace,
|
||||
reapHandles,
|
||||
rememberedWorkspace,
|
||||
@@ -71,6 +73,7 @@ import {
|
||||
removeScratch,
|
||||
removeSessions,
|
||||
repoRoots,
|
||||
resetSubagentCursor,
|
||||
scanProject,
|
||||
SESSION_MAX_AGE_MS,
|
||||
sessionDir,
|
||||
@@ -88,9 +91,11 @@ import {
|
||||
workspaceForAgent,
|
||||
writeCursor,
|
||||
writeJsonAtomic,
|
||||
writeSubagentCursor,
|
||||
writeWorkspaceCursor,
|
||||
} from "./lib.mjs";
|
||||
import { RUN_EVENTS, TASK_EVENTS, MAX_TASKS, isTaskCount, progressEntry } from "./public/meter.js";
|
||||
import { blockFor, offered } from "./public/subagents.js";
|
||||
import { changeLine } from "./public/workspace.js";
|
||||
|
||||
// Mirrors the server's absolute lifetime cap: a handle older than this cannot
|
||||
@@ -310,7 +315,11 @@ async function cmdOpen() {
|
||||
die(`could not write the session state: ${written ? written.error : "unknown"}`, 1);
|
||||
}
|
||||
state = written.state;
|
||||
appendEvent(dir, { type: "open", resumed: Boolean(args.resume || args.session), carried });
|
||||
appendEvent(dir, { type: "open", resumed: Boolean(args.resume || args.session), carried, caps: ["subagents"] });
|
||||
// A new agent conversation has been told nothing yet (FR-6).
|
||||
try {
|
||||
resetSubagentCursor(dir);
|
||||
} catch {}
|
||||
trace("open: state written");
|
||||
|
||||
// Dashboard launches are recorded too (they score nothing), so the folder
|
||||
@@ -337,9 +346,18 @@ async function cmdOpen() {
|
||||
removeScratch(HOME_DIR, sweptScratch).catch(() => {});
|
||||
};
|
||||
|
||||
// A standing instruction the new agent is owed, as `subagents` and a
|
||||
// `reply` holding only its lines; neither key when nothing is owed.
|
||||
const subagentsOwed = () => {
|
||||
awaitSubagentSync(dir, state.workflow);
|
||||
const [out, cursor] = withSubagents(dir, { reply: "" });
|
||||
return [out.subagents ? out : {}, cursor];
|
||||
};
|
||||
|
||||
// Reuse a live server if one is already serving this session.
|
||||
if (existing && (await reusable)) {
|
||||
if (!args["no-open"]) openBrowser(existing.url);
|
||||
const [owed, subCursor] = subagentsOwed();
|
||||
print({
|
||||
ok: true,
|
||||
sid,
|
||||
@@ -349,9 +367,11 @@ async function cmdOpen() {
|
||||
pendingResult: carried,
|
||||
terminalLine: terminalLine(existing.url),
|
||||
workspace,
|
||||
...owed,
|
||||
...swept,
|
||||
...remoteWarning(),
|
||||
});
|
||||
advanceSubagents(dir, subCursor);
|
||||
sweep();
|
||||
return;
|
||||
}
|
||||
@@ -384,6 +404,7 @@ async function cmdOpen() {
|
||||
const notes = [];
|
||||
if (remote.note) notes.push(remote.note);
|
||||
if (carried) notes.push("Answers are already waiting. Run `wait` to collect them.");
|
||||
const [owed, subCursor] = subagentsOwed();
|
||||
print({
|
||||
ok: true,
|
||||
sid,
|
||||
@@ -394,10 +415,12 @@ async function cmdOpen() {
|
||||
pendingResult: carried,
|
||||
terminalLine: terminalLine(handle.url),
|
||||
workspace,
|
||||
...owed,
|
||||
...swept,
|
||||
...(remote.remote ? { remote: remote.remote } : {}),
|
||||
...(notes.length ? { note: notes.join(" ") } : {}),
|
||||
});
|
||||
advanceSubagents(dir, subCursor);
|
||||
// After the print, never before it: the page and the link wait for nothing.
|
||||
sweep();
|
||||
}
|
||||
@@ -774,7 +797,7 @@ function serverGone(sid) {
|
||||
|
||||
// Quick questions and nothing else: an ordinary exit 0 with no card actions.
|
||||
function deliverChat(dir, sid, entries, url) {
|
||||
const [out, changes] = withWorkspace(dir, {
|
||||
const [withWs, changes] = withWorkspace(dir, {
|
||||
type: "chat",
|
||||
at: nowIso(),
|
||||
sid,
|
||||
@@ -782,9 +805,11 @@ function deliverChat(dir, sid, entries, url) {
|
||||
chat: entries,
|
||||
reply: chatReplyLines(entries),
|
||||
});
|
||||
const [out, subCursor] = withSubagents(dir, withWs);
|
||||
print({ ...out, ...(url ? { terminalLine: terminalLine(url) } : {}) });
|
||||
advanceCursor(dir, entries);
|
||||
advanceWorkspace(dir, changes);
|
||||
advanceSubagents(dir, subCursor);
|
||||
process.exitCode = 0;
|
||||
}
|
||||
|
||||
@@ -806,6 +831,52 @@ function advanceWorkspace(dir, changes) {
|
||||
} catch {}
|
||||
}
|
||||
|
||||
// The server rewrites the session's setting for a new workflow only once its
|
||||
// watcher sees the state `open` just wrote, so a launch or hop that read the
|
||||
// file at once would find the old workflow's and owe the agent nothing until
|
||||
// its next pickup. Give the server a moment to catch up instead, never
|
||||
// writing the file ourselves (FR-7). A session with no setting file at all is
|
||||
// an older server, which never writes one: a short look, not the full wait.
|
||||
const SUBAGENT_SYNC_WAIT_MS = 1500;
|
||||
const SUBAGENT_SYNC_MISSING_MS = 250;
|
||||
function awaitSubagentSync(dir, workflow) {
|
||||
if (!offered(workflow)) return;
|
||||
const start = Date.now();
|
||||
for (;;) {
|
||||
const setting = readSubagentSetting(dir);
|
||||
if (setting && setting.workflow === workflow) return;
|
||||
const budget = setting ? SUBAGENT_SYNC_WAIT_MS : SUBAGENT_SYNC_MISSING_MS;
|
||||
if (Date.now() - start >= budget) return;
|
||||
sleepSync(25);
|
||||
}
|
||||
}
|
||||
|
||||
// The Subagents switch the agent is owed, added to what it is about to read:
|
||||
// the setting as `subagents`, and its lines last in `reply`, after card lines,
|
||||
// Quick questions and Workspace lines (FR-9). Read from the session's own
|
||||
// setting file only, which only the server writes (FR-7). A setting for
|
||||
// another workflow is the server not having caught up with a hop yet: it
|
||||
// rides on the next pickup instead.
|
||||
function withSubagents(dir, out) {
|
||||
const setting = readSubagentSetting(dir);
|
||||
if (!setting) return [out, null];
|
||||
const workflow = (readJson(path.join(dir, "state.json")) || {}).workflow;
|
||||
if (setting.workflow !== workflow) return [out, null];
|
||||
const block = blockFor(setting, readSubagentCursor(dir));
|
||||
if (!block) return [out, null];
|
||||
const reply = [out.reply, ...block.lines].filter(Boolean).join("\n");
|
||||
return [{ ...out, subagents: block.field, reply }, block.cursor];
|
||||
}
|
||||
|
||||
// After the print, like advanceWorkspace(): a kill in between repeats the
|
||||
// block at the next pickup, never loses it.
|
||||
function advanceSubagents(dir, cursor) {
|
||||
if (!cursor) return;
|
||||
try {
|
||||
writeSubagentCursor(dir, cursor);
|
||||
} catch {}
|
||||
}
|
||||
|
||||
// Print first, then this, exactly as consume() stamps a result: a kill in
|
||||
// between can only hand the same chat over again, and collectChat() drops
|
||||
// anything that already has a reply.
|
||||
@@ -832,15 +903,17 @@ async function cmdChat() {
|
||||
}
|
||||
const entries = deliverableChat(collectChat(dir, readJson(path.join(dir, "state.json")) || {}));
|
||||
const changes = pendingWorkspaceChanges(dir);
|
||||
if (!entries.length && !changes.length) {
|
||||
const reply = [chatReplyLines(entries), ...changes.map(changeLine)].filter(Boolean).join("\n");
|
||||
const [out, subCursor] = withSubagents(dir, { chat: entries, workspace: changes, reply });
|
||||
if (!entries.length && !changes.length && !subCursor) {
|
||||
print({ chat: [] });
|
||||
process.exitCode = 10;
|
||||
return;
|
||||
}
|
||||
const reply = [chatReplyLines(entries), ...changes.map(changeLine)].filter(Boolean).join("\n");
|
||||
print({ chat: entries, workspace: changes, reply, terminalLine: terminalLine(handle.url) });
|
||||
print({ ...out, terminalLine: terminalLine(handle.url) });
|
||||
advanceCursor(dir, entries);
|
||||
advanceWorkspace(dir, changes);
|
||||
advanceSubagents(dir, subCursor);
|
||||
process.exitCode = 0;
|
||||
}
|
||||
|
||||
@@ -865,7 +938,8 @@ function consume(dir, resultPath, result, url, chat = []) {
|
||||
// never on result.json itself.
|
||||
const withChat = { ...collected, chat };
|
||||
if (chat.length) withChat.reply = [collected.reply, chatReplyLines(chat)].filter(Boolean).join("\n");
|
||||
const [out, changes] = withWorkspace(dir, withChat);
|
||||
const [withWs, changes] = withWorkspace(dir, withChat);
|
||||
const [out, subCursor] = withSubagents(dir, withWs);
|
||||
print(url ? { ...out, terminalLine: terminalLine(url) } : out);
|
||||
try {
|
||||
writeJsonAtomic(resultPath, collected);
|
||||
@@ -874,6 +948,7 @@ function consume(dir, resultPath, result, url, chat = []) {
|
||||
ledgerAnswers(dir, result);
|
||||
advanceCursor(dir, chat);
|
||||
advanceWorkspace(dir, changes);
|
||||
advanceSubagents(dir, subCursor);
|
||||
process.exitCode = result.type === "cancel" ? 30 : 0;
|
||||
}
|
||||
|
||||
@@ -986,12 +1061,18 @@ port, and the filesystem as transport; this CLI is the whole agent surface.
|
||||
path, description?, original? }], missing? }, the folders this
|
||||
console session reads as context, addressed as @name. The list is
|
||||
remembered per folder and spec in workspaces.json beside looks.json.
|
||||
May also print subagents: { state, revision, max, instruction } and
|
||||
a reply holding only its "Subagents: ..." lines, when a standing
|
||||
instruction (the page's Subagents switch) is owed to you.
|
||||
post --session <sid> --file <patch.json>
|
||||
Merge a patch into the session. Prints terminalLine while the
|
||||
server is live. Exit 3 = rejected; stderr says why. A patch may
|
||||
carry run: { event, id, tasks? } (session meter points) and folderIssue:
|
||||
{ name, reason, hint? } (a workspace folder you could not read);
|
||||
both go to the ledger, never into the state.
|
||||
both go to the ledger, never into the state. A patch may also
|
||||
carry helpers: [{ id, title, ask, state, result? }] or one
|
||||
{ id: "alone", alone: true }, merged by id, for the Subagents tab
|
||||
(see console.md → Standing instructions).
|
||||
wait --session <sid> [--seconds <N>]
|
||||
A bounded wait slice, sized below your shell timeout. Exit 0 = the
|
||||
result is on stdout, 10 = still waiting ("Waiting on your answer
|
||||
@@ -1002,10 +1083,14 @@ port, and the filesystem as transport; this CLI is the whole agent surface.
|
||||
"workspace" (changes since you last heard, each once, with a
|
||||
"Workspace: ..." line in reply); exit 10 counts them as
|
||||
pendingWorkspace, and a change alone never ends a slice.
|
||||
Exit 0 may also carry "subagents" (a console setting, not typed
|
||||
by the person, with its "Subagents: ..." lines last in reply); a
|
||||
setting change alone never ends a slice either.
|
||||
chat --session <sid>
|
||||
Collect Quick questions and workspace changes now, never waiting,
|
||||
never touching card sends. Exit 0 = { chat, workspace, reply,
|
||||
terminalLine }, 10 = none, 20 = server gone.
|
||||
Collect Quick questions, workspace changes and a Subagents
|
||||
setting change now, never waiting, never touching card sends.
|
||||
Exit 0 = { chat, workspace, subagents?, reply, terminalLine },
|
||||
10 = none, 20 = server gone.
|
||||
terminalLine is "→ Look at the web console: <url>": end your terminal
|
||||
messages with it during a console session.
|
||||
keep --session <sid> --upload <path> --name <name> --spec specs/<idea> [--from <file>]
|
||||
|
||||
@@ -25,6 +25,7 @@ import { fileURLToPath } from "node:url";
|
||||
import { CHAT_LIMIT } from "./public/chat.js";
|
||||
import { DOC_TYPES } from "./public/answers.js";
|
||||
import { defaultName } from "./public/workspace.js";
|
||||
import { checkHelpers, cleanSetting, defaultSetting, offered } from "./public/subagents.js";
|
||||
|
||||
export const HERE = path.dirname(fileURLToPath(import.meta.url));
|
||||
export const PUBLIC_DIR = path.join(HERE, "public");
|
||||
@@ -491,9 +492,16 @@ export async function removeSessions(sessionsDir, sids) {
|
||||
}
|
||||
|
||||
// The console folder's own files that no sweep may ever remove: the person's
|
||||
// looks, the folders remembered per project and spec, the pointer to this
|
||||
// console's directory, and the cached release check.
|
||||
export const PROTECTED_CONSOLE_FILES = new Set(["looks.json", "workspaces.json", "console-dir", "update-check.json"]);
|
||||
// looks, the folders remembered per project and spec, the Subagents switch
|
||||
// saved per project and workflow, the pointer to this console's directory,
|
||||
// and the cached release check.
|
||||
export const PROTECTED_CONSOLE_FILES = new Set([
|
||||
"looks.json",
|
||||
"workspaces.json",
|
||||
"subagents.json",
|
||||
"console-dir",
|
||||
"update-check.json",
|
||||
]);
|
||||
|
||||
function isScratchName(name) {
|
||||
return (
|
||||
@@ -1142,6 +1150,19 @@ const DOC_DEFAULTS = { version: 1, stale: false, blocks: [] };
|
||||
// Blocks merge by id like docs do, so a patch that only settles a block's
|
||||
// state keeps its text. Blocks left out of the patch stay as they are.
|
||||
function mergeDocs(current, patchList) {
|
||||
// A doc's version only moves forward. One going back is a stale or copied
|
||||
// payload (last phase's progress script, say), and the page would quietly
|
||||
// show the old content under the new run's name.
|
||||
for (const entry of patchList) {
|
||||
if (!isPlainObject(entry) || typeof entry.version !== "number") continue;
|
||||
const prev = (current || []).find((d) => d && d.id === entry.id);
|
||||
if (prev && typeof prev.version === "number" && entry.version < prev.version) {
|
||||
throw new Error(
|
||||
`doc "${entry.id}" is at version ${prev.version} on the page; this patch sends version ${entry.version}. ` +
|
||||
"Versions only go up: bump it, and check the payload is the current one."
|
||||
);
|
||||
}
|
||||
}
|
||||
const merged = mergeKeyed(current, patchList, "id", DOC_DEFAULTS, "docs");
|
||||
for (const entry of patchList) {
|
||||
if (!Array.isArray(entry.blocks)) continue;
|
||||
@@ -1184,6 +1205,13 @@ export function applyPatch(state, patch) {
|
||||
if (!Array.isArray(v)) throw new Error('"topics" must be an array');
|
||||
next.topics = mergeKeyed(next.topics, v, "id", {}, "topics");
|
||||
break;
|
||||
case "helpers":
|
||||
// The agent's report of its helpers, for the page's Subagents tab.
|
||||
// Only `post` writes it; the server's /submit never touches it.
|
||||
if (!Array.isArray(v)) throw new Error('"helpers" must be an array');
|
||||
if (!v.every(isPlainObject)) throw new Error('"helpers" entries must be objects, each { id, title, ask, state }');
|
||||
next.helpers = mergeKeyed(next.helpers, v, "id", {}, "helpers");
|
||||
break;
|
||||
case "docs":
|
||||
if (!Array.isArray(v)) throw new Error('"docs" must be an array');
|
||||
next.docs = mergeDocs(next.docs, v);
|
||||
@@ -1478,6 +1506,20 @@ export function validate(state) {
|
||||
JSON.stringify(state.menu || {});
|
||||
problems.push(...proseProblems(prose));
|
||||
|
||||
// The agent's report of its helpers: the shape the page draws from
|
||||
// (subagents.js), then the same prose scan as everything else it writes.
|
||||
if (state.helpers != null) {
|
||||
problems.push(...checkHelpers(state.helpers));
|
||||
for (const helper of Array.isArray(state.helpers) ? state.helpers : []) {
|
||||
if (!isPlainObject(helper)) continue;
|
||||
for (const field of ["title", "ask", "result"]) {
|
||||
if (typeof helper[field] === "string") {
|
||||
problems.push(...proseProblems(helper[field], `helper "${helper.id}" ${field}`));
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
return problems;
|
||||
}
|
||||
|
||||
@@ -1507,7 +1549,8 @@ export function blankState({ sid, workflow, title, project, specDir }) {
|
||||
* A resume that passes through the dashboard (a finished skill going back to
|
||||
* it, or a launch from its menu) is a new skill taking the page over, so it
|
||||
* starts from a blank page: the last skill's questions, sections, docs,
|
||||
* headline and ending are its record on disk, not the next skill's opening.
|
||||
* helpers, headline and ending are its record on disk, not the next skill's
|
||||
* opening.
|
||||
* Only the session's identity carries across. `workspace.json`,
|
||||
* `ledger.ndjson` and the cursors live beside `state.json`, so the workspace
|
||||
* and the meter outlive every hop.
|
||||
@@ -1534,6 +1577,8 @@ export function switchWorkflow(state, { workflow, title, specDir }) {
|
||||
// workspace.json the server. Folders, version, change log, missing, remote.
|
||||
// ledger.ndjson console.mjs. Append-only meter events and folder issues.
|
||||
// workspace-cursor.json console.mjs. The last workspace version handed to the agent.
|
||||
// subagents-setting.json the server. The Subagents switch for this session, with its revision.
|
||||
// subagents-cursor.json console.mjs. The last Subagents revision and state handed to the agent.
|
||||
export const CHAT_FILE = "chat.ndjson";
|
||||
export const CHAT_CURSOR_FILE = "chat-cursor.json";
|
||||
export const WORKSPACE_FILE = "workspace.json";
|
||||
@@ -1989,6 +2034,98 @@ export function pendingWorkspaceChanges(dir) {
|
||||
return (readWorkspace(dir)?.changes || []).filter((c) => c.version > cursor);
|
||||
}
|
||||
|
||||
/* ------------------------------------------------------ the Subagents switch */
|
||||
|
||||
// The person's Subagents switch, remembered per project folder and workflow:
|
||||
//
|
||||
// { "<folded project path>": { "<workflow>": { on, instruction, max } } }
|
||||
//
|
||||
// Keyed with foldKey(), as workspaces.json is. `instruction: null` is the
|
||||
// workflow's shipped default.
|
||||
export const SUBAGENTS_FILE = path.join(HOME_DIR, "subagents.json");
|
||||
const SUBAGENTS_LOCK = "subagents.json.lock";
|
||||
|
||||
function readSubagentStore() {
|
||||
const saved = readJson(SUBAGENTS_FILE, null);
|
||||
return saved && typeof saved === "object" && !Array.isArray(saved) ? saved : {};
|
||||
}
|
||||
|
||||
// The saved `{ on, instruction, max }` for this folder and workflow, or the
|
||||
// default's when nothing (or something malformed) is saved.
|
||||
export function subagentStoreEntry(worktree, workflow) {
|
||||
const { on, instruction, max } = defaultSetting(workflow);
|
||||
const project = offered(workflow) ? readSubagentStore()[foldKey(worktree)] : null;
|
||||
const saved = project && typeof project === "object" ? cleanSetting(project[workflow]) : null;
|
||||
return saved && !saved.error ? saved : { on, instruction, max };
|
||||
}
|
||||
|
||||
// Single-writer rule: only server.mjs may call this.
|
||||
export function saveSubagentStoreEntry(worktree, workflow, value) {
|
||||
ensureDir(path.dirname(SUBAGENTS_FILE));
|
||||
withStateLock(
|
||||
path.dirname(SUBAGENTS_FILE),
|
||||
() => {
|
||||
const store = readSubagentStore();
|
||||
const key = foldKey(worktree);
|
||||
const project = store[key] && typeof store[key] === "object" ? store[key] : {};
|
||||
store[key] = { ...project, [workflow]: { on: value.on, instruction: value.instruction, max: value.max } };
|
||||
writeJsonAtomic(SUBAGENTS_FILE, store);
|
||||
},
|
||||
SUBAGENTS_LOCK
|
||||
);
|
||||
}
|
||||
|
||||
export const SUBAGENTS_SETTING_FILE = "subagents-setting.json";
|
||||
|
||||
const isCount = (n) => Number.isInteger(n) && n >= 0;
|
||||
|
||||
// This session's switch, `{ workflow, on, instruction, max, revision }`, or
|
||||
// null when there is none or it is malformed.
|
||||
export function readSubagentSetting(dir) {
|
||||
const s = readJson(path.join(dir, SUBAGENTS_SETTING_FILE), null);
|
||||
if (!s || typeof s !== "object") return null;
|
||||
if (typeof s.workflow !== "string" || typeof s.on !== "boolean" || !Number.isInteger(s.max) || !isCount(s.revision)) return null;
|
||||
return s;
|
||||
}
|
||||
|
||||
// Single-writer rule: only server.mjs may call this. The revision never goes
|
||||
// backwards within a session.
|
||||
export function writeSubagentSetting(dir, setting) {
|
||||
const previous = readSubagentSetting(dir);
|
||||
const revision = Math.max(previous ? previous.revision : 0, setting.revision);
|
||||
return writeJsonAtomic(path.join(dir, SUBAGENTS_SETTING_FILE), { ...setting, revision });
|
||||
}
|
||||
|
||||
export const SUBAGENTS_CURSOR_FILE = "subagents-cursor.json";
|
||||
const CURSOR_STATES = new Set(["none", "on", "off"]);
|
||||
|
||||
// What the agent was last told: `{ revision, state }`.
|
||||
export function readSubagentCursor(dir) {
|
||||
const saved = readJson(path.join(dir, SUBAGENTS_CURSOR_FILE), null);
|
||||
if (!saved || !isCount(saved.revision) || !CURSOR_STATES.has(saved.state)) return { revision: 0, state: "none" };
|
||||
return { revision: saved.revision, state: saved.state };
|
||||
}
|
||||
|
||||
// Single-writer rule: only console.mjs may call this. Never backwards, like
|
||||
// writeWorkspaceCursor(): a killed `wait` may repeat a change, never skip one.
|
||||
export function writeSubagentCursor(dir, cursor) {
|
||||
const old = readSubagentCursor(dir);
|
||||
const next = cursor.revision < old.revision ? old : { revision: cursor.revision, state: cursor.state };
|
||||
writeJsonAtomic(path.join(dir, SUBAGENTS_CURSOR_FILE), next);
|
||||
}
|
||||
|
||||
// The one place the cursor may go back: `open`, which starts a fresh agent.
|
||||
export function resetSubagentCursor(dir) {
|
||||
writeJsonAtomic(path.join(dir, SUBAGENTS_CURSOR_FILE), { revision: 0, state: "none" });
|
||||
}
|
||||
|
||||
// The `caps` of the last `open` event: what the agent's console copy can do.
|
||||
export function latestOpenCaps(dir) {
|
||||
const opens = readJsonLines(path.join(dir, "events.ndjson")).filter((e) => e.type === "open");
|
||||
const last = opens[opens.length - 1];
|
||||
return last && Array.isArray(last.caps) ? last.caps : [];
|
||||
}
|
||||
|
||||
/**
|
||||
* Flag the case where the link cannot be opened by the person it is for.
|
||||
*
|
||||
|
||||
@@ -208,6 +208,26 @@ body {
|
||||
.stop-btn:hover:not(:disabled) { color: var(--warn); border-color: var(--warn); }
|
||||
.brief-btn:hover:not(:disabled) { color: var(--accent); border-color: var(--accent-line); }
|
||||
|
||||
/* Subagents: an orchestrator and its helpers. Unlit is a hollow outline in
|
||||
the quiet ink; lit fills the nodes with the highlight color. */
|
||||
.subagents-btn { border-color: var(--rule-2); color: var(--ink-2); display: inline-flex; align-items: center; justify-content: center; }
|
||||
.btn.subagents-btn { padding: 0 6px; align-self: stretch; }
|
||||
.subagents-btn[hidden] { display: none; }
|
||||
.subagents-btn svg { width: 16px; height: 16px; display: block; }
|
||||
.subagents-btn .sa-link { fill: none; stroke: var(--ink-2); stroke-width: 1.2; stroke-linecap: round; }
|
||||
.subagents-btn .sa-hub { fill: none; stroke: var(--ink-2); stroke-width: 1.4; }
|
||||
.subagents-btn .sa-node { fill: none; stroke: var(--ink-2); stroke-width: 1.2; }
|
||||
.subagents-btn[aria-pressed="true"] .sa-hub,
|
||||
.subagents-btn[aria-pressed="true"] .sa-node { fill: var(--accent); stroke: var(--accent); }
|
||||
.subagents-btn[aria-pressed="true"] .sa-link { stroke: var(--accent); }
|
||||
.subagents-btn:hover:not(:disabled) { color: var(--accent); border-color: var(--accent-line); }
|
||||
.subagents-btn:hover:not(:disabled) .sa-link,
|
||||
.subagents-btn:hover:not(:disabled) .sa-hub,
|
||||
.subagents-btn:hover:not(:disabled) .sa-node { stroke: var(--accent); }
|
||||
.subagents-btn:disabled .sa-link,
|
||||
.subagents-btn:disabled .sa-hub,
|
||||
.subagents-btn:disabled .sa-node { stroke: var(--ink-3); fill: none; }
|
||||
|
||||
.ident { display: flex; align-items: baseline; gap: 12px; min-width: 0; }
|
||||
|
||||
/* The session meter: a ring that fills with the points and a few words, in
|
||||
@@ -1430,6 +1450,30 @@ h1 {
|
||||
.pill.done { background: var(--ok-soft); color: var(--ok); }
|
||||
.pill.staged { background: var(--stage-soft); color: var(--stage); }
|
||||
|
||||
/* The Subagents tab: one row per reported helper, newest state in a pill. */
|
||||
.sa-card h2 { margin: 0 0 6px; }
|
||||
.sa-card > .help { margin: 0 0 16px; }
|
||||
.sa-alone { margin: 0; color: var(--ink-2); }
|
||||
.sa-list { list-style: none; margin: 0; padding: 0; display: grid; gap: 10px; }
|
||||
.sa-row { border: 1px solid var(--rule); border-radius: 8px; background: var(--panel-2); padding: 12px 14px; }
|
||||
.sa-head { display: flex; align-items: center; justify-content: space-between; gap: 10px; }
|
||||
.sa-title { min-width: 0; overflow-wrap: anywhere; }
|
||||
.sa-ask {
|
||||
margin: 4px 0 0; color: var(--ink-2); font-size: 13.5px;
|
||||
display: -webkit-box; -webkit-box-orient: vertical; -webkit-line-clamp: 2; line-clamp: 2; overflow: hidden;
|
||||
}
|
||||
.sa-result { margin: 8px 0 0; padding-top: 8px; border-top: 1px solid var(--rule); font-size: 13.5px; }
|
||||
.sa-pill { display: inline-flex; align-items: center; gap: 6px; flex: none; }
|
||||
.sa-pill.is-running { background: var(--accent-soft); color: var(--accent); border-color: var(--accent-line); }
|
||||
.sa-pill.is-done { background: var(--ok-soft); color: var(--ok); }
|
||||
.sa-pill.is-failed { background: var(--warn-soft); color: var(--warn); }
|
||||
.sa-pill .spinner.tiny { width: 10px; height: 10px; }
|
||||
/* The dialog's number box, themed like the page's other inputs. */
|
||||
.subagents input[type="number"] {
|
||||
width: 5em; font: inherit; color: var(--ink); background: var(--panel-2);
|
||||
border: 1px solid var(--rule-2); border-radius: 6px; padding: 4px 8px;
|
||||
}
|
||||
|
||||
/* ------------------------------------------------------ settled answer */
|
||||
|
||||
.answered {
|
||||
@@ -1971,6 +2015,8 @@ h4.md-h, h5.md-h, h6.md-h { font-size: 15px; }
|
||||
cursor: pointer;
|
||||
}
|
||||
.footer-where:hover { text-decoration: underline; }
|
||||
/* The project name, in the person's highlight color. */
|
||||
.where-project { color: var(--accent); font-weight: 600; }
|
||||
/* A folder is missing or the agent could not read one: the dialog says which. */
|
||||
.where-alert {
|
||||
display: inline-block; width: 7px; height: 7px; margin-left: 6px;
|
||||
|
||||
@@ -103,6 +103,15 @@ import { FOOTER_TIERS, footerLabel, nameProblem } from "./workspace.js";
|
||||
import { RED_BANNER } from "./meter.js";
|
||||
import { applyMention, matchNames, mentionAt } from "./mentions.js";
|
||||
import { faviconState, setFavicon } from "./favicon.js";
|
||||
import {
|
||||
CHECKIN_LINE,
|
||||
PATHFINDER_RESEARCH_LINE,
|
||||
defaultInstruction,
|
||||
helperRows,
|
||||
showSwitch,
|
||||
showTab,
|
||||
switchLabel,
|
||||
} from "./subagents.js";
|
||||
|
||||
const $ = (id) => document.getElementById(id);
|
||||
|
||||
@@ -530,6 +539,9 @@ let meterFrame = null;
|
||||
// The frame's update ({ installed, latest }), present only when a newer
|
||||
// release is out; null otherwise.
|
||||
let updateFrame = null;
|
||||
// The frame's Subagents switch ({ offered, supported, on, instruction, max,
|
||||
// revision }), or null before a server that sends it.
|
||||
let subagentsFrame = null;
|
||||
let chatDot = false;
|
||||
let chatSending = false;
|
||||
let chatResetting = false;
|
||||
@@ -880,6 +892,8 @@ function adopt(body) {
|
||||
if (body.meter) meterFrame = body.meter;
|
||||
// Always replaced: an absent key means no update.
|
||||
updateFrame = body.update || null;
|
||||
// Always replaced too: an older server sends none, and then there is no switch.
|
||||
subagentsFrame = body.subagents || null;
|
||||
lastContact = Date.now();
|
||||
if (gone) {
|
||||
gone = false;
|
||||
@@ -1301,6 +1315,7 @@ function render() {
|
||||
renderChrome();
|
||||
renderStatus();
|
||||
renderBriefButton();
|
||||
renderSubagentsButton();
|
||||
renderStopButton();
|
||||
renderHomeButton();
|
||||
tabAdded = renderViews();
|
||||
@@ -1566,7 +1581,7 @@ function renderChrome() {
|
||||
renderMeter();
|
||||
$("title").textContent = S.title || "Session";
|
||||
$("badge").textContent = workflowLabel(S.workflow);
|
||||
document.title = (S.title || "Session") + " · #" + String(S.sid || "").slice(-6) + " · Plan2Code";
|
||||
renderTabTitle();
|
||||
|
||||
const h = S.headline || {};
|
||||
// On a finished session an open item is frozen: the send on it counts as
|
||||
@@ -1835,6 +1850,69 @@ function renderBriefButton() {
|
||||
if (offer) btn.disabled = gone || pendingResult;
|
||||
}
|
||||
|
||||
// Shown only where the skill opts in and the agent's console copy can deliver
|
||||
// it. Lit while helpers are on; a click opens the dialog, never toggles.
|
||||
function renderSubagentsButton() {
|
||||
const btn = $("btn-subagents");
|
||||
const offer = showSwitch(subagentsFrame);
|
||||
btn.hidden = !offer;
|
||||
if (!offer) return;
|
||||
const label = switchLabel(subagentsFrame);
|
||||
btn.setAttribute("aria-pressed", String(Boolean(subagentsFrame.on)));
|
||||
btn.title = label;
|
||||
btn.setAttribute("aria-label", label);
|
||||
btn.disabled = gone;
|
||||
}
|
||||
|
||||
// The Subagents dialog, filled from the frame each time it opens. A null
|
||||
// instruction is the shipped default, shown as its text so it can be edited.
|
||||
function openSubagents() {
|
||||
if (!showSwitch(subagentsFrame)) return;
|
||||
const on = Boolean(subagentsFrame.on);
|
||||
for (const radio of document.querySelectorAll('input[name="subagents-on"]')) {
|
||||
radio.checked = radio.value === (on ? "on" : "off");
|
||||
}
|
||||
$("subagents-instruction").value = subagentsFrame.instruction ?? defaultInstruction(S.workflow);
|
||||
$("subagents-max").value = String(subagentsFrame.max);
|
||||
$("subagents-checkin").textContent = CHECKIN_LINE;
|
||||
const research = $("subagents-research");
|
||||
research.textContent = PATHFINDER_RESEARCH_LINE;
|
||||
research.hidden = S.workflow !== "pathfinder";
|
||||
$("subagents-status").textContent = "";
|
||||
$("subagents-save").disabled = false;
|
||||
$("subagents-modal").showModal();
|
||||
const checked = document.querySelector('input[name="subagents-on"]:checked');
|
||||
if (checked) checked.focus();
|
||||
}
|
||||
|
||||
const SUBAGENTS_ERRORS = {
|
||||
max: "Pick a number from 1 to 20.",
|
||||
"too-long": "The instruction is over 2,000 characters.",
|
||||
"not-offered": "This skill doesn't use helpers.",
|
||||
bad: "That didn't save. Try again.",
|
||||
};
|
||||
const SUBAGENTS_LOST = "Lost contact with Plan2Code. Try again once it's back.";
|
||||
|
||||
async function saveSubagents() {
|
||||
const save = $("subagents-save");
|
||||
const status = $("subagents-status");
|
||||
const picked = document.querySelector('input[name="subagents-on"]:checked');
|
||||
const text = $("subagents-instruction").value.trim();
|
||||
// The shipped default is stored as null, so a later release's wording
|
||||
// reaches everyone who never changed it.
|
||||
const instruction = text === defaultInstruction(S.workflow) ? null : text;
|
||||
const body = { on: Boolean(picked && picked.value === "on"), instruction, max: Number($("subagents-max").value) };
|
||||
save.disabled = true;
|
||||
status.textContent = "";
|
||||
const res = await postJson("/subagents", body);
|
||||
save.disabled = false;
|
||||
// The next state frame redraws the button.
|
||||
if (res.status === 200) return $("subagents-modal").close();
|
||||
if (res.status === 400) status.textContent = SUBAGENTS_ERRORS[res.body && res.body.error] || SUBAGENTS_ERRORS.bad;
|
||||
else if (res.status === 403 || res.status === 0) status.textContent = SUBAGENTS_LOST;
|
||||
else status.textContent = SUBAGENTS_ERRORS.bad;
|
||||
}
|
||||
|
||||
function renderViews() {
|
||||
const nav = $("views");
|
||||
nav.replaceChildren();
|
||||
@@ -1850,6 +1928,14 @@ function renderViews() {
|
||||
if (hasOverview) tabs.push({ id: "overview", label: "Overview", count: 0 });
|
||||
else if (view === "overview") view = "questions";
|
||||
for (const d of docs()) tabs.push({ id: "doc:" + d.id, label: d.title || "Document", count: 0 });
|
||||
// The helpers the agent reported, from the first one on; cleared by a
|
||||
// dashboard hop, which sends the person home like the Overview tab does.
|
||||
if (showTab(subagentsFrame, S.helpers)) {
|
||||
// From the rows the tab draws, so the badge never counts helpers the
|
||||
// working-alone note hides.
|
||||
const running = helperRows(S.helpers).rows.filter((r) => r.state === "running").length;
|
||||
tabs.push({ id: "subagents", label: "Subagents", count: running });
|
||||
} else if (view === "subagents") view = "questions";
|
||||
// Always last, on every workflow and after a finish: the Quick question chat.
|
||||
// The ring left of "Ask" shows exactly when the conversation's own ring does:
|
||||
// a question the agent picked up and has not answered yet.
|
||||
@@ -2130,6 +2216,7 @@ function paintMain(main) {
|
||||
if (view.startsWith("doc:")) return renderDoc(main, view.slice(4));
|
||||
if (view === "overview") return renderOverview(main);
|
||||
if (view === "ask") return renderAsk(main);
|
||||
if (view === "subagents") return renderSubagents(main);
|
||||
|
||||
// The session's own page, reached from the PAUSED / SESSION ENDED item at
|
||||
// the top of the rail. The hand-off lives here alone now, rather than
|
||||
@@ -4774,6 +4861,42 @@ function renderOverview(main) {
|
||||
main.appendChild(box);
|
||||
}
|
||||
|
||||
// The helpers the agent reported, as it last posted them. Everything here is
|
||||
// the agent's text, so it goes in as text, never as markup.
|
||||
function renderSubagents(main) {
|
||||
const card = el("section", "card sa-card");
|
||||
card.appendChild(el("h2", null, "Subagents"));
|
||||
card.appendChild(el("p", "help", CHECKIN_LINE));
|
||||
const { alone, rows } = helperRows(S.helpers);
|
||||
if (alone) {
|
||||
card.appendChild(
|
||||
el("p", "sa-alone", "Working alone: your agent has no way to start helpers here, so it is doing this skill's work itself.")
|
||||
);
|
||||
main.appendChild(card);
|
||||
return;
|
||||
}
|
||||
const list = el("ul", "sa-list");
|
||||
for (const row of rows) {
|
||||
const item = el("li", "sa-row");
|
||||
const head = el("div", "sa-head");
|
||||
head.appendChild(el("strong", "sa-title", row.title));
|
||||
const pill = el("span", "pill sa-pill is-" + row.state);
|
||||
if (row.state === "running") {
|
||||
const spin = el("span", "spinner tiny");
|
||||
spin.setAttribute("aria-hidden", "true");
|
||||
pill.appendChild(spin);
|
||||
}
|
||||
pill.appendChild(document.createTextNode(row.stateLabel));
|
||||
head.appendChild(pill);
|
||||
item.appendChild(head);
|
||||
item.appendChild(el("p", "sa-ask", row.ask));
|
||||
if (row.result) item.appendChild(el("p", "sa-result", row.result));
|
||||
list.appendChild(item);
|
||||
}
|
||||
card.appendChild(list);
|
||||
main.appendChild(card);
|
||||
}
|
||||
|
||||
/* ---------------------------------------------------------------- ask */
|
||||
|
||||
// The frame's chat block, with `offline` worked out now rather than when the
|
||||
@@ -5956,10 +6079,30 @@ const workspaceFolders = () => (wsFrame && Array.isArray(wsFrame.folders) ? wsFr
|
||||
// session opened before the server wrote `worktree` has nothing to show, so
|
||||
// the slot stays hidden. The footer renders on every tick, so the DOM is only
|
||||
// touched when the labels change, or when a resize clears the key.
|
||||
// The project's name: the workspace's original folder, or the session's
|
||||
// worktree folder before a frame carries the workspace.
|
||||
function projectName() {
|
||||
const folders = workspaceFolders();
|
||||
if (folders.length && folders[0].name) return folders[0].name;
|
||||
const path = (S && S.worktree) || "";
|
||||
return path ? path.split(/[\\/]/).filter(Boolean).pop() || path : "";
|
||||
}
|
||||
|
||||
// The browser tab's title, led by the project so tabs from different
|
||||
// projects are told apart. Called from the chrome and the footer, since the
|
||||
// workspace frame can arrive after either.
|
||||
function renderTabTitle() {
|
||||
if (!S) return;
|
||||
const name = projectName();
|
||||
document.title =
|
||||
(name ? name + " · " : "") + (S.title || "Session") + " · #" + String(S.sid || "").slice(-6) + " · Plan2Code";
|
||||
}
|
||||
|
||||
function renderWhere() {
|
||||
const b = $("footer-where");
|
||||
const folders = workspaceFolders();
|
||||
const path = S.worktree || "";
|
||||
renderTabTitle();
|
||||
const alert = Boolean(folders.length && ((wsFrame.missing || []).length || (wsFrame.issues || []).length));
|
||||
const labels = folders.length
|
||||
? Array.from({ length: FOOTER_TIERS }, (_, tier) => footerLabel({ folders, branch: S.branch }, tier))
|
||||
@@ -5972,7 +6115,16 @@ function renderWhere() {
|
||||
let label = labels[0];
|
||||
for (const text of labels) {
|
||||
label = text;
|
||||
b.textContent = text;
|
||||
// The project name takes the highlight color, so several consoles side by
|
||||
// side tell apart at a glance; the rest of the label stays quiet.
|
||||
const name = projectName();
|
||||
b.textContent = "";
|
||||
if (name && text.startsWith(name)) {
|
||||
b.appendChild(el("span", "where-project", name));
|
||||
b.appendChild(document.createTextNode(text.slice(name.length)));
|
||||
} else {
|
||||
b.textContent = text;
|
||||
}
|
||||
if (alert) {
|
||||
const dot = el("span", "where-alert");
|
||||
dot.setAttribute("aria-hidden", "true");
|
||||
@@ -7197,6 +7349,7 @@ function lightDismiss(dlg) {
|
||||
});
|
||||
}
|
||||
lightDismiss($("looks-modal"));
|
||||
lightDismiss($("subagents-modal"));
|
||||
lightDismiss($("help-modal"));
|
||||
lightDismiss($("workspace-modal"));
|
||||
lightDismiss($("welcome-modal"));
|
||||
@@ -7499,6 +7652,13 @@ $("cleanup-scan").addEventListener("click", scanCleanup);
|
||||
$("cleanup-delete").addEventListener("click", deleteCleanup);
|
||||
|
||||
$("btn-brief").addEventListener("click", openBrief);
|
||||
$("btn-subagents").addEventListener("click", openSubagents);
|
||||
$("subagents-default").addEventListener("click", () => {
|
||||
$("subagents-instruction").value = defaultInstruction(S.workflow);
|
||||
});
|
||||
$("subagents-save").addEventListener("click", saveSubagents);
|
||||
$("subagents-cancel").addEventListener("click", () => $("subagents-modal").close());
|
||||
$("subagents-modal").addEventListener("close", () => $("btn-subagents").focus());
|
||||
$("brief-cancel").addEventListener("click", () => $("brief-modal").close());
|
||||
$("brief-go").addEventListener("click", sendBrief);
|
||||
for (const radio of document.querySelectorAll('input[name="brief-range"]')) {
|
||||
|
||||
@@ -19,6 +19,7 @@ export const HELP_TABS = Object.freeze([
|
||||
tab("dashboard", "The dashboard", true),
|
||||
tab("meter", "Session meter", false),
|
||||
tab("build", "Watching a build", false),
|
||||
tab("subagents", "Helpers (subagents)", false),
|
||||
tab("ask", "Ask a quick question", false),
|
||||
tab("finishing", "Stopping and finishing", false),
|
||||
tab("stuck", "When something looks stuck", true),
|
||||
@@ -39,6 +40,7 @@ export function helpTabFor({ view, dashboard, gone, adrift, finished, workflow,
|
||||
if (gone || adrift) return "stuck";
|
||||
if (workspace) return "workspace";
|
||||
if (v === "ask") return "ask";
|
||||
if (v === "subagents") return "subagents";
|
||||
if (dashboard && meterRed) return "meter";
|
||||
if (dashboard) return "dashboard";
|
||||
if (v === "overview" || v.startsWith("doc:")) return "docs";
|
||||
|
||||
@@ -21,6 +21,7 @@
|
||||
<link rel="modulepreload" href="/starters.js" />
|
||||
<link rel="modulepreload" href="/workspace.js" />
|
||||
<link rel="modulepreload" href="/meter.js" />
|
||||
<link rel="modulepreload" href="/subagents.js" />
|
||||
<link rel="modulepreload" href="/mentions.js" />
|
||||
<link rel="modulepreload" href="/favicon.js" />
|
||||
<link rel="modulepreload" href="/vendor/marked.esm.js" />
|
||||
@@ -172,6 +173,18 @@
|
||||
<button type="button" class="btn ghost small brief-btn" id="btn-brief" hidden>
|
||||
Write a brief
|
||||
</button>
|
||||
<!-- Subagents: opted-in skills only. Lit while helpers are on; a click
|
||||
opens the Subagents dialog and never toggles them itself. -->
|
||||
<button type="button" class="btn ghost small subagents-btn" id="btn-subagents" aria-pressed="false" hidden>
|
||||
<!-- An orchestrator and its helpers: one larger node linked to three smaller ones. -->
|
||||
<svg viewBox="0 0 16 16" aria-hidden="true" focusable="false">
|
||||
<path class="sa-link" d="M6.9 6.6L10.9 3.9M7.4 8h3.5M6.9 9.4l4 2.7" />
|
||||
<circle cx="4.6" cy="8" r="2.6" class="sa-hub" />
|
||||
<circle cx="12.4" cy="3" r="1.5" class="sa-node" />
|
||||
<circle cx="12.4" cy="8" r="1.5" class="sa-node" />
|
||||
<circle cx="12.4" cy="13" r="1.5" class="sa-node" />
|
||||
</svg>
|
||||
</button>
|
||||
</div>
|
||||
<div class="views-group">
|
||||
<span class="views-arrow" aria-hidden="true">
|
||||
@@ -580,6 +593,13 @@
|
||||
<rect x="3" y="9" width="18" height="6" rx="3" />
|
||||
<path d="M6 12h7" />
|
||||
</symbol>
|
||||
<symbol id="hi-subagents" viewBox="0 0 24 24" fill="none">
|
||||
<circle cx="7" cy="12" r="3.5" />
|
||||
<circle cx="18" cy="5" r="2" />
|
||||
<circle cx="18" cy="12" r="2" />
|
||||
<circle cx="18" cy="19" r="2" />
|
||||
<path d="M10 10l6-4M10.5 12H16M10 14l6 4" />
|
||||
</symbol>
|
||||
<symbol id="hi-ask" viewBox="0 0 24 24" fill="none">
|
||||
<path d="M4 5h16v11H10l-4 4v-4H4z" />
|
||||
<path d="M8 9.5h8M8 12.5h5" />
|
||||
@@ -1477,7 +1497,61 @@
|
||||
</p>
|
||||
</section>
|
||||
|
||||
<!-- Tab 12: Ask a quick question -->
|
||||
<!-- Tab 12: Helpers (subagents) -->
|
||||
<section class="help-panel" data-tab="subagents">
|
||||
<h3>Helpers (subagents)</h3>
|
||||
<p>
|
||||
On a build, a review and Pathfinder, Plan2Code can hand independent
|
||||
pieces of work to helpers (subagents) while it keeps the conversation
|
||||
with you. The <strong>Subagents</strong> button in the top bar, after
|
||||
Stop session, is lit while helpers are on.
|
||||
</p>
|
||||
<h4>The switch</h4>
|
||||
<ul>
|
||||
<li>
|
||||
Clicking the button opens the <strong>Subagents</strong> dialog; it
|
||||
never switches helpers on or off by itself. Pick <strong>Use
|
||||
helpers</strong> or <strong>Work alone</strong>, edit the instruction
|
||||
Plan2Code follows (<strong>Reset to default</strong> puts the
|
||||
shipped one back), and say how many may run at once.
|
||||
</li>
|
||||
<li>
|
||||
It is off by default and saved for this project and this skill, so
|
||||
the next session of the same skill here starts the same way.
|
||||
</li>
|
||||
<li>
|
||||
The change reaches Plan2Code at its next check-in, as a setting,
|
||||
not as something you typed. How many helpers it can really start is
|
||||
up to your agent; some have no helpers at all.
|
||||
</li>
|
||||
<li>The button only appears on skills that use helpers, and only when Plan2Code can pass the setting on.</li>
|
||||
</ul>
|
||||
<h4>The Subagents tab</h4>
|
||||
<ul>
|
||||
<li>
|
||||
With the first helper, a <strong>Subagents</strong> tab appears before
|
||||
Ask: one row each, with what it was asked, whether it is running, done
|
||||
or failed, and a one-line result at the end. The number on the tab is
|
||||
how many are still running.
|
||||
</li>
|
||||
<li>
|
||||
Helpers report through Plan2Code, so the rows change at its
|
||||
check-ins, not live. The page cannot stop a helper; ask Plan2Code
|
||||
on the Ask tab if one should stop.
|
||||
</li>
|
||||
<li>
|
||||
<strong>Working alone</strong> means your agent has no way to start
|
||||
helpers here, so it is doing the work itself.
|
||||
</li>
|
||||
<li>
|
||||
Pathfinder always uses helpers for its research questions, whatever
|
||||
the switch says, and they show here too.
|
||||
</li>
|
||||
<li>The tab clears when you go back to the dashboard.</li>
|
||||
</ul>
|
||||
</section>
|
||||
|
||||
<!-- Tab 13: Ask a quick question -->
|
||||
<section class="help-panel" data-tab="ask">
|
||||
<h3>Ask a quick question</h3>
|
||||
<p class="help-lead">
|
||||
@@ -1568,7 +1642,7 @@
|
||||
</p>
|
||||
</section>
|
||||
|
||||
<!-- Tab 13: Stopping and finishing -->
|
||||
<!-- Tab 14: Stopping and finishing -->
|
||||
<section class="help-panel" data-tab="finishing">
|
||||
<h3>Stopping and finishing</h3>
|
||||
<p class="help-lead">
|
||||
@@ -1650,7 +1724,7 @@
|
||||
</p>
|
||||
</section>
|
||||
|
||||
<!-- Tab 14: When something looks stuck -->
|
||||
<!-- Tab 15: When something looks stuck -->
|
||||
<section class="help-panel" data-tab="stuck">
|
||||
<h3>When something looks stuck</h3>
|
||||
<p class="help-lead">
|
||||
@@ -1772,7 +1846,7 @@
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<!-- Tab 15: Keyboard and preferences -->
|
||||
<!-- Tab 16: Keyboard and preferences -->
|
||||
<section class="help-panel" data-tab="prefs">
|
||||
<h3>Keyboard and preferences</h3>
|
||||
<p class="help-lead">
|
||||
@@ -1888,7 +1962,7 @@
|
||||
</ul>
|
||||
</section>
|
||||
|
||||
<!-- Tab 16: Privacy and where things are saved -->
|
||||
<!-- Tab 17: Privacy and where things are saved -->
|
||||
<section class="help-panel" data-tab="privacy">
|
||||
<h3>Privacy and where things are saved</h3>
|
||||
<p class="help-lead">
|
||||
@@ -1925,7 +1999,11 @@
|
||||
</li>
|
||||
<li>
|
||||
your role, theme, colors, card width and sounds, in
|
||||
<code>looks.json</code>.
|
||||
<code>looks.json</code>;
|
||||
</li>
|
||||
<li>
|
||||
your Subagents switch for each project and skill, in
|
||||
<code>subagents.json</code>.
|
||||
</li>
|
||||
</ul>
|
||||
<p>
|
||||
@@ -2039,6 +2117,46 @@
|
||||
</div>
|
||||
</dialog>
|
||||
|
||||
<!-- Subagents: the switch for this skill, filled from the frame's
|
||||
`subagents` by app.js and saved through POST /subagents. It borrows
|
||||
the User Preferences dialog's classes, so it needs no dialog styles of
|
||||
its own, only a themed number box. -->
|
||||
<dialog class="modal looks subagents" id="subagents-modal" aria-labelledby="subagents-title">
|
||||
<h2 id="subagents-title">Subagents</h2>
|
||||
<p class="modal-blurb">
|
||||
Let Plan2Code hand independent work to helpers in this skill. Saved for this
|
||||
project and this skill.
|
||||
</p>
|
||||
<fieldset class="modal-ranges looks-row">
|
||||
<legend>Helpers</legend>
|
||||
<label><input type="radio" name="subagents-on" value="on" /> <span>Use helpers</span></label>
|
||||
<label><input type="radio" name="subagents-on" value="off" checked /> <span>Work alone</span></label>
|
||||
</fieldset>
|
||||
<fieldset class="modal-ranges">
|
||||
<legend>Instruction</legend>
|
||||
<textarea id="subagents-instruction" rows="4" maxlength="2000" aria-label="Instruction"></textarea>
|
||||
<div class="models-actions">
|
||||
<button type="button" class="btn small ghost" id="subagents-default">Reset to default</button>
|
||||
<span class="help">Passed to the agent as written, at its next check-in.</span>
|
||||
</div>
|
||||
</fieldset>
|
||||
<fieldset class="modal-ranges">
|
||||
<legend>At most</legend>
|
||||
<label>
|
||||
<input type="number" id="subagents-max" min="1" max="20" step="1" aria-label="At most this many helpers at once" />
|
||||
<span>helpers at once</span>
|
||||
</label>
|
||||
<p class="help">Advisory: your agent's own limit still applies.</p>
|
||||
</fieldset>
|
||||
<p class="help" id="subagents-checkin"></p>
|
||||
<p class="help" id="subagents-research" hidden></p>
|
||||
<p class="help" id="subagents-status" role="status"></p>
|
||||
<div class="modal-actions">
|
||||
<button type="button" class="btn ghost" id="subagents-cancel">Cancel</button>
|
||||
<button type="button" class="btn primary" id="subagents-save">Save</button>
|
||||
</div>
|
||||
</dialog>
|
||||
|
||||
<!-- The Workspace: the folder this session started in plus any added as
|
||||
context. The list is drawn by app.js from the frame's `workspace`;
|
||||
every change goes through the server's /workspace routes. -->
|
||||
|
||||
@@ -0,0 +1,223 @@
|
||||
// Plan2Code Web Console - the Subagents switch's opt-in table, wording and checks.
|
||||
//
|
||||
// The source of truth for which workflows offer the switch, the instruction
|
||||
// each one ships with, the fixed frame every "on" block carries, the exact
|
||||
// lines the agent reads at a pickup (blockFor()), and the house rules for the
|
||||
// helpers an agent reports back (checkHelper()). No DOM access at module scope
|
||||
// and no imports: the server, console.mjs, the page and `node --test` all
|
||||
// import this file.
|
||||
|
||||
// The one place a skill opts in (FR-1). Wording is behaviour-level and names
|
||||
// no harness tool, so any agent can follow it or harmlessly ignore it.
|
||||
export const SUBAGENT_WORKFLOWS = Object.freeze({
|
||||
implement: Object.freeze({
|
||||
instruction:
|
||||
"Hand independent tasks in a phase to helpers: tasks that touch different files and do not depend on each other. Keep tasks that share files, the phase's tests and the sign-off with you.",
|
||||
}),
|
||||
"implement-review": Object.freeze({
|
||||
instruction:
|
||||
"Hand independent tasks in a phase to helpers: tasks that touch different files and do not depend on each other. Keep tasks that share files, the phase's tests and the sign-off with you.",
|
||||
}),
|
||||
"quick-task": Object.freeze({
|
||||
instruction:
|
||||
"Use helpers for side lookups, such as reading unfamiliar code or checking documentation, while you make the change yourself.",
|
||||
}),
|
||||
review: Object.freeze({
|
||||
instruction:
|
||||
"Split the review across helpers by area (for example correctness, tests and security), then merge and de-duplicate their findings yourself before you report.",
|
||||
}),
|
||||
pathfinder: Object.freeze({
|
||||
instruction:
|
||||
"Use helpers for codebase recon, sketches and lookups beside the conversation. Keep every question for the person with you.",
|
||||
}),
|
||||
});
|
||||
|
||||
export function offered(workflow) {
|
||||
return typeof workflow === "string" && Object.prototype.hasOwnProperty.call(SUBAGENT_WORKFLOWS, workflow);
|
||||
}
|
||||
|
||||
export const MAX_MIN = 1;
|
||||
export const MAX_MAX = 20;
|
||||
export const DEFAULT_MAX = 3;
|
||||
export const INSTRUCTION_MAX_CHARS = 2000;
|
||||
export const HELPER_TITLE_MAX = 80;
|
||||
export const HELPER_ASK_MAX = 400;
|
||||
export const HELPER_RESULT_MAX = 200;
|
||||
export const HELPER_STATES = Object.freeze(["running", "done", "failed"]);
|
||||
|
||||
/* ------------------------------------------------------------- settings */
|
||||
|
||||
export function defaultInstruction(workflow) {
|
||||
return offered(workflow) ? SUBAGENT_WORKFLOWS[workflow].instruction : "";
|
||||
}
|
||||
|
||||
// The person's own text when they wrote some, else the workflow's default.
|
||||
export function effectiveInstruction(setting) {
|
||||
const own = setting && typeof setting.instruction === "string" ? setting.instruction.trim() : "";
|
||||
return own || defaultInstruction(setting && setting.workflow);
|
||||
}
|
||||
|
||||
export function defaultSetting(workflow) {
|
||||
return { workflow, on: false, instruction: null, max: DEFAULT_MAX };
|
||||
}
|
||||
|
||||
/**
|
||||
* `{ on, instruction, max }` from untrusted input, or `{ error }` naming the
|
||||
* field that failed: "bad" (wrong type), "too-long" (instruction) or "max".
|
||||
* Returns an error object rather than throwing, so the route and the store
|
||||
* reader share one validator. An empty instruction means the default: null.
|
||||
*/
|
||||
export function cleanSetting(input) {
|
||||
if (!input || typeof input !== "object" || Array.isArray(input)) return { error: "bad" };
|
||||
if (typeof input.on !== "boolean") return { error: "bad" };
|
||||
let instruction = null;
|
||||
if (input.instruction !== null && input.instruction !== undefined) {
|
||||
if (typeof input.instruction !== "string") return { error: "bad" };
|
||||
const trimmed = input.instruction.trim();
|
||||
if (trimmed.length > INSTRUCTION_MAX_CHARS) return { error: "too-long" };
|
||||
instruction = trimmed || null;
|
||||
}
|
||||
const max = input.max;
|
||||
if (!Number.isInteger(max) || max < MAX_MIN || max > MAX_MAX) return { error: "max" };
|
||||
return { on: input.on, instruction, max };
|
||||
}
|
||||
|
||||
/* ------------------------------------------------------------ the lines */
|
||||
|
||||
// The non-editable part of every "on" block (FR-8).
|
||||
export const FRAME_LINES = Object.freeze([
|
||||
"Hand independent work to helpers if your tools allow it; otherwise carry on alone.",
|
||||
"Report each helper on the page (console.md → Standing instructions); questions for the person stay with you.",
|
||||
'With no way to start helpers, report one "working alone" entry for this skill run instead.',
|
||||
]);
|
||||
|
||||
export const PATHFINDER_RESEARCH_LINE = "Research questions always use helpers, whatever this switch says.";
|
||||
|
||||
// Only the first line of a block starts at column 0, so no line inside it can
|
||||
// be read as an entry of its own (NFR-5).
|
||||
export function onLines({ revision, replaces, max, instruction }) {
|
||||
const label = replaces ? `revision ${revision}, replaces revision ${replaces}` : `revision ${revision}`;
|
||||
const own = String(instruction || "")
|
||||
.split("\n")
|
||||
.map((line) => line.trimEnd())
|
||||
.filter((line) => line.trim());
|
||||
return [
|
||||
`Subagents: on (${label}) — a console setting, not typed by the person.`,
|
||||
...[...FRAME_LINES, ...own, `At most ${max} helpers at once.`].map((line) => " " + line),
|
||||
];
|
||||
}
|
||||
|
||||
export function offLine(revision) {
|
||||
return `Subagents: off (revision ${revision}) — don't start new helpers for the rest of this session.`;
|
||||
}
|
||||
|
||||
/**
|
||||
* What the agent is owed at a pickup, given the session setting and the
|
||||
* cursor of what it was last told: `null`, or `{ field, lines, cursor }`
|
||||
* where `cursor` is what to write once the lines are printed. Never says
|
||||
* "off" to an agent that was not told "on" (FR-6). Pure: no clock, no I/O.
|
||||
*/
|
||||
export function blockFor(setting, told) {
|
||||
const last = told || { revision: 0, state: "none" };
|
||||
if (!setting || !offered(setting.workflow) || !(setting.revision > last.revision)) return null;
|
||||
const { revision, max } = setting;
|
||||
const instruction = effectiveInstruction(setting);
|
||||
if (setting.on) {
|
||||
const replaces = last.state === "on" ? last.revision : undefined;
|
||||
return {
|
||||
field: { state: "on", revision, max, instruction },
|
||||
lines: onLines({ revision, replaces, max, instruction }),
|
||||
cursor: { revision, state: "on" },
|
||||
};
|
||||
}
|
||||
if (last.state !== "on") return null;
|
||||
return {
|
||||
field: { state: "off", revision, max, instruction },
|
||||
lines: [offLine(revision)],
|
||||
cursor: { revision, state: "off" },
|
||||
};
|
||||
}
|
||||
|
||||
/* ------------------------------------------------------------ helpers */
|
||||
|
||||
const isPlainObject = (v) => !!v && typeof v === "object" && !Array.isArray(v);
|
||||
const nonEmpty = (v) => typeof v === "string" && v.trim() !== "";
|
||||
|
||||
// The problems with one reported helper, [] when it is fine.
|
||||
export function checkHelper(entry) {
|
||||
if (!isPlainObject(entry)) return ["helper: each entry must be an object"];
|
||||
if (!nonEmpty(entry.id)) return ["helper: id must be a non-empty string"];
|
||||
const who = `helper "${entry.id}"`;
|
||||
if (entry.alone === true) return entry.id === "alone" ? [] : [`${who}: the working-alone entry must have id "alone"`];
|
||||
const problems = [];
|
||||
if (!nonEmpty(entry.title)) problems.push(`${who}: title must be a non-empty string`);
|
||||
else if (entry.title.length > HELPER_TITLE_MAX) problems.push(`${who}: title must be at most ${HELPER_TITLE_MAX} characters`);
|
||||
if (!nonEmpty(entry.ask)) problems.push(`${who}: ask must be a non-empty string`);
|
||||
else if (entry.ask.length > HELPER_ASK_MAX) problems.push(`${who}: ask must be at most ${HELPER_ASK_MAX} characters`);
|
||||
if (!HELPER_STATES.includes(entry.state)) problems.push(`${who}: state must be running, done or failed`);
|
||||
if (entry.result !== undefined) {
|
||||
if (typeof entry.result !== "string") problems.push(`${who}: result must be a string`);
|
||||
else if (entry.result.length > HELPER_RESULT_MAX) problems.push(`${who}: result must be at most ${HELPER_RESULT_MAX} characters`);
|
||||
}
|
||||
return problems;
|
||||
}
|
||||
|
||||
// The problems with a whole merged list.
|
||||
export function checkHelpers(list) {
|
||||
if (!Array.isArray(list)) return ["helpers must be an array"];
|
||||
const problems = [];
|
||||
const seen = new Set();
|
||||
let alone = 0;
|
||||
for (const entry of list) {
|
||||
if (isPlainObject(entry) && nonEmpty(entry.id)) {
|
||||
if (seen.has(entry.id)) problems.push(`helper "${entry.id}": duplicate id`);
|
||||
seen.add(entry.id);
|
||||
if (entry.alone === true && ++alone === 2) problems.push(`helper "${entry.id}": only one working-alone entry is allowed`);
|
||||
}
|
||||
problems.push(...checkHelper(entry));
|
||||
}
|
||||
return problems;
|
||||
}
|
||||
|
||||
/* ------------------------------------------------------------ the page */
|
||||
|
||||
// The page's rules for the button, the modal and the tab, kept here so they
|
||||
// are tested without a browser. `frame` is the state frame's `subagents`
|
||||
// block; app.js only renders what these say.
|
||||
|
||||
export const CHECKIN_LINE = "Helpers report through Plan2Code, so their progress shows here at its check-ins, not live.";
|
||||
|
||||
const STATE_LABELS = Object.freeze({ running: "Running", done: "Done", failed: "Failed" });
|
||||
|
||||
// The switch shows only where the skill opts in AND the agent's console copy
|
||||
// said it can deliver it (FR-3).
|
||||
export function showSwitch(frame) {
|
||||
return Boolean(frame && frame.offered && frame.supported);
|
||||
}
|
||||
|
||||
// The button's tooltip and accessible name (FR-2).
|
||||
export function switchLabel(frame) {
|
||||
return frame && frame.on ? "Subagents: on" : "Subagents: off";
|
||||
}
|
||||
|
||||
// What the Subagents tab draws: the working-alone note, or one row per helper
|
||||
// in the order the agent reported them. A result shows once the helper ended.
|
||||
export function helperRows(helpers) {
|
||||
const list = Array.isArray(helpers) ? helpers.filter(isPlainObject) : [];
|
||||
if (list.some((h) => h.alone === true)) return { alone: true, rows: [] };
|
||||
const rows = list.map(({ id, title, ask, state, result }) => ({
|
||||
id,
|
||||
title,
|
||||
ask,
|
||||
state,
|
||||
stateLabel: STATE_LABELS[state] || STATE_LABELS.running,
|
||||
...((state === "done" || state === "failed") && typeof result === "string" && result ? { result } : {}),
|
||||
}));
|
||||
return { alone: false, rows };
|
||||
}
|
||||
|
||||
// Never an empty tab. Independent of on / off, so Pathfinder's research
|
||||
// helpers show even with the switch off (FR-11, FR-12).
|
||||
export function showTab(frame, helpers) {
|
||||
return showSwitch(frame) && Array.isArray(helpers) && helpers.length > 0;
|
||||
}
|
||||
@@ -25,6 +25,7 @@ import {
|
||||
LOOKS_FILE,
|
||||
PUBLIC_DIR,
|
||||
SHIPPED_MODELS_FILE,
|
||||
SUBAGENTS_SETTING_FILE,
|
||||
UPDATE_CHECK_FILE,
|
||||
USER_MODELS_FILE,
|
||||
WORKSPACE_FILE,
|
||||
@@ -38,6 +39,7 @@ import {
|
||||
fileStamp,
|
||||
handleFile,
|
||||
initialWorkspace,
|
||||
latestOpenCaps,
|
||||
nowIso,
|
||||
parseArgs,
|
||||
pendingChatCount,
|
||||
@@ -46,20 +48,25 @@ import {
|
||||
readJson,
|
||||
readLedger,
|
||||
readOverview,
|
||||
readSubagentSetting,
|
||||
readWorkspace,
|
||||
rememberWorkspace,
|
||||
rememberedWorkspace,
|
||||
removeCleanup,
|
||||
remoteWarning,
|
||||
saveSubagentStoreEntry,
|
||||
specKey,
|
||||
subagentStoreEntry,
|
||||
typedCount,
|
||||
withStateLock,
|
||||
writeJsonAtomic,
|
||||
writeSubagentSetting,
|
||||
writeWorkspace,
|
||||
} from "./lib.mjs";
|
||||
import { DOC_TYPES, MAX_ATTACHMENTS, MAX_DOC_BYTES, docExt, workflowLabel, workflowTitle } from "./public/answers.js";
|
||||
import { CHAT_LIMIT, CHAT_MAX_CHARS, chatOffline } from "./public/chat.js";
|
||||
import { meterView } from "./public/meter.js";
|
||||
import { cleanSetting, defaultSetting, offered } from "./public/subagents.js";
|
||||
import { ACCENTS, DEFAULT_ACCENT, DEFAULT_CARD_WIDTH, cardWidth } from "./public/palette.js";
|
||||
import { defaultName, freeName, nameProblem } from "./public/workspace.js";
|
||||
import { checkForUpdate } from "./update-check.mjs";
|
||||
@@ -212,6 +219,7 @@ const SERVABLE = new Set([
|
||||
"starters.js",
|
||||
"workspace.js",
|
||||
"meter.js",
|
||||
"subagents.js",
|
||||
"mentions.js",
|
||||
"favicon.js",
|
||||
"start-stop.mp3",
|
||||
@@ -601,6 +609,48 @@ function ensureConversation(state) {
|
||||
if (entry) appendEvent(DIR, { type: "chat-reset", reason: entry.reason });
|
||||
}
|
||||
|
||||
/* ------------------------------------------------------------ subagents */
|
||||
|
||||
// subagents-setting.json has one writer, this server, and the agent hears of
|
||||
// it only through what console.mjs reads there; events.ndjson's latest `open`
|
||||
// says whether the agent's console copy can carry it. Both re-read only when
|
||||
// their file has moved.
|
||||
const SUBAGENTS_SETTING_PATH = path.join(DIR, SUBAGENTS_SETTING_FILE);
|
||||
const EVENTS_PATH = path.join(DIR, "events.ndjson");
|
||||
|
||||
let subagentSettingSeen = { stamp: null, setting: null };
|
||||
function subagentSettingNow() {
|
||||
const stamp = fileStamp(SUBAGENTS_SETTING_PATH);
|
||||
if (stamp !== subagentSettingSeen.stamp) subagentSettingSeen = { stamp, setting: readSubagentSetting(DIR) };
|
||||
return subagentSettingSeen.setting;
|
||||
}
|
||||
|
||||
let capsSeen = { stamp: null, caps: [] };
|
||||
function openCapsNow() {
|
||||
const stamp = fileStamp(EVENTS_PATH);
|
||||
if (stamp !== capsSeen.stamp) capsSeen = { stamp, caps: latestOpenCaps(DIR) };
|
||||
return capsSeen.caps;
|
||||
}
|
||||
|
||||
const sameSetting = (a, b) => a.workflow === b.workflow && a.on === b.on && a.instruction === b.instruction && a.max === b.max;
|
||||
|
||||
/**
|
||||
* Turn the per-project store into this session's setting, for the workflow
|
||||
* the session is in now. The only place that happens (FR-7): a session an
|
||||
* older server ran has no setting file, so nothing is ever injected into it.
|
||||
* A record that already matches is left alone, revision and all, so a
|
||||
* restart alone never re-tells the agent anything.
|
||||
*/
|
||||
function syncSubagentSetting(state) {
|
||||
if (!state || typeof state.workflow !== "string") return;
|
||||
const { workflow } = state;
|
||||
const { on, instruction, max } = offered(workflow) ? subagentStoreEntry(sessionWorktree(), workflow) : defaultSetting(workflow);
|
||||
const target = { workflow, on, instruction, max };
|
||||
const current = readSubagentSetting(DIR);
|
||||
if (current && sameSetting(current, target)) return;
|
||||
writeSubagentSetting(DIR, { ...target, revision: (current ? current.revision : 0) + 1 });
|
||||
}
|
||||
|
||||
// What the page needs to draw itself, in the shape of the SSE state frame.
|
||||
// `have` names that exact view, for the page to hand back when it opens its
|
||||
// stream (see /events).
|
||||
@@ -615,20 +665,33 @@ function stateFrame(state) {
|
||||
chat: { ...chatForFrame(chatEntries(), state), pickedUp: chatPickedUp(), offline: chatOfflineNow(state) },
|
||||
workspace: workspaceView(),
|
||||
meter: meterView(ledgerEntries()),
|
||||
subagents: subagentsView(state),
|
||||
...(updateInfo ? { update: updateInfo } : {}),
|
||||
have: haveKey(),
|
||||
};
|
||||
}
|
||||
|
||||
// The page shows the switch only when `offered && supported` (FR-3); the
|
||||
// frame says both and leaves combining them to the page. `instruction: null`
|
||||
// is the shipped default, which the page reads from subagents.js itself.
|
||||
function subagentsView(state) {
|
||||
const workflow = state && state.workflow;
|
||||
const { on, instruction, max, revision } = subagentSettingNow() || { ...defaultSetting(workflow), revision: 0 };
|
||||
return { offered: offered(workflow), supported: openCapsNow().includes("subagents"), on, instruction, max, revision };
|
||||
}
|
||||
|
||||
function haveKey() {
|
||||
const { pending, stop } = resultFlags();
|
||||
chatEntries();
|
||||
chatPickedUp();
|
||||
workspaceNow();
|
||||
ledgerEntries();
|
||||
subagentSettingNow();
|
||||
openCapsNow();
|
||||
return (
|
||||
`${STARTED}.${rev}.${pending ? 1 : 0}${stop ? 1 : 0}.${chatSeen.stamp || ""}.${cursorSeen.stamp || ""}` +
|
||||
`.${workspaceSeen.stamp || ""}.${ledgerSeen.stamp || ""}.${updateInfo ? updateInfo.latest : ""}`
|
||||
`.${workspaceSeen.stamp || ""}.${ledgerSeen.stamp || ""}.${updateInfo ? updateInfo.latest : ""}` +
|
||||
`.${subagentSettingSeen.stamp || ""}.${capsSeen.stamp || ""}`
|
||||
);
|
||||
}
|
||||
|
||||
@@ -1172,6 +1235,39 @@ const server = http.createServer((req, res) => {
|
||||
});
|
||||
}
|
||||
|
||||
// The Subagents switch for the session's workflow. Saved per project folder
|
||||
// for the next session, and applied to this one with a bumped revision, which
|
||||
// is what console.mjs hands the agent at its next pickup. Never blocked by,
|
||||
// and never blocking, a card send.
|
||||
if (pathname === "/subagents" && req.method === "POST") {
|
||||
if (!originOk(req, port)) return json(res, 403, { error: "bad origin" });
|
||||
return readBody(req, (err, body) => {
|
||||
if (err) return json(res, err.tooBig ? 413 : 400, { error: err.tooBig ? "too large" : "body must be JSON" });
|
||||
const state = readState();
|
||||
if (!state || !offered(state.workflow)) return json(res, 400, { error: "not-offered" });
|
||||
const clean = cleanSetting(body);
|
||||
if (clean.error) return json(res, 400, { error: clean.error });
|
||||
const { on, instruction, max } = clean;
|
||||
const current = readSubagentSetting(DIR);
|
||||
const next = { workflow: state.workflow, on, instruction, max };
|
||||
// The store is per project, so another session may have moved it since
|
||||
// this one synced: it always takes the person's latest pick. Only a
|
||||
// real change to this session's setting bumps what the agent hears.
|
||||
const unchanged = Boolean(current && sameSetting(current, next));
|
||||
try {
|
||||
saveSubagentStoreEntry(sessionWorktree(), state.workflow, { on, instruction, max });
|
||||
if (!unchanged) writeSubagentSetting(DIR, { ...next, revision: (current ? current.revision : 0) + 1 });
|
||||
} catch (e) {
|
||||
return json(res, 500, { error: String(e.message) });
|
||||
}
|
||||
if (unchanged) return json(res, 200, { ok: true, setting: current });
|
||||
const setting = readSubagentSetting(DIR);
|
||||
appendEvent(DIR, { type: "subagents", on, revision: setting.revision });
|
||||
pushState();
|
||||
return json(res, 200, { ok: true, setting });
|
||||
});
|
||||
}
|
||||
|
||||
// The launcher's model menu: what ships (read-only here) and what the user added.
|
||||
if (pathname === "/models" && req.method === "GET") {
|
||||
const saved = readJson(USER_MODELS_FILE, null) || {};
|
||||
@@ -1400,6 +1496,9 @@ const server = http.createServer((req, res) => {
|
||||
try {
|
||||
ensureConversation(written.state);
|
||||
} catch {}
|
||||
try {
|
||||
syncSubagentSetting(written.state);
|
||||
} catch {}
|
||||
}
|
||||
}
|
||||
// Name the items that went. A page with OTHER answers staged should drop
|
||||
@@ -1726,6 +1825,9 @@ function checkState() {
|
||||
try {
|
||||
ensureConversation(parsed);
|
||||
} catch {}
|
||||
try {
|
||||
syncSubagentSetting(parsed);
|
||||
} catch {}
|
||||
try {
|
||||
followSpecDir(parsed);
|
||||
} catch {}
|
||||
@@ -1900,6 +2002,9 @@ function onListening(port) {
|
||||
try {
|
||||
bootWorkspace();
|
||||
} catch {}
|
||||
try {
|
||||
syncSubagentSetting(readState());
|
||||
} catch {}
|
||||
process.stdout.write(JSON.stringify({ type: "ready", url, port, sid: SID }) + "\n");
|
||||
try {
|
||||
startUpdateCheck();
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "Plan2Code",
|
||||
"version": "2.4.2",
|
||||
"version": "2.5.0",
|
||||
"description": "A structured 4-step workflow methodology for AI-assisted software development",
|
||||
"keywords": [
|
||||
"ai",
|
||||
@@ -17,6 +17,6 @@
|
||||
"url": "https://github.com/jparkerweb/plan2code"
|
||||
},
|
||||
"homepage": "https://github.com/jparkerweb/plan2code",
|
||||
"releaseDate": "2026-10-05",
|
||||
"releaseDate": "2026-10-06",
|
||||
"mode": "utility"
|
||||
}
|
||||
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "Plan2Code",
|
||||
"version": "2.4.2",
|
||||
"version": "2.5.0",
|
||||
"description": "A structured 4-step workflow methodology for AI-assisted software development",
|
||||
"keywords": [
|
||||
"ai",
|
||||
@@ -17,6 +17,6 @@
|
||||
"url": "https://github.com/jparkerweb/plan2code"
|
||||
},
|
||||
"homepage": "https://github.com/jparkerweb/plan2code",
|
||||
"releaseDate": "2026-10-05",
|
||||
"releaseDate": "2026-10-06",
|
||||
"mode": "utility"
|
||||
}
|
||||
@@ -64,6 +64,13 @@ progress bar is the first thing someone watching a build looks at. The session
|
||||
meter counts the build's tasks from `cleared` as it rises, so keep it current,
|
||||
and start every phase (a second one in the same run too) at `"cleared": 0`.
|
||||
|
||||
`"version": 1` is for the first phase of a session only. A doc's version
|
||||
never goes back (console.md → House rules, rule 9), so a later phase in the
|
||||
same session reposts `phase` and `phasefile` at one more than the version the
|
||||
page holds, with the new phase's title and content. The same goes for
|
||||
`report` at sign-off and `review` in a mid-session review: version 1 the
|
||||
first time, then up from wherever the page has it.
|
||||
|
||||
`phasefile` is the whole `phase-X.md`, verbatim from disk, as its own tab —
|
||||
the person can read the prerequisites and task specs while you build. Re-post
|
||||
it whenever the file changes, which is every task: the checkbox write that
|
||||
@@ -111,6 +118,12 @@ printed), never into the project or into `~/.plan2code/console/` directly:
|
||||
- Do not call `wait` while building. There is nothing to collect, and the page
|
||||
holds anything the person sends until you next look.
|
||||
|
||||
A build may receive a `Subagents:` standing instruction, on `open` output or a
|
||||
`chat` check between tasks. Follow console.md → Standing instructions for
|
||||
handing independent tasks to helpers and reporting them as `helpers`. Keep the
|
||||
per-task progress posts, the checkbox writes, the chat checks and the sign-off
|
||||
with you.
|
||||
|
||||
### Quick questions between tasks
|
||||
|
||||
The person can ask a Quick question on the Ask tab at any point in a build
|
||||
@@ -195,7 +208,8 @@ only ever be offered once nothing could come of it:
|
||||
`reply` carries `Approve this phase: approved`, which is the terminal's
|
||||
`approved`. If the note that came with an approval asks for a change, treat it
|
||||
as "describe any issues": do the change first and ask again. `changes` means
|
||||
exactly what it says: address it, bump the report's version, and reopen the
|
||||
exactly what it says: address it, bump the report's version (a later phase's
|
||||
report starts above the last one's, too), and reopen the
|
||||
item (`"status": "reopened"`) with a reply in its `thread`. `review` is the
|
||||
person asking for the code review before they approve anything — see "The
|
||||
review, mid-session" below.
|
||||
|
||||
@@ -170,7 +170,7 @@ so even a kill at the worst possible moment costs you a repeat, never an answer.
|
||||
|
||||
| Exit | Meaning | What you do |
|
||||
| --- | --- | --- |
|
||||
| `0` | They pressed Send, or asked a Quick question. stdout is the result JSON, and may carry `workspace` (changes to the folder list, see Workspace). | Handle the cards (if any), the chat (if any) and any `workspace` changes, then post once (below, Quick questions and Workspace). |
|
||||
| `0` | They pressed Send, or asked a Quick question. stdout is the result JSON, and may carry `workspace` (changes to the folder list, see Workspace) and `subagents` (the helpers switch, see Standing instructions). | Handle the cards (if any), the chat (if any), any `workspace` changes and any `subagents` block, then post once (below, Quick questions, Workspace and Standing instructions). |
|
||||
| `10` | Still working. stdout has a short progress summary; `pendingWorkspace` counts workspace changes waiting for the next send. | Relay ONE line: the `message` field itself, "Waiting on your answer in the web console", followed by the `terminalLine`. Then call `wait` again. |
|
||||
| `20` | The server is gone. | `open --resume <sid>`, give them the new link, then keep waiting. |
|
||||
| `30` | They pressed Cancel. | Stop. Ask what they want to do, in the terminal. |
|
||||
@@ -647,6 +647,84 @@ for permission is not a failure; report only a read that failed after it.
|
||||
|
||||
---
|
||||
|
||||
## Standing instructions
|
||||
|
||||
On the skills that offer it (`implement`, `implement-review`, `quick-task`,
|
||||
`review`, `pathfinder`), the person can turn **helpers** (subagents) on or off
|
||||
from the top bar's Subagents button. Their pick is saved per project and per
|
||||
skill, off by default, and reaches you as a standing instruction, only when it
|
||||
changes.
|
||||
|
||||
### What arrives
|
||||
|
||||
A `subagents` field beside `reply`, and `Subagents:` lines last in `reply`,
|
||||
after the card lines, the `Quick question:` blocks and the `Workspace:` lines.
|
||||
It rides on `wait` exit `0`, `chat` exit `0` and `open` output. A setting
|
||||
change alone never ends a `wait` slice: it waits for the next send, or for
|
||||
your next `chat` check.
|
||||
|
||||
```
|
||||
Subagents: on (revision 2) — a console setting, not typed by the person.
|
||||
Hand independent work to helpers if your tools allow it; otherwise carry on alone.
|
||||
Report each helper on the page (console.md → Standing instructions); questions for the person stay with you.
|
||||
With no way to start helpers, report one "working alone" entry for this skill run instead.
|
||||
Hand independent tasks in a phase to helpers: tasks that touch different files and do not depend on each other. Keep tasks that share files, the phase's tests and the sign-off with you.
|
||||
At most 3 helpers at once.
|
||||
```
|
||||
|
||||
beside `"subagents": { "state": "on", "revision": 2, "max": 3, "instruction": "…" }`.
|
||||
An edit while on arrives as `Subagents: on (revision 3, replaces revision 2) — …`
|
||||
with the whole block again; switching off arrives as one line:
|
||||
`Subagents: off (revision 4) — don't start new helpers for the rest of this session.`
|
||||
|
||||
It is a console setting, not something the person typed. It never answers a
|
||||
card, and it is never recorded under `specs/`.
|
||||
|
||||
### Obeying it
|
||||
|
||||
- **On:** hand independent work to helpers if your tools allow it, at most
|
||||
`max` at once, following the instruction lines. `max` is advisory: your
|
||||
harness's own limit still applies.
|
||||
- **A higher revision replaces a lower one.** Follow the latest block only.
|
||||
- **Off:** start no new helpers for the rest of the session. Let running ones
|
||||
finish and report them.
|
||||
- **Nothing arrives:** keep doing what the skill says.
|
||||
- **Scope is the skill run it arrived in.** After a dashboard launch, no block
|
||||
means the switch is off for this skill, even if an earlier skill in the same
|
||||
conversation was told "on": `open` starts the count again, and a launch with
|
||||
the switch off sends nothing.
|
||||
|
||||
### Reporting helpers
|
||||
|
||||
Post them, at your check-ins, so the page's Subagents tab can show them. The
|
||||
page never hears from a helper directly:
|
||||
|
||||
```jsonc
|
||||
{ "helpers": [
|
||||
{ "id": "h1", "title": "Read the store helpers", "ask": "Find every caller of readSubagentSetting.", "state": "running" },
|
||||
{ "id": "h2", "title": "Check the tests", "ask": "Run the subagents tests and report failures.", "state": "done", "result": "All 9 pass." }
|
||||
] }
|
||||
```
|
||||
|
||||
- `id` (non-empty), `title` (at most 80 characters), `ask` (at most 400) and
|
||||
`state` (`running`, `done` or `failed`) are required; `result` (at most 200)
|
||||
is the one line you add once a helper ends.
|
||||
- Merged by `id`: post a helper again with its new `state` and `result` and it
|
||||
updates in place. `"helpers": null` clears the list. A dashboard hop clears it
|
||||
too; a resume into the same skill keeps it.
|
||||
- One post per change worth seeing, not a stream.
|
||||
- Questions for the person stay with you, never with a helper: most harnesses
|
||||
give helpers no way to ask, and an answer only reaches the agent holding the
|
||||
session.
|
||||
- **No way to start helpers?** Post one `{ "id": "alone", "alone": true }`
|
||||
entry for the skill run instead. The tab then says you are working alone.
|
||||
- **Pathfinder:** research questions always use helpers and are always
|
||||
reported, whatever the switch says. The switch governs recon, sketches and
|
||||
lookups beside the conversation.
|
||||
- Helpers add no session meter points. Post no `run` for them.
|
||||
|
||||
---
|
||||
|
||||
## Launches (dashboard only)
|
||||
|
||||
A `dashboard` session is not a conversation: the page draws a menu of every
|
||||
@@ -763,7 +841,10 @@ commands follow the pipeline: the sign-off's is
|
||||
|
||||
### Review (`review`)
|
||||
|
||||
Scope questions up front, then the findings report as a doc (`id: "report"`),
|
||||
Scope questions up front — run standalone with nothing named, the first is
|
||||
a `choice`, "What should I review?", built from a quick scan (branch changes,
|
||||
uncommitted changes, specs, files you name; each option with its size),
|
||||
never an assumed target; a build's review skips it (`building.md`). Then the findings report as a doc (`id: "report"`),
|
||||
then the pick-what-gets-fixed menu as a `multi` or `choice` keyed by finding
|
||||
id, carrying `"doc": "report"` so the card links straight to the findings.
|
||||
Settle that item (`"status": "answered"` plus the `answer` they sent) in
|
||||
@@ -797,6 +878,8 @@ that is what the person is there to download. The finish carries no
|
||||
- Chart Step 8's research subagents must all report back before the
|
||||
finish (Finishing → Nothing of yours may still be running); the finish
|
||||
body then names what each one found.
|
||||
- Report every research subagent as a helper, whatever the Subagents switch
|
||||
says (Standing instructions → Reporting helpers).
|
||||
- At every session end, post `finish` (headline, `body`, and Form A's command as
|
||||
`command`) BEFORE `stop`. Someone who spent the session in the browser never
|
||||
sees the Trail Footer, and without this their last screen promises a question
|
||||
@@ -1146,6 +1229,16 @@ A patch that breaks one of these is rejected with exit `3` and a message:
|
||||
(Session meter) and a non-empty `id`; a `folderIssue` needs non-empty
|
||||
`name` and `reason` strings, and `hint`, when present, is one too. Rules 4
|
||||
and 5 cover `reason` and `hint`.
|
||||
8. **`helpers` entries are well formed** (Standing instructions → Reporting
|
||||
helpers): an array of objects, each with a unique `id`, a `title`, an `ask`
|
||||
and a known `state` within their limits, plus at most one `alone` entry.
|
||||
Rules 4 and 5 cover `title`, `ask` and `result`.
|
||||
9. **A doc's `version` never goes back.** Sending a known doc a lower
|
||||
`version` than the page holds is refused: it is almost always a stale or
|
||||
copied payload. The same version again is fine, and a dashboard hop starts
|
||||
every doc fresh. Anything else reusing a doc id in the same session (a
|
||||
build's second phase, a second report or review) continues from the
|
||||
version the page holds.
|
||||
|
||||
These are workflow rules you already follow. The server just makes them checkable.
|
||||
|
||||
@@ -1167,7 +1260,9 @@ cannot see them, and the moment it says the session ended, the person is
|
||||
free to close that terminal and kill them mid-write. While you wait, post
|
||||
`{"agent":{"status":"working","activity":"Researching 3 questions (1 of 3 back)"}}`
|
||||
and update the count as each returns. Never write a `finish.body` that says
|
||||
work "is running in the background" or "will finish on its own".
|
||||
work "is running in the background" or "will finish on its own". Mark every
|
||||
reported helper `done` or `failed` before the finish, so the Subagents tab
|
||||
never ends on a row still running.
|
||||
|
||||
### 1. Post the finish
|
||||
|
||||
|
||||
@@ -64,6 +64,8 @@ import {
|
||||
readChat,
|
||||
readJson,
|
||||
readLedger,
|
||||
readSubagentCursor,
|
||||
readSubagentSetting,
|
||||
readWorkspace,
|
||||
reapHandles,
|
||||
rememberedWorkspace,
|
||||
@@ -71,6 +73,7 @@ import {
|
||||
removeScratch,
|
||||
removeSessions,
|
||||
repoRoots,
|
||||
resetSubagentCursor,
|
||||
scanProject,
|
||||
SESSION_MAX_AGE_MS,
|
||||
sessionDir,
|
||||
@@ -88,9 +91,11 @@ import {
|
||||
workspaceForAgent,
|
||||
writeCursor,
|
||||
writeJsonAtomic,
|
||||
writeSubagentCursor,
|
||||
writeWorkspaceCursor,
|
||||
} from "./lib.mjs";
|
||||
import { RUN_EVENTS, TASK_EVENTS, MAX_TASKS, isTaskCount, progressEntry } from "./public/meter.js";
|
||||
import { blockFor, offered } from "./public/subagents.js";
|
||||
import { changeLine } from "./public/workspace.js";
|
||||
|
||||
// Mirrors the server's absolute lifetime cap: a handle older than this cannot
|
||||
@@ -310,7 +315,11 @@ async function cmdOpen() {
|
||||
die(`could not write the session state: ${written ? written.error : "unknown"}`, 1);
|
||||
}
|
||||
state = written.state;
|
||||
appendEvent(dir, { type: "open", resumed: Boolean(args.resume || args.session), carried });
|
||||
appendEvent(dir, { type: "open", resumed: Boolean(args.resume || args.session), carried, caps: ["subagents"] });
|
||||
// A new agent conversation has been told nothing yet (FR-6).
|
||||
try {
|
||||
resetSubagentCursor(dir);
|
||||
} catch {}
|
||||
trace("open: state written");
|
||||
|
||||
// Dashboard launches are recorded too (they score nothing), so the folder
|
||||
@@ -337,9 +346,18 @@ async function cmdOpen() {
|
||||
removeScratch(HOME_DIR, sweptScratch).catch(() => {});
|
||||
};
|
||||
|
||||
// A standing instruction the new agent is owed, as `subagents` and a
|
||||
// `reply` holding only its lines; neither key when nothing is owed.
|
||||
const subagentsOwed = () => {
|
||||
awaitSubagentSync(dir, state.workflow);
|
||||
const [out, cursor] = withSubagents(dir, { reply: "" });
|
||||
return [out.subagents ? out : {}, cursor];
|
||||
};
|
||||
|
||||
// Reuse a live server if one is already serving this session.
|
||||
if (existing && (await reusable)) {
|
||||
if (!args["no-open"]) openBrowser(existing.url);
|
||||
const [owed, subCursor] = subagentsOwed();
|
||||
print({
|
||||
ok: true,
|
||||
sid,
|
||||
@@ -349,9 +367,11 @@ async function cmdOpen() {
|
||||
pendingResult: carried,
|
||||
terminalLine: terminalLine(existing.url),
|
||||
workspace,
|
||||
...owed,
|
||||
...swept,
|
||||
...remoteWarning(),
|
||||
});
|
||||
advanceSubagents(dir, subCursor);
|
||||
sweep();
|
||||
return;
|
||||
}
|
||||
@@ -384,6 +404,7 @@ async function cmdOpen() {
|
||||
const notes = [];
|
||||
if (remote.note) notes.push(remote.note);
|
||||
if (carried) notes.push("Answers are already waiting. Run `wait` to collect them.");
|
||||
const [owed, subCursor] = subagentsOwed();
|
||||
print({
|
||||
ok: true,
|
||||
sid,
|
||||
@@ -394,10 +415,12 @@ async function cmdOpen() {
|
||||
pendingResult: carried,
|
||||
terminalLine: terminalLine(handle.url),
|
||||
workspace,
|
||||
...owed,
|
||||
...swept,
|
||||
...(remote.remote ? { remote: remote.remote } : {}),
|
||||
...(notes.length ? { note: notes.join(" ") } : {}),
|
||||
});
|
||||
advanceSubagents(dir, subCursor);
|
||||
// After the print, never before it: the page and the link wait for nothing.
|
||||
sweep();
|
||||
}
|
||||
@@ -774,7 +797,7 @@ function serverGone(sid) {
|
||||
|
||||
// Quick questions and nothing else: an ordinary exit 0 with no card actions.
|
||||
function deliverChat(dir, sid, entries, url) {
|
||||
const [out, changes] = withWorkspace(dir, {
|
||||
const [withWs, changes] = withWorkspace(dir, {
|
||||
type: "chat",
|
||||
at: nowIso(),
|
||||
sid,
|
||||
@@ -782,9 +805,11 @@ function deliverChat(dir, sid, entries, url) {
|
||||
chat: entries,
|
||||
reply: chatReplyLines(entries),
|
||||
});
|
||||
const [out, subCursor] = withSubagents(dir, withWs);
|
||||
print({ ...out, ...(url ? { terminalLine: terminalLine(url) } : {}) });
|
||||
advanceCursor(dir, entries);
|
||||
advanceWorkspace(dir, changes);
|
||||
advanceSubagents(dir, subCursor);
|
||||
process.exitCode = 0;
|
||||
}
|
||||
|
||||
@@ -806,6 +831,52 @@ function advanceWorkspace(dir, changes) {
|
||||
} catch {}
|
||||
}
|
||||
|
||||
// The server rewrites the session's setting for a new workflow only once its
|
||||
// watcher sees the state `open` just wrote, so a launch or hop that read the
|
||||
// file at once would find the old workflow's and owe the agent nothing until
|
||||
// its next pickup. Give the server a moment to catch up instead, never
|
||||
// writing the file ourselves (FR-7). A session with no setting file at all is
|
||||
// an older server, which never writes one: a short look, not the full wait.
|
||||
const SUBAGENT_SYNC_WAIT_MS = 1500;
|
||||
const SUBAGENT_SYNC_MISSING_MS = 250;
|
||||
function awaitSubagentSync(dir, workflow) {
|
||||
if (!offered(workflow)) return;
|
||||
const start = Date.now();
|
||||
for (;;) {
|
||||
const setting = readSubagentSetting(dir);
|
||||
if (setting && setting.workflow === workflow) return;
|
||||
const budget = setting ? SUBAGENT_SYNC_WAIT_MS : SUBAGENT_SYNC_MISSING_MS;
|
||||
if (Date.now() - start >= budget) return;
|
||||
sleepSync(25);
|
||||
}
|
||||
}
|
||||
|
||||
// The Subagents switch the agent is owed, added to what it is about to read:
|
||||
// the setting as `subagents`, and its lines last in `reply`, after card lines,
|
||||
// Quick questions and Workspace lines (FR-9). Read from the session's own
|
||||
// setting file only, which only the server writes (FR-7). A setting for
|
||||
// another workflow is the server not having caught up with a hop yet: it
|
||||
// rides on the next pickup instead.
|
||||
function withSubagents(dir, out) {
|
||||
const setting = readSubagentSetting(dir);
|
||||
if (!setting) return [out, null];
|
||||
const workflow = (readJson(path.join(dir, "state.json")) || {}).workflow;
|
||||
if (setting.workflow !== workflow) return [out, null];
|
||||
const block = blockFor(setting, readSubagentCursor(dir));
|
||||
if (!block) return [out, null];
|
||||
const reply = [out.reply, ...block.lines].filter(Boolean).join("\n");
|
||||
return [{ ...out, subagents: block.field, reply }, block.cursor];
|
||||
}
|
||||
|
||||
// After the print, like advanceWorkspace(): a kill in between repeats the
|
||||
// block at the next pickup, never loses it.
|
||||
function advanceSubagents(dir, cursor) {
|
||||
if (!cursor) return;
|
||||
try {
|
||||
writeSubagentCursor(dir, cursor);
|
||||
} catch {}
|
||||
}
|
||||
|
||||
// Print first, then this, exactly as consume() stamps a result: a kill in
|
||||
// between can only hand the same chat over again, and collectChat() drops
|
||||
// anything that already has a reply.
|
||||
@@ -832,15 +903,17 @@ async function cmdChat() {
|
||||
}
|
||||
const entries = deliverableChat(collectChat(dir, readJson(path.join(dir, "state.json")) || {}));
|
||||
const changes = pendingWorkspaceChanges(dir);
|
||||
if (!entries.length && !changes.length) {
|
||||
const reply = [chatReplyLines(entries), ...changes.map(changeLine)].filter(Boolean).join("\n");
|
||||
const [out, subCursor] = withSubagents(dir, { chat: entries, workspace: changes, reply });
|
||||
if (!entries.length && !changes.length && !subCursor) {
|
||||
print({ chat: [] });
|
||||
process.exitCode = 10;
|
||||
return;
|
||||
}
|
||||
const reply = [chatReplyLines(entries), ...changes.map(changeLine)].filter(Boolean).join("\n");
|
||||
print({ chat: entries, workspace: changes, reply, terminalLine: terminalLine(handle.url) });
|
||||
print({ ...out, terminalLine: terminalLine(handle.url) });
|
||||
advanceCursor(dir, entries);
|
||||
advanceWorkspace(dir, changes);
|
||||
advanceSubagents(dir, subCursor);
|
||||
process.exitCode = 0;
|
||||
}
|
||||
|
||||
@@ -865,7 +938,8 @@ function consume(dir, resultPath, result, url, chat = []) {
|
||||
// never on result.json itself.
|
||||
const withChat = { ...collected, chat };
|
||||
if (chat.length) withChat.reply = [collected.reply, chatReplyLines(chat)].filter(Boolean).join("\n");
|
||||
const [out, changes] = withWorkspace(dir, withChat);
|
||||
const [withWs, changes] = withWorkspace(dir, withChat);
|
||||
const [out, subCursor] = withSubagents(dir, withWs);
|
||||
print(url ? { ...out, terminalLine: terminalLine(url) } : out);
|
||||
try {
|
||||
writeJsonAtomic(resultPath, collected);
|
||||
@@ -874,6 +948,7 @@ function consume(dir, resultPath, result, url, chat = []) {
|
||||
ledgerAnswers(dir, result);
|
||||
advanceCursor(dir, chat);
|
||||
advanceWorkspace(dir, changes);
|
||||
advanceSubagents(dir, subCursor);
|
||||
process.exitCode = result.type === "cancel" ? 30 : 0;
|
||||
}
|
||||
|
||||
@@ -986,12 +1061,18 @@ port, and the filesystem as transport; this CLI is the whole agent surface.
|
||||
path, description?, original? }], missing? }, the folders this
|
||||
console session reads as context, addressed as @name. The list is
|
||||
remembered per folder and spec in workspaces.json beside looks.json.
|
||||
May also print subagents: { state, revision, max, instruction } and
|
||||
a reply holding only its "Subagents: ..." lines, when a standing
|
||||
instruction (the page's Subagents switch) is owed to you.
|
||||
post --session <sid> --file <patch.json>
|
||||
Merge a patch into the session. Prints terminalLine while the
|
||||
server is live. Exit 3 = rejected; stderr says why. A patch may
|
||||
carry run: { event, id, tasks? } (session meter points) and folderIssue:
|
||||
{ name, reason, hint? } (a workspace folder you could not read);
|
||||
both go to the ledger, never into the state.
|
||||
both go to the ledger, never into the state. A patch may also
|
||||
carry helpers: [{ id, title, ask, state, result? }] or one
|
||||
{ id: "alone", alone: true }, merged by id, for the Subagents tab
|
||||
(see console.md → Standing instructions).
|
||||
wait --session <sid> [--seconds <N>]
|
||||
A bounded wait slice, sized below your shell timeout. Exit 0 = the
|
||||
result is on stdout, 10 = still waiting ("Waiting on your answer
|
||||
@@ -1002,10 +1083,14 @@ port, and the filesystem as transport; this CLI is the whole agent surface.
|
||||
"workspace" (changes since you last heard, each once, with a
|
||||
"Workspace: ..." line in reply); exit 10 counts them as
|
||||
pendingWorkspace, and a change alone never ends a slice.
|
||||
Exit 0 may also carry "subagents" (a console setting, not typed
|
||||
by the person, with its "Subagents: ..." lines last in reply); a
|
||||
setting change alone never ends a slice either.
|
||||
chat --session <sid>
|
||||
Collect Quick questions and workspace changes now, never waiting,
|
||||
never touching card sends. Exit 0 = { chat, workspace, reply,
|
||||
terminalLine }, 10 = none, 20 = server gone.
|
||||
Collect Quick questions, workspace changes and a Subagents
|
||||
setting change now, never waiting, never touching card sends.
|
||||
Exit 0 = { chat, workspace, subagents?, reply, terminalLine },
|
||||
10 = none, 20 = server gone.
|
||||
terminalLine is "→ Look at the web console: <url>": end your terminal
|
||||
messages with it during a console session.
|
||||
keep --session <sid> --upload <path> --name <name> --spec specs/<idea> [--from <file>]
|
||||
|
||||
@@ -25,6 +25,7 @@ import { fileURLToPath } from "node:url";
|
||||
import { CHAT_LIMIT } from "./public/chat.js";
|
||||
import { DOC_TYPES } from "./public/answers.js";
|
||||
import { defaultName } from "./public/workspace.js";
|
||||
import { checkHelpers, cleanSetting, defaultSetting, offered } from "./public/subagents.js";
|
||||
|
||||
export const HERE = path.dirname(fileURLToPath(import.meta.url));
|
||||
export const PUBLIC_DIR = path.join(HERE, "public");
|
||||
@@ -491,9 +492,16 @@ export async function removeSessions(sessionsDir, sids) {
|
||||
}
|
||||
|
||||
// The console folder's own files that no sweep may ever remove: the person's
|
||||
// looks, the folders remembered per project and spec, the pointer to this
|
||||
// console's directory, and the cached release check.
|
||||
export const PROTECTED_CONSOLE_FILES = new Set(["looks.json", "workspaces.json", "console-dir", "update-check.json"]);
|
||||
// looks, the folders remembered per project and spec, the Subagents switch
|
||||
// saved per project and workflow, the pointer to this console's directory,
|
||||
// and the cached release check.
|
||||
export const PROTECTED_CONSOLE_FILES = new Set([
|
||||
"looks.json",
|
||||
"workspaces.json",
|
||||
"subagents.json",
|
||||
"console-dir",
|
||||
"update-check.json",
|
||||
]);
|
||||
|
||||
function isScratchName(name) {
|
||||
return (
|
||||
@@ -1142,6 +1150,19 @@ const DOC_DEFAULTS = { version: 1, stale: false, blocks: [] };
|
||||
// Blocks merge by id like docs do, so a patch that only settles a block's
|
||||
// state keeps its text. Blocks left out of the patch stay as they are.
|
||||
function mergeDocs(current, patchList) {
|
||||
// A doc's version only moves forward. One going back is a stale or copied
|
||||
// payload (last phase's progress script, say), and the page would quietly
|
||||
// show the old content under the new run's name.
|
||||
for (const entry of patchList) {
|
||||
if (!isPlainObject(entry) || typeof entry.version !== "number") continue;
|
||||
const prev = (current || []).find((d) => d && d.id === entry.id);
|
||||
if (prev && typeof prev.version === "number" && entry.version < prev.version) {
|
||||
throw new Error(
|
||||
`doc "${entry.id}" is at version ${prev.version} on the page; this patch sends version ${entry.version}. ` +
|
||||
"Versions only go up: bump it, and check the payload is the current one."
|
||||
);
|
||||
}
|
||||
}
|
||||
const merged = mergeKeyed(current, patchList, "id", DOC_DEFAULTS, "docs");
|
||||
for (const entry of patchList) {
|
||||
if (!Array.isArray(entry.blocks)) continue;
|
||||
@@ -1184,6 +1205,13 @@ export function applyPatch(state, patch) {
|
||||
if (!Array.isArray(v)) throw new Error('"topics" must be an array');
|
||||
next.topics = mergeKeyed(next.topics, v, "id", {}, "topics");
|
||||
break;
|
||||
case "helpers":
|
||||
// The agent's report of its helpers, for the page's Subagents tab.
|
||||
// Only `post` writes it; the server's /submit never touches it.
|
||||
if (!Array.isArray(v)) throw new Error('"helpers" must be an array');
|
||||
if (!v.every(isPlainObject)) throw new Error('"helpers" entries must be objects, each { id, title, ask, state }');
|
||||
next.helpers = mergeKeyed(next.helpers, v, "id", {}, "helpers");
|
||||
break;
|
||||
case "docs":
|
||||
if (!Array.isArray(v)) throw new Error('"docs" must be an array');
|
||||
next.docs = mergeDocs(next.docs, v);
|
||||
@@ -1478,6 +1506,20 @@ export function validate(state) {
|
||||
JSON.stringify(state.menu || {});
|
||||
problems.push(...proseProblems(prose));
|
||||
|
||||
// The agent's report of its helpers: the shape the page draws from
|
||||
// (subagents.js), then the same prose scan as everything else it writes.
|
||||
if (state.helpers != null) {
|
||||
problems.push(...checkHelpers(state.helpers));
|
||||
for (const helper of Array.isArray(state.helpers) ? state.helpers : []) {
|
||||
if (!isPlainObject(helper)) continue;
|
||||
for (const field of ["title", "ask", "result"]) {
|
||||
if (typeof helper[field] === "string") {
|
||||
problems.push(...proseProblems(helper[field], `helper "${helper.id}" ${field}`));
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
return problems;
|
||||
}
|
||||
|
||||
@@ -1507,7 +1549,8 @@ export function blankState({ sid, workflow, title, project, specDir }) {
|
||||
* A resume that passes through the dashboard (a finished skill going back to
|
||||
* it, or a launch from its menu) is a new skill taking the page over, so it
|
||||
* starts from a blank page: the last skill's questions, sections, docs,
|
||||
* headline and ending are its record on disk, not the next skill's opening.
|
||||
* helpers, headline and ending are its record on disk, not the next skill's
|
||||
* opening.
|
||||
* Only the session's identity carries across. `workspace.json`,
|
||||
* `ledger.ndjson` and the cursors live beside `state.json`, so the workspace
|
||||
* and the meter outlive every hop.
|
||||
@@ -1534,6 +1577,8 @@ export function switchWorkflow(state, { workflow, title, specDir }) {
|
||||
// workspace.json the server. Folders, version, change log, missing, remote.
|
||||
// ledger.ndjson console.mjs. Append-only meter events and folder issues.
|
||||
// workspace-cursor.json console.mjs. The last workspace version handed to the agent.
|
||||
// subagents-setting.json the server. The Subagents switch for this session, with its revision.
|
||||
// subagents-cursor.json console.mjs. The last Subagents revision and state handed to the agent.
|
||||
export const CHAT_FILE = "chat.ndjson";
|
||||
export const CHAT_CURSOR_FILE = "chat-cursor.json";
|
||||
export const WORKSPACE_FILE = "workspace.json";
|
||||
@@ -1989,6 +2034,98 @@ export function pendingWorkspaceChanges(dir) {
|
||||
return (readWorkspace(dir)?.changes || []).filter((c) => c.version > cursor);
|
||||
}
|
||||
|
||||
/* ------------------------------------------------------ the Subagents switch */
|
||||
|
||||
// The person's Subagents switch, remembered per project folder and workflow:
|
||||
//
|
||||
// { "<folded project path>": { "<workflow>": { on, instruction, max } } }
|
||||
//
|
||||
// Keyed with foldKey(), as workspaces.json is. `instruction: null` is the
|
||||
// workflow's shipped default.
|
||||
export const SUBAGENTS_FILE = path.join(HOME_DIR, "subagents.json");
|
||||
const SUBAGENTS_LOCK = "subagents.json.lock";
|
||||
|
||||
function readSubagentStore() {
|
||||
const saved = readJson(SUBAGENTS_FILE, null);
|
||||
return saved && typeof saved === "object" && !Array.isArray(saved) ? saved : {};
|
||||
}
|
||||
|
||||
// The saved `{ on, instruction, max }` for this folder and workflow, or the
|
||||
// default's when nothing (or something malformed) is saved.
|
||||
export function subagentStoreEntry(worktree, workflow) {
|
||||
const { on, instruction, max } = defaultSetting(workflow);
|
||||
const project = offered(workflow) ? readSubagentStore()[foldKey(worktree)] : null;
|
||||
const saved = project && typeof project === "object" ? cleanSetting(project[workflow]) : null;
|
||||
return saved && !saved.error ? saved : { on, instruction, max };
|
||||
}
|
||||
|
||||
// Single-writer rule: only server.mjs may call this.
|
||||
export function saveSubagentStoreEntry(worktree, workflow, value) {
|
||||
ensureDir(path.dirname(SUBAGENTS_FILE));
|
||||
withStateLock(
|
||||
path.dirname(SUBAGENTS_FILE),
|
||||
() => {
|
||||
const store = readSubagentStore();
|
||||
const key = foldKey(worktree);
|
||||
const project = store[key] && typeof store[key] === "object" ? store[key] : {};
|
||||
store[key] = { ...project, [workflow]: { on: value.on, instruction: value.instruction, max: value.max } };
|
||||
writeJsonAtomic(SUBAGENTS_FILE, store);
|
||||
},
|
||||
SUBAGENTS_LOCK
|
||||
);
|
||||
}
|
||||
|
||||
export const SUBAGENTS_SETTING_FILE = "subagents-setting.json";
|
||||
|
||||
const isCount = (n) => Number.isInteger(n) && n >= 0;
|
||||
|
||||
// This session's switch, `{ workflow, on, instruction, max, revision }`, or
|
||||
// null when there is none or it is malformed.
|
||||
export function readSubagentSetting(dir) {
|
||||
const s = readJson(path.join(dir, SUBAGENTS_SETTING_FILE), null);
|
||||
if (!s || typeof s !== "object") return null;
|
||||
if (typeof s.workflow !== "string" || typeof s.on !== "boolean" || !Number.isInteger(s.max) || !isCount(s.revision)) return null;
|
||||
return s;
|
||||
}
|
||||
|
||||
// Single-writer rule: only server.mjs may call this. The revision never goes
|
||||
// backwards within a session.
|
||||
export function writeSubagentSetting(dir, setting) {
|
||||
const previous = readSubagentSetting(dir);
|
||||
const revision = Math.max(previous ? previous.revision : 0, setting.revision);
|
||||
return writeJsonAtomic(path.join(dir, SUBAGENTS_SETTING_FILE), { ...setting, revision });
|
||||
}
|
||||
|
||||
export const SUBAGENTS_CURSOR_FILE = "subagents-cursor.json";
|
||||
const CURSOR_STATES = new Set(["none", "on", "off"]);
|
||||
|
||||
// What the agent was last told: `{ revision, state }`.
|
||||
export function readSubagentCursor(dir) {
|
||||
const saved = readJson(path.join(dir, SUBAGENTS_CURSOR_FILE), null);
|
||||
if (!saved || !isCount(saved.revision) || !CURSOR_STATES.has(saved.state)) return { revision: 0, state: "none" };
|
||||
return { revision: saved.revision, state: saved.state };
|
||||
}
|
||||
|
||||
// Single-writer rule: only console.mjs may call this. Never backwards, like
|
||||
// writeWorkspaceCursor(): a killed `wait` may repeat a change, never skip one.
|
||||
export function writeSubagentCursor(dir, cursor) {
|
||||
const old = readSubagentCursor(dir);
|
||||
const next = cursor.revision < old.revision ? old : { revision: cursor.revision, state: cursor.state };
|
||||
writeJsonAtomic(path.join(dir, SUBAGENTS_CURSOR_FILE), next);
|
||||
}
|
||||
|
||||
// The one place the cursor may go back: `open`, which starts a fresh agent.
|
||||
export function resetSubagentCursor(dir) {
|
||||
writeJsonAtomic(path.join(dir, SUBAGENTS_CURSOR_FILE), { revision: 0, state: "none" });
|
||||
}
|
||||
|
||||
// The `caps` of the last `open` event: what the agent's console copy can do.
|
||||
export function latestOpenCaps(dir) {
|
||||
const opens = readJsonLines(path.join(dir, "events.ndjson")).filter((e) => e.type === "open");
|
||||
const last = opens[opens.length - 1];
|
||||
return last && Array.isArray(last.caps) ? last.caps : [];
|
||||
}
|
||||
|
||||
/**
|
||||
* Flag the case where the link cannot be opened by the person it is for.
|
||||
*
|
||||
|
||||
@@ -208,6 +208,26 @@ body {
|
||||
.stop-btn:hover:not(:disabled) { color: var(--warn); border-color: var(--warn); }
|
||||
.brief-btn:hover:not(:disabled) { color: var(--accent); border-color: var(--accent-line); }
|
||||
|
||||
/* Subagents: an orchestrator and its helpers. Unlit is a hollow outline in
|
||||
the quiet ink; lit fills the nodes with the highlight color. */
|
||||
.subagents-btn { border-color: var(--rule-2); color: var(--ink-2); display: inline-flex; align-items: center; justify-content: center; }
|
||||
.btn.subagents-btn { padding: 0 6px; align-self: stretch; }
|
||||
.subagents-btn[hidden] { display: none; }
|
||||
.subagents-btn svg { width: 16px; height: 16px; display: block; }
|
||||
.subagents-btn .sa-link { fill: none; stroke: var(--ink-2); stroke-width: 1.2; stroke-linecap: round; }
|
||||
.subagents-btn .sa-hub { fill: none; stroke: var(--ink-2); stroke-width: 1.4; }
|
||||
.subagents-btn .sa-node { fill: none; stroke: var(--ink-2); stroke-width: 1.2; }
|
||||
.subagents-btn[aria-pressed="true"] .sa-hub,
|
||||
.subagents-btn[aria-pressed="true"] .sa-node { fill: var(--accent); stroke: var(--accent); }
|
||||
.subagents-btn[aria-pressed="true"] .sa-link { stroke: var(--accent); }
|
||||
.subagents-btn:hover:not(:disabled) { color: var(--accent); border-color: var(--accent-line); }
|
||||
.subagents-btn:hover:not(:disabled) .sa-link,
|
||||
.subagents-btn:hover:not(:disabled) .sa-hub,
|
||||
.subagents-btn:hover:not(:disabled) .sa-node { stroke: var(--accent); }
|
||||
.subagents-btn:disabled .sa-link,
|
||||
.subagents-btn:disabled .sa-hub,
|
||||
.subagents-btn:disabled .sa-node { stroke: var(--ink-3); fill: none; }
|
||||
|
||||
.ident { display: flex; align-items: baseline; gap: 12px; min-width: 0; }
|
||||
|
||||
/* The session meter: a ring that fills with the points and a few words, in
|
||||
@@ -1430,6 +1450,30 @@ h1 {
|
||||
.pill.done { background: var(--ok-soft); color: var(--ok); }
|
||||
.pill.staged { background: var(--stage-soft); color: var(--stage); }
|
||||
|
||||
/* The Subagents tab: one row per reported helper, newest state in a pill. */
|
||||
.sa-card h2 { margin: 0 0 6px; }
|
||||
.sa-card > .help { margin: 0 0 16px; }
|
||||
.sa-alone { margin: 0; color: var(--ink-2); }
|
||||
.sa-list { list-style: none; margin: 0; padding: 0; display: grid; gap: 10px; }
|
||||
.sa-row { border: 1px solid var(--rule); border-radius: 8px; background: var(--panel-2); padding: 12px 14px; }
|
||||
.sa-head { display: flex; align-items: center; justify-content: space-between; gap: 10px; }
|
||||
.sa-title { min-width: 0; overflow-wrap: anywhere; }
|
||||
.sa-ask {
|
||||
margin: 4px 0 0; color: var(--ink-2); font-size: 13.5px;
|
||||
display: -webkit-box; -webkit-box-orient: vertical; -webkit-line-clamp: 2; line-clamp: 2; overflow: hidden;
|
||||
}
|
||||
.sa-result { margin: 8px 0 0; padding-top: 8px; border-top: 1px solid var(--rule); font-size: 13.5px; }
|
||||
.sa-pill { display: inline-flex; align-items: center; gap: 6px; flex: none; }
|
||||
.sa-pill.is-running { background: var(--accent-soft); color: var(--accent); border-color: var(--accent-line); }
|
||||
.sa-pill.is-done { background: var(--ok-soft); color: var(--ok); }
|
||||
.sa-pill.is-failed { background: var(--warn-soft); color: var(--warn); }
|
||||
.sa-pill .spinner.tiny { width: 10px; height: 10px; }
|
||||
/* The dialog's number box, themed like the page's other inputs. */
|
||||
.subagents input[type="number"] {
|
||||
width: 5em; font: inherit; color: var(--ink); background: var(--panel-2);
|
||||
border: 1px solid var(--rule-2); border-radius: 6px; padding: 4px 8px;
|
||||
}
|
||||
|
||||
/* ------------------------------------------------------ settled answer */
|
||||
|
||||
.answered {
|
||||
@@ -1971,6 +2015,8 @@ h4.md-h, h5.md-h, h6.md-h { font-size: 15px; }
|
||||
cursor: pointer;
|
||||
}
|
||||
.footer-where:hover { text-decoration: underline; }
|
||||
/* The project name, in the person's highlight color. */
|
||||
.where-project { color: var(--accent); font-weight: 600; }
|
||||
/* A folder is missing or the agent could not read one: the dialog says which. */
|
||||
.where-alert {
|
||||
display: inline-block; width: 7px; height: 7px; margin-left: 6px;
|
||||
|
||||
@@ -103,6 +103,15 @@ import { FOOTER_TIERS, footerLabel, nameProblem } from "./workspace.js";
|
||||
import { RED_BANNER } from "./meter.js";
|
||||
import { applyMention, matchNames, mentionAt } from "./mentions.js";
|
||||
import { faviconState, setFavicon } from "./favicon.js";
|
||||
import {
|
||||
CHECKIN_LINE,
|
||||
PATHFINDER_RESEARCH_LINE,
|
||||
defaultInstruction,
|
||||
helperRows,
|
||||
showSwitch,
|
||||
showTab,
|
||||
switchLabel,
|
||||
} from "./subagents.js";
|
||||
|
||||
const $ = (id) => document.getElementById(id);
|
||||
|
||||
@@ -530,6 +539,9 @@ let meterFrame = null;
|
||||
// The frame's update ({ installed, latest }), present only when a newer
|
||||
// release is out; null otherwise.
|
||||
let updateFrame = null;
|
||||
// The frame's Subagents switch ({ offered, supported, on, instruction, max,
|
||||
// revision }), or null before a server that sends it.
|
||||
let subagentsFrame = null;
|
||||
let chatDot = false;
|
||||
let chatSending = false;
|
||||
let chatResetting = false;
|
||||
@@ -880,6 +892,8 @@ function adopt(body) {
|
||||
if (body.meter) meterFrame = body.meter;
|
||||
// Always replaced: an absent key means no update.
|
||||
updateFrame = body.update || null;
|
||||
// Always replaced too: an older server sends none, and then there is no switch.
|
||||
subagentsFrame = body.subagents || null;
|
||||
lastContact = Date.now();
|
||||
if (gone) {
|
||||
gone = false;
|
||||
@@ -1301,6 +1315,7 @@ function render() {
|
||||
renderChrome();
|
||||
renderStatus();
|
||||
renderBriefButton();
|
||||
renderSubagentsButton();
|
||||
renderStopButton();
|
||||
renderHomeButton();
|
||||
tabAdded = renderViews();
|
||||
@@ -1566,7 +1581,7 @@ function renderChrome() {
|
||||
renderMeter();
|
||||
$("title").textContent = S.title || "Session";
|
||||
$("badge").textContent = workflowLabel(S.workflow);
|
||||
document.title = (S.title || "Session") + " · #" + String(S.sid || "").slice(-6) + " · Plan2Code";
|
||||
renderTabTitle();
|
||||
|
||||
const h = S.headline || {};
|
||||
// On a finished session an open item is frozen: the send on it counts as
|
||||
@@ -1835,6 +1850,69 @@ function renderBriefButton() {
|
||||
if (offer) btn.disabled = gone || pendingResult;
|
||||
}
|
||||
|
||||
// Shown only where the skill opts in and the agent's console copy can deliver
|
||||
// it. Lit while helpers are on; a click opens the dialog, never toggles.
|
||||
function renderSubagentsButton() {
|
||||
const btn = $("btn-subagents");
|
||||
const offer = showSwitch(subagentsFrame);
|
||||
btn.hidden = !offer;
|
||||
if (!offer) return;
|
||||
const label = switchLabel(subagentsFrame);
|
||||
btn.setAttribute("aria-pressed", String(Boolean(subagentsFrame.on)));
|
||||
btn.title = label;
|
||||
btn.setAttribute("aria-label", label);
|
||||
btn.disabled = gone;
|
||||
}
|
||||
|
||||
// The Subagents dialog, filled from the frame each time it opens. A null
|
||||
// instruction is the shipped default, shown as its text so it can be edited.
|
||||
function openSubagents() {
|
||||
if (!showSwitch(subagentsFrame)) return;
|
||||
const on = Boolean(subagentsFrame.on);
|
||||
for (const radio of document.querySelectorAll('input[name="subagents-on"]')) {
|
||||
radio.checked = radio.value === (on ? "on" : "off");
|
||||
}
|
||||
$("subagents-instruction").value = subagentsFrame.instruction ?? defaultInstruction(S.workflow);
|
||||
$("subagents-max").value = String(subagentsFrame.max);
|
||||
$("subagents-checkin").textContent = CHECKIN_LINE;
|
||||
const research = $("subagents-research");
|
||||
research.textContent = PATHFINDER_RESEARCH_LINE;
|
||||
research.hidden = S.workflow !== "pathfinder";
|
||||
$("subagents-status").textContent = "";
|
||||
$("subagents-save").disabled = false;
|
||||
$("subagents-modal").showModal();
|
||||
const checked = document.querySelector('input[name="subagents-on"]:checked');
|
||||
if (checked) checked.focus();
|
||||
}
|
||||
|
||||
const SUBAGENTS_ERRORS = {
|
||||
max: "Pick a number from 1 to 20.",
|
||||
"too-long": "The instruction is over 2,000 characters.",
|
||||
"not-offered": "This skill doesn't use helpers.",
|
||||
bad: "That didn't save. Try again.",
|
||||
};
|
||||
const SUBAGENTS_LOST = "Lost contact with Plan2Code. Try again once it's back.";
|
||||
|
||||
async function saveSubagents() {
|
||||
const save = $("subagents-save");
|
||||
const status = $("subagents-status");
|
||||
const picked = document.querySelector('input[name="subagents-on"]:checked');
|
||||
const text = $("subagents-instruction").value.trim();
|
||||
// The shipped default is stored as null, so a later release's wording
|
||||
// reaches everyone who never changed it.
|
||||
const instruction = text === defaultInstruction(S.workflow) ? null : text;
|
||||
const body = { on: Boolean(picked && picked.value === "on"), instruction, max: Number($("subagents-max").value) };
|
||||
save.disabled = true;
|
||||
status.textContent = "";
|
||||
const res = await postJson("/subagents", body);
|
||||
save.disabled = false;
|
||||
// The next state frame redraws the button.
|
||||
if (res.status === 200) return $("subagents-modal").close();
|
||||
if (res.status === 400) status.textContent = SUBAGENTS_ERRORS[res.body && res.body.error] || SUBAGENTS_ERRORS.bad;
|
||||
else if (res.status === 403 || res.status === 0) status.textContent = SUBAGENTS_LOST;
|
||||
else status.textContent = SUBAGENTS_ERRORS.bad;
|
||||
}
|
||||
|
||||
function renderViews() {
|
||||
const nav = $("views");
|
||||
nav.replaceChildren();
|
||||
@@ -1850,6 +1928,14 @@ function renderViews() {
|
||||
if (hasOverview) tabs.push({ id: "overview", label: "Overview", count: 0 });
|
||||
else if (view === "overview") view = "questions";
|
||||
for (const d of docs()) tabs.push({ id: "doc:" + d.id, label: d.title || "Document", count: 0 });
|
||||
// The helpers the agent reported, from the first one on; cleared by a
|
||||
// dashboard hop, which sends the person home like the Overview tab does.
|
||||
if (showTab(subagentsFrame, S.helpers)) {
|
||||
// From the rows the tab draws, so the badge never counts helpers the
|
||||
// working-alone note hides.
|
||||
const running = helperRows(S.helpers).rows.filter((r) => r.state === "running").length;
|
||||
tabs.push({ id: "subagents", label: "Subagents", count: running });
|
||||
} else if (view === "subagents") view = "questions";
|
||||
// Always last, on every workflow and after a finish: the Quick question chat.
|
||||
// The ring left of "Ask" shows exactly when the conversation's own ring does:
|
||||
// a question the agent picked up and has not answered yet.
|
||||
@@ -2130,6 +2216,7 @@ function paintMain(main) {
|
||||
if (view.startsWith("doc:")) return renderDoc(main, view.slice(4));
|
||||
if (view === "overview") return renderOverview(main);
|
||||
if (view === "ask") return renderAsk(main);
|
||||
if (view === "subagents") return renderSubagents(main);
|
||||
|
||||
// The session's own page, reached from the PAUSED / SESSION ENDED item at
|
||||
// the top of the rail. The hand-off lives here alone now, rather than
|
||||
@@ -4774,6 +4861,42 @@ function renderOverview(main) {
|
||||
main.appendChild(box);
|
||||
}
|
||||
|
||||
// The helpers the agent reported, as it last posted them. Everything here is
|
||||
// the agent's text, so it goes in as text, never as markup.
|
||||
function renderSubagents(main) {
|
||||
const card = el("section", "card sa-card");
|
||||
card.appendChild(el("h2", null, "Subagents"));
|
||||
card.appendChild(el("p", "help", CHECKIN_LINE));
|
||||
const { alone, rows } = helperRows(S.helpers);
|
||||
if (alone) {
|
||||
card.appendChild(
|
||||
el("p", "sa-alone", "Working alone: your agent has no way to start helpers here, so it is doing this skill's work itself.")
|
||||
);
|
||||
main.appendChild(card);
|
||||
return;
|
||||
}
|
||||
const list = el("ul", "sa-list");
|
||||
for (const row of rows) {
|
||||
const item = el("li", "sa-row");
|
||||
const head = el("div", "sa-head");
|
||||
head.appendChild(el("strong", "sa-title", row.title));
|
||||
const pill = el("span", "pill sa-pill is-" + row.state);
|
||||
if (row.state === "running") {
|
||||
const spin = el("span", "spinner tiny");
|
||||
spin.setAttribute("aria-hidden", "true");
|
||||
pill.appendChild(spin);
|
||||
}
|
||||
pill.appendChild(document.createTextNode(row.stateLabel));
|
||||
head.appendChild(pill);
|
||||
item.appendChild(head);
|
||||
item.appendChild(el("p", "sa-ask", row.ask));
|
||||
if (row.result) item.appendChild(el("p", "sa-result", row.result));
|
||||
list.appendChild(item);
|
||||
}
|
||||
card.appendChild(list);
|
||||
main.appendChild(card);
|
||||
}
|
||||
|
||||
/* ---------------------------------------------------------------- ask */
|
||||
|
||||
// The frame's chat block, with `offline` worked out now rather than when the
|
||||
@@ -5956,10 +6079,30 @@ const workspaceFolders = () => (wsFrame && Array.isArray(wsFrame.folders) ? wsFr
|
||||
// session opened before the server wrote `worktree` has nothing to show, so
|
||||
// the slot stays hidden. The footer renders on every tick, so the DOM is only
|
||||
// touched when the labels change, or when a resize clears the key.
|
||||
// The project's name: the workspace's original folder, or the session's
|
||||
// worktree folder before a frame carries the workspace.
|
||||
function projectName() {
|
||||
const folders = workspaceFolders();
|
||||
if (folders.length && folders[0].name) return folders[0].name;
|
||||
const path = (S && S.worktree) || "";
|
||||
return path ? path.split(/[\\/]/).filter(Boolean).pop() || path : "";
|
||||
}
|
||||
|
||||
// The browser tab's title, led by the project so tabs from different
|
||||
// projects are told apart. Called from the chrome and the footer, since the
|
||||
// workspace frame can arrive after either.
|
||||
function renderTabTitle() {
|
||||
if (!S) return;
|
||||
const name = projectName();
|
||||
document.title =
|
||||
(name ? name + " · " : "") + (S.title || "Session") + " · #" + String(S.sid || "").slice(-6) + " · Plan2Code";
|
||||
}
|
||||
|
||||
function renderWhere() {
|
||||
const b = $("footer-where");
|
||||
const folders = workspaceFolders();
|
||||
const path = S.worktree || "";
|
||||
renderTabTitle();
|
||||
const alert = Boolean(folders.length && ((wsFrame.missing || []).length || (wsFrame.issues || []).length));
|
||||
const labels = folders.length
|
||||
? Array.from({ length: FOOTER_TIERS }, (_, tier) => footerLabel({ folders, branch: S.branch }, tier))
|
||||
@@ -5972,7 +6115,16 @@ function renderWhere() {
|
||||
let label = labels[0];
|
||||
for (const text of labels) {
|
||||
label = text;
|
||||
b.textContent = text;
|
||||
// The project name takes the highlight color, so several consoles side by
|
||||
// side tell apart at a glance; the rest of the label stays quiet.
|
||||
const name = projectName();
|
||||
b.textContent = "";
|
||||
if (name && text.startsWith(name)) {
|
||||
b.appendChild(el("span", "where-project", name));
|
||||
b.appendChild(document.createTextNode(text.slice(name.length)));
|
||||
} else {
|
||||
b.textContent = text;
|
||||
}
|
||||
if (alert) {
|
||||
const dot = el("span", "where-alert");
|
||||
dot.setAttribute("aria-hidden", "true");
|
||||
@@ -7197,6 +7349,7 @@ function lightDismiss(dlg) {
|
||||
});
|
||||
}
|
||||
lightDismiss($("looks-modal"));
|
||||
lightDismiss($("subagents-modal"));
|
||||
lightDismiss($("help-modal"));
|
||||
lightDismiss($("workspace-modal"));
|
||||
lightDismiss($("welcome-modal"));
|
||||
@@ -7499,6 +7652,13 @@ $("cleanup-scan").addEventListener("click", scanCleanup);
|
||||
$("cleanup-delete").addEventListener("click", deleteCleanup);
|
||||
|
||||
$("btn-brief").addEventListener("click", openBrief);
|
||||
$("btn-subagents").addEventListener("click", openSubagents);
|
||||
$("subagents-default").addEventListener("click", () => {
|
||||
$("subagents-instruction").value = defaultInstruction(S.workflow);
|
||||
});
|
||||
$("subagents-save").addEventListener("click", saveSubagents);
|
||||
$("subagents-cancel").addEventListener("click", () => $("subagents-modal").close());
|
||||
$("subagents-modal").addEventListener("close", () => $("btn-subagents").focus());
|
||||
$("brief-cancel").addEventListener("click", () => $("brief-modal").close());
|
||||
$("brief-go").addEventListener("click", sendBrief);
|
||||
for (const radio of document.querySelectorAll('input[name="brief-range"]')) {
|
||||
|
||||
Loaded 100 of 179 files, more files were not shown because too many files have changed in this diff.
Show more
Reference in new issue
Block a user