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