@yycholla/pi-dynamic-workflows 3.3.0

package/dist/workflow-context-measurement.d.ts

@@ -0,0 +1,72 @@
+/** Package-relative generated context-measurement artifact. */
+export declare const WORKFLOW_CONTEXT_MEASUREMENT_PATH = "docs/workflow-context-surfaces.json";
+/** Canonical task profiles used for stable byte-based on-demand context measurements. */
+export declare const WORKFLOW_AUTHORING_PROFILES: readonly [{
+    readonly name: "write";
+    readonly files: readonly ["skills/workflow-authoring/SKILL.md", "skills/workflow-authoring/references/runtime.md", "skills/workflow-authoring/references/pattern-selection.md", "skills/workflow-authoring/references/focused-recipes.md", "skills/workflow-authoring/examples/fan-out-and-synthesize.js", "skills/workflow-authoring/examples/structured-output.js"];
+}, {
+    readonly name: "edit";
+    readonly files: readonly ["skills/workflow-authoring/SKILL.md", "skills/workflow-authoring/references/runtime.md", "skills/workflow-authoring/references/lifecycle.md", "skills/workflow-authoring/references/focused-recipes.md", "skills/workflow-authoring/examples/phased-budgets.js", "skills/workflow-authoring/examples/saved-nested-workflows.js"];
+}, {
+    readonly name: "review";
+    readonly files: readonly ["skills/workflow-authoring/SKILL.md", "skills/workflow-authoring/references/runtime.md", "skills/workflow-authoring/references/review.md", "skills/workflow-authoring/references/quality-helpers.md", "skills/workflow-authoring/examples/adversarial-verification.js"];
+}, {
+    readonly name: "debug";
+    readonly files: readonly ["skills/workflow-authoring/SKILL.md", "skills/workflow-authoring/references/runtime.md", "skills/workflow-authoring/references/debugging.md", "skills/workflow-authoring/references/specialized-helpers.md", "skills/workflow-authoring/examples/validated-gate.js"];
+}, {
+    readonly name: "loop";
+    readonly files: readonly ["skills/workflow-authoring/SKILL.md", "skills/workflow-authoring/references/runtime.md", "skills/workflow-authoring/references/pattern-selection.md", "skills/workflow-authoring/references/lifecycle.md", "skills/workflow-authoring/references/focused-recipes.md", "skills/workflow-authoring/examples/loop-until-done.js", "skills/workflow-authoring/examples/structured-output.js"];
+}, {
+    readonly name: "retry";
+    readonly files: readonly ["skills/workflow-authoring/SKILL.md", "skills/workflow-authoring/references/runtime.md", "skills/workflow-authoring/references/retry-helper.md", "skills/workflow-authoring/references/focused-recipes.md", "skills/workflow-authoring/examples/bounded-semantic-retry.js", "skills/workflow-authoring/examples/structured-output.js"];
+}];
+interface ByteSurface {
+    serialization: string;
+    bytes: number;
+}
+/** One registered skill's always-on discovery-entry byte cost. */
+export interface SkillDiscoverySurface extends ByteSurface {
+    root: string;
+}
+/** Versioned byte measurements for always-on, discovery, corpus, and representative authoring surfaces. */
+export interface WorkflowContextMeasurement {
+    formatVersion: 3;
+    encoding: "utf8";
+    sources: ["src/workflow-tool.ts", "skills/workflow-authoring", "package.json#pi.skills"];
+    surfaces: {
+        permanentWorkflowPrompt: ByteSurface;
+        providerVisibleWorkflowToolDefinition: ByteSurface;
+        /**
+         * Every skill this package registers (package.json's `pi.skills` — read
+         * from disk, not hardcoded here) contributes an always-on discovery entry
+         * (name + description) the model sees regardless of whether the skill is
+         * ever loaded. This sums all of them, not just workflow-authoring, so a
+         * new skill's always-on cost can't silently go untracked.
+         */
+        registeredSkillsDiscovery: ByteSurface & {
+            skills: SkillDiscoverySurface[];
+        };
+        ordinaryWorkflowOwnedAlwaysOn: ByteSurface;
+        workflowAuthoringSkillCorpus: ByteSurface & {
+            files: number;
+        };
+        representativeAuthoringProfiles: {
+            serialization: "sum of UTF-8 bytes for each profile's declared package-relative files";
+            medianBytes: number;
+            profiles: Array<{
+                name: string;
+                files: string[];
+                bytes: number;
+            }>;
+        };
+    };
+}
+/** Measures permanent, discovery, corpus, and canonical on-demand workflow context surfaces. */
+export declare function measureWorkflowContextSurfaces(root?: string): WorkflowContextMeasurement;
+/** Render the current measurement as deterministic formatted JSON. */
+export declare function renderWorkflowContextMeasurement(): string;
+/** Write the generated measurement under root and return the measured values. */
+export declare function writeWorkflowContextMeasurement(root: string): WorkflowContextMeasurement;
+/** Report whether committed or supplied measurement JSON matches current package bytes. */
+export declare function checkWorkflowContextMeasurement(root: string, actual?: string): boolean;
+export {};

