@yycholla/pi-dynamic-workflows 3.3.0

package/src/deep-research.ts

@@ -0,0 +1,135 @@
+/**
+ * Deep research workflow.
+ * Built-in workflow for comprehensive research across multiple sources.
+ */
+
+export interface DeepResearchConfig {
+  /** Number of distinct search angles/queries to explore. */
+  angles: number;
+  /** Minimum distinct sources required for a claim to survive cross-checking. */
+  minSupport: number;
+}
+
+/**
+ * Generate a deep-research workflow that uses the real web_search/web_fetch tools.
+ *
+ * The script is static and reads its inputs from `args` (question/angles/minSupport),
+ * so the question is never string-interpolated into source — no escaping hazards.
+ * Inject the web tools at run time via the agent's `tools` option.
+ */
+export function generateDeepResearchWorkflow(): string {
+  return `export const meta = {
+  name: 'deep_research',
+  description: 'Deep research with real web search and cross-checked claims',
+  phases: [
+    { title: 'Queries' },
+    { title: 'Gather' },
+    { title: 'Verify' },
+    { title: 'Report' },
+  ],
+}
+
+const question = (args && args.question) || ''
+const angles = (args && args.angles) || 4
+const minSupport = (args && args.minSupport) || 2
+
+phase('Queries')
+const plan = await agent(
+  'You are planning web research for this question:\\n' + question +
+  '\\n\\nProduce ' + angles + ' diverse, specific search queries that together cover the question from different angles.',
+  { label: 'plan queries', schema: { type: 'object', properties: { queries: { type: 'array', items: { type: 'string' } } }, required: ['queries'] } }
+)
+// The planner agent() can return null (e.g. a subagent that died on a terminal
+// provider error) or omit a usable queries array. Mirror the null-tolerance the
+// Gather phase uses below and fall back to the original question as a single
+// query so research still proceeds (degraded) instead of crashing on plan.queries.
+const planned = plan && Array.isArray(plan.queries) ? plan.queries.filter((q) => typeof q === 'string' && q.trim().length > 0) : []
+const queries = (planned.length > 0 ? planned : [question]).slice(0, angles)
+
+phase('Gather')
+const gathered = await parallel(queries.map((q, i) => () =>
+  agent(
+    'Research this query using the web_search and web_fetch tools.\\nQuery: ' + q +
+    '\\n\\nSteps: (1) call web_search with the query; (2) web_fetch the 2 most relevant result URLs; ' +
+    '(3) extract concrete, verifiable factual claims, each tagged with the exact source URL it came from. ' +
+    'Do NOT invent sources or claims — report only what the fetched pages actually say.',
+    { label: 'research ' + (i + 1), schema: { type: 'object', properties: { sources: { type: 'array', items: { type: 'object', properties: { url: { type: 'string' }, claims: { type: 'array', items: { type: 'string' } } }, required: ['url', 'claims'] } } }, required: ['sources'] } }
+  )
+))
+const allSources = gathered.filter(Boolean).flatMap((g) => (g && g.sources) || [])
+
+phase('Verify')
+const verdict = await agent(
+  'Cross-check these research sources. Group claims that assert the same fact across different source URLs. ' +
+  'Keep a claim only if it is supported by at least ' + minSupport + ' distinct source URLs OR by one clearly authoritative source. ' +
+  'Discard claims found in a single weak source or that conflict with others.\\n\\nSOURCES JSON:\\n' + JSON.stringify(allSources),
+  { label: 'cross-check', schema: { type: 'object', properties: { supported: { type: 'array', items: { type: 'object', properties: { claim: { type: 'string' }, sources: { type: 'array', items: { type: 'string' } } }, required: ['claim', 'sources'] } }, discarded: { type: 'array', items: { type: 'string' } } }, required: ['supported'] } }
+)
+
+phase('Report')
+const report = await agent(
+  'Write a concise, well-structured research report that answers the question using ONLY the supported claims below. ' +
+  'Cite source URLs inline next to each claim. If the evidence is thin, say so explicitly.\\n\\n' +
+  'QUESTION: ' + question + '\\n\\nSUPPORTED CLAIMS JSON:\\n' + JSON.stringify((verdict && verdict.supported) || []),
+  { label: 'write report' }
+)
+
+return { question, queries, supported: (verdict && verdict.supported) || [], report }`;
+}
+
+/**
+ * Generate a codebase audit workflow.
+ *
+ * `scope` and each `checks` entry are user-supplied strings that get baked
+ * directly into the generated script's source (unlike the runtime-args-driven
+ * generators above), so every one is embedded via JSON.stringify — a proper JS
+ * string literal that can't be broken out of by a quote, backslash, or
+ * backtick in the value. Only the human-readable `meta.description` is
+ * truncated for display; the operative `scope` used by the agents is always
+ * the full, untruncated value.
+ */
+export function generateCodebaseAuditWorkflow(scope: string, checks: string[]): string {
+  const displayScope = scope.length > 60 ? `${scope.slice(0, 60)}…` : scope;
+  const checkAgents = checks
+    .map((check, i) => {
+      const label =
+        check
+          .toLowerCase()
+          .replace(/[^a-z0-9]+/g, "-")
+          .replace(/^-+|-+$/g, "")
+          .slice(0, 20) || `check-${i + 1}`;
+      return `  () => agent(${JSON.stringify(`Audit ${check} across: `)} + scope, { label: ${JSON.stringify(label)} }),`;
+    })
+    .join("\n");
+
+  return `export const meta = {
+  name: 'codebase_audit',
+  description: ${JSON.stringify(`Codebase audit: ${displayScope}`)},
+  phases: [
+    { title: 'Individual Checks' },
+    { title: 'Cross-Validation' },
+    { title: 'Report' },
+  ],
+};
+
+phase('Individual Checks');
+const scope = ${JSON.stringify(scope)};
+const findings = await parallel([
+${checkAgents}
+]);
+
+phase('Cross-Validation');
+const validated = await agent(
+  'Cross-validate these audit findings. Remove false positives and confirm real issues:\\n' +
+  JSON.stringify(findings),
+  { label: 'validator' }
+);
+
+phase('Report');
+const report = await agent(
+  'Generate a prioritized audit report with actionable recommendations:\\n' + validated,
+  { label: 'report-writer' }
+);
+
+return { findings, validated, report };`;
+}

