2026-10-06 17:57:22 -07:00
// Plan2Code Web Console - the Subagents switch's opt-in table, wording and checks.
//
// The source of truth for which workflows offer the switch, the instruction
// each one ships with, the fixed frame every "on" block carries, the exact
// lines the agent reads at a pickup (blockFor()), and the house rules for the
// helpers an agent reports back (checkHelper()). No DOM access at module scope
// and no imports: the server, console.mjs, the page and `node --test` all
// import this file.
// The one place a skill opts in (FR-1). Wording is behaviour-level and names
// no harness tool, so any agent can follow it or harmlessly ignore it.
export const SUBAGENT_WORKFLOWS = Object . freeze ({
implement : Object . freeze ({
instruction :
"Hand independent tasks in a phase to helpers: tasks that touch different files and do not depend on each other. Keep tasks that share files, the phase's tests and the sign-off with you." ,
}),
"implement-review" : Object . freeze ({
instruction :
"Hand independent tasks in a phase to helpers: tasks that touch different files and do not depend on each other. Keep tasks that share files, the phase's tests and the sign-off with you." ,
}),
"quick-task" : Object . freeze ({
instruction :
"Use helpers for side lookups, such as reading unfamiliar code or checking documentation, while you make the change yourself." ,
}),
review : Object . freeze ({
instruction :
"Split the review across helpers by area (for example correctness, tests and security), then merge and de-duplicate their findings yourself before you report." ,
}),
pathfinder : Object . freeze ({
instruction :
"Use helpers for codebase recon, sketches and lookups beside the conversation. Keep every question for the person with you." ,
}),
});
export function offered ( workflow ) {
return typeof workflow === "string" && Object . prototype . hasOwnProperty . call ( SUBAGENT_WORKFLOWS , workflow );
}
export const MAX_MIN = 1 ;
export const MAX_MAX = 20 ;
export const DEFAULT_MAX = 3 ;
export const INSTRUCTION_MAX_CHARS = 2000 ;
export const HELPER_TITLE_MAX = 80 ;
export const HELPER_ASK_MAX = 400 ;
export const HELPER_RESULT_MAX = 200 ;
export const HELPER_STATES = Object . freeze ([ "running" , "done" , "failed" ]);
/* ------------------------------------------------------------- settings */
export function defaultInstruction ( workflow ) {
return offered ( workflow ) ? SUBAGENT_WORKFLOWS [ workflow ]. instruction : "" ;
}
// The person's own text when they wrote some, else the workflow's default.
export function effectiveInstruction ( setting ) {
const own = setting && typeof setting . instruction === "string" ? setting . instruction . trim () : "" ;
return own || defaultInstruction ( setting && setting . workflow );
}
export function defaultSetting ( workflow ) {
return { workflow , on : false , instruction : null , max : DEFAULT_MAX };
}
/**
* `{ on, instruction, max }` from untrusted input, or `{ error }` naming the
* field that failed: "bad" (wrong type), "too-long" (instruction) or "max".
* Returns an error object rather than throwing, so the route and the store
* reader share one validator. An empty instruction means the default: null.
*/
export function cleanSetting ( input ) {
if ( ! input || typeof input !== "object" || Array . isArray ( input )) return { error : "bad" };
if ( typeof input . on !== "boolean" ) return { error : "bad" };
let instruction = null ;
if ( input . instruction !== null && input . instruction !== undefined ) {
if ( typeof input . instruction !== "string" ) return { error : "bad" };
const trimmed = input . instruction . trim ();
if ( trimmed . length > INSTRUCTION_MAX_CHARS ) return { error : "too-long" };
instruction = trimmed || null ;
}
const max = input . max ;
if ( ! Number . isInteger ( max ) || max < MAX_MIN || max > MAX_MAX ) return { error : "max" };
return { on : input . on , instruction , max };
}
/* ------------------------------------------------------------ the lines */
// The non-editable part of every "on" block (FR-8).
export const FRAME_LINES = Object . freeze ([
"Hand independent work to helpers if your tools allow it; otherwise carry on alone." ,
"Report each helper on the page (console.md → Standing instructions); questions for the person stay with you." ,
2026-10-07 16:42:16 -07:00
'If your tools cannot start helpers at all, report one "working alone" entry for this skill run instead; a real helper report removes it.' ,
2026-10-06 17:57:22 -07:00
]);
export const PATHFINDER_RESEARCH_LINE = "Research questions always use helpers, whatever this switch says." ;
// Only the first line of a block starts at column 0, so no line inside it can
// be read as an entry of its own (NFR-5).
export function onLines ({ revision , replaces , max , instruction }) {
const label = replaces ? `revision ${ revision } , replaces revision ${ replaces } ` : `revision ${ revision } ` ;
const own = String ( instruction || "" )
. split ( "\n" )
. map (( line ) => line . trimEnd ())
. filter (( line ) => line . trim ());
return [
`Subagents: on ( ${ label } ) — a console setting, not typed by the person.` ,
...[... FRAME_LINES , ... own , `At most ${ max } helpers at once.` ]. map (( line ) => " " + line ),
];
}
export function offLine ( revision ) {
return `Subagents: off (revision ${ revision } ) — don't start new helpers for the rest of this session.` ;
}
/**
* What the agent is owed at a pickup, given the session setting and the
* cursor of what it was last told: `null`, or `{ field, lines, cursor }`
* where `cursor` is what to write once the lines are printed. Never says
* "off" to an agent that was not told "on" (FR-6). Pure: no clock, no I/O.
*/
export function blockFor ( setting , told ) {
const last = told || { revision : 0 , state : "none" };
if ( ! setting || ! offered ( setting . workflow ) || ! ( setting . revision > last . revision )) return null ;
const { revision , max } = setting ;
const instruction = effectiveInstruction ( setting );
if ( setting . on ) {
const replaces = last . state === "on" ? last . revision : undefined ;
return {
field : { state : "on" , revision , max , instruction },
lines : onLines ({ revision , replaces , max , instruction }),
cursor : { revision , state : "on" },
};
}
if ( last . state !== "on" ) return null ;
return {
field : { state : "off" , revision , max , instruction },
lines : [ offLine ( revision )],
cursor : { revision , state : "off" },
};
}
/* ------------------------------------------------------------ helpers */
const isPlainObject = ( v ) => !! v && typeof v === "object" && ! Array . isArray ( v );
const nonEmpty = ( v ) => typeof v === "string" && v . trim () !== "" ;
// The problems with one reported helper, [] when it is fine.
export function checkHelper ( entry ) {
if ( ! isPlainObject ( entry )) return [ "helper: each entry must be an object" ];
if ( ! nonEmpty ( entry . id )) return [ "helper: id must be a non-empty string" ];
const who = `helper " ${ entry . id } "` ;
if ( entry . alone === true ) return entry . id === "alone" ? [] : [ ` ${ who } : the working-alone entry must have id "alone"` ];
const problems = [];
if ( ! nonEmpty ( entry . title )) problems . push ( ` ${ who } : title must be a non-empty string` );
else if ( entry . title . length > HELPER_TITLE_MAX ) problems . push ( ` ${ who } : title must be at most ${ HELPER_TITLE_MAX } characters` );
if ( ! nonEmpty ( entry . ask )) problems . push ( ` ${ who } : ask must be a non-empty string` );
else if ( entry . ask . length > HELPER_ASK_MAX ) problems . push ( ` ${ who } : ask must be at most ${ HELPER_ASK_MAX } characters` );
if ( ! HELPER_STATES . includes ( entry . state )) problems . push ( ` ${ who } : state must be running, done or failed` );
if ( entry . result !== undefined ) {
if ( typeof entry . result !== "string" ) problems . push ( ` ${ who } : result must be a string` );
else if ( entry . result . length > HELPER_RESULT_MAX ) problems . push ( ` ${ who } : result must be at most ${ HELPER_RESULT_MAX } characters` );
}
return problems ;
}
// The problems with a whole merged list.
export function checkHelpers ( list ) {
if ( ! Array . isArray ( list )) return [ "helpers must be an array" ];
const problems = [];
const seen = new Set ();
let alone = 0 ;
for ( const entry of list ) {
if ( isPlainObject ( entry ) && nonEmpty ( entry . id )) {
if ( seen . has ( entry . id )) problems . push ( `helper " ${ entry . id } ": duplicate id` );
seen . add ( entry . id );
if ( entry . alone === true && ++ alone === 2 ) problems . push ( `helper " ${ entry . id } ": only one working-alone entry is allowed` );
}
problems . push (... checkHelper ( entry ));
}
return problems ;
}
/* ------------------------------------------------------------ the page */
// The page's rules for the button, the modal and the tab, kept here so they
// are tested without a browser. `frame` is the state frame's `subagents`
// block; app.js only renders what these say.
2026-10-07 23:18:40 -07:00
export const CHECKIN_LINE = "Helpers report through Plan2Code, so their progress is shown as it checks-in, not live." ;
2026-10-06 17:57:22 -07:00
const STATE_LABELS = Object . freeze ({ running : "Running" , done : "Done" , failed : "Failed" });
// The switch shows only where the skill opts in AND the agent's console copy
// said it can deliver it (FR-3).
export function showSwitch ( frame ) {
return Boolean ( frame && frame . offered && frame . supported );
}
// The button's tooltip and accessible name (FR-2).
export function switchLabel ( frame ) {
return frame && frame . on ? "Subagents: on" : "Subagents: off" ;
}
// What the Subagents tab draws: the working-alone note, or one row per helper
2026-10-07 16:42:16 -07:00
// 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.
2026-10-06 17:57:22 -07:00
export function helperRows ( helpers ) {
const list = Array . isArray ( helpers ) ? helpers . filter ( isPlainObject ) : [];
2026-10-07 16:42:16 -07:00
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 }) => ({
2026-10-06 17:57:22 -07:00
id ,
title ,
ask ,
state ,
stateLabel : STATE_LABELS [ state ] || STATE_LABELS . running ,
...(( state === "done" || state === "failed" ) && typeof result === "string" && result ? { result } : {}),
}));
return { alone : false , rows };
}
// Never an empty tab. Independent of on / off, so Pathfinder's research
// helpers show even with the switch off (FR-11, FR-12).
export function showTab ( frame , helpers ) {
return showSwitch ( frame ) && Array . isArray ( helpers ) && helpers . length > 0 ;
}