Let helpers run at a strength matched to their job, chosen in the Subagents dialog

AI Assisted
This commit is contained in:
jparkerweb committed 2026-10-25 15:33:35 -07:00
1 parent 5f91fb665f
commit 1d146cce6f
23 files changed
+482 -73

No files matched your search

+3 -2
View File
@@ -16,7 +16,8 @@ plan2code/
│ │ ├── handoff.md # Clearing gate + PLAN-DRAFT handoff
│ │ └── trail.md # Every-response map visual + pathed resume command
│ ├── shared-references/ # Reference files shared across skills
│ │ └── building-habits.md # Find the cause, test first, pin behaviour (quick-task, implement, implement-review)
│ │ ├── building-habits.md # Find the cause, test first, pin behaviour (quick-task, implement, implement-review)
│ │ └── helper-strength.md # How strong a model and how much effort each helper gets (pathfinder, quick-task, implement, implement-review, review)
│ ├── plan2code-review-references/ # Reference files for review skill
│ │ ├── verification-protocol.md # Deep verification + confidence calibration
│ │ ├── dimensions.md # 11 dimensions with detailed checklists
@@ -254,7 +255,7 @@ Optional local browser UI shipped with **every** skill. Source lives in `src/web
| `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/app-bridge.js` | The messages the page posts to the desktop app that frames it. `framed()` is true inside a frame; `tellApp(kind, extra)` posts `{ plan2code: kind }`, a named request with no free text: `looks` (the highlight's dark shades, from `applyLooks()`, for the app bar's buttons), `agent-continue` (the in-app **continue** button on the Not running line: the app types `continue` and Enter into the agent's terminal) and `new-session` (the meter popover's New Session: the app presses its own bar button, confirm and all). Nothing outside a frame |
| `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, the `cmd-*.mjs` files, `patches.mjs`, `settings.mjs`, the page and the tests; in `SERVABLE` and preloaded |
| `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, strength }` or `{ error }`: `bad`, `too-long` past 2,000 characters, `max` outside 1-20, `strength` not one of `STRENGTHS`; `strength` is `balanced`, `thrifty`, `best` or `session`, missing reads as `balanced`, saved per project and skill in each `subagents.json` entry and sent as a `Helper strength:` line in the "on" block), `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, the `cmd-*.mjs` files, `patches.mjs`, `settings.mjs`, the page and the tests; in `SERVABLE` and preloaded |
| `handoffs.mjs` | the handoff store, the only code that names, lists, marks, deletes and sweeps handoffs, all in `~/.plan2code/handoffs/` (`PLAN2CODE_HANDOFFS_DIR` for tests; `PLAN2CODE_NOW` pins its clock): `newHandoff()` claims `YYYY-MM-DD-HHmm-handoff` (`-2`, `-3` on a clash, the `.json` created exclusively) and writes only `<id>.json` (`{ v: 1, id, title, worktree, project, spec, workflow, skill, written, fromStop, usedAt }`), the agent writing `<id>.md`; `listHandoffs(worktree)` (unused, same worktree, `.md` present, newest first, title and Next task read off the document); `readHandoffMeta()`, `markHandoffUsed()`; `removeHandoff()` (`HANDOFF_ID` only, regular files, never a link, realpath inside the folder, throws on any refusal); `staleHandoffs()` / `removeHandoffs()` for the sweep |
| `notepads.mjs` | the notebook store (the feature is named Notebook; its code, routes and storage folder keep the name `notepad`), the only code that names, reads, writes and removes notebooks, one per folder Plan2Code runs in, in `~/.plan2code/notepads/<folder-name>-<12 hex>/` (`PLAN2CODE_NOTEPADS_DIR` for tests), split into named tabs: `meta.json` (`{ v: 2, folder, created }`), `tabs.json` (`{ v: 1, order, last, tabs: { id: { name, created } } }`) and `tabs/<id>/note.md` with `tabs/<id>/images/`. `notepadKey()` (the folder's basename slug and the first 12 hex of `sha256(foldKey(folder))`), `listTabs()` / `defaultTabId()`, `readNotepad(folder, tab)` (never creates or writes anything; `{ tabs, last, tab }` with the tab's `text`, `savedAt` and `images` repeated at the top), the tab changes `createTab()` / `renameTab()` / `reorderTabs()` / `setLastTab()` / `deleteTab()` (index first, then the folder; names pass `normalizeTabName()`, `TAB_NAME_MAX` 40, any case compared by `nameKey()`, `NOTEPAD_MAX_TABS` 20), `saveNote(folder, tab, text)` (1 MB cap, atomic), `addImage()` / `addThumb()` / `removeImage()` (JPEG bytes only, 200 pictures per tab, UUID names), `imagePath()` (regular files whose realpath stays inside the folder), `staleNotepads(now, maxAgeMs)` (the real folders directly under it named like a key, never a link or a file, whose newest file is at least `maxAgeMs` old, as `{ key, folder, path }` with `folder` from `meta.json` or null), `removeNotepad(key)` (the key checked against `NOTEPAD_KEY_RE`, the path kept inside the notepads folder by `path.relative`, a link refused, then the whole folder removed; User Preferences, Cleanup is its only caller) and `NotepadError` (`code` and `status`, turned into `{ error }` by the `/notepad` routes). **Migration:** a notepad in the first shape (`note.md` and `images/` at the top) reads as one virtual tab, Notes (`LEGACY_TAB_ID`), and writes nothing; its first write moves the files into `tabs/<LEGACY_TAB_ID>/` and writes `tabs.json` last, every step safe to run again after a crash. A `tabs.json` that does not hold up is set aside as `tabs.json.corrupt` and rebuilt from the tab folders on the next write. Every write runs under a `notepad.lock` in the notepad's folder. The agent CLI never imports it: nothing in a notepad reaches the agent |
| `public/notepad.js` | PURE, no imports: the Notebook's rules. `SAVE_DEBOUNCE_MS` 800, `RETRY_STEPS_MS` (1 s up to 30 s), `NOTE_MAX_BYTES` / `NOTEPAD_MAX_IMAGES` / `TAB_NAME_MAX` / `NOTEPAD_MAX_TABS` / `IMAGE_ID_RE` / `TAB_ID_RE` (kept equal to `notepads.mjs` by a test), `noteBytes()`, the save-state reducer `nextSave(state, event)` from `SAVE_START` (states `idle`, `pending`, `saving`, `saved`, `failed`, `too-long`; it returns the timer to arm), `saveStatus()` (the status line's words), `unsaved()` (what `beforeunload` asks on), `keepsText()` (unsaved or too long: a reopen never replaces the editor's text then), `tabSwitch()` (whether leaving a tab must save it first), `NOT_LOADED`, `EDITOR_NOT_LOADED`, `errorSentence()` (one sentence per `/notepad` refusal, else a lost connection), the tab rules `cleanTabName()`, `nameTaken()`, `tabNameProblem()`, `moveTab()`, `dropTab()` and the two-confirm delete `nextDelete()` / `DELETE_STAGES`, and `step()` (wrapping through the pictures) |
+9 -2
View File
@@ -397,7 +397,11 @@ Pathfinder, the agent can hand independent pieces of work to helpers
- **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
run at once (1 to 20; your agent's own limit still applies). Under Helpers,
**Helper strength** sets how strong a model and how much effort helpers get:
**Balanced** (the default), **Thrifty** (one step lighter; reviews never
below standard), **Best** (strongest and high effort, except lookups) or
**Match my session** (nothing set on helpers). **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**, on until switched off, in
@@ -407,7 +411,10 @@ Pathfinder, the agent can hand independent pieces of work to helpers
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.
to start helpers here. Each row may carry one quiet line such as "Standard,
medium effort" ("Session model" when the helper runs on yours). The rules
live in `helper-strength.md` and apply in terminal sessions too. 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.
+3 -2
View File
@@ -42,7 +42,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 **git board** for the `git` workflow (three tabs, Changes, Branches and Sync, opening on the likely next step; branches, pull, push, commits and pull-request links, drawn from `state.git`; contract in `notes/git.md`), **Stop with a handoff** (handoffs live in `~/.plan2code/handoffs/`, owned by `handoffs.mjs`, swept after 30 days, and offered as dashboard chips to pick up in the same session), a private **Notebook** in the top bar (named tabs of Markdown and pictures, a live-preview CodeMirror editor, one notepad per folder in `~/.plan2code/notepads/`, owned by `notepads.mjs`, never shown to the agent, removed only through Cleanup once a month untouched), a built-in 18-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 (on by default for those skills until switched off, 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-subagents.md`). Per-skill facts live in one list, `public/skills.js`, from which the meter, the resume command, Help's card list and the CLI's workflow list are derived; task files are read through `spec-files.mjs` (shared with the `specs.mjs` skill script), and the rule for which hops start the page clean is `startsClean()` in `public/hops.js`. The agent contract is read in pieces: `console.md` once per conversation, then a topic file (`console-*.md`, `notes/<workflow>.md`, `building*.md`) only when its moment comes; 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 **git board** for the `git` workflow (three tabs, Changes, Branches and Sync, opening on the likely next step; branches, pull, push, commits and pull-request links, drawn from `state.git`; contract in `notes/git.md`), **Stop with a handoff** (handoffs live in `~/.plan2code/handoffs/`, owned by `handoffs.mjs`, swept after 30 days, and offered as dashboard chips to pick up in the same session), a private **Notebook** in the top bar (named tabs of Markdown and pictures, a live-preview CodeMirror editor, one notepad per folder in `~/.plan2code/notepads/`, owned by `notepads.mjs`, never shown to the agent, removed only through Cleanup once a month untouched), a built-in 18-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 (on by default for those skills until switched off, saved in `~/.plan2code/console/subagents.json`), and a Helper strength choice (Balanced, Thrifty, Best, Match my session; rules in `src/shared-references/helper-strength.md`, shipped in the five helper skills); 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-subagents.md`). Per-skill facts live in one list, `public/skills.js`, from which the meter, the resume command, Help's card list and the CLI's workflow list are derived; task files are read through `spec-files.mjs` (shared with the `specs.mjs` skill script), and the rule for which hops start the page clean is `startsClean()` in `public/hops.js`. The agent contract is read in pieces: `console.md` once per conversation, then a topic file (`console-*.md`, `notes/<workflow>.md`, `building*.md`) only when its moment comes; 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)
## Skill Scripts
@@ -103,7 +103,8 @@ When you make a mistake, get corrected, or discover something about this codebas
- Before deleting a test file that upstream split or removed, diff plan2code's copy against the rebranded upstream base and port the plan2code-only tests: v2.7.0's split of the web console suite would otherwise have dropped seven hardening tests (now in `scripts/test-web-console-hardening.mjs`).
- Register a new skill in `install.js` `SOURCE_PROMPTS` before running its `scripts/test-script-<name>.mjs`: importing `scripts/skill-script-helpers.mjs` rebuilds `skills/` and prunes any skill folder `install.js` does not list, so the script under test vanishes.
- When a `CHANGELOG.md` heading gets a version number, set the same number in `version.json` (with its `releaseDate`), the root `package.json` and README's `Version X.Y.Z` line in the same change, then run `npm run build:skills`. The changelog skill only touches `package.json`: v2.9.0 nearly shipped with `version.json` at 2.8.1, and README's line sat at 2.6.0 for three releases.
- When `npm test` fails only timing-bound suites (the chat stress test, the page-cards redraw test "a redraw keeps the place of...", then a cascade in the session suite starting at "no submitted frame within 5s") while the machine is busy, rerun those files alone, and the `node --test` list with `--test-concurrency=4`, before suspecting the change: they failed that way on untouched code under load during the web console file split, and the redraw test did again in three phases of web-console-health. In web-console-notepad, four more failed only in full runs and passed alone: the Workspace page's @-mention test, the dashboard page's handoff chip test, the session suite's document route (`connect ETIMEDOUT`) and the notepad page's 200 KB typing test (why its budget there is 200 ms, not the 92 ms it takes alone).
- When `npm test` fails only timing-bound suites (the chat stress test, the page-cards redraw test "a redraw keeps the place of...", then a cascade in the session suite starting at "no submitted frame within 5s") while the machine is busy, rerun those files alone, and the `node --test` list with `--test-concurrency=4`, before suspecting the change: they failed that way on untouched code under load during the web console file split, and the redraw test did again in three phases of web-console-health. In web-console-notepad, four more failed only in full runs and passed alone: the Workspace page's @-mention test, the dashboard page's handoff chip test, the session suite's document route (`connect ETIMEDOUT`) and the notepad page's 200 KB typing test (why its budget there is 200 ms, not the 92 ms it takes alone). In helper-strength, the page-cards test "a card cut by the window fades at its bottom edge..." did the same.
- Run `npm test` from a terminal outside the desktop app, or with `PLAN2CODE_IN_APP`, `PLAN2CODE_APP_TOKEN`, `PLAN2CODE_APP_VERSION`, `PLAN2CODE_APP_ANNOUNCE` and `PLAN2CODE_EMBED_ORIGIN` unset (`env -u ... npm test`): inherited from the app they fail about 34 tests that check behaviour outside the app (the update banner, the terminal line, cookies, open's browser launch), which pass once unset.
- Post a helper as `done` or `failed` in the same turn its completion notice arrives: its row stays `running` on the Subagents tab until a post says otherwise (a build once reached its sign-off with one row spinning). A `finish` is now refused while any helper is `running`.
- Bring the Windows folder picker (`picker.mjs`, copied into `src/launcher/plan2code.js`) to the front with an Alt tap before `SetForegroundWindow`, never with `windowsHide`, the owner form's `TopMost`, `HWND_TOPMOST` or `AttachThreadInput`: measured on Windows 11, `SetWindowPos(HWND_TOPMOST)` returns true while the dialog stays non-topmost behind the browser, and only the Alt tap made it the foreground window. Check with `GetForegroundWindow` from a second process, since no test can see it.
- Add any new file or folder Plan2Code writes at the top of `~/.plan2code/` to `KEPT_PLAN2CODE_ENTRIES` in `src/web-console/sessions.mjs` and to the Cleanup test in `scripts/test-web-console-server.mjs`: User Preferences → Cleanup offers every other entry there for deletion once it is an hour old, and the desktop app's `app/` and `app.json` were about to be listed.
+2
View File
@@ -9,6 +9,8 @@ All notable changes to Plan2Code will be documented in this file.
- **desktop app**: a cross-platform app (Rust, Tauri) that is the single window for working with an AI agent. It opens the Plan2Code dashboard as its main surface, runs Claude Code, Devin or Codex in a pseudo-terminal panel it owns, and adds a **New Session** button that replaces the agent with a fresh one on a brief the app builds from its own record of the session, with the in-progress work and recent activity carried over. Every console page (Ask, Workspace, Help, Preferences, Git, Notebook) opens inside the app, not a separate browser tab.
- **desktop app**: **Update skills** in the bar brings the installed skills level with the app from the exact release the app ships, with live progress and a **Reconnect the console** offer once it finishes; an app older than the installed skills says so instead of trying to fix it by updating skills again.
- **desktop app**: the window's own title (and so its taskbar entry) now reads **Plan2Code - &lt;folder name&gt;** once a project is open, instead of a plain **Plan2Code** every window shares; two or more windows on different projects read apart without opening each one to check.
- **helpers**: a helper (subagent) no longer has to run on the session's own model and effort. A new shared reference, `helper-strength.md`, shipped in Pathfinder, Quick Task, Implement, Implement + Review and Review, matches each helper job to a strength (`light`, `standard`, `strongest` or `inherit`) and an effort (`low`, `medium` or `high`) from signals that can be checked, with floors, one-step escalation and a fallback order for tools that cannot set either, and never names a model or vendor. Review, Implement + Review and Pathfinder name the strength for the helpers they start, and the rules apply in terminal sessions too.
- **web console**: the Subagents dialog has a **Helper strength** choice under Helpers: **Balanced** (the default), **Thrifty**, **Best** or **Match my session**, saved per project and skill and delivered to the agent as a `Helper strength:` line. Helper reports may say what each helper ran with (`strength`, `effort`), and the Subagents tab shows it as one quiet line, such as "Standard, medium effort".
- `plan2code` opens the app automatically when a desktop is available; `plan2code --classic` (or no desktop, e.g. over SSH) keeps today's terminal-only flow unchanged, and the installer brings the app in alongside the skills and the command.
### 🔧 Changed
+11 -2
View File
@@ -161,7 +161,10 @@ const SOURCE_PROMPTS = [
name: 'pathfinder',
displayName: 'Pathfinder Mode',
description: 'charting of a foggy idea as a map of decision questions, cleared one at a time',
additionalReferences: [{ source: 'web-console', target: 'web-console' }]
additionalReferences: [
{ source: 'web-console', target: 'web-console' },
{ source: 'shared-references/helper-strength.md', target: 'helper-strength.md' }
]
},
{
source: 'plan2code-quick-task.md',
@@ -176,6 +179,7 @@ const SOURCE_PROMPTS = [
additionalReferences: [
{ source: 'web-console', target: 'web-console' },
{ source: 'shared-references/building-habits.md', target: 'building-habits.md' },
{ source: 'shared-references/helper-strength.md', target: 'helper-strength.md' },
{ source: 'plan2code-review.md', target: 'review.md' },
{ source: 'plan2code-review-references' }
]
@@ -219,6 +223,7 @@ const SOURCE_PROMPTS = [
additionalReferences: [
{ source: 'web-console', target: 'web-console' },
{ source: 'shared-references/building-habits.md', target: 'building-habits.md' },
{ source: 'shared-references/helper-strength.md', target: 'helper-strength.md' },
{ source: 'plan2code-review.md', target: 'review.md' },
{ source: 'plan2code-review-references' }
]
@@ -234,6 +239,7 @@ const SOURCE_PROMPTS = [
{ source: 'web-console', target: 'web-console' },
{ source: 'plan2code-3-implement.md', target: 'implement.md' },
{ source: 'shared-references/building-habits.md', target: 'building-habits.md' },
{ source: 'shared-references/helper-strength.md', target: 'helper-strength.md' },
{ source: 'plan2code-review.md', target: 'review.md' },
{ source: 'plan2code-review-references' }
]
@@ -246,7 +252,10 @@ const SOURCE_PROMPTS = [
description: 'Comprehensive post-implementation review with spec compliance checking',
isUtility: true,
scripts: ['specs.mjs', 'commit-msg.mjs', 'review-scope.mjs'],
additionalReferences: [{ source: 'web-console', target: 'web-console' }]
additionalReferences: [
{ source: 'web-console', target: 'web-console' },
{ source: 'shared-references/helper-strength.md', target: 'helper-strength.md' }
]
},
{
source: 'plan2code-4-finalize.md',
+47 -8
View File
@@ -1999,7 +1999,7 @@ test("subagents: only the five opted-in workflows offer the switch", () => {
assert.equal(defaultInstruction(w), "");
}
assert.equal(Object.keys(SUBAGENT_WORKFLOWS).length, 5);
assert.deepEqual(defaultSetting("review"), { workflow: "review", on: true, instruction: null, max: 3 });
assert.deepEqual(defaultSetting("review"), { workflow: "review", on: true, instruction: null, max: 3, strength: "balanced" });
assert.equal(defaultSetting("plan").on, false, "a skill without the switch is never on");
assert.equal(effectiveInstruction({ workflow: "review", instruction: " " }), defaultInstruction("review"));
assert.equal(effectiveInstruction({ workflow: "review", instruction: " Mine " }), "Mine");
@@ -2015,7 +2015,7 @@ test("subagents: blockFor walks every switch transition, and never says off to a
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.field, { state: "on", revision: 2, max: 3, instruction: defaultInstruction("implement"), strength: "balanced" });
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);
@@ -2025,7 +2025,7 @@ test("subagents: blockFor walks every switch transition, and never says off to a
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.deepEqual(nested.lines.slice(-4, -2), [" - 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");
@@ -2053,9 +2053,26 @@ test("subagents: the injected wording names no harness tool", () => {
}
});
// Guards NFR-1: the strength guidance and the wording the console injects speak
// in strength words only, never a model or vendor name, so they stay right on
// every harness and every model line-up.
const MODEL_NAMES = /\b(haiku|sonnet|opus|fable|gpt|o\d|codex|gemini|flash|pro|claude|anthropic|openai|google|swe-\d)\b/i;
test("subagents: the strength guidance and the injected wording name no model or vendor", () => {
const texts = [
fs.readFileSync(path.join(ROOT, "src", "shared-references", "helper-strength.md"), "utf8"),
...FRAME_LINES,
...Object.keys(SUBAGENT_WORKFLOWS).map(defaultInstruction),
];
for (const text of texts) assert.doesNotMatch(text, MODEL_NAMES);
assert.match("Start it on Sonnet at high effort.", MODEL_NAMES, "the check catches a model name");
});
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.deepEqual(cleanSetting({ on: true, instruction: null, max: 3 }), { on: true, instruction: null, max: 3, strength: "balanced" });
assert.deepEqual(cleanSetting({ on: false, instruction: " Do it ", max: 20, strength: "best" }), { on: false, instruction: "Do it", max: 20, strength: "best" });
assert.equal(cleanSetting({ on: true, instruction: null, max: 3, strength: null }).strength, "balanced", "a null strength is the default");
for (const strength of ["fast", "Balanced", 1, ""]) assert.deepEqual(cleanSetting({ on: true, instruction: null, max: 3, strength }), { error: "strength" }, String(strength));
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" });
@@ -2129,6 +2146,28 @@ test("subagents: helperRows labels each state, shows a result only once a helper
assert.equal(rows[2].result, "Timed out");
});
test("subagents: helperRows turns a reported strength and effort into one line, and leaves it out when neither was reported", () => {
const line = (extra) => helperRows([{ id: "h1", title: "One", ask: "a", state: "running", ...extra }]).rows[0];
const cases = [
[{ strength: "standard", effort: "medium" }, "Standard, medium effort"],
[{ strength: "light" }, "Light"],
[{ strength: "strongest", effort: "high" }, "Strongest, high effort"],
[{ strength: "inherit", effort: "high" }, "Session model, high effort"],
[{ strength: "inherit" }, "Session model"],
[{ effort: "low" }, "Low effort"],
];
for (const [extra, want] of cases) {
const row = line(extra);
assert.equal(row.strengthLine, want, JSON.stringify(extra));
assert.equal(row.strength, extra.strength);
assert.equal(row.effort, extra.effort);
}
for (const extra of [{}, { strength: "huge", effort: "max" }]) {
const row = line(extra);
for (const key of ["strengthLine", "strength", "effort"]) assert.equal(key in row, false, `${JSON.stringify(extra)}: no ${key}`);
}
});
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">/);
@@ -2153,7 +2192,7 @@ test("subagents: the store round-trips per project and workflow under the consol
const script = `
const lib = await import(${JSON.stringify(new URL("../src/web-console/settings.mjs", import.meta.url).href)});
const project = ${JSON.stringify(project)};
lib.saveSubagentStoreEntry(project, "implement", { on: true, instruction: "Mine", max: 5 });
lib.saveSubagentStoreEntry(project, "implement", { on: true, instruction: "Mine", max: 5, strength: "best" });
const flipped = project.replace(/My Repo$/, "MY REPO");
console.log(JSON.stringify({
file: lib.SUBAGENTS_FILE,
@@ -2169,11 +2208,11 @@ test("subagents: the store round-trips per project and workflow under the consol
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 });
assert.deepEqual(out.saved, { on: true, instruction: "Mine", max: 5, strength: "best" });
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: true, instruction: null, max: 3 }, "nothing saved means on");
assert.deepEqual(out.unsaved, { on: true, instruction: null, max: 3, strength: "balanced" }, "nothing saved means on, at balanced");
assert.ok(!fs.existsSync(path.join(home, "subagents.json.lock")), "the lock is released");
} finally {
fs.rmSync(home, { recursive: true, force: true });
+61
View File
@@ -211,3 +211,64 @@ test("posting helpers adds a Subagents tab that lists each with its state and re
assert.match(await textOf(done), /All 9 pass\./);
assert.match(await textOf(running), /Find the callers of applyPatch/);
});
// What a person sees break: the strength they saved not shown when the dialog
// opens again, a help line that ignores their pick, or Save dropping it.
test("the Subagents dialog shows the saved strength, explains the picked one, goes inert under Work alone and saves it", async (t) => {
const s = await openSession(await suite.browser(), {
t,
workflow: "implement",
payload: { agent: { status: "working", activity: "Task 1 of 2" } },
});
const modal = s.page.locator("#subagents-modal");
const radio = (value) => modal.locator(`input[name="subagents-strength"][value="${value}"]`);
const help = modal.locator("#subagents-strength-help");
const open = async () => {
await s.page.locator("#btn-subagents").click();
await modal.waitFor();
};
await open();
assert.equal(await radio("balanced").isChecked(), true, "an unsaved strength opens as Balanced");
assert.match(await textOf(help), /light for lookups/);
await radio("thrifty").check();
assert.match(await textOf(help), /One step lighter everywhere/);
await modal.locator('input[name="subagents-on"][value="off"]').check();
for (const value of ["balanced", "thrifty", "best", "session"]) assert.equal(await radio(value).isDisabled(), true, `${value} is inert under Work alone`);
await modal.locator('input[name="subagents-on"][value="on"]').check();
assert.equal(await radio("thrifty").isEnabled(), true);
const posted = s.page.waitForRequest((r) => r.url().endsWith("/subagents") && r.method() === "POST");
await modal.getByRole("button", { name: "Save", exact: true }).click();
assert.equal(JSON.parse((await posted).postData()).strength, "thrifty");
await modal.waitFor({ state: "hidden" });
// The next frame carries the saved strength; the dialog opens on it.
await s.page.waitForFunction(async () => (await (await fetch("/state")).json()).subagents.strength === "thrifty");
await open();
assert.equal(await radio("thrifty").isChecked(), true, "the saved strength is checked");
assert.match(await textOf(help), /One step lighter everywhere/);
});
// What a person sees break: the strength a helper ran with missing from the
// tab, or a stray line under a helper that reported none.
test("the Subagents tab shows a reported helper's strength line and none for a helper without one", async (t) => {
const s = await openSession(await suite.browser(), {
t,
workflow: "implement",
payload: { agent: { status: "working", activity: "Task 1 of 2" } },
});
s.post({
helpers: [
reportedHelper("h1", { title: "Read the store helpers", strength: "standard", effort: "medium" }),
reportedHelper("h2", { title: "Check the tests" }),
],
});
const tab = s.page.locator("nav").getByRole("button", { name: /^Subagents/ });
await tab.waitFor();
await tab.click();
const rows = s.page.locator("#main .sa-card .sa-row");
await rows.first().waitFor();
assert.equal(await textOf(rows.filter({ hasText: "Read the store helpers" }).locator(".sa-strength")), "Standard, medium effort");
assert.equal(await rows.filter({ hasText: "Check the tests" }).locator(".sa-strength").count(), 0);
});
+17
View File
@@ -25,6 +25,7 @@ import fs from "node:fs";
import os from "node:os";
import path from "node:path";
import { createRequire } from "node:module";
import { execFileSync } from "node:child_process";
import { ROOT, cli, poseTemplate } from "./web-console-test-helpers.mjs";
import { SUBAGENT_WORKFLOWS } from "../src/web-console/public/subagents.js";
import { TEMPLATE_WORKFLOWS } from "../src/web-console/public/starters.js";
@@ -380,3 +381,19 @@ test("Implement's card launches Implement + Review when Review is ticked", () =>
const quick = SKILL_CATALOG.find((e) => e.skill === "plan2code-quick-task");
assert.equal(launchVariant(quick, true), quick, "a card with no Review box is unchanged");
});
test("helper-strength.md ships in the five skills that start helpers, and in no other", () => {
// npm test has just built skills/; a direct run builds it so the check never reads a stale tree.
if (process.env.npm_lifecycle_event !== "test") {
execFileSync(process.execPath, [path.join(ROOT, "install.js"), "--build-skills"], { stdio: "ignore" });
}
const built = path.join(ROOT, "skills");
const having = fs.readdirSync(built).filter((dir) => fs.existsSync(path.join(built, dir, "references", "helper-strength.md")));
assert.deepEqual(having.sort(), [
"plan2code-0-pathfinder",
"plan2code-3-implement",
"plan2code-3-implement-review",
"plan2code-quick-task",
"plan2code-review",
]);
});
+83 -4
View File
@@ -8,7 +8,7 @@ import test from "node:test";
import assert from "node:assert/strict";
import fs from "node:fs";
import path from "node:path";
import { defaultInstruction, offered } from "../src/web-console/public/subagents.js";
import { defaultInstruction, offered, onLines, STRENGTH_LINES, STRENGTHS } from "../src/web-console/public/subagents.js";
import { readSubagentCursor } from "../src/web-console/settings.mjs";
import {
ROOT,
@@ -64,13 +64,13 @@ test("subagents: a change reaches the next pickup once, last in reply, edits nam
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.deepEqual(on.body.setting, { workflow: "implement", on: true, instruction: null, max: 3, strength: "balanced", 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") });
assert.deepEqual(first.json.subagents, { state: "on", revision: rev, max: 3, instruction: defaultInstruction("implement"), strength: "balanced" });
const reply = first.json.reply;
const at = (re) => reply.search(re);
assert.ok(at(/^Export format: a$/m) === 0, reply);
@@ -149,7 +149,7 @@ test("subagents: a resume re-states an on setting once, says nothing when off, a
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.deepEqual(resumed.json.subagents, { state: "on", revision: rev, max: 3, instruction: defaultInstruction("implement"), strength: "balanced" });
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");
@@ -254,6 +254,7 @@ test("subagents: a workflow without the switch refuses it, bad bodies name the f
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.deepEqual(await setSubagents(s, { ...ON3, strength: "fast" }), { status: 400, body: { error: "strength" } });
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");
@@ -272,6 +273,60 @@ test("subagents: a workflow without the switch refuses it, bad bodies name the f
}
});
test("subagents: a strength-only change reaches the agent once, with its profile line", async () => {
const s = subagentsSession();
try {
const before = (await frameSubagents(s)).revision;
const thrifty = await setSubagents(s, { ...ON3, strength: "thrifty" });
assert.equal(thrifty.status, 200);
assert.equal(thrifty.body.setting.revision, before + 1, "a strength alone is a change");
assert.equal(thrifty.body.setting.strength, "thrifty");
const picked = await submitAndWait(s);
assert.equal(picked.json.subagents.strength, "thrifty");
assert.ok(picked.json.reply.endsWith(["", STRENGTH_LINES.thrifty, "At most 3 helpers at once."].join("\n ")), picked.json.reply);
assert.equal((await frameSubagents(s)).strength, "thrifty");
const again = await setSubagents(s, { ...ON3, strength: "thrifty" });
assert.equal(again.body.setting.revision, before + 1, "the same strength again bumps nothing");
assert.equal("subagents" in (await submitAndWait(s)).json, false);
} finally {
cli(["stop", "--session", s.sid]);
}
});
test("subagents: a setting saved before strength existed reads as balanced and bumps nothing", async () => {
const s = subagentsSession();
try {
assert.equal((await setSubagents(s, { ...ON3, max: 4 })).status, 200);
const strip = (file, entries) => {
const saved = JSON.parse(fs.readFileSync(file, "utf8"));
for (const entry of entries(saved)) delete entry.strength;
fs.writeFileSync(file, JSON.stringify(saved));
};
strip(SUBAGENTS_STORE, (store) => Object.values(store).flatMap((project) => Object.values(project)));
strip(path.join(s.session, "subagents-setting.json"), (setting) => [setting]);
const rev = JSON.parse(fs.readFileSync(path.join(s.session, "subagents-setting.json"), "utf8")).revision;
cli(["stop", "--session", s.sid]);
const resumed = sessionUrl(cli(["open", "--resume", s.sid, "--no-open"]).json.url);
const frame = (await (await fetch(`${resumed.base}/state`, { headers: { cookie: resumed.cookie, connection: "close" } })).json()).subagents;
assert.deepEqual([frame.max, frame.strength, frame.revision], [4, "balanced", rev], "an upgrade alone bumps nothing");
} finally {
cli(["stop", "--session", s.sid]);
}
});
test("subagents: every strength renders its own profile line, and a missing one is balanced", () => {
const base = { revision: 1, max: 3, instruction: "Split by file." };
for (const strength of STRENGTHS) {
const lines = onLines({ ...base, strength });
assert.equal(lines[lines.length - 2], " " + STRENGTH_LINES[strength], strength);
assert.equal(lines.filter((l) => l.includes("Helper strength:")).length, 1, strength);
}
assert.equal(new Set(STRENGTHS.map((k) => STRENGTH_LINES[k])).size, STRENGTHS.length, "four different lines");
assert.equal(onLines(base).at(-2), " " + STRENGTH_LINES.balanced);
});
/* ------------------------------------------ subagents: helper reports */
@@ -334,6 +389,30 @@ test("helpers: every malformed report exits 3 naming the helper, and nothing is
}
});
test("helpers: a reported strength and effort are kept, other values exit 3 naming the helper, and both stay optional", () => {
const s = consoleSession(["--workflow", "implement"]);
try {
const ran = reportedHelper("h1", { strength: "standard", effort: "medium" });
assert.equal(postPatch(s, { helpers: [ran] }).status, 0);
assert.deepEqual(readState(s.session).helpers, [ran], "strength and effort are kept as reported");
const statePath = path.join(s.session, "state.json");
const before = fs.readFileSync(statePath, "utf8");
for (const [name, extra, re] of [
["unknown strength", { strength: "huge" }, /helper "h2": strength must be light, standard, strongest or inherit/],
["unknown effort", { effort: "max" }, /helper "h2": effort must be low, medium or high/],
]) {
const res = postPatch(s, { helpers: [reportedHelper("h2", extra)] }, { expectFail: true });
assert.equal(res.status, 3, name);
assert.match(res.stderr, re, name);
assert.equal(fs.readFileSync(statePath, "utf8"), before, `${name}: nothing written`);
}
assert.equal(postPatch(s, { helpers: [reportedHelper("h3")] }).status, 0, "a helper without the fields still posts");
assert.deepEqual(readState(s.session).helpers.map((h) => h.id), ["h1", "h3"]);
} 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 {
@@ -58,6 +58,8 @@ The only type an agent resolves alone, and the only type that may run several at
One subagent per research question. Do not read the docs yourself in the main session — the point is that the main session's context stays clean for the decision work.
Start each research subagent at standard strength and medium effort per `helper-strength.md` (its fallback order applies; a re-fired subagent from `refire` goes one strength up).
The subagent's brief must carry, verbatim:
1. The absolute path of the question file it owns.
+1 -1
View File
@@ -54,7 +54,7 @@ Run Review Mode with this explicit scope:
- Use overview.md and the active phase file for spec-compliance context; they do not broaden scope to other phases.
- Read related callers, dependencies, and project files when needed to verify a finding, but do not turn them into unrelated review targets.
- Review all changed files completely and apply the full focused-review depth required by Review Mode.
- Review Mode's helper rule applies: a fresh helper runs the analysis when available, this session verifies every finding, and the Stage 4 report carries the Reviewed by line. The helper's brief carries the phase's `phase-X.md` and its change set only, never Stage 1's work notes.
- Review Mode's helper rule applies: a fresh helper runs the analysis when available, at the strength `helper-strength.md` gives for the phase's review (standard and high, or strongest and high when the phase touches security, auth or data), this session verifies every finding, and the Stage 4 report carries the Reviewed by line. The helper's brief carries the phase's `phase-X.md` and its change set only, never Stage 1's work notes.
Override Review Mode's completion and session-end behavior:
@@ -1,7 +1,7 @@
# Reviewer Brief
> Part of plan2code-review: filled in by the main session at Step 3 (Analyze) and handed, whole, to ONE fresh helper.
Fill every `{{...}}` field, drop the lines that do not apply, and send the filled text as the helper's entire instructions. Never add the builder's conversation, reasoning, work notes or self-review: the helper's value is that it did not see them.
Fill every `{{...}}` field, drop the lines that do not apply, and send the filled text as the helper's entire instructions. Never add the builder's conversation, reasoning, work notes or self-review: the helper's value is that it did not see them. Start the helper at the strength and effort `helper-strength.md` gives for review analysis, following its fallback order.
---
+1 -1
View File
@@ -93,7 +93,7 @@ Three levels -- auto-detected, always respect explicit user override:
### Step 3: Analyze
**Who reviews:** when your tool can start a helper (subagent) and helpers are not switched off for this skill run, fill references/reviewer-brief.md and hand the analysis to ONE fresh helper; do not analyze in parallel. The brief carries the review-depth references, the dimensions and the finding format: send only the filled brief. With no helper, or one that fails or returns nothing usable, run this step in this session.
**Who reviews:** when your tool can start a helper (subagent) and helpers are not switched off for this skill run, fill references/reviewer-brief.md and hand the analysis to ONE fresh helper; do not analyze in parallel. The brief carries the review-depth references, the dimensions and the finding format: send only the filled brief. Start the helper at the strength and effort references/helper-strength.md gives for review analysis (standard and high for a focused scope; strongest and high for branch or full scope, or changes touching security, auth or data), following its fallback order. With no helper, or one that fails or returns nothing usable, run this step in this session.
**Load review depth (conditional on scope):**
+58
View File
@@ -0,0 +1,58 @@
# Helper Strength
> Shared by the skills that start helpers (subagents): Pathfinder, Quick Task, Implement, Implement + Review and Review. Read it when you first start a helper in a session. Never invoked as a skill.
## The words
- **Strength:** `light`, `standard`, `strongest` or `inherit`.
- `light`: your tool's fastest, cheapest model class.
- `strongest`: its most capable model class.
- `standard`: the one between them, often your tool's default.
- `inherit`: the helper runs with the session's own model.
- **Effort:** `low`, `medium` or `high`, where your tool lets you set how hard a model thinks.
Never write a model or vendor name in a brief, a report or a file, and never invent a model id: map the word to whatever your tool offers.
## Picking a strength
| Helper's job | Strength | Effort |
|---|---|---|
| Lookups, reading code, checking docs, recon | light | low |
| Build task in 1 or 2 files, with the change spelled out in the task | light | medium |
| Build task across several files, integration work, debugging | standard | medium |
| Build task needing a design decision the spec leaves open | strongest (or keep it yourself) | high |
| Pathfinder research question, sketch | standard | medium |
| Review analysis, focused scope | standard | high |
| Review analysis, branch or full scope, or touching security, auth or data | strongest | high |
Decide from these signals: how many files the job touches, whether the task spells out the change, whether a design decision is still open, and the review's scope and risk. Never decide from how hard the task feels.
## Floor and escalation
- A review helper never runs below `standard`.
- A retry, after a helper fails or after its work fails the phase's tests, goes one strength up and at least `medium` effort. Never retry at the same strength.
- When a `strongest` helper fails, its task comes back to you.
## Setting it
In this order:
1. Your tool accepts a model or effort setting when it starts a helper: set the closest match.
2. It lets you choose a helper profile or agent type instead: pick the one that matches.
3. Neither: start the helper without one, and it inherits.
Set it explicitly wherever you can. A helper left unset usually inherits the session's most capable and most expensive model.
## The person's choice (web console)
On the web console the person picks a profile in the Subagents dialog. A `Helper strength:` line in a `Subagents:` block replaces the Balanced default:
| Choice | Effect |
|---|---|
| Balanced (default) | The table as written |
| Thrifty | One step lighter in strength and effort; reviews never below standard |
| Best | Strongest and high effort for everything except lookups, which stay light |
| Match my session | No model or effort set on any helper, whatever the skill files say |
## Reporting
On the web console, report each helper's `strength` and `effort` as it actually ran (`console-subagents.md`, Reporting helpers). Report `inherit` when you could not set it. When `console-subagents.md` does not list those two fields yet, your console is older than this file: leave them out, since it ignores them.
+4 -4
View File
@@ -51,7 +51,7 @@ 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
May also print subagents: { state, revision, max, instruction, strength } 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 | -> [--wait <N>]
@@ -66,9 +66,9 @@ port, and the filesystem as transport; this CLI is the whole agent surface.
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. A patch may also
carry helpers: [{ id, title, ask, state, result? }] or one
{ id: "alone", alone: true }, merged by id, for the Subagents tab
(help subagents).
carry helpers: [{ id, title, ask, state, result?, strength?,
effort? }] or one { id: "alone", alone: true }, merged by id, for
the Subagents tab (help subagents).
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
+20 -4
View File
@@ -22,11 +22,21 @@ 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-subagents.md); questions for the person stay with you.
If your tools cannot start helpers at all, report one "working alone" entry for this skill run instead; a real helper report removes it.
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.
Match each helper's strength and effort to its job, as helper-strength.md says; when your tools cannot set them, start the helper without them.
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. Pick each helper's strength and effort from helper-strength.md's table: light for a 1-2 file task the task file spells out, standard for multi-file or debugging work.
Helper strength: balanced (the table in helper-strength.md as written).
At most 3 helpers at once.
```
beside `"subagents": { "state": "on", "revision": 2, "max": 3, "instruction": "…" }`.
beside `"subagents": { "state": "on", "revision": 2, "max": 3, "instruction": "…", "strength": "balanced" }`.
The `Helper strength:` line carries the person's profile, and replaces the
Balanced default when they pick another:
- `balanced`: the table in `helper-strength.md` as written (the default).
- `thrifty`: one step lighter in strength and effort; reviews never below standard.
- `best`: strongest and high effort for every helper except lookups, which stay light.
- `session`: set no model or effort on any helper.
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.`
@@ -39,6 +49,9 @@ card, and it is never recorded under `specs/`.
- **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.
- **Strength:** start each helper at the strength and effort
`helper-strength.md` (in the skill's `references/`) gives for its job,
following its fallback order. Read it when you first start a helper.
- **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.
@@ -56,13 +69,16 @@ 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": "h2", "title": "Check the tests", "ask": "Run the subagents tests and report failures.", "state": "done", "result": "All 9 pass.", "strength": "light", "effort": "low" }
] }
```
- `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. Anything else is exit `3`, and
is the one line you add once a helper ends. `strength` (`light`,
`standard`, `strongest` or `inherit`) and `effort` (`low`, `medium` or
`high`) are optional: report what the helper actually ran with, and
`inherit` when its strength could not be set. Anything else is exit `3`, and
the house rules on completion markers and metric-like words cover `title`,
`ask` and `result`.
- Merged by `id`: post a helper again with its new `state` and `result` and it
+39
View File
@@ -2086,6 +2086,31 @@
</li>
<li>The button only appears on skills that use helpers, and only when Plan2Code can pass the setting on.</li>
</ul>
<h4>Helper strength</h4>
<p>
Under Helpers, the dialog also asks how strong the helpers should be.
Like the rest of the dialog it is saved for this project and this
skill, and it does nothing under <strong>Work alone</strong>.
</p>
<ul>
<li>
<strong>Balanced</strong> (the default): each helper gets the
strength its job needs: light for lookups, stronger for reviews and
design work.
</li>
<li>
<strong>Thrifty</strong>: one step lighter everywhere to save cost;
reviews stay at standard or above.
</li>
<li>
<strong>Best</strong>: the strongest model and high effort for
everything except lookups.
</li>
<li>
<strong>Match my session</strong>: helpers run on whatever your
session uses; nothing is set for them.
</li>
</ul>
<h4>The Subagents tab</h4>
<ul>
<li>
@@ -2099,6 +2124,12 @@
check-ins, not live. The page cannot stop a helper; ask Plan2Code
on the Ask tab if one should stop.
</li>
<li>
Under each helper, a line such as "Standard, medium effort" shows
what that helper actually ran with. "Session model" means the agent
could not set a strength for it, so it ran on the session's own
model. A helper that reported neither shows no line.
</li>
<li>
<strong>Working alone</strong> means your agent reported it has no
way to start helpers here. If it starts one after all, the note
@@ -2639,6 +2670,14 @@
<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 looks-row" id="subagents-strength-row">
<legend>Helper strength</legend>
<label><input type="radio" name="subagents-strength" value="balanced" checked /> <span>Balanced</span></label>
<label><input type="radio" name="subagents-strength" value="thrifty" /> <span>Thrifty</span></label>
<label><input type="radio" name="subagents-strength" value="best" /> <span>Best</span></label>
<label><input type="radio" name="subagents-strength" value="session" /> <span>Match my session</span></label>
<p class="help" id="subagents-strength-help"></p>
</fieldset>
<fieldset class="modal-ranges">
<legend>Instruction</legend>
<textarea id="subagents-instruction" rows="4" maxlength="2000" aria-label="Instruction"></textarea>
+23 -4
View File
@@ -10,7 +10,7 @@ import { thumbs, uploadUrl, docChip, attachTray, CHAT_IMAGES, attachFiles, incom
import { attachMentions } from "../mention-box.js";
import { pickerAccept, attachmentKind, noteAwaiting, threadWho, threadText } from "../answers.js";
import { postJson } from "../net.js";
import { CHECKIN_LINE, helperRows, showSwitch, switchLabel, defaultInstruction, PATHFINDER_RESEARCH_LINE } from "../subagents.js";
import { CHECKIN_LINE, helperRows, showSwitch, switchLabel, defaultInstruction, PATHFINDER_RESEARCH_LINE, STRENGTHS, DEFAULT_STRENGTH, STRENGTH_HELP } from "../subagents.js";
const $ = (id) => document.getElementById(id);
@@ -724,6 +724,7 @@ export function renderSubagents(main) {
head.appendChild(pill);
item.appendChild(head);
item.appendChild(el("p", "sa-ask", row.ask));
if (row.strengthLine) item.appendChild(el("p", "sa-strength", row.strengthLine));
if (row.result) item.appendChild(el("p", "sa-result", row.result));
list.appendChild(item);
}
@@ -755,6 +756,9 @@ export function openSubagents() {
}
$("subagents-instruction").value = page.subagentsFrame.instruction ?? defaultInstruction(page.S.workflow);
$("subagents-max").value = String(page.subagentsFrame.max);
const strength = STRENGTHS.includes(page.subagentsFrame.strength) ? page.subagentsFrame.strength : DEFAULT_STRENGTH;
for (const radio of document.querySelectorAll('input[name="subagents-strength"]')) radio.checked = radio.value === strength;
syncStrengthHelp();
$("subagents-checkin").textContent = CHECKIN_LINE;
const research = $("subagents-research");
research.textContent = PATHFINDER_RESEARCH_LINE;
@@ -767,17 +771,25 @@ export function openSubagents() {
if (checked) checked.focus();
}
// Instruction and "at most" only mean anything with helpers on, so they are
// inert under Work alone (kept as typed, for when helpers go back on).
// Instruction, "at most" and strength only mean anything with helpers on, so
// they are inert under Work alone (kept as picked, for when helpers go back on).
export function syncSubagentsFields() {
const picked = document.querySelector('input[name="subagents-on"]:checked');
const off = !picked || picked.value !== "on";
for (const id of ["subagents-instruction", "subagents-max", "subagents-default"]) $(id).disabled = off;
for (const radio of document.querySelectorAll('input[name="subagents-strength"]')) radio.disabled = off;
}
// The line under the strength radios explains the picked one.
function syncStrengthHelp() {
const picked = document.querySelector('input[name="subagents-strength"]:checked');
$("subagents-strength-help").textContent = STRENGTH_HELP[picked ? picked.value : DEFAULT_STRENGTH];
}
const SUBAGENTS_ERRORS = {
max: "Pick a number from 1 to 20.",
"too-long": "The instruction is over 2,000 characters.",
strength: "That strength isn't one of the four choices.",
"not-offered": "This skill doesn't use helpers.",
bad: "That didn't save. Try again.",
};
@@ -792,7 +804,13 @@ export async function saveSubagents() {
// The shipped default is stored as null, so a later release's wording
// reaches everyone who never changed it.
const instruction = text === defaultInstruction(page.S.workflow) ? null : text;
const body = { on: Boolean(picked && picked.value === "on"), instruction, max: Number($("subagents-max").value) };
const strength = document.querySelector('input[name="subagents-strength"]:checked');
const body = {
on: Boolean(picked && picked.value === "on"),
instruction,
max: Number($("subagents-max").value),
strength: strength ? strength.value : DEFAULT_STRENGTH,
};
save.disabled = true;
status.textContent = "";
const res = await postJson("/subagents", body);
@@ -811,6 +829,7 @@ export const askOfflineFlipped = () => (askState().send.state === "offline") !==
// The Subagents dialog's buttons, and dropping files onto the notes panel.
export function wireAsk() {
for (const radio of document.querySelectorAll('input[name="subagents-on"]')) radio.addEventListener("change", syncSubagentsFields);
for (const radio of document.querySelectorAll('input[name="subagents-strength"]')) radio.addEventListener("change", syncStrengthHelp);
lightDismiss($("subagents-modal"));
$("btn-subagents").addEventListener("click", openSubagents);
$("subagents-default").addEventListener("click", () => {
+4 -4
View File
@@ -46,7 +46,7 @@
// Shared by Implement and Implement + Review.
const BUILD_HELPERS =
"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.";
"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. Pick each helper's strength and effort from helper-strength.md's table: light for a 1-2 file task the task file spells out, standard for multi-file or debugging work.";
// Pathfinder's and Plan's reason on a finished spec (a fixed bug).
export const FIXED_REASON = "This bug is fixed. Delete it with the Delete button on its chip, or move it to specs--completed/.";
@@ -110,7 +110,7 @@ export const SKILLS = Object.freeze([
pose: "pathfinder",
builds: false, phased: false, metered: false, templates: true,
weight: null, started: null, ran: null, resume: "folder",
subagents: "Use helpers for codebase recon, sketches and lookups beside the conversation. Keep every question for the person with you.",
subagents: "Use helpers for codebase recon, sketches and lookups beside the conversation. Keep every question for the person with you. Recon and lookups at light strength, research questions at standard.",
states: ["none", "unrecognized", "exploring"], marksNext: true,
greyed: {
default: "This spec is already past the questions",
@@ -264,7 +264,7 @@ export const SKILLS = Object.freeze([
pose: "quick-task",
builds: true, phased: false, metered: true, templates: true,
weight: 1, started: "Quick task started", ran: "Quick task built", resume: null,
subagents: "Use helpers for side lookups, such as reading unfamiliar code or checking documentation, while you make the change yourself.",
subagents: "Use helpers for side lookups, such as reading unfamiliar code or checking documentation, while you make the change yourself. Side lookups at light strength, low effort.",
states: "any",
greyed: null,
card: {
@@ -284,7 +284,7 @@ export const SKILLS = Object.freeze([
pose: "review",
builds: false, phased: false, metered: true, templates: false,
weight: 2, started: "Review started", ran: "Code review run", resume: null,
subagents: "Run the review's analysis in one fresh helper briefed only with the spec and the change set (references/reviewer-brief.md); verify every finding yourself before you report.",
subagents: "Run the review's analysis in one fresh helper briefed only with the spec and the change set (references/reviewer-brief.md); verify every finding yourself before you report. At standard strength or above (strongest for branch or full scope), high effort.",
states: "any",
greyed: null,
card: {
+1
View File
@@ -161,6 +161,7 @@
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-strength { margin: 4px 0 0; color: var(--ink-3); font-size: 12.5px; }
.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); }
+68 -18
View File
@@ -31,6 +31,20 @@ 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"]);
// The person's Helper strength profile, applied on top of helper-strength.md's table.
export const STRENGTHS = Object.freeze(["balanced", "thrifty", "best", "session"]);
export const DEFAULT_STRENGTH = "balanced";
// What the dialog's strength radios say, and the line under them for the picked one.
export const STRENGTH_LABELS = Object.freeze({ balanced: "Balanced", thrifty: "Thrifty", best: "Best", session: "Match my session" });
export const STRENGTH_HELP = Object.freeze({
balanced: "Each helper gets the strength its job needs: light for lookups, stronger for reviews and design work.",
thrifty: "One step lighter everywhere to save cost; reviews stay at standard or above.",
best: "The strongest model and high effort for everything except lookups.",
session: "Helpers run on whatever your session uses; nothing is set for them.",
});
// What a reported helper may say it actually ran with.
export const HELPER_STRENGTHS = Object.freeze(["light", "standard", "strongest", "inherit"]);
export const HELPER_EFFORTS = Object.freeze(["low", "medium", "high"]);
/* ------------------------------------------------------------- settings */
@@ -46,12 +60,13 @@ export function effectiveInstruction(setting) {
export function defaultSetting(workflow) {
// On until the person turns it off, for the workflows that offer the switch.
return { workflow, on: offered(workflow), instruction: null, max: DEFAULT_MAX };
return { workflow, on: offered(workflow), instruction: null, max: DEFAULT_MAX, strength: DEFAULT_STRENGTH };
}
/**
* `{ on, instruction, max }` from untrusted input, or `{ error }` naming the
* field that failed: "bad" (wrong type), "too-long" (instruction) or "max".
* `{ on, instruction, max, strength }` from untrusted input, or `{ error }`
* naming the field that failed: "bad" (wrong type), "too-long" (instruction),
* "max" or "strength". A missing strength is the default, balanced.
* Returns an error object rather than throwing, so the route and the store
* reader share one validator. An empty instruction means the default: null.
*/
@@ -67,7 +82,9 @@ export function cleanSetting(input) {
}
const max = input.max;
if (!Number.isInteger(max) || max < MAX_MIN || max > MAX_MAX) return { error: "max" };
return { on: input.on, instruction, max };
const strength = input.strength === undefined || input.strength === null ? DEFAULT_STRENGTH : input.strength;
if (!STRENGTHS.includes(strength)) return { error: "strength" };
return { on: input.on, instruction, max, strength };
}
/* ------------------------------------------------------------ the lines */
@@ -77,13 +94,22 @@ 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-subagents.md); questions for the person stay with you.",
'If your tools cannot start helpers at all, report one "working alone" entry for this skill run instead; a real helper report removes it.',
"Match each helper's strength and effort to its job, as helper-strength.md says; when your tools cannot set them, start the helper without them.",
]);
export const PATHFINDER_RESEARCH_LINE = "Research questions always use helpers, whatever this switch says.";
// The profile line each strength adds to an "on" block.
export const STRENGTH_LINES = Object.freeze({
balanced: "Helper strength: balanced (the table in helper-strength.md as written).",
thrifty: "Helper strength: thrifty (one step lighter in strength and effort than the table; reviews never below standard).",
best: "Helper strength: best (strongest and high effort for every helper except lookups, which stay light).",
session: "Helper strength: match the session (set no model or effort on any helper, whatever the skill files say).",
});
// 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 }) {
export function onLines({ revision, replaces, max, instruction, strength }) {
const label = replaces ? `revision ${revision}, replaces revision ${replaces}` : `revision ${revision}`;
const own = String(instruction || "")
.split("\n")
@@ -91,7 +117,7 @@ export function onLines({ revision, replaces, max, instruction }) {
.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),
...[...FRAME_LINES, ...own, STRENGTH_LINES[strength] || STRENGTH_LINES[DEFAULT_STRENGTH], `At most ${max} helpers at once.`].map((line) => " " + line),
];
}
@@ -110,17 +136,18 @@ export function blockFor(setting, told) {
if (!setting || !offered(setting.workflow) || !(setting.revision > last.revision)) return null;
const { revision, max } = setting;
const instruction = effectiveInstruction(setting);
const strength = STRENGTHS.includes(setting.strength) ? setting.strength : DEFAULT_STRENGTH;
if (setting.on) {
const replaces = last.state === "on" ? last.revision : undefined;
return {
field: { state: "on", revision, max, instruction },
lines: onLines({ revision, replaces, max, instruction }),
field: { state: "on", revision, max, instruction, strength },
lines: onLines({ revision, replaces, max, instruction, strength }),
cursor: { revision, state: "on" },
};
}
if (last.state !== "on") return null;
return {
field: { state: "off", revision, max, instruction },
field: { state: "off", revision, max, instruction, strength },
lines: [offLine(revision)],
cursor: { revision, state: "off" },
};
@@ -147,6 +174,8 @@ export function checkHelper(entry) {
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`);
}
if (entry.strength !== undefined && !HELPER_STRENGTHS.includes(entry.strength)) problems.push(`${who}: strength must be light, standard, strongest or inherit`);
if (entry.effort !== undefined && !HELPER_EFFORTS.includes(entry.effort)) problems.push(`${who}: effort must be low, medium or high`);
return problems;
}
@@ -191,22 +220,43 @@ export function switchLabel(frame) {
// What the Subagents tab draws: the working-alone note, or one row per helper
// in the order the agent reported them. A real helper supersedes the
// working-alone marker, so the note only draws when no helper was ever
// reported. A result shows once the helper ended.
// reported. A result shows once the helper ended, and a reported strength or
// effort as one line ("Standard, medium effort").
export function helperRows(helpers) {
const list = Array.isArray(helpers) ? helpers.filter(isPlainObject) : [];
const real = list.filter((h) => h.alone !== true);
if (!real.length) return { alone: list.some((h) => h.alone === true), rows: [] };
const rows = real.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 } : {}),
}));
const rows = real.map(({ id, title, ask, state, result, strength, effort }) => {
const ran = {
...(HELPER_STRENGTHS.includes(strength) ? { strength } : {}),
...(HELPER_EFFORTS.includes(effort) ? { effort } : {}),
};
const line = strengthLine(ran.strength, ran.effort);
return {
id,
title,
ask,
state,
stateLabel: STATE_LABELS[state] || STATE_LABELS.running,
...((state === "done" || state === "failed") && typeof result === "string" && result ? { result } : {}),
...ran,
...(line ? { strengthLine: line } : {}),
};
});
return { alone: false, rows };
}
const HELPER_STRENGTH_WORDS = Object.freeze({ light: "Light", standard: "Standard", strongest: "Strongest", inherit: "Session model" });
// "Standard, medium effort", "Light", "Medium effort", or "" when neither was reported.
function strengthLine(strength, effort) {
const parts = [];
if (strength) parts.push(HELPER_STRENGTH_WORDS[strength]);
if (effort) parts.push(`${effort} effort`);
const line = parts.join(", ");
return line && line[0].toUpperCase() + line.slice(1);
}
// 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) {
+3 -3
View File
@@ -455,15 +455,15 @@ function subagentsPost(req, res, ctx) {
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 { on, instruction, max, strength } = clean;
const current = readSubagentSetting(ctx.dir);
const next = { workflow: state.workflow, on, instruction, max };
const next = { workflow: state.workflow, on, instruction, max, strength };
// 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(ctx.worktree(), state.workflow, { on, instruction, max });
saveSubagentStoreEntry(ctx.worktree(), state.workflow, { on, instruction, max, strength });
if (!unchanged) writeSubagentSetting(ctx.dir, { ...next, revision: (current ? current.revision : 0) + 1 });
} catch (e) {
return json(res, 500, { error: String(e.message) });
+21 -13
View File
@@ -2,7 +2,7 @@
import path from "node:path";
import { cleanSetting, defaultSetting, offered } from "./public/subagents.js";
import { cleanSetting, defaultSetting, DEFAULT_STRENGTH, offered } from "./public/subagents.js";
import { ensureDir, fileStamp, HOME_DIR, readJson, readJsonLines, withStateLock, writeJsonAtomic } from "./files.mjs";
import { foldKey } from "./workspace.mjs";
@@ -10,10 +10,11 @@ import { foldKey } from "./workspace.mjs";
// The person's Subagents switch, remembered per project folder and workflow:
//
// { "<folded project path>": { "<workflow>": { on, instruction, max } } }
// { "<folded project path>": { "<workflow>": { on, instruction, max, strength } } }
//
// Keyed with foldKey(), as workspaces.json is. `instruction: null` is the
// workflow's shipped default.
// workflow's shipped default; an entry saved before `strength` existed reads
// as balanced.
export const SUBAGENTS_FILE = path.join(HOME_DIR, "subagents.json");
const SUBAGENTS_LOCK = "subagents.json.lock";
@@ -22,13 +23,13 @@ function readSubagentStore() {
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.
// The saved `{ on, instruction, max, strength }` 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 { on, instruction, max, strength } = 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 };
return saved && !saved.error ? saved : { on, instruction, max, strength };
}
// Single-writer rule: only the server may call this (its routes).
@@ -40,7 +41,7 @@ export function saveSubagentStoreEntry(worktree, workflow, value) {
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 } };
store[key] = { ...project, [workflow]: { on: value.on, instruction: value.instruction, max: value.max, strength: value.strength } };
writeJsonAtomic(SUBAGENTS_FILE, store);
},
SUBAGENTS_LOCK
@@ -127,7 +128,14 @@ export function latestOpenCaps(dir) {
/* ------------------------------------------------- the server's Subagents */
export const sameSetting = (a, b) => a.workflow === b.workflow && a.on === b.on && a.instruction === b.instruction && a.max === b.max;
// A side without `strength` (a session file written before it existed) is
// balanced, so an upgrade alone never bumps the revision.
export const sameSetting = (a, b) =>
a.workflow === b.workflow &&
a.on === b.on &&
a.instruction === b.instruction &&
a.max === b.max &&
(a.strength || DEFAULT_STRENGTH) === (b.strength || DEFAULT_STRENGTH);
/**
* The Subagents switch as the server keeps it. subagents-setting.json has one
@@ -166,8 +174,8 @@ export function serverSubagents(ctx) {
function sync(state) {
if (!state || typeof state.workflow !== "string") return;
const { workflow } = state;
const { on, instruction, max } = offered(workflow) ? subagentStoreEntry(ctx.worktree(), workflow) : defaultSetting(workflow);
const target = { workflow, on, instruction, max };
const { on, instruction, max, strength } = offered(workflow) ? subagentStoreEntry(ctx.worktree(), workflow) : defaultSetting(workflow);
const target = { workflow, on, instruction, max, strength };
const current = readSubagentSetting(dir);
if (current && sameSetting(current, target)) return;
writeSubagentSetting(dir, { ...target, revision: (current ? current.revision : 0) + 1 });
@@ -178,8 +186,8 @@ export function serverSubagents(ctx) {
// is the shipped default, which the page reads from subagents.js itself.
function view(state) {
const workflow = state && state.workflow;
const { on, instruction, max, revision } = settingNow() || { ...defaultSetting(workflow), revision: 0 };
return { offered: offered(workflow), supported: capsNow().includes("subagents"), on, instruction, max, revision };
const { on, instruction, max, strength, revision } = settingNow() || { ...defaultSetting(workflow), revision: 0 };
return { offered: offered(workflow), supported: capsNow().includes("subagents"), on, instruction, max, strength: strength || DEFAULT_STRENGTH, revision };
}
return {