@signalridge/pi-workflows 1.5.0 → 1.7.0

package/src/strengths.ts

@@ -0,0 +1,93 @@
+/**
+ * strengths.ts — the workflow strength vocabulary.
+ *
+ * A workflow speaks one word about cost: how much effort a step deserves. It
+ * does not speak "tier". A script names a strength, the user's `strengths`
+ * table says which Agent tier each strength runs on, and pi-subagents resolves
+ * that tier the way it resolves every other one.
+ *
+ * The vocabulary is closed on purpose. An open one would have no typo to catch
+ * — every misspelling would be a legal strength nobody had configured, which
+ * dispatches silently instead of failing — and `/workflows strength` could not
+ * show a complete list of what there is to configure. Three effort levels are
+ * what a workflow can meaningfully distinguish; a fourth would be a model
+ * policy wearing a strength's name.
+ *
+ * Deliberately not derived from the shipped scripts. The set is the contract
+ * a script author writes against, so it has to be listed where the author and
+ * the settings menu can both read it, not inferred from whichever words the
+ * built-ins happen to use this release.
+ *
+ * There is deliberately no *default* strength either. A call that names none
+ * dispatches with no tier at all and takes the agent's ordinary default — its
+ * own frontmatter tier, then the host's configured one — exactly as an unmapped
+ * strength does, and exactly as every non-workflow Agent spawn does. Defaulting
+ * to `medium` was tried and is wrong: a tier a call requests outranks the agent
+ * type's own (`selectAgentTier` in pi-subagents: `call` before `frontmatter`),
+ * so on a stock install — where the shipped table maps `medium -> medium` —
+ * every unlabelled dispatch would have pinned `medium` over whatever the agent
+ * declared. `Explore` ships with `tier: low` precisely so read-only search stays
+ * cheap; a default strength would have silently overruled it, and re-priced in
+ * the wrong direction the one agent this indirection exists to leave alone.
+ * Nothing is lost: a script that named no strength stated no opinion, and the
+ * host's ordinary precedence is the right answer to that. What the table must
+ * reach is every call a script did label, and the shipped scripts label all of
+ * theirs.
+ */
+
+/** Every strength a script may name, cheapest first. */
+export const WORKFLOW_STRENGTHS = ["low", "medium", "high"] as const;
+
+export type WorkflowStrength = (typeof WORKFLOW_STRENGTHS)[number];
+
+/**
+ * A strength -> Agent tier table.
+ *
+ * Keyed on the closed vocabulary rather than on `string`, because every table
+ * that reaches a run has already passed {@link isWorkflowStrength} on each key:
+ * the settings layer drops the rest at read, and `runWorkflow` drops them again
+ * for callers that reach it through JS without types. Partial because an
+ * omitted strength is a real state — unmapped, taking the agent's own default —
+ * and not a hole.
+ */
+export type WorkflowStrengthTable = Readonly<Partial<Record<WorkflowStrength, string>>>;
+
+export function isWorkflowStrength(value: unknown): value is WorkflowStrength {
+  return typeof value === "string" && (WORKFLOW_STRENGTHS as readonly string[]).includes(value);
+}
+
+/** The vocabulary as a bare list, for error messages and menus. */
+export const WORKFLOW_STRENGTH_LIST = WORKFLOW_STRENGTHS.join(", ");
+
+/**
+ * The table a host uses before anyone configures one: each strength on the
+ * catalogue tier that shares its name, and only where the host defines one.
+ *
+ * Shipped as a *table*, not as a resolution rule, and that distinction is the
+ * whole design. A rule saying "an unmapped strength falls back to the tier of
+ * the same name" would be unremovable — the way the old passthrough was — so a
+ * fan-out could never be re-priced without dragging every ordinary spawn that
+ * names the same tier along with it. A default table is just the first entry in
+ * the same slot the user writes, so replacing it is one command, and the user's
+ * table still remains the only thing that binds a strength to a tier.
+ *
+ * Computed against the live catalogue rather than hardcoded, because a shipped
+ * constant would be an assertion about someone else's tier names — exactly the
+ * claim the retired `shippedScript` flag existed to walk back. On a host whose
+ * tiers are called `cheap`/`deep` this yields nothing, every strength is
+ * unmapped, and no run start complains about configuration the user never
+ * wrote. On a stock install it yields the identity table, so the shipped
+ * scripts' `low`/`medium` distinctions mean something out of the box instead of
+ * collapsing onto the managed default — which is the more expensive rung.
+ *
+ * An unknown catalogue yields nothing for the same reason: assert only what can
+ * be checked.
+ */
+export function defaultStrengthTable(knownTiers: ReadonlySet<string> | undefined): WorkflowStrengthTable {
+  const table: Partial<Record<WorkflowStrength, string>> = {};
+  if (!knownTiers) return table;
+  for (const strength of WORKFLOW_STRENGTHS) {
+    if (knownTiers.has(strength)) table[strength] = strength;
+  }
+  return table;
+}