package/src/display.ts

@@ -0,0 +1,367 @@
+import type { ExtensionContext, Theme } from "@earendil-works/pi-coding-agent";
+import type { AgentUsage } from "./agent.js";
+import type { AgentHistoryEntry } from "./agent-history.js";
+import type { WorkflowErrorCode } from "./errors.js";
+import type { WorkflowMeta } from "./workflow.js";
+
+export type WorkflowAgentStatus = "queued" | "running" | "done" | "error" | "skipped";
+
+export interface WorkflowAgentSnapshot {
+  id: number;
+  /** Runtime call identity (`${runId}:${callIndex}`), used to rehydrate journaled results. */
+  callId?: string;
+  label: string;
+  phase?: string;
+  prompt: string;
+  status: WorkflowAgentStatus;
+  /** Full agent result, retained for the interactive detail pager. */
+  result?: unknown;
+  resultPreview?: string;
+  error?: string;
+  errorCode?: WorkflowErrorCode;
+  recoverable?: boolean;
+  history?: AgentHistoryEntry[];
+  /** Tokens used by this agent (a scalar estimate when the provider reports no usage). */
+  tokens?: number;
+  /** Per-agent token usage breakdown (fresh input+output vs cached), when known. */
+  tokenUsage?: AgentUsage;
+  /** The model this agent ran on (provider/id), when known. */
+  model?: string;
+}
+
+export interface WorkflowSnapshot {
+  name: string;
+  description?: string;
+  phases: string[];
+  currentPhase?: string;
+  logs: string[];
+  agents: WorkflowAgentSnapshot[];
+  agentCount: number;
+  runningCount: number;
+  doneCount: number;
+  errorCount: number;
+  durationMs?: number;
+  result?: unknown;
+  tokenUsage?: {
+    input: number;
+    output: number;
+    total: number;
+    cost?: number;
+    cacheRead?: number;
+    cacheWrite?: number;
+  };
+  runId?: string;
+}
+
+export interface WorkflowDisplay {
+  update(snapshot: WorkflowSnapshot): void;
+  complete(snapshot: WorkflowSnapshot): void;
+  clear(): void;
+}
+
+export interface WorkflowDisplayOptions {
+  key?: string;
+  placement?: "aboveEditor" | "belowEditor";
+  maxAgents?: number;
+  showStatus?: boolean;
+  showResultPreviews?: boolean;
+}
+
+/**
+ * Displayable fresh/cached figures from a usage breakdown and/or a scalar
+ * estimate. The token pipeline has two sources that don't always agree: the
+ * provider-reported breakdown (input/output/cacheRead/cacheWrite) and a scalar
+ * estimate (`total` at run level, `tokens` per agent) that keeps accruing even
+ * when the provider reports nothing. Two rules:
+ * - `fresh` counts input+output+cacheWrite: cache writes are first-time
+ *   ingestion billed at full (or premium) price, so hiding them would
+ *   under-report real spend; only cacheRead is the cheap reuse shown apart.
+ * - `fresh` is never less than what the estimate can account for after
+ *   removing cache reads, so estimate-only providers, cost-only providers
+ *   (billed but zero token counts), and mixed runs keep the count the display
+ *   showed before the split existed, instead of a false "0 tok".
+ */
+export function tokenFigures(
+  usage: Partial<AgentUsage> | undefined,
+  scalarTokens?: number,
+): { fresh: number; cacheRead: number } {
+  const cacheRead = usage?.cacheRead ?? 0;
+  const reported = (usage?.input ?? 0) + (usage?.output ?? 0) + (usage?.cacheWrite ?? 0);
+  const estimate = Math.max(scalarTokens ?? 0, usage?.total ?? 0);
+  return { fresh: Math.max(reported, estimate - cacheRead), cacheRead };
+}
+
+/** Sum a set of agents into fresh vs cacheRead totals, via {@link tokenFigures}. */
+export function aggregateAgentUsage(agents: ReadonlyArray<Pick<WorkflowAgentSnapshot, "tokens" | "tokenUsage">>): {
+  fresh: number;
+  cacheRead: number;
+} {
+  let fresh = 0;
+  let cacheRead = 0;
+  for (const a of agents) {
+    const f = tokenFigures(a.tokenUsage, a.tokens);
+    fresh += f.fresh;
+    cacheRead += f.cacheRead;
+  }
+  return { fresh, cacheRead };
+}
+
+/**
+ * Format a token count for a display surface: "12.4K tok" on its own, or
+ * "89K tok · 3.0M cached" when there were cache reads. The cache segment is shown
+ * only when `cacheRead > 0`, so a non-caching provider (or a single-turn agent that
+ * never re-reads its cache) reads as a plain "tok" rather than a bare, contextless
+ * "fresh". `fmt` adapts the number style per surface (compact in panels, full in
+ * the print view).
+ */
+export function fmtTokenCount(fresh: number, cacheRead: number, fmt: (n: number) => string): string {
+  const f = fmt(fresh) || "0";
+  return cacheRead > 0 ? `${f} tok · ${fmt(cacheRead)} cached` : `${f} tok`;
+}
+
+/**
+ * Like {@link fmtTokenCount}, but "" when nothing is known yet (both figures 0),
+ * so surfaces omit the segment instead of rendering a false "0 tok" — e.g. for a
+ * journal-replayed resume or a run whose agents were all skipped. Every surface
+ * should use this rather than re-implementing the zero guard.
+ */
+export function fmtTokenSegment(figures: { fresh: number; cacheRead: number }, fmt: (n: number) => string): string {
+  return figures.fresh + figures.cacheRead > 0 ? fmtTokenCount(figures.fresh, figures.cacheRead, fmt) : "";
+}
+
+/**
+ * "$1.23" from one cent up, four decimals below it, and "<$0.0001" for
+ * anything smaller — a real cost never rounds to a zero-looking "$0.00".
+ */
+export function fmtCost(cost: number): string {
+  if (cost > 0 && cost < 0.0001) return "<$0.0001";
+  return `$${cost.toFixed(cost >= 0.01 ? 2 : 4)}`;
+}
+
+/** Full (non-compact) number style for print/text surfaces: locale-grouped digits. */
+export const fmtFull = (n: number): string => n.toLocaleString();
+
+export function createWorkflowSnapshot(meta: WorkflowMeta): WorkflowSnapshot {
+  return {
+    name: meta.name,
+    description: meta.description,
+    phases: meta.phases?.map((phase) => phase.title) ?? [],
+    logs: [],
+    agents: [],
+    agentCount: 0,
+    runningCount: 0,
+    doneCount: 0,
+    errorCount: 0,
+  };
+}
+
+export function recomputeWorkflowSnapshot(snapshot: WorkflowSnapshot): WorkflowSnapshot {
+  const runningCount = snapshot.agents.filter((agent) => agent.status === "running").length;
+  const doneCount = snapshot.agents.filter((agent) => agent.status === "done").length;
+  const errorCount = snapshot.agents.filter((agent) => agent.status === "error").length;
+  return { ...snapshot, agentCount: snapshot.agents.length, runningCount, doneCount, errorCount };
+}
+
+export function createWidgetWorkflowDisplay(
+  ctx: Pick<ExtensionContext, "ui" | "hasUI">,
+  options: WorkflowDisplayOptions = {},
+): WorkflowDisplay {
+  const key = options.key ?? "workflow";
+  const placement = options.placement ?? "belowEditor";
+  const showStatus = options.showStatus ?? false;
+
+  // Mutable state captured by the component closure so re-renders
+  // always read the latest snapshot even though the factory ran once.
+  let snapshot: WorkflowSnapshot | undefined;
+  let completed = false;
+
+  // Store the factory so update()/complete() can re-register it to trigger re-render.
+  const widgetFactory = (_tui: unknown, theme: Theme) => ({
+    render: () => (snapshot ? renderWorkflowLines(snapshot, options, theme) : []),
+    invalidate: () => {},
+  });
+
+  if (ctx.hasUI) {
+    ctx.ui.setWidget(key, widgetFactory, { placement });
+  }
+
+  return {
+    update(s) {
+      snapshot = s;
+      if (!ctx.hasUI) return;
+      if (showStatus) ctx.ui.setStatus(key, statusLine(s, completed));
+      ctx.ui.setWidget(key, widgetFactory, { placement });
+    },
+    complete(s) {
+      snapshot = s;
+      completed = true;
+      if (!ctx.hasUI) return;
+      if (showStatus) ctx.ui.setStatus(key, statusLine(s, true));
+      ctx.ui.setWidget(key, widgetFactory, { placement });
+    },
+    clear() {
+      if (!ctx.hasUI) return;
+      if (showStatus) ctx.ui.setStatus(key, undefined);
+      ctx.ui.setWidget(key, undefined);
+    },
+  };
+}
+
+export function createToolUpdateWorkflowDisplay(
+  onUpdate: ((result: { content: Array<{ type: "text"; text: string }>; details: unknown }) => void) | undefined,
+  ctx?: Pick<ExtensionContext, "ui" | "hasUI">,
+  options: WorkflowDisplayOptions & { streamToolUpdates?: boolean } = {},
+): WorkflowDisplay {
+  const widget = ctx ? createWidgetWorkflowDisplay(ctx, options) : undefined;
+  const streamToolUpdates = options.streamToolUpdates ?? !ctx?.hasUI;
+
+  const emit = (snapshot: WorkflowSnapshot, completed = false) => {
+    if (streamToolUpdates) {
+      onUpdate?.({
+        content: [{ type: "text", text: renderWorkflowText(snapshot, completed) }],
+        details: snapshot,
+      });
+    }
+    if (completed) widget?.complete(snapshot);
+    else widget?.update(snapshot);
+  };
+
+  return {
+    update(snapshot) {
+      emit(snapshot, false);
+    },
+    complete(snapshot) {
+      emit(snapshot, true);
+    },
+    clear() {
+      widget?.clear();
+    },
+  };
+}
+
+/** Minimal theme surface so rendering works without a real Theme (tool output, tests). */
+export interface ThemeLike {
+  fg(color: string, text: string): string;
+  bold(text: string): string;
+}
+
+/** Identity passthrough for contexts where no theme is available (tool text output). */
+const NO_THEME: ThemeLike = { fg: (_c, t) => t, bold: (t) => t };
+
+/** The bracketed per-agent token cell (" [89 tok · 3,000 cached]"), or "" when nothing is known yet. */
+function agentTokenCell(agent: WorkflowAgentSnapshot, theme: ThemeLike): string {
+  const segment = fmtTokenSegment(tokenFigures(agent.tokenUsage, agent.tokens), fmtFull);
+  return segment ? theme.fg("dim", ` [${segment}]`) : "";
+}
+
+export function renderWorkflowLines(
+  snapshot: WorkflowSnapshot,
+  options: WorkflowDisplayOptions = {},
+  theme: ThemeLike = NO_THEME,
+): string[] {
+  const maxAgents = options.maxAgents ?? 8;
+  const showResultPreviews = options.showResultPreviews ?? false;
+  const state =
+    snapshot.errorCount > 0
+      ? `, ${snapshot.errorCount} errors`
+      : snapshot.runningCount > 0
+        ? `, ${snapshot.runningCount} running`
+        : "";
+  // Build header with token info (and cost when the provider reports it)
+  const usage = snapshot.tokenUsage;
+  const costInfo = usage?.cost ? ` · ${fmtCost(usage.cost)}` : "";
+  const segment = fmtTokenSegment(tokenFigures(usage), fmtFull);
+  const tokenInfo = `${segment ? ` · ${segment}` : ""}${costInfo}`;
+  const lines = [
+    `${theme.bold(`◆ Workflow: ${snapshot.name}`)} (${snapshot.doneCount}/${snapshot.agentCount} done${state}${tokenInfo})`,
+  ];
+
+  const phaseNames = snapshot.phases.length
+    ? snapshot.phases
+    : unique(snapshot.agents.map((agent) => agent.phase).filter(Boolean) as string[]);
+  const rendered = new Set<WorkflowAgentSnapshot>();
+
+  for (const phase of phaseNames) {
+    const agents = snapshot.agents.filter((agent) => agent.phase === phase);
+    for (const agent of agents) rendered.add(agent);
+    const done = agents.filter((agent) => agent.status === "done").length;
+    const running = agents.filter((agent) => agent.status === "running").length;
+    const errors = agents.filter((agent) => agent.status === "error").length;
+    const skipped = agents.filter((agent) => agent.status === "skipped").length;
+    const complete = agents.length > 0 && done + errors + skipped === agents.length;
+    const marker = running > 0 || (!complete && snapshot.currentPhase === phase) ? "▶" : complete ? "✓" : " ";
+    lines.push(
+      theme.fg("accent", `  ${marker} ${phase}`) +
+        theme.fg(
+          "dim",
+          ` ${done}/${agents.length}${running ? ` · ${running} running` : ""}${errors ? ` · ${errors} errors` : ""}${skipped ? ` · ${skipped} skipped` : ""}`,
+        ),
+    );
+
+    const visibleAgents = agents.slice(-maxAgents);
+    for (const agent of visibleAgents) {
+      const order = `[${agent.id}]`;
+      const result = showResultPreviews && agent.resultPreview ? ` — ${agent.resultPreview}` : "";
+      lines.push(
+        `    ${order} ${statusIcon(agent.status)} ${shorten(agent.label, 48)}${agentTokenCell(agent, theme)}${result}`,
+      );
+    }
+    if (agents.length > visibleAgents.length)
+      lines.push(theme.fg("dim", `    … ${agents.length - visibleAgents.length} earlier agents`));
+  }
+
+  const unphased = snapshot.agents.filter((agent) => !rendered.has(agent));
+  if (unphased.length) {
+    lines.push(theme.fg("accent", "  Unphased"));
+    for (const agent of unphased.slice(-maxAgents)) {
+      const result = showResultPreviews && agent.resultPreview ? ` — ${agent.resultPreview}` : "";
+      lines.push(
+        `    [${agent.id}] ${statusIcon(agent.status)} ${shorten(agent.label, 48)}${agentTokenCell(agent, theme)}${result}`,
+      );
+    }
+  }
+
+  return lines;
+}
+
+export function renderWorkflowText(snapshot: WorkflowSnapshot, completed = false): string {
+  const header = completed ? "Workflow completed" : "Workflow running";
+  return [header, ...renderWorkflowLines(snapshot)].join("\n");
+}
+
+function statusLine(snapshot: WorkflowSnapshot, completed: boolean): string {
+  if (completed) return `workflow ✓ ${snapshot.name}: ${snapshot.doneCount}/${snapshot.agentCount}`;
+  if (snapshot.runningCount > 0)
+    return `workflow ${snapshot.name}: ${snapshot.runningCount} running, ${snapshot.doneCount}/${snapshot.agentCount} done`;
+  return `workflow ${snapshot.name}: ${snapshot.doneCount}/${snapshot.agentCount} done`;
+}
+
+export function statusIcon(status: WorkflowAgentStatus): string {
+  switch (status) {
+    case "queued":
+      return "○";
+    case "running":
+      return "●";
+    case "done":
+      return "✓";
+    case "error":
+      return "✗";
+    case "skipped":
+      return "-";
+  }
+}
+
+function unique(values: string[]): string[] {
+  return [...new Set(values)];
+}
+
+export function shorten(value: string, max: number): string {
+  const text = value.replace(/\s+/g, " ").trim();
+  return text.length > max ? `${text.slice(0, max - 1)}…` : text;
+}
+
+export function preview(value: unknown, max = 80): string {
+  const text = typeof value === "string" ? value : JSON.stringify(value);
+  if (!text) return "";
+  return text.length > max ? `${text.slice(0, max - 1)}…` : text;
+}