package/dist/workflow-context-measurement.js

@@ -0,0 +1,213 @@
+import { readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join, relative } from "node:path";
+import { createWorkflowTool } from "./workflow-tool.js";
+/** Package-relative generated context-measurement artifact. */
+export const WORKFLOW_CONTEXT_MEASUREMENT_PATH = "docs/workflow-context-surfaces.json";
+const ROOT = join(import.meta.dirname, "..");
+const SKILL_ROOT = "skills/workflow-authoring";
+const SKILL_PATH = `${SKILL_ROOT}/SKILL.md`;
+/** Canonical task profiles used for stable byte-based on-demand context measurements. */
+export const WORKFLOW_AUTHORING_PROFILES = [
+    {
+        name: "write",
+        files: [
+            SKILL_PATH,
+            `${SKILL_ROOT}/references/runtime.md`,
+            `${SKILL_ROOT}/references/pattern-selection.md`,
+            `${SKILL_ROOT}/references/focused-recipes.md`,
+            `${SKILL_ROOT}/examples/fan-out-and-synthesize.js`,
+            `${SKILL_ROOT}/examples/structured-output.js`,
+        ],
+    },
+    {
+        name: "edit",
+        files: [
+            SKILL_PATH,
+            `${SKILL_ROOT}/references/runtime.md`,
+            `${SKILL_ROOT}/references/lifecycle.md`,
+            `${SKILL_ROOT}/references/focused-recipes.md`,
+            `${SKILL_ROOT}/examples/phased-budgets.js`,
+            `${SKILL_ROOT}/examples/saved-nested-workflows.js`,
+        ],
+    },
+    {
+        name: "review",
+        files: [
+            SKILL_PATH,
+            `${SKILL_ROOT}/references/runtime.md`,
+            `${SKILL_ROOT}/references/review.md`,
+            `${SKILL_ROOT}/references/quality-helpers.md`,
+            `${SKILL_ROOT}/examples/adversarial-verification.js`,
+        ],
+    },
+    {
+        name: "debug",
+        files: [
+            SKILL_PATH,
+            `${SKILL_ROOT}/references/runtime.md`,
+            `${SKILL_ROOT}/references/debugging.md`,
+            `${SKILL_ROOT}/references/specialized-helpers.md`,
+            `${SKILL_ROOT}/examples/validated-gate.js`,
+        ],
+    },
+    {
+        name: "loop",
+        files: [
+            SKILL_PATH,
+            `${SKILL_ROOT}/references/runtime.md`,
+            `${SKILL_ROOT}/references/pattern-selection.md`,
+            `${SKILL_ROOT}/references/lifecycle.md`,
+            `${SKILL_ROOT}/references/focused-recipes.md`,
+            `${SKILL_ROOT}/examples/loop-until-done.js`,
+            `${SKILL_ROOT}/examples/structured-output.js`,
+        ],
+    },
+    {
+        name: "retry",
+        files: [
+            SKILL_PATH,
+            `${SKILL_ROOT}/references/runtime.md`,
+            `${SKILL_ROOT}/references/retry-helper.md`,
+            `${SKILL_ROOT}/references/focused-recipes.md`,
+            `${SKILL_ROOT}/examples/bounded-semantic-retry.js`,
+            `${SKILL_ROOT}/examples/structured-output.js`,
+        ],
+    },
+];
+function bytes(value) {
+    return Buffer.byteLength(value, "utf8");
+}
+function fileBytes(root, path) {
+    return bytes(readFileSync(join(root, path), "utf8"));
+}
+function skillFiles(root) {
+    const absoluteRoot = join(root, SKILL_ROOT);
+    const pending = [absoluteRoot];
+    const files = [];
+    while (pending.length > 0) {
+        const directory = pending.pop();
+        if (!directory)
+            continue;
+        for (const entry of readdirSync(directory, { withFileTypes: true })) {
+            const absolute = join(directory, entry.name);
+            if (entry.isDirectory())
+                pending.push(absolute);
+            else if (entry.isFile())
+                files.push(relative(root, absolute).replaceAll("\\", "/"));
+        }
+    }
+    return files.sort();
+}
+/**
+ * Every skill root this package registers, read from package.json's
+ * `pi.skills` array rather than hardcoded — so a newly added skill is picked
+ * up automatically instead of silently missing from the always-on tally.
+ */
+function registeredSkillRoots(root) {
+    const manifest = JSON.parse(readFileSync(join(root, "package.json"), "utf8"));
+    const skills = manifest.pi?.skills;
+    if (!Array.isArray(skills) || skills.length === 0 || !skills.every((s) => typeof s === "string")) {
+        throw new Error("package.json must declare a non-empty pi.skills array of skill root paths");
+    }
+    return skills;
+}
+function skillDiscoveryEntry(root, skillRoot) {
+    const skillPath = `${skillRoot}/SKILL.md`;
+    const skill = readFileSync(join(root, skillPath), "utf8");
+    const name = /^name:\s*(.+)$/m.exec(skill)?.[1]?.trim();
+    const description = /^description:\s*(.+)$/m.exec(skill)?.[1]?.trim();
+    if (!name || !description)
+        throw new Error(`${skillPath} must declare name and description`);
+    return [
+        "<skill>",
+        `  <name>${name}</name>`,
+        `  <description>${description}</description>`,
+        `  <location>${skillPath}</location>`,
+        "</skill>",
+    ].join("\n");
+}
+function median(values) {
+    const sorted = [...values].sort((left, right) => left - right);
+    const middle = sorted.length / 2;
+    return sorted.length % 2 === 0
+        ? ((sorted[middle - 1] ?? 0) + (sorted[middle] ?? 0)) / 2
+        : (sorted[Math.floor(middle)] ?? 0);
+}
+/** Measures permanent, discovery, corpus, and canonical on-demand workflow context surfaces. */
+export function measureWorkflowContextSurfaces(root = ROOT) {
+    const tool = createWorkflowTool();
+    const permanentWorkflowPrompt = [
+        `- workflow: ${tool.promptSnippet}`,
+        ...(tool.promptGuidelines ?? []).map((guideline) => `- ${guideline}`),
+    ].join("\n");
+    const providerVisibleWorkflowToolDefinition = JSON.stringify({
+        name: tool.name,
+        description: tool.description,
+        parameters: tool.parameters,
+    });
+    const skillRoots = registeredSkillRoots(root);
+    const skillDiscoverySurfaces = skillRoots.map((skillRoot) => ({
+        root: skillRoot,
+        serialization: "UTF-8 bytes of normalized Pi skill XML with package-relative location",
+        bytes: bytes(skillDiscoveryEntry(root, skillRoot)),
+    }));
+    const registeredSkillsDiscoveryBytes = skillDiscoverySurfaces.reduce((sum, surface) => sum + surface.bytes, 0);
+    const corpusFiles = skillFiles(root);
+    const corpusBytes = corpusFiles.reduce((sum, path) => sum + fileBytes(root, path), 0);
+    const profiles = WORKFLOW_AUTHORING_PROFILES.map((profile) => ({
+        name: profile.name,
+        files: [...profile.files],
+        bytes: profile.files.reduce((sum, path) => sum + fileBytes(root, path), 0),
+    }));
+    const promptBytes = bytes(permanentWorkflowPrompt);
+    const toolBytes = bytes(providerVisibleWorkflowToolDefinition);
+    return {
+        formatVersion: 3,
+        encoding: "utf8",
+        sources: ["src/workflow-tool.ts", "skills/workflow-authoring", "package.json#pi.skills"],
+        surfaces: {
+            permanentWorkflowPrompt: {
+                serialization: "UTF-8 bytes of LF-joined Pi prompt lines",
+                bytes: promptBytes,
+            },
+            providerVisibleWorkflowToolDefinition: {
+                serialization: "UTF-8 bytes of JSON.stringify({ name, description, parameters })",
+                bytes: toolBytes,
+            },
+            registeredSkillsDiscovery: {
+                serialization: "sum of UTF-8 bytes of normalized Pi skill XML (name + description + location) across every root in package.json's pi.skills",
+                bytes: registeredSkillsDiscoveryBytes,
+                skills: skillDiscoverySurfaces,
+            },
+            ordinaryWorkflowOwnedAlwaysOn: {
+                serialization: "sum of permanent prompt, provider-visible tool definition, and every registered skill's discovery bytes",
+                bytes: promptBytes + toolBytes + registeredSkillsDiscoveryBytes,
+            },
+            workflowAuthoringSkillCorpus: {
+                serialization: "sum of UTF-8 bytes for every file under skills/workflow-authoring",
+                files: corpusFiles.length,
+                bytes: corpusBytes,
+            },
+            representativeAuthoringProfiles: {
+                serialization: "sum of UTF-8 bytes for each profile's declared package-relative files",
+                medianBytes: median(profiles.map(({ bytes: profileBytes }) => profileBytes)),
+                profiles,
+            },
+        },
+    };
+}
+/** Render the current measurement as deterministic formatted JSON. */
+export function renderWorkflowContextMeasurement() {
+    return `${JSON.stringify(measureWorkflowContextSurfaces(), null, 2)}\n`;
+}
+/** Write the generated measurement under root and return the measured values. */
+export function writeWorkflowContextMeasurement(root) {
+    const measurement = measureWorkflowContextSurfaces(root);
+    writeFileSync(join(root, WORKFLOW_CONTEXT_MEASUREMENT_PATH), `${JSON.stringify(measurement, null, 2)}\n`);
+    return measurement;
+}
+/** Report whether committed or supplied measurement JSON matches current package bytes. */
+export function checkWorkflowContextMeasurement(root, actual) {
+    const committed = actual ?? readFileSync(join(root, WORKFLOW_CONTEXT_MEASUREMENT_PATH), "utf8");
+    return committed === `${JSON.stringify(measureWorkflowContextSurfaces(root), null, 2)}\n`;
+}

