mirror of
https://github.com/jparkerweb/plan2code.git
synced 2026-11-16 20:45:33 -08:00
Let helpers run at a strength matched to their job, chosen in the Subagents dialog
AI Assisted
This commit is contained in:
1 parent
5f91fb665f
commit
1d146cce6f
23 files changed
+482
-73
No files matched your search
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -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):**
|
||||
|
||||
|
||||
@@ -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.
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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>
|
||||
|
||||
@@ -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", () => {
|
||||
|
||||
@@ -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: {
|
||||
|
||||
@@ -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); }
|
||||
|
||||
@@ -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) {
|
||||
|
||||
@@ -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) });
|
||||
|
||||
@@ -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 {
|
||||
|
||||
Reference in new issue
Block a user