@yycholla/pi-dynamic-workflows 3.3.0

package/dist/config.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Configuration constants for pi-dynamic-workflows.
+ */
+/** Maximum number of agents allowed per workflow run. */
+export declare const MAX_AGENTS_PER_RUN = 1000;
+/** Default timeout for a single agent in milliseconds. null means no hard timeout. */
+export declare const DEFAULT_AGENT_TIMEOUT_MS: null;
+/** Maximum concurrent agents (matches Claude Code limit). */
+export declare const MAX_CONCURRENCY = 16;
+/** Maximum automatic retry attempts after a recoverable agent failure. */
+export declare const MAX_AGENT_RETRIES = 3;
+/** Default token budget if none specified. */
+export declare const DEFAULT_TOKEN_BUDGET: null;
+/** Legacy project-relative directory for persisted workflow run state. New writes use workflowProjectPaths(). */
+export declare const WORKFLOW_RUNS_DIR = ".pi/workflows/runs";
+/** Legacy project-relative directory for saved workflow commands. New writes use workflowProjectPaths(). */
+export declare const WORKFLOW_SAVED_DIR = ".pi/workflows/saved";
+/** User-level saved workflows directory. */
+export declare const USER_WORKFLOW_SAVED_DIR = "~/.pi/workflows/saved";
+/** User-level model tiers config file, relative to the home directory. */
+export declare const MODEL_TIERS_FILE = ".pi/workflows/model-tiers.json";
+/** User-level workflow extension settings file, relative to the home directory. */
+export declare const WORKFLOW_SETTINGS_FILE = ".pi/workflows/settings.json";
+/** Default keyword that arms workflows mode from interactive input. */
+export declare const DEFAULT_KEYWORD_TRIGGER_WORD = "workflow";
+/** Normalize a user-configured keyword trigger word. */
+export declare function normalizeKeywordTriggerWord(value: unknown): string | undefined;
+/**
+ * Named workflow subagent definitions directory. Resolved project-relative
+ * (cwd/.pi/agents), plus user-level at `~/.pi/agent/agents/` (the primary
+ * location, via `getAgentDir()` in agent-registry.ts) with the legacy
+ * `~/.pi/agents/` (this constant, home-relative) scanned as a deprecated
+ * fallback. Project entries win on name collision, then the primary user
+ * location, then the legacy one. Each `*.md` file is an agent definition
+ * (frontmatter + body prompt).
+ */
+export declare const AGENTS_DIR = ".pi/agents";

package/dist/config.js

@@ -0,0 +1,44 @@
+/**
+ * Configuration constants for pi-dynamic-workflows.
+ */
+/** Maximum number of agents allowed per workflow run. */
+export const MAX_AGENTS_PER_RUN = 1000;
+/** Default timeout for a single agent in milliseconds. null means no hard timeout. */
+export const DEFAULT_AGENT_TIMEOUT_MS = null;
+/** Maximum concurrent agents (matches Claude Code limit). */
+export const MAX_CONCURRENCY = 16;
+/** Maximum automatic retry attempts after a recoverable agent failure. */
+export const MAX_AGENT_RETRIES = 3;
+/** Default token budget if none specified. */
+export const DEFAULT_TOKEN_BUDGET = null;
+/** Legacy project-relative directory for persisted workflow run state. New writes use workflowProjectPaths(). */
+export const WORKFLOW_RUNS_DIR = ".pi/workflows/runs";
+/** Legacy project-relative directory for saved workflow commands. New writes use workflowProjectPaths(). */
+export const WORKFLOW_SAVED_DIR = ".pi/workflows/saved";
+/** User-level saved workflows directory. */
+export const USER_WORKFLOW_SAVED_DIR = "~/.pi/workflows/saved";
+/** User-level model tiers config file, relative to the home directory. */
+export const MODEL_TIERS_FILE = ".pi/workflows/model-tiers.json";
+/** User-level workflow extension settings file, relative to the home directory. */
+export const WORKFLOW_SETTINGS_FILE = ".pi/workflows/settings.json";
+/** Default keyword that arms workflows mode from interactive input. */
+export const DEFAULT_KEYWORD_TRIGGER_WORD = "workflow";
+/** Normalize a user-configured keyword trigger word. */
+export function normalizeKeywordTriggerWord(value) {
+    if (typeof value !== "string")
+        return undefined;
+    const word = value.trim();
+    if (!word || word.startsWith("/") || /\s/.test(word))
+        return undefined;
+    return word;
+}
+/**
+ * Named workflow subagent definitions directory. Resolved project-relative
+ * (cwd/.pi/agents), plus user-level at `~/.pi/agent/agents/` (the primary
+ * location, via `getAgentDir()` in agent-registry.ts) with the legacy
+ * `~/.pi/agents/` (this constant, home-relative) scanned as a deprecated
+ * fallback. Project entries win on name collision, then the primary user
+ * location, then the legacy one. Each `*.md` file is an agent definition
+ * (frontmatter + body prompt).
+ */
+export const AGENTS_DIR = ".pi/agents";

package/dist/deep-research.d.ts