package/dist/workflow-control-tool.d.ts

@@ -0,0 +1,30 @@
+import { type ToolDefinition } from "@earendil-works/pi-coding-agent";
+import { type Static, Type } from "typebox";
+import type { RunStatus } from "./run-persistence.js";
+import type { WorkflowManager } from "./workflow-manager.js";
+declare const workflowControlSchema: Type.TObject<{
+    action: Type.TUnion<[Type.TLiteral<"list">, Type.TLiteral<"status">, Type.TLiteral<"pause">, Type.TLiteral<"resume">, Type.TLiteral<"stop">]>;
+    runId: Type.TOptional<Type.TString>;
+}>;
+export type WorkflowControlInput = Static<typeof workflowControlSchema>;
+export interface WorkflowControlToolOptions {
+    manager: WorkflowManager;
+}
+export interface WorkflowControlRunDetails {
+    runId: string;
+    workflowName: string;
+    status: RunStatus;
+    phase: string | null;
+    counts: {
+        total: number;
+        done: number;
+        running: number;
+        queued: number;
+        error: number;
+        skipped: number;
+    };
+    activeLabels: string[];
+    tokenTotal: number;
+}
+export declare function createWorkflowControlTool(options: WorkflowControlToolOptions): ToolDefinition<typeof workflowControlSchema, Record<string, unknown>>;
+export {};