package/src/workflow-settings.ts

@@ -1,8 +1,10 @@
-/** Small, package-owned workflow presentation settings. */
+/** Small, package-owned workflow presentation and routing settings. */
 import { createHash } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import { basename, join, resolve } from "node:path";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { isManagedAgentTier } from "@signalridge/pi-subagents-protocol";
+import { isWorkflowStrength, type WorkflowStrength, type WorkflowStrengthTable } from "./strengths.js";
 
 export type WorkflowProgressMode = "compact" | "detailed";
 
@@ -12,6 +14,80 @@ export interface WorkflowSettings {
   effort?: "off" | "high" | "ultra";
   keywordTriggerWord?: string;
   keywordTriggerEnabled?: boolean;
+  /**
+   * Which Agent tier each workflow strength runs on: all of workflow routing.
+   *
+   * A script names a strength — one of `low`/`medium`/`high`, this package's
+   * own word for how much effort a step deserves — and this table is the only
+   * thing that binds one to an Agent tier. A strength it does not define
+   * dispatches with no tier at all and takes the agent's ordinary default.
+   *
+   * Absent entirely, the run uses `defaultStrengthTable()`: each strength on
+   * the catalogue tier of the same name, wherever this host defines one. That
+   * default is a table and not a fallback rule, so writing one here replaces it
+   * outright and a strength this file omits stays unmapped even on a host that
+   * defines a tier of the same name. Which is what keeps a 26-agent fan-out
+   * re-priceable without dragging the Explore agent and everything else that
+   * names the same tier: point the strength elsewhere, do not edit the tier.
+   *
+   * This is not the retired `workflow.tiers` key and must not become it. That
+   * one carried its own model and thinking values, which made it a second model
+   * policy resolved by a second resolver. Every value here is a *key in the
+   * host's one catalogue* and nothing else: pi-subagents still owns every model,
+   * every thinking level, and the only `resolveAgentTier()`. What this table
+   * decides is which key a workflow asks for, and pi-subagents cannot tell that
+   * choice apart from a script that named the key itself. No entry here may ever
+   * grow a `model` or `thinking` field — that is the line between this and the
+   * key that was deleted, and the name no longer states it, so this does.
+   *
+   * Any key the host defines is a legal value. There is no shortlist: the target
+   * is checked against the live catalogue at run start, so a profile added to
+   * subagents.json is usable here the moment it exists.
+   *
+   * A project that defines this table replaces the global one outright rather
+   * than merging into it, so a project can shorten the table and not only
+   * extend it; a project that omits it inherits the global table unchanged.
+   */
+  strengths?: WorkflowStrengthTable;
+}
+
+/**
+ * Keep the entries a run could actually honor: a known strength, a usable key.
+ *
+ * The key side is the closed vocabulary, not a shape test. A word outside it
+ * can never match what a script asks for, so storing one would put a line in
+ * the file that looks like policy and can never fire. The value side is only a
+ * shape test, because the catalogue belongs to the host and may gain the tier
+ * later — the live check happens at run start.
+ *
+ * A strength mapped to its own spelling is kept, unlike every earlier revision
+ * of this function. It stopped being a no-op when the passthrough went away:
+ * `low → low` is the only way a written table can say "run this on the
+ * catalogue tier that happens to share the name" — the shipped default says it
+ * for a file that is absent, not for one that is present and omits the entry —
+ * so dropping it as redundant would silently mean the opposite.
+ *
+ * Malformed entries are dropped rather than tombstoned, which is what every
+ * other key in this file does — the catalogue that owns tombstones is the one
+ * in pi-subagents, and inventing a second tombstone vocabulary for this table
+ * would be a heavier promise than the table is worth.
+ */
+function sanitizeStrengths(raw: unknown): WorkflowStrengthTable | undefined {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return undefined;
+  // An empty table is kept, because it is a statement: "map nothing; every
+  // strength takes the agent's default". It became sayable — and worth saying —
+  // once an absent key started meaning the shipped default instead of that. A
+  // table whose every entry was dropped is not the same statement; it is a
+  // broken file, and storing it as an explicit "map nothing" would promote a
+  // typo to a policy, so that one still yields undefined below.
+  if (Object.keys(raw).length === 0) return {};
+  const strengths: Partial<Record<WorkflowStrength, string>> = {};
+  // No entry cap: the vocabulary is closed, so the table cannot outgrow it.
+  for (const [strength, tier] of Object.entries(raw as Record<string, unknown>)) {
+    if (!isWorkflowStrength(strength) || !isManagedAgentTier(tier)) continue;
+    strengths[strength] = tier;
+  }
+  return Object.keys(strengths).length > 0 ? strengths : undefined;
 }
 
 const DEFAULT_SETTINGS: Required<
