pi-pstack-adapter 0.7.0 → 0.9.0

package/src/status.ts

@@ -1,7 +1,12 @@
 import { CERTIFIED } from "./certified.ts";
-import { CAPABILITY_LABELS, GENERAL_ROLE, MODEL_ROLES, TIER_ORDER } from "./registry.ts";
-import type { AdapterConfig } from "./config.ts";
-import { splitModelSpec, trustWarning } from "./config.ts";
+import { CAPABILITY_LABELS, MODEL_ROLES, PANEL_DEFAULT_ROLES, PANEL_ROLES, TIER_ORDER } from "./registry.ts";
+import type { AdapterConfig, ModelSpec } from "./config.ts";
+import { trustWarning } from "./config.ts";
+import { type FilterOrigin, briefLine, describeOrigin, filterOf, isRestricting } from "./filter.ts";
+import { type PanelSeat, type ResolutionContext, type ResolvedPanel, type RoleResolution, defaultSeats, resolvePanel, resolveRole } from "./pools.ts";
+
+export { resolvePanel } from "./pools.ts";
+export type { PanelSeat, ResolvedPanel } from "./pools.ts";
 import { DELEGATION_BACKENDS, delegationOrder } from "./delegation.ts";
 import type { PrerequisiteReport } from "./capabilities.ts";
 import type {
@@ -30,10 +35,16 @@ export interface StatusInput {
   readonly bootstrapped: boolean;
   /** Runtime findings that generation could not know, such as agent registration results. */
   readonly runtimeDiagnostics?: readonly Diagnostic[];
+  /** The model filter in force and where it came from. None when omitted. */
+  readonly filter?: FilterOrigin;
+  /** `provider/id` of the session's model, which an inheriting role runs on. */
+  readonly parentModel?: string;
 }
 
 export function renderStatus(input: StatusInput): string {
   const { config, source } = input;
+  const origin = input.filter ?? { kind: "none" };
+  const context: ResolutionContext = { filter: filterOf(origin), parentModel: input.parentModel };
   const lines: string[] = [];
 
   lines.push(`# ${config.namespace} adapter status`);
@@ -60,6 +71,7 @@ export function renderStatus(input: StatusInput): string {
   lines.push(`| Poteto Mode | ${input.modeActive ? "active" : "off"} |`);
   lines.push(`| delegation order | ${delegationOrder(config.delegation).map((backend) => backend.id).join(", then ")} |`);
   lines.push(`| delegation | ${describeDelegation(input.capabilities)} |`);
+  lines.push(`| model filter | ${describeOrigin(origin)} |`);
   lines.push("");
 
   const warning = trustWarning(source.trust, config);
@@ -90,23 +102,35 @@ export function renderStatus(input: StatusInput): string {
   lines.push("");
   lines.push(`| role | model | thinking |`);
   lines.push(`| --- | --- | --- |`);
-  const extra = Object.keys(config.models).filter((role) => !MODEL_ROLES.includes(role)).sort();
-  const general = config.models[GENERAL_ROLE];
-  for (const role of [...MODEL_ROLES, ...extra]) {
-    const configured = config.models[role];
-    if (configured === undefined && general !== undefined) {
-      const spec = splitModelSpec(general);
-      lines.push(`| ${role} | ${spec.model} (from ${GENERAL_ROLE}) | ${spec.thinking ?? "backend default"} (from ${GENERAL_ROLE}) |`);
-      continue;
-    }
-    if (configured === undefined) {
-      lines.push(`| ${role} | inherit (parent session model) | inherit (parent session thinking) |`);
-      continue;
-    }
-    const spec = splitModelSpec(configured);
-    lines.push(`| ${role} | ${spec.model} | ${spec.thinking ?? "backend default"} |`);
+  for (const role of [...MODEL_ROLES, ...extraRoles(config)]) {
+    const [model, thinking] = describeRole(resolveRole(config, role, context), role);
+    lines.push(`| ${role} | ${model} | ${thinking} |`);
+  }
+  lines.push("");
+  const policy = renderModelPolicy(config, origin, input.parentModel);
+  if (policy) {
+    lines.push(policy);
+    lines.push("");
+  }
+
+  lines.push(`## Panel roles`);
+  lines.push("");
+  lines.push("A panel runs one seat per entry. An unset panel uses `judgment`, then `general`.");
+  lines.push("");
+  lines.push(`| panel | seats | source |`);
+  lines.push(`| --- | --- | --- |`);
+  const panels = PANEL_ROLES.map((panel) => resolvePanel(config, panel, context));
+  for (const panel of panels) {
+    lines.push(`| ${panel.role} | ${panel.seats.map(describeSeat).join("; ")} | ${panel.configured ? "configured" : `unset, so ${PANEL_DEFAULT_ROLES.join(", ")}`} |`);
   }
   lines.push("");
+  for (const panel of panels) {
+    const warning = panelWarning(panel, config, context);
+    if (warning) {
+      lines.push(`> Warning. ${warning}`);
+      lines.push("");
+    }
+  }
 
   lines.push(`## Support tiers`);
   lines.push("");
@@ -140,6 +164,156 @@ export function renderStatus(input: StatusInput): string {
   return lines.join("\n");
 }
 
+function describeSpec(spec: ModelSpec): string {
+  return `${spec.model} at ${spec.thinking ?? "backend default"}`;
+}
+
+function describeSeat(seat: PanelSeat): string {
+  const origin = seat.from ? ` (${seat.from})` : "";
+  switch (seat.kind) {
+    case "parent":
+      return `model of the agent that starts the panel${origin}`;
+    case "model":
+      return `${describeSpec(seat.spec)}${origin}`;
+    case "choice":
+      return `one of ${seat.choices.map(describeSpec).join(" or ")}, picked once for this seat${origin}`;
+    case "blocked":
+      return `BLOCKED, ${seat.reason}${origin}`;
+  }
+}
+
+const PARENT_MODEL = "the model of the agent that starts the panel";
+
+/** The model a seat runs on, when it is already determined. */
+function seatModel(seat: PanelSeat): string | undefined {
+  switch (seat.kind) {
+    case "parent":
+      return PARENT_MODEL;
+    case "model":
+      return seat.spec.model;
+    case "choice": {
+      const models = new Set(seat.choices.map((choice) => choice.model));
+      return models.size === 1 ? [...models][0] : undefined;
+    }
+    case "blocked":
+      return undefined;
+  }
+}
+
+function seatModels(seats: readonly PanelSeat[]): Set<string> | undefined {
+  const models = new Set<string>();
+  for (const seat of seats) {
+    const model = seatModel(seat);
+    if (model !== undefined) models.add(model);
+    else if (seat.kind === "choice") return undefined;
+  }
+  return models;
+}
+
+/**
+ * Upstream's default panels span two model families. A panel whose seats all land on one model
+ * lost that because of configuration, not because no other model exists, so say so where the
+ * agent reads it. Families are left to the agent, which knows them better than a prefix list.
+ */
+export function panelWarning(panel: ResolvedPanel, config: AdapterConfig, context: ResolutionContext = {}): string | undefined {
+  const usable = panel.seats.filter((seat) => seat.kind !== "blocked");
+  const models = seatModels(usable);
+  const pool = panel.role === "arena-cross-judge-pool";
+  // Upstream lets a panel line hold one entry on purpose, so only the judge pool warns at one seat.
+  if (models === undefined || models.size !== 1 || (usable.length < 2 && !pool)) return undefined;
+  const [model] = [...models];
+  const named = model === PARENT_MODEL ? PARENT_MODEL : `\`${model}\``;
+  const cause = panel.configured
+    ? `its configured entries all name ${named}`
+    : `it is unset, and ${PANEL_DEFAULT_ROLES.map((role) => `\`${role}\``).join(" and ")} both resolve to ${named}`;
+  return `Every seat of \`${panel.role}\` runs on ${named}, because ${cause}, ${pool ? poolEffect(panel, config, model, context) : "so the panel has one model and no second family"}. This comes from the adapter configuration, not from which models are available. Run \`/skill:${config.namespace}-setup\` to put this panel on two model families, as upstream's defaults do.`;
+}
+
+/**
+ * Arena's judge is never from the session's family. When no pool entry qualifies, upstream tries
+ * its default pool, which here is `judgment`, then `general`, before it skips the judge.
+ */
+function poolEffect(panel: ResolvedPanel, config: AdapterConfig, model: string | undefined, context: ResolutionContext): string {
+  const fallback = defaultSeats(config, context);
+  const fallbackModels = seatModels(fallback);
+  const lead =
+    model === PARENT_MODEL
+      ? "and an `inherit` entry never judges, so arena"
+      : `so a session on the family of \`${model}\` gets no judge from the pool, and arena`;
+  const sameFallback = !panel.configured || (fallbackModels?.size === 1 && fallbackModels.has(model ?? PARENT_MODEL));
+  return sameFallback
+    ? `${lead} skips the judge`
+    : `${lead} tries its default pool, ${fallback.map(describeSeat).join("; ")}, before it skips the judge`;
+}
+
+/** The panels a workflow reads, for its `check` report. */
+export function renderPanels(config: AdapterConfig, roles: readonly string[], context: ResolutionContext = {}): string {
+  const lines = roles.map((role) => {
+    const panel = resolvePanel(config, role, context);
+    const source = panel.configured ? "configured" : `unset, so ${PANEL_DEFAULT_ROLES.join(", ")}`;
+    const warning = panelWarning(panel, config, context);
+    return `- \`${role}\` (${source}): ${panel.seats.map(describeSeat).join("; ")}.${warning ? ` Warning. ${warning}` : ""}`;
+  });
+  return `Panels this workflow uses, one seat per entry:\n${lines.join("\n")}`;
+}
+
+/** One `model roles` row: the model column and the thinking column. */
+function describeRole(resolution: RoleResolution, role: string): readonly [string, string] {
+  const via = resolution.from === role ? "" : ` (from ${resolution.from})`;
+  switch (resolution.kind) {
+    case "inherit":
+      return ["inherit (parent session model)", "inherit (parent session thinking)"];
+    case "blocked": {
+      const excluded = resolution.choices.map((choice) => choice.spec.model);
+      return [`BLOCKED, ${resolution.reason}${excluded.length > 0 ? `: ${excluded.join(", ")}` : ""}. Do not delegate this role${via}`, "-"];
+    }
+    case "pool": {
+      const [only] = resolution.choices;
+      if (resolution.choices.length === 1 && only) return [`${only.spec.model}${via}`, `${only.spec.thinking ?? "backend default"}${via}`];
+      const eligible = resolution.choices.filter((choice) => choice.eligible).map((choice) => describeSpec(choice.spec));
+      const excluded = resolution.choices.filter((choice) => !choice.eligible).map((choice) => describeSpec(choice.spec));
+      const tail = excluded.length > 0 ? `; excluded by the model filter: ${excluded.join(", ")}` : "";
+      return [`pool, pick one of ${eligible.join(", ")}${tail}${via}`, `per choice${via}`];
+    }
+  }
+}
+
+/**
+ * The delegation rules a workflow's `check` report adds when pools, a model filter, or blocked roles
+ * are in play. Nothing when none of them is, so the report stays as it was.
+ */
+export function renderModelPolicy(config: AdapterConfig, origin: FilterOrigin, parentModel: string | undefined): string | undefined {
+  const filter = filterOf(origin);
+  const context: ResolutionContext = { filter, parentModel };
+  const roles = [...MODEL_ROLES, ...extraRoles(config)];
+  const resolutions = roles.map((role) => [role, resolveRole(config, role, context)] as const);
+  const blocked = resolutions.filter(([, resolution]) => resolution.kind === "blocked");
+  const pools = resolutions.filter(([, resolution]) => resolution.kind === "pool" && resolution.choices.length > 1);
+  if (!isRestricting(filter) && pools.length === 0 && blocked.length === 0) return undefined;
+  const lines: string[] = [];
+  if (isRestricting(filter)) {
+    lines.push(`Model filter: ${describeOrigin(origin)}. The adapter blocks a delegation whose model it excludes, or whose model it cannot tell.`);
+    lines.push(`Put this line in each brief, verbatim: "${briefLine(filter)}"`);
+  }
+  if (pools.length > 0) {
+    lines.push(
+      `Pools: ${pools.map(([role, resolution]) => `\`${role}\` picks one of ${describeRole(resolution, role)[0].replace(/^pool, pick one of /, "")}`).join("; ")}. For each delegation, pick ONE eligible model from the role's pool by fit. A pool is not a retry list and not a panel: do not start the same task on several of its models, and when a delegation fails, report the failure instead of trying another model.`,
+    );
+  }
+  if (blocked.length > 0) {
+    lines.push(
+      `Blocked roles: ${blocked.map(([role, resolution]) => `\`${role}\` (${resolution.kind === "blocked" ? resolution.reason : ""})`).join("; ")}. Do not delegate work for a blocked role, and do not move it to \`general\` or your own model. Tell the user which role is blocked and why.`,
+    );
+  }
+  return lines.join("\n\n");
+}
+
+function extraRoles(config: AdapterConfig): string[] {
+  return Object.keys(config.models)
+    .filter((role) => !MODEL_ROLES.includes(role) && !PANEL_ROLES.includes(role))
+    .sort();
+}
+
 function describeDelegation(capabilities: readonly CapabilityStatus[]): string {
   const backend = capabilities.find((capability) => capability.id === "delegation")?.backend;
   if (!backend) return "none available";
@@ -178,6 +352,10 @@ export function renderCheck(
   report: PrerequisiteReport,
   /** The resolved `delegation` capability, named for a workflow that delegates. */
   delegation?: CapabilityStatus,
+  /** The workflow's panels, from `renderPanels`. */
+  panels?: string,
+  /** Pools, the model filter, and blocked roles, from `renderModelPolicy`. */
+  policy?: string,
 ): string {
   const parts = [`\`/skill:${skill.generatedName}\` is tier **${skill.tier}**.`];
   if (entry.note) parts.push(entry.note);
@@ -196,6 +374,8 @@ export function renderCheck(
       delegation?.backend ? delegationInstruction(delegation.backend, delegation.tools) : "No delegation tool is usable in this session, so do not delegate.",
     );
   }
+  if (panels && skill.tier !== "unsupported") parts.push(panels);
+  if (policy && skill.capabilities.includes("delegation") && skill.tier !== "unsupported") parts.push(policy);
   if (skill.tier === "experimental" && report.ok) {
     parts.push("Tier `experimental` means parts of this workflow have no Pi equivalent. Expect gaps.");
   }

package/src/vocabulary.ts

@@ -0,0 +1,123 @@
+import { readdirSync, readFileSync } from "node:fs";
+import { join, relative, sep } from "node:path";
+import type { Diagnostic } from "./types.ts";
+
+/**
+ * A Cursor name that an upstream body can use. `key` must appear in the Cursor column of a
+ * host mapping row, so deleting the row, or adding a term without one, fails certification.
+ */
+export interface CursorTerm {
+  readonly key: string;
+  readonly pattern: RegExp;
+}
+
+/**
+ * Ported from the `TERMS` list in upstream's `scripts/generate-pstack-harness-trees.mjs`, which
+ * fails when a skill uses a term that `pstack/docs/harness/claude-code.md` has no row for. The
+ * keys name this adapter's rows. Upstream's single "Cursor-only features" term is split into one
+ * term per feature, and the terms after it cover rows upstream does not scan for.
+ */
+export const CURSOR_TERMS: readonly CursorTerm[] = [
+  { key: "`Task` tool", pattern: /`Task`|\bTask (tool|subagent|call)/ },
+  { key: "`AskQuestion`", pattern: /AskQuestion/ },
+  { key: "todolist", pattern: /\btodo ?list\b/i },
+  { key: "`subagent_type: generalPurpose`", pattern: /generalPurpose/ },
+  { key: "`poteto-agent`", pattern: /poteto-agent/ },
+  { key: "`comment-sicko`", pattern: /comment-sicko/ },
+  { key: "`readonly: true`", pattern: /readonly: true|readonly\/Ask/ },
+  { key: "`readonly: false`", pattern: /readonly: false/ },
+  { key: "`environment: \"cloud\"`", pattern: /environment: "cloud"/ },
+  { key: "`environment: \"local\"`", pattern: /environment: "local"/ },
+  { key: "`cloud_base_branch`", pattern: /cloud_base_branch/ },
+  { key: "`run_in_background: true`", pattern: /run_in_background/ },
+  { key: "`resume`", pattern: /`resume`/ },
+  { key: "`file_attachments`", pattern: /file_attachments/ },
+  { key: "`claude-opus-5-5-xhigh`", pattern: /\bclaude-[a-z]+-\d/ },
+  { key: "`grok-4.7-xhigh-fast`", pattern: /\bgrok-\d/ },
+  { key: "`gpt-*`", pattern: /\bgpt-\d/ },
+  { key: "`inherit-parent`", pattern: /inherit-parent/ },
+  { key: "`~/.cursor/rules/pstack-models.mdc`", pattern: /pstack-models\.mdc/ },
+  { key: "`.cursor/skills/`", pattern: /\.cursor\/skills/ },
+  { key: "`~/.cursor/plugins/`", pattern: /\.cursor\/plugins|\.cursor-plugin/ },
+  // pstack-models.mdc has its own row, so it does not count as a use of the general rule row.
+  { key: "`.cursor/rules/*.mdc`", pattern: /\.cursor\/rules(?!\/pstack-models\.mdc)|always-applied rule/ },
+  { key: "agent-transcripts", pattern: /agent-transcripts|\.cursor\/projects/ },
+  { key: "Bugbot", pattern: /Bugbot/ },
+  { key: "Cursor Automations", pattern: /Cursor [Aa]utomation|cursor\.(sh|com)\/automations/ },
+  { key: "Cursor cloud agents", pattern: /[Cc]loud [Aa]gent/ },
+  { key: "a built-in PR tool", pattern: /built-in PR tool/i },
+  { key: "`Grep`, `Glob`", pattern: /\bGrep\b|\bGlob\b/ },
+  { key: "`AskUserQuestion`", pattern: /AskUserQuestion/ },
+  { key: "`TodoWrite`", pattern: /TodoWrite|TaskCreate|TaskUpdate/ },
+  { key: "`/visualize`", pattern: /\/visualize\b/ },
+  { key: "Cursor `/loop`", pattern: /(^|[\s(`])\/loop\b/ },
+  { key: "a skill under `plugins/cache/`", pattern: /plugins\/cache\// },
+  { key: "a Custom Mode", pattern: /Custom Mode/ },
+];
+
+/** One upstream Markdown file, named by its skill and its path inside the skill directory. */
+export interface SkillMarkdown {
+  readonly skill: string;
+  readonly path: string;
+  readonly text: string;
+}
+
+/**
+ * The entry file generation reads, then every other Markdown file under the skill directory in
+ * sorted path order. The entry is read through `entryPath` even when it is a symbolic link,
+ * because generation follows it too. Other symbolic links below `dir` are not followed, as
+ * generation skips them when it copies support files. `dir` itself comes from discovery, which
+ * lists only real directories, not symbolic links, under the manifest's skills directory.
+ */
+export function skillMarkdown(skill: string, dir: string, entryPath: string): SkillMarkdown[] {
+  const files: SkillMarkdown[] = [{ skill, path: "SKILL.md", text: readFileSync(entryPath, "utf8") }];
+  const visit = (current: string) => {
+    for (const entry of readdirSync(current, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+      const path = join(current, entry.name);
+      if (current === dir && entry.name === "SKILL.md") continue;
+      if (entry.isSymbolicLink()) continue;
+      if (entry.isDirectory()) visit(path);
+      else if (entry.isFile() && entry.name.endsWith(".md")) {
+        files.push({ skill, path: relative(dir, path).split(sep).join("/"), text: readFileSync(path, "utf8") });
+      }
+    }
+  };
+  visit(dir);
+  return files;
+}
+
+/** The Cursor column of every table row in a host mapping document. */
+export function mappedCursorNames(mapping: string): string[] {
+  return mapping
+    .split(/\r?\n/)
+    .filter((line) => line.startsWith("| ") && !/^\| [-\s|]+$/.test(line))
+    .map((line) => {
+      const end = line.indexOf(" | ", 1);
+      return end < 0 ? line.slice(2) : line.slice(2, end);
+    });
+}
+
+/**
+ * One warning per term that an upstream skill uses and no host mapping row names, in term order
+ * with skills sorted, so a revision with new Cursor vocabulary fails certification.
+ */
+export function vocabularyDiagnostics(
+  files: readonly SkillMarkdown[],
+  mapping: string,
+  terms: readonly CursorTerm[] = CURSOR_TERMS,
+): Diagnostic[] {
+  const cursorColumn = mappedCursorNames(mapping);
+  const diagnostics: Diagnostic[] = [];
+  for (const term of terms) {
+    if (cursorColumn.some((cell) => cell.includes(term.key))) continue;
+    const skills = [...new Set(files.filter((file) => term.pattern.test(file.text)).map((file) => file.skill))].sort();
+    if (skills.length === 0) continue;
+    diagnostics.push({
+      level: "warning",
+      resource: `host-mapping:${term.key}`,
+      message: `Upstream ${skills.length === 1 ? "skill" : "skills"} ${skills.map((name) => `\`${name}\``).join(", ")} ${skills.length === 1 ? "uses" : "use"} the Cursor term ${term.key}, but no host mapping row names it in its Cursor column, so Pi would have to guess what it means.`,
+      action: `Read what the term means in those skills and in upstream's pstack/docs/harness/claude-code.md at this commit, then add a row that names ${term.key} to hostMappingDocument in src/generate.ts and rerun the probe.`,
+    });
+  }
+  return diagnostics;
+}