package/dist/workflow-control-tool.js

@@ -0,0 +1,176 @@
+import { defineTool } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { aggregateAgentUsage, tokenFigures } from "./display.js";
+// A tool's top-level parameter schema must be a JSON Schema object (`type:
+// "object"`). A discriminated Type.Union of two objects serializes to a
+// top-level `anyOf` with no `type`, which strict providers (e.g. DeepSeek)
+// reject with "schema must be type object, got type: null". So the schema is a
+// single object: `action` is the full set of verbs and `runId` is optional at
+// the schema level. The per-action requirement (runId is mandatory for every
+// action except `list`, and `list` takes no runId) is enforced at runtime in
+// normalizeInput() and guarded again in execute().
+const workflowControlSchema = Type.Object({
+    action: Type.Union([
+        Type.Literal("list"),
+        Type.Literal("status"),
+        Type.Literal("pause"),
+        Type.Literal("resume"),
+        Type.Literal("stop"),
+    ], { description: "list = all runs (no runId); status/pause/resume/stop act on one run and require runId." }),
+    runId: Type.Optional(Type.String({
+        minLength: 1,
+        description: "Canonical workflow run ID. Required for status, pause, resume, and stop; omit for list.",
+    })),
+}, { additionalProperties: false });
+export function createWorkflowControlTool(options) {
+    const manager = options.manager;
+    return defineTool({
+        name: "workflow_control",
+        label: "Workflow Control",
+        description: "List and inspect workflow runs, or pause, resume, and stop them without asking the user to run slash commands.",
+        promptSnippet: "Inspect and manage workflow runs directly by canonical run ID.",
+        promptGuidelines: [
+            "Use workflow_control for workflow lifecycle management; do not ask the user to type /workflows when this tool can perform the action.",
+            "Use stop to terminate or quit a run. Closing the navigator does not stop a run.",
+        ],
+        parameters: workflowControlSchema,
+        prepareArguments: normalizeInput,
+        async execute(_toolCallId, params) {
+            if (params.action === "list") {
+                const runs = manager.listRuns();
+                const summaries = runs.map((run) => summarizeRun(run, manager.getSnapshot(run.runId)));
+                return result(summaries.length
+                    ? `action=list result=ok runs=${summaries.length}\n${summaries.map(formatRun).join("\n")}`
+                    : "action=list result=ok runs=0", { action: "list", result: "ok", runs: summaries });
+            }
+            // runId is optional in the schema (see workflowControlSchema) but required
+            // for every non-list action; normalizeInput already enforces this, and this
+            // guard both narrows the type and returns a structured error if a model
+            // somehow calls a run action without one.
+            if (!params.runId)
+                return controlError(params.action, "", "runId is required for this action", ["list"]);
+            const run = findRun(manager, params.runId);
+            if (!run)
+                return controlError(params.action, params.runId, "run not found", ["list"]);
+            try {
+                switch (params.action) {
+                    case "status": {
+                        const summary = summarizeRun(run, manager.getSnapshot(run.runId));
+                        return result(`action=status result=ok ${formatRun(summary)}`, {
+                            action: "status",
+                            result: "ok",
+                            run: summary,
+                        });
+                    }
+                    case "pause":
+                        if (!manager.pause(run.runId))
+                            return invalidTransition("pause", run);
+                        return actionSuccess("pause", "paused", currentSummary(manager, run));
+                    case "resume":
+                        if (!(await manager.resume(run.runId)))
+                            return invalidTransition("resume", run);
+                        return actionSuccess("resume", "resumed", currentSummary(manager, run));
+                    case "stop":
+                        if (!manager.stop(run.runId))
+                            return invalidTransition("stop", run);
+                        return actionSuccess("stop", "stopped", currentSummary(manager, run));
+                }
+            }
+            catch (err) {
+                // A transient persistence I/O error (or any unexpected throw from the
+                // manager) shouldn't surface as a raw stack trace to the model — report
+                // it via the tool's normal structured error shape instead.
+                const message = err instanceof Error ? err.message : String(err);
+                return controlError(params.action, run.runId, message, allowedActions(run.status));
+            }
+        },
+    });
+}
+function normalizeInput(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error("workflow_control requires an object argument");
+    }
+    const input = value;
+    const actions = new Set(["list", "status", "pause", "resume", "stop"]);
+    if (typeof input.action !== "string" || !actions.has(input.action)) {
+        throw new Error("workflow_control requires action: list|status|pause|resume|stop");
+    }
+    const allowedKeys = input.action === "list" ? new Set(["action"]) : new Set(["action", "runId"]);
+    const extraKey = Object.keys(input).find((key) => !allowedKeys.has(key));
+    if (extraKey)
+        throw new Error(`workflow_control action "${input.action}" does not accept ${extraKey}`);
+    if (input.action !== "list" && (typeof input.runId !== "string" || !input.runId.trim())) {
+        throw new Error(`workflow_control action "${input.action}" requires runId`);
+    }
+    return input;
+}
+function result(text, details) {
+    return { content: [{ type: "text", text }], details };
+}
+function findRun(manager, runId) {
+    return manager.listRuns().find((candidate) => candidate.runId === runId);
+}
+function currentSummary(manager, fallback) {
+    const current = findRun(manager, fallback.runId) ?? fallback;
+    return summarizeRun(current, manager.getSnapshot(current.runId));
+}
+function actionSuccess(action, actionResult, run) {
+    return result(`action=${action} result=${actionResult} ${formatRun(run)}`, {
+        action,
+        result: actionResult,
+        run,
+    });
+}
+function invalidTransition(action, run) {
+    return controlError(action, run.runId, `cannot ${action} run with status ${run.status}`, allowedActions(run.status));
+}
+function controlError(action, runId, message, allowed) {
+    return result(`action=${action} result=error runId=${runId} error=${message} allowed=${allowed.join(",") || "none"}`, { action, result: "error", runId, error: message, allowedActions: allowed });
+}
+function allowedActions(status) {
+    switch (status) {
+        case "running":
+            return ["status", "pause", "stop"];
+        case "paused":
+            return ["status", "resume", "stop"];
+        case "failed":
+        case "pending":
+            return ["status", "resume"];
+        case "completed":
+        case "aborted":
+            return ["status"];
+    }
+}
+function summarizeRun(run, live) {
+    const agents = live?.agents ?? run.agents;
+    const counts = countAgents(agents);
+    const liveUsage = tokenFigures(live?.tokenUsage);
+    const persistedUsage = tokenFigures(run.tokenUsage);
+    const agentUsage = aggregateAgentUsage(agents);
+    return {
+        runId: run.runId,
+        workflowName: live?.name ?? run.workflowName,
+        status: run.status,
+        phase: live?.currentPhase ?? run.currentPhase ?? null,
+        counts,
+        activeLabels: agents.filter((agent) => agent.status === "running").map((agent) => agent.label),
+        tokenTotal: Math.max(liveUsage.fresh + liveUsage.cacheRead, persistedUsage.fresh + persistedUsage.cacheRead, agentUsage.fresh + agentUsage.cacheRead),
+    };
+}
+function countAgents(agents) {
+    return {
+        total: agents.length,
+        done: agents.filter((agent) => agent.status === "done").length,
+        running: agents.filter((agent) => agent.status === "running").length,
+        queued: agents.filter((agent) => agent.status === "queued").length,
+        error: agents.filter((agent) => agent.status === "error").length,
+        skipped: agents.filter((agent) => agent.status === "skipped").length,
+    };
+}
+function formatRun(run) {
+    const active = run.activeLabels.join(",") || "-";
+    return `runId=${run.runId} name=${quote(run.workflowName)} status=${run.status} phase=${quote(run.phase ?? "-")} total=${run.counts.total} done=${run.counts.done} running=${run.counts.running} queued=${run.counts.queued} error=${run.counts.error} skipped=${run.counts.skipped} active=${quote(active)} tokens=${run.tokenTotal}`;
+}
+function quote(value) {
+    return JSON.stringify(value);
+}