@@ -0,0 +1,30 @@
+/**
+ * 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 declare function generateDeepResearchWorkflow(): string;
+/**
+ * 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 declare function generateCodebaseAuditWorkflow(scope: string, checks: string[]): string;

package/dist/deep-research.js

@@ -0,0 +1,124 @@
+/**
+ * Deep research workflow.
+ * Built-in workflow for comprehensive research across multiple sources.
+ */
+/**
+ * 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() {
+    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, checks) {
+    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/dist/display.d.ts

@@ -0,0 +1,134 @@
+import type { ExtensionContext } 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 declare function tokenFigures(usage: Partial<AgentUsage> | undefined, scalarTokens?: number): {
+    fresh: number;
+    cacheRead: number;
+};
+/** Sum a set of agents into fresh vs cacheRead totals, via {@link tokenFigures}. */
+export declare function aggregateAgentUsage(agents: ReadonlyArray<Pick<WorkflowAgentSnapshot, "tokens" | "tokenUsage">>): {
+    fresh: number;
+    cacheRead: number;
+};
+/**
+ * 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 declare function fmtTokenCount(fresh: number, cacheRead: number, fmt: (n: number) => string): string;
+/**
+ * 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 declare function fmtTokenSegment(figures: {
+    fresh: number;
+    cacheRead: number;
+}, fmt: (n: number) => string): string;
+/**
+ * "$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 declare function fmtCost(cost: number): string;
+/** Full (non-compact) number style for print/text surfaces: locale-grouped digits. */
+export declare const fmtFull: (n: number) => string;
+export declare function createWorkflowSnapshot(meta: WorkflowMeta): WorkflowSnapshot;
+export declare function recomputeWorkflowSnapshot(snapshot: WorkflowSnapshot): WorkflowSnapshot;
+export declare function createWidgetWorkflowDisplay(ctx: Pick<ExtensionContext, "ui" | "hasUI">, options?: WorkflowDisplayOptions): WorkflowDisplay;
+export declare function createToolUpdateWorkflowDisplay(onUpdate: ((result: {
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    details: unknown;
+}) => void) | undefined, ctx?: Pick<ExtensionContext, "ui" | "hasUI">, options?: WorkflowDisplayOptions & {
+    streamToolUpdates?: boolean;
+}): WorkflowDisplay;
+/** 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;
+}
+export declare function renderWorkflowLines(snapshot: WorkflowSnapshot, options?: WorkflowDisplayOptions, theme?: ThemeLike): string[];
+export declare function renderWorkflowText(snapshot: WorkflowSnapshot, completed?: boolean): string;
+export declare function statusIcon(status: WorkflowAgentStatus): string;
+export declare function shorten(value: string, max: number): string;
+export declare function preview(value: unknown, max?: number): string;

package/dist/display.js

@@ -0,0 +1,248 @@
+/**
+ * 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, scalarTokens) {
+    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) {
+    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, cacheRead, fmt) {
+    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, fmt) {
+    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) {
+    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) => n.toLocaleString();
+export function createWorkflowSnapshot(meta) {
+    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) {
+    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, options = {}) {
+    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;
+    let completed = false;
+    // Store the factory so update()/complete() can re-register it to trigger re-render.
+    const widgetFactory = (_tui, 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, ctx, options = {}) {
+    const widget = ctx ? createWidgetWorkflowDisplay(ctx, options) : undefined;
+    const streamToolUpdates = options.streamToolUpdates ?? !ctx?.hasUI;
+    const emit = (snapshot, 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();
+        },
+    };
+}
+/** Identity passthrough for contexts where no theme is available (tool text output). */
+const NO_THEME = { 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, theme) {
+    const segment = fmtTokenSegment(tokenFigures(agent.tokenUsage, agent.tokens), fmtFull);
+    return segment ? theme.fg("dim", ` [${segment}]`) : "";
+}
+export function renderWorkflowLines(snapshot, options = {}, theme = NO_THEME) {
+    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));
+    const rendered = new Set();
+    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, completed = false) {
+    const header = completed ? "Workflow completed" : "Workflow running";
+    return [header, ...renderWorkflowLines(snapshot)].join("\n");
+}
+function statusLine(snapshot, completed) {
+    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) {
+    switch (status) {
+        case "queued":
+            return "○";
+        case "running":
+            return "●";
+        case "done":
+            return "✓";
+        case "error":
+            return "✗";
+        case "skipped":
+            return "-";
+    }
+}
+function unique(values) {
+    return [...new Set(values)];
+}
+export function shorten(value, max) {
+    const text = value.replace(/\s+/g, " ").trim();
+    return text.length > max ? `${text.slice(0, max - 1)}…` : text;
+}
+export function preview(value, max = 80) {
+    const text = typeof value === "string" ? value : JSON.stringify(value);
+    if (!text)
+        return "";
+    return text.length > max ? `${text.slice(0, max - 1)}…` : text;
+}

package/dist/effort-command.d.ts

@@ -0,0 +1,28 @@
+/**
+ * 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 } from "@earendil-works/pi-coding-agent";
+export type EffortLevel = "off" | "high" | "ultra";
+export interface EffortState {
+    level: EffortLevel;
+}
+export declare function createEffortState(): EffortState;
+/** The extra directive appended to the forced-workflow prompt for an effort level. */
+export declare function effortDirective(level: EffortLevel): string | 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 declare function isSubstantive(text: string): boolean;
+export declare function registerEffortCommand(pi: ExtensionAPI, state: EffortState): void;