@@ -35,6 +111,7 @@ function readSettings(path: string): WorkflowSettings {
     const parsed: unknown = JSON.parse(readFileSync(path, "utf8"));
     if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return {};
     const value = parsed as Record<string, unknown>;
+    const strengths = sanitizeStrengths(value.strengths);
     return {
       ...(value.progressMode === "compact" || value.progressMode === "detailed"
         ? { progressMode: value.progressMode }
@@ -55,6 +132,7 @@ function readSettings(path: string): WorkflowSettings {
       ...(typeof value.keywordTriggerEnabled === "boolean"
         ? { keywordTriggerEnabled: value.keywordTriggerEnabled }
         : {}),
+      ...(strengths ? { strengths } : {}),
     };
   } catch {
     return {};
@@ -69,7 +147,22 @@ export function loadWorkflowSettings(
   return { ...DEFAULT_SETTINGS, ...readSettings(globalPath), ...readSettings(projectPath) };
 }
 
+/**
+ * Only what this project's own file says, with no global or default layered in.
+ *
+ * What a command has to edit, because {@link saveWorkflowSettings} writes the
+ * project file wholesale: handed the merged view, it would copy every global
+ * value and every default into the project on the first edit, and the project
+ * would stop tracking the global file from then on. That is loud for
+ * `strengths`, which a project replaces outright rather than merging.
+ */
+export function loadProjectWorkflowSettings(cwd: string = process.cwd()): WorkflowSettings {
+  return readSettings(join(projectDirectory(cwd), "settings.json"));
+}
+
+/** Replace this project's settings file. Pass project scope, never the merged view. */
 export function saveWorkflowSettings(settings: WorkflowSettings, cwd: string = process.cwd()): void {
+  const savedStrengths = sanitizeStrengths(settings.strengths);
   const safe: WorkflowSettings = {
     ...(settings.progressMode === "compact" || settings.progressMode === "detailed"
       ? { progressMode: settings.progressMode }
@@ -90,6 +183,7 @@ export function saveWorkflowSettings(settings: WorkflowSettings, cwd: string = p
     ...(typeof settings.keywordTriggerEnabled === "boolean"
       ? { keywordTriggerEnabled: settings.keywordTriggerEnabled }
       : {}),
+    ...(savedStrengths ? { strengths: savedStrengths } : {}),
   };
   const directory = projectDirectory(cwd);
   mkdirSync(directory, { recursive: true });