package/dist/workflow-delivery-choice.d.ts

@@ -0,0 +1,20 @@
+/** One model-facing timing decision for invoking the workflow tool. */
+export interface WorkflowDeliveryChoiceScenario {
+    id: string;
+    prompt: string;
+    expectedBackground: boolean;
+}
+/** Pure scoring result for one captured workflow tool invocation. */
+export interface WorkflowDeliveryChoiceEvaluation {
+    passed: boolean;
+    resolvedBackground: boolean | null;
+    assertions: Array<{
+        name: string;
+        passed: boolean;
+        details: string;
+    }>;
+}
+/** Focused #89 scenarios for default background delivery versus same-turn use. */
+export declare const WORKFLOW_DELIVERY_CHOICE_SCENARIOS: readonly WorkflowDeliveryChoiceScenario[];
+/** Score captured workflow arguments without executing the submitted workflow. */
+export declare function evaluateWorkflowDeliveryChoice(scenario: WorkflowDeliveryChoiceScenario, value: unknown): WorkflowDeliveryChoiceEvaluation;

package/dist/workflow-delivery-choice.js

@@ -0,0 +1,48 @@
+/** Focused #89 scenarios for default background delivery versus same-turn use. */
+export const WORKFLOW_DELIVERY_CHOICE_SCENARIOS = [
+    {
+        id: "background-delivery",
+        prompt: "Run a workflow to audit the repository from several independent angles. I do not need the result in this turn; let it be delivered back later so I can keep working.",
+        expectedBackground: true,
+    },
+    {
+        id: "inline-result",
+        prompt: "Run a workflow to compare the two proposed designs, then use its result in your answer in this same turn. I am waiting for the result before you respond.",
+        expectedBackground: false,
+    },
+];
+/** Score captured workflow arguments without executing the submitted workflow. */
+export function evaluateWorkflowDeliveryChoice(scenario, value) {
+    const input = isRecord(value) ? value : null;
+    const hasScript = typeof input?.script === "string" && input.script.trim().length > 0;
+    const validBackground = input !== null && (input.background === undefined || typeof input.background === "boolean");
+    const resolvedBackground = validBackground ? (typeof input.background === "boolean" ? input.background : true) : null;
+    const timingMatches = resolvedBackground === scenario.expectedBackground;
+    const assertions = [
+        {
+            name: "workflow:called-with-script",
+            passed: hasScript,
+            details: "the model must invoke the real workflow tool shape with a nonblank script",
+        },
+        {
+            name: "background:valid-type",
+            passed: validBackground,
+            details: "background must be omitted for its true default or supplied as a boolean",
+        },
+        {
+            name: "background:matches-user-timing",
+            passed: timingMatches,
+            details: scenario.expectedBackground
+                ? "later delivery should use the default background run"
+                : "same-turn use should pass background: false",
+        },
+    ];
+    return {
+        passed: assertions.every(({ passed }) => passed),
+        resolvedBackground,
+        assertions,
+    };
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/dist/workflow-editor.d.ts

@@ -0,0 +1,93 @@
+/**
+ * "Workflows mode" keyword trigger: while the submitted message contains the
+ * bounded word `workflow`/`workflows` (or a configured custom trigger word),
+ * the message is transformed at submit time to instruct Pi to actually run the
+ * workflow tool. Detection is purely textual (`event.text` on the `input`
+ * hook) — it does not depend on, or own, the host's editor component.
+ */
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { type EffortState } from "./effort-command.js";
+import { type WorkflowSettingsStore } from "./workflow-settings.js";
+export declare function hasTrigger(text: string, triggerWord?: string): boolean;
+export declare function endsWithTrigger(textBeforeCursor: string, triggerWord?: string): boolean;
+/** Shared, mutable view of whether "workflows mode" is currently armed. */
+export interface WorkflowModeState {
+    active: boolean;
+    keywordTriggerEnabled: boolean;
+    keywordTriggerWord?: string;
+    suppressedKeywordText?: string;
+}
+export interface InstallWorkflowKeywordArmingOptions {
+    settingsStore?: WorkflowSettingsStore;
+}
+/**
+ * Why a turn was armed. This is stated truthfully in the banner so the model
+ * isn't told "the trigger word you typed" on a path where no word was typed:
+ *  - "keyword": the user typed the configured workflow trigger word.
+ *  - "effort": standing `/effort` armed this turn (no workflow word was typed).
+ */
+export type ArmReason = "keyword" | "effort";
+/**
+ * Appended to the effort-path directive: standing `/effort` arms on every
+ * substantive message, so the model must be told it can decline the workflow on
+ * a conversational or trivial turn (mirrors "solo only on conversational turns").
+ */
+export declare const EFFORT_CONVERSATIONAL_ESCAPE = "This turn was armed by standing effort mode, not by an explicit workflow request: if it is conversational or trivial, skip the workflow and just respond directly.";
+/**
+ * The directive appended to a submitted message when workflows mode is ARMED by a
+ * HEURISTIC path — the keyword trigger or standing `/effort`. (The explicit
+ * `/workflows run` command uses {@link buildForcedWorkflowPrompt} instead.)
+ *
+ * This authorizes — it does not force. Arming is a confirmed opt-in signal that
+ * lifts the always-on "do not call the tool" gate for THIS message; the model
+ * still decides whether the message is actually a request to do work (→ call the
+ * `workflow` tool) or just talk about workflows (→ answer directly). The old
+ * "You MUST / the ONLY acceptable action / Do NOT answer directly" forcing text
+ * caused two bugs: it over-triggered on messages that merely mention workflows
+ * (#88), and — by commanding the model to emit nothing but one `workflow` call
+ * and not talk — it produced a bare background run that ends the turn and leaves
+ * the user at an idle prompt (#89).
+ *
+ * The banner therefore (1) LEADS with the decision boundary (question/trivial →
+ * answer directly; a real decomposable request → call `workflow`) rather than
+ * leading with "call the tool"; (2) states the truthful opt-in `reason` for THIS
+ * path (no "the word you typed" on the effort path, where none was); and (3)
+ * carries the #89 background/deliver-back reassurance so an ending turn reads as
+ * expected. The how-to mechanics are NOT here — they live in the tool's static
+ * `description` (see createWorkflowTool), visible whenever the model looks at the
+ * tool, so they aren't re-injected per armed turn (#65).
+ *
+ * `extraDirective` (e.g. an effort-tier nudge + EFFORT_CONVERSATIONAL_ESCAPE) is
+ * appended when present.
+ */
+export declare function buildArmedWorkflowPrompt(text: string, opts?: {
+    reason?: ArmReason;
+    extraDirective?: string;
+}): string;
+/**
+ * The directive for the explicit `/workflows run <prompt>` command. Unlike the
+ * heuristic {@link buildArmedWorkflowPrompt}, `/workflows run` is a maximal-intent
+ * command — the user typed a command whose whole purpose is to execute a workflow
+ * now — so it does NOT get the "if it's a question, just answer" escape. It still
+ * avoids the old MUST/ONLY forcing language (which caused #88/#89) and still
+ * carries the #89 background/deliver-back reassurance so an ending turn reads as
+ * expected. `extraDirective` (e.g. a standing effort-tier nudge) is appended.
+ */
+export declare function buildForcedWorkflowPrompt(text: string, extraDirective?: string): string;
+/** The exact name of the workflow tool that workflows mode forces. */
+export declare const WORKFLOW_TOOL_NAME = "workflow";
+export declare function registerWorkflowTriggerCommand(pi: ExtensionAPI, state: WorkflowModeState, settingsStore?: WorkflowSettingsStore): void;
+/**
+ * Register the bottom progress-panel preference command:
+ *  - `/workflows-progress compact|detailed|status` — switch (or report) the panel mode.
+ *  - `/workflows-progress max <1-1000>` — cap agents shown per phase in detailed mode.
+ * Both persist via `settingsStore` and take effect on the next live run (the panel
+ * live-reads its settings), so no session restart is needed.
+ */
+export declare function registerWorkflowProgressCommands(pi: ExtensionAPI, settingsStore?: WorkflowSettingsStore): void;
+/**
+ * Install the keyword-trigger arming hook (submit-time detection + prompt
+ * rewrite) and the related trigger/progress commands. Call once (e.g. in
+ * `session_start`).
+ */
+export declare function installWorkflowKeywordArming(pi: ExtensionAPI, effort?: EffortState, options?: InstallWorkflowKeywordArmingOptions): WorkflowModeState;