package/src/effort-command.ts

@@ -0,0 +1,87 @@
+/**
+ * Standing `/effort` opt-in (pi's answer to CC's ultracode): a session toggle that
+ * auto-arms a workflow for substantive interactive messages, with effort-tier
+ * guidance nudging fan-out breadth and the hard caps (tokenBudget / maxAgents) the
+ * model should set on the workflow tool call.
+ *
+ * Honest scope: the runtime cannot enforce "reviewer N / loop K" — those live in
+ * the script the model writes — so the tiers are guidance plus the model setting
+ * the real hard caps (tokenBudget/maxAgents are genuine runtime ceilings). The
+ * pre-flight ceiling-confirm dialog (roadmap P1-5 #4) is a downscope point: an
+ * `input` hook transforms synchronously and can't await a confirm, so it is left
+ * to a follow-up; `/effort` is explicit opt-in, which is the safety valve.
+ */
+
+import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+
+export type EffortLevel = "off" | "high" | "ultra";
+
+export interface EffortState {
+  level: EffortLevel;
+}
+
+export function createEffortState(): EffortState {
+  return { level: "off" };
+}
+
+const HIGH_DIRECTIVE =
+  "Effort: HIGH. Be thorough — use a few parallel reviewers/perspectives and an adversarial verify pass (see verify()/judgePanel()); set a moderate tokenBudget and maxAgents on the workflow tool call.";
+const ULTRA_DIRECTIVE =
+  "Effort: ULTRA. Be exhaustive — fan out widely (more reviewers/judges, deeper loopUntilDry rounds, a completenessCheck at the end), and prefer the big tier for synthesis. This can spend a lot of tokens quickly, so set explicit caps you're comfortable paying for (a generous but bounded tokenBudget and a high maxAgents) on the workflow tool call rather than leaving them unbounded.";
+
+/** The extra directive appended to the forced-workflow prompt for an effort level. */
+export function effortDirective(level: EffortLevel): string | undefined {
+  if (level === "high") return HIGH_DIRECTIVE;
+  if (level === "ultra") return ULTRA_DIRECTIVE;
+  return undefined;
+}
+
+/**
+ * Whether a message should auto-arm under effort mode: a real interactive request,
+ * not a terse acknowledgement or a slash command. (hasTrigger handles the explicit
+ * "workflow(s)" keyword separately.)
+ */
+export function isSubstantive(text: string): boolean {
+  const t = text.trim();
+  return t.length >= 16 && !t.startsWith("/");
+}
+
+export function registerEffortCommand(pi: ExtensionAPI, state: EffortState): void {
+  pi.registerCommand("effort", {
+    description: "Standing workflow effort: off | high | ultra — auto-arms a workflow for substantive messages",
+    async handler(args: string, _ctx: ExtensionCommandContext) {
+      const arg = args.trim().toLowerCase();
+      const say = (content: string) => pi.sendMessage({ customType: "effort", content, display: true });
+      if (arg === "off" || arg === "high" || arg === "ultra") {
+        state.level = arg;
+        await say(
+          arg === "off"
+            ? "Effort off — messages are no longer auto-armed as workflows."
+            : `Effort ${arg} — substantive messages now auto-arm a workflow (${arg === "ultra" ? "exhaustive" : "thorough"} fan-out). Use /effort off to stop.`,
+        );
+        return;
+      }
+      await say(`Effort is currently "${state.level}". Usage: /effort off | high | ultra`);
+    },
+  });
+
+  // `/ultracode` — the headline name for the maximal-effort mode (Pi's ultracode):
+  // `/ultracode` turns it on, `/ultracode off` turns it off. Alias for /effort ultra.
+  pi.registerCommand("ultracode", {
+    description:
+      "Ultracode: standing maximal-effort mode (this session only, never persisted) — auto-arms an exhaustive workflow for substantive messages. /ultracode off to stop.",
+    async handler(args: string, _ctx: ExtensionCommandContext) {
+      const arg = args.trim().toLowerCase();
+      const say = (content: string) => pi.sendMessage({ customType: "effort", content, display: true });
+      if (arg === "off") {
+        state.level = "off";
+        await say("Ultracode off — messages are no longer auto-armed as workflows.");
+        return;
+      }
+      state.level = "ultra";
+      await say(
+        "Ultracode ON — substantive messages now auto-arm an exhaustive workflow (wide fan-out, big-tier synthesis). Use /ultracode off to stop.",
+      );
+    },
+  });
+}

package/src/enums.ts

@@ -0,0 +1,77 @@
+/** Classifies a workflow capability by its runtime and documentation role. */
+export enum CapabilityClassification {
+  RUNTIME_GLOBAL = "runtime-global",
+  WORKFLOW_TOOL_INPUT = "workflow-tool-input",
+  SCRIPT_CONTRACT = "script-contract",
+  COMPATIBILITY_BEHAVIOR = "compatibility-behavior",
+  INTERNAL_SUBSTRATE = "internal-substrate",
+  DYNAMIC_REFERENCE = "dynamic-reference",
+}
+
+/** Declares whether workflow authors should use a capability. */
+export enum CapabilitySupport {
+  SUPPORTED = "supported",
+  COMPATIBILITY = "compatibility",
+  INTERNAL = "internal",
+}
+
+/** Identifies the model-visible surface responsible for discovery. */
+export enum DiscoveryPlacement {
+  COMPACT_GUIDANCE = "compact-guidance",
+  WORKFLOW_AUTHORING_SKILL = "workflow-authoring-skill",
+  NONE = "none",
+}
+
+/** Names the subsystem that owns a capability's behavior. */
+export enum CapabilityOrigin {
+  PROJECT = "project",
+  TOOL_ADAPTER = "tool-adapter",
+  VM_REALM = "vm-realm",
+  LIVE_CONFIGURATION = "live-configuration",
+}
+
+/** Severity carried by capability-alignment diagnostics. */
+export enum DiagnosticSeverity {
+  ERROR = "error",
+  WARNING = "warning",
+  INFORMATION = "information",
+}
+
+/** Optional model-comprehension scenario groups. */
+export enum ComprehensionSuite {
+  QUICK = "quick",
+  FULL = "full",
+  COVERAGE = "coverage",
+}
+
+/** Authoring operation exercised by a comprehension scenario. */
+export enum ComprehensionTaskKind {
+  WRITE = "write",
+  EDIT = "edit",
+  REVIEW = "review",
+  DEBUG = "debug",
+}
+
+/** Whether authoring guidance may be optimized against behavioral evidence or must remain frozen. */
+export enum WorkflowAuthoringProtection {
+  BEHAVIORALLY_COVERED = "behaviorally-covered",
+  GUIDANCE_FROZEN = "guidance-frozen",
+}
+
+/** Machine-readable release-gate failure and warning domains. */
+export enum WorkflowReleaseDiagnosticCode {
+  INCOMPATIBLE_VERSION = "INCOMPATIBLE_VERSION",
+  MISSING_BEHAVIOR_EVIDENCE = "MISSING_BEHAVIOR_EVIDENCE",
+  UNRESOLVED_BEHAVIOR_EVIDENCE = "UNRESOLVED_BEHAVIOR_EVIDENCE",
+  BROKEN_CONTRACT_REFERENCE = "BROKEN_CONTRACT_REFERENCE",
+  MISSING_PACKAGE_RESOURCE = "MISSING_PACKAGE_RESOURCE",
+  BROKEN_PACKAGE_LINK = "BROKEN_PACKAGE_LINK",
+  STALE_GENERATED_SURFACE = "STALE_GENERATED_SURFACE",
+  TOOL_INPUT_MISMATCH = "TOOL_INPUT_MISMATCH",
+  RUNTIME_CONSTRAINT_DISAGREEMENT = "RUNTIME_CONSTRAINT_DISAGREEMENT",
+  NON_CONTRACTUAL_PROSE_DRIFT = "NON_CONTRACTUAL_PROSE_DRIFT",
+  MISSING_AUTHORING_COVERAGE = "MISSING_AUTHORING_COVERAGE",
+  UNPROTECTED_AUTHORING_GUIDANCE = "UNPROTECTED_AUTHORING_GUIDANCE",
+  PROTECTED_GUIDANCE_DRIFT = "PROTECTED_GUIDANCE_DRIFT",
+  UNKNOWN_COMPREHENSION_SCENARIO = "UNKNOWN_COMPREHENSION_SCENARIO",
+}