pi-feats 0.1.4 → 0.1.7

package/extensions/lib/workflow-harness.ts

@@ -1,6 +1,11 @@
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { DatabaseSync } from "node:sqlite";
 import { AsyncLocalStorage } from "node:async_hooks";
+import { readFile, readdir } from "node:fs/promises";
+import { homedir } from "node:os";
+import { basename, join, resolve } from "node:path";
+import { evaluateWorkflowRequirement, evaluateWorkflowTask, workflowEvaluationConfig, type RequirementDecision } from "./workflow-evaluator.ts";
+import { Box, Text } from "@earendil-works/pi-tui";
 /** Session ownership and execution gates. Prompts explain state; these gates enforce it. */
 export function workflowHarness(host: ExtensionAPI, db: DatabaseSync) {
     db.exec("PRAGMA busy_timeout = 5000");
@@ -9,7 +14,21 @@ export function workflowHarness(host: ExtensionAPI, db: DatabaseSync) {
     }
     db.exec(`CREATE INDEX IF NOT EXISTS workflow_session_idx ON workflows(session_id);
     CREATE TABLE IF NOT EXISTS workflow_focus (session_id TEXT PRIMARY KEY, stack TEXT NOT NULL);
-    CREATE TABLE IF NOT EXISTS workflow_collect_checkpoint (task_id INTEGER PRIMARY KEY REFERENCES workflow_tasks(id), user_entry_id TEXT);`);
+    CREATE TABLE IF NOT EXISTS workflow_collect_checkpoint (task_id INTEGER PRIMARY KEY REFERENCES workflow_tasks(id), user_entry_id TEXT);
+    CREATE TABLE IF NOT EXISTS workflow_harness_events (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      session_id TEXT NOT NULL,
+      workflow_id INTEGER REFERENCES workflows(id),
+      phase TEXT NOT NULL,
+      origin TEXT,
+      payload TEXT NOT NULL,
+      created_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP
+    );
+    CREATE TABLE IF NOT EXISTS workflow_requirement_blocks (
+      session_id TEXT PRIMARY KEY,
+      reason TEXT NOT NULL,
+      created_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP
+    );`);
     const context = new AsyncLocalStorage<ExtensionContext>();
     const session = () => {
         const id = context.getStore()?.sessionManager.getSessionId();
@@ -19,7 +38,7 @@ export function workflowHarness(host: ExtensionAPI, db: DatabaseSync) {
     };
     const row = (id: number) => db.prepare("SELECT * FROM workflows WHERE id = ?").get(id) as any;
     const task = (id: number) => db.prepare("SELECT * FROM workflow_tasks WHERE workflow_id = ? AND status NOT IN ('accepted', 'failed') ORDER BY position LIMIT 1").get(id) as any;
-    const active = (w: any) => w && ["running", "awaiting_user", "evaluating"].includes(w.status);
+    const active = (w: any) => w && ["pending_definition", "running", "awaiting_user", "evaluating"].includes(w.status);
     const save = (stack: number[]) => db.prepare("INSERT INTO workflow_focus VALUES (?, ?) ON CONFLICT(session_id) DO UPDATE SET stack=excluded.stack").run(session(), JSON.stringify(stack));
     const stack = (): number[] => {
         const saved = db.prepare("SELECT stack FROM workflow_focus WHERE session_id = ?").get(session()) as any;
@@ -29,6 +48,14 @@ export function workflowHarness(host: ExtensionAPI, db: DatabaseSync) {
         });
     };
     const focus = () => stack().at(-1);
+    const requirementBlock = () => db.prepare("SELECT reason FROM workflow_requirement_blocks WHERE session_id = ?").get(session()) as { reason: string } | undefined;
+    const clearRequirementBlock = () => db.prepare("DELETE FROM workflow_requirement_blocks WHERE session_id = ?").run(session());
+    const blockRequirement = (reason: string) => db.prepare("INSERT INTO workflow_requirement_blocks(session_id, reason) VALUES (?, ?) ON CONFLICT(session_id) DO UPDATE SET reason = excluded.reason, created_at = CURRENT_TIMESTAMP").run(session(), reason);
+    const pendingWorkflow = () => {
+        const id = focus();
+        const item = id ? row(id) : undefined;
+        return item?.status === "pending_definition" ? id : undefined;
+    };
     const own = (id: number) => {
         const w = row(id);
         if (!w || w.session_id !== session())
@@ -36,6 +63,87 @@ export function workflowHarness(host: ExtensionAPI, db: DatabaseSync) {
         return w;
     };
     const userEntry = () => context.getStore()!.sessionManager.getBranch().filter((e: any) => e.type === "message" && e.message.role === "user").at(-1)?.id ?? null;
+    const addEvent = (workflowId: number, phase: string, payload: unknown) => db.prepare("INSERT INTO workflow_events(workflow_id, phase, payload) VALUES (?, ?, ?) ").run(workflowId, phase, JSON.stringify(payload));
+    const audit = (phase: string, payload: unknown, origin?: "user_input" | "skill", workflowId?: number, display = false) => {
+        db.prepare("INSERT INTO workflow_harness_events(session_id, workflow_id, phase, origin, payload) VALUES (?, ?, ?, ?, ?)").run(session(), workflowId ?? null, phase, origin ?? null, JSON.stringify(payload));
+        if (workflowId)
+            addEvent(workflowId, `harness_${phase}`, payload);
+        if (display)
+            host.sendMessage({ customType: "sequential-workflow-harness", display: true, content: (payload as any).message ?? phase, details: { phase, origin, workflowId, ...(payload as any) } });
+    };
+    const blockEvaluation = (reason: string, payload: Record<string, unknown> = {}, origin?: "user_input" | "skill", workflowId?: number) => {
+        blockRequirement(reason);
+        audit("evaluation_blocked", { ...payload, reason, message: "Sequential Workflow decision is unresolved; work remains blocked." }, origin, workflowId, true);
+    };
+    type DefinitionActivation = "definition" | "template";
+    const definitionTools = (activation: DefinitionActivation) => activation === "template"
+        ? ["read", "sequential_workflow_create_from_template"]
+        : ["sequential_workflow_create"];
+    const definitionCreationTool = (activation: DefinitionActivation) => activation === "template"
+        ? "sequential_workflow_create_from_template"
+        : "sequential_workflow_create";
+    const definitionMode = (workflowId = pendingWorkflow()) => {
+        if (!workflowId)
+            return undefined;
+        const event = db.prepare("SELECT payload FROM workflow_events WHERE workflow_id = ? AND phase = 'definition_mode_started' ORDER BY id DESC LIMIT 1").get(workflowId) as any;
+        if (!event)
+            return undefined;
+        try {
+            const mode = JSON.parse(event.payload) as { origin: "user_input" | "skill"; userRequest: string; skillPath?: string; activeTools: string[]; activation?: DefinitionActivation; templatePath?: string };
+            return { ...mode, activation: mode.activation ?? "definition" };
+        }
+        catch {
+            return undefined;
+        }
+    };
+    const restoreDefinitionTools = (workflowId: number) => {
+        const mode = definitionMode(workflowId);
+        if (mode?.activeTools?.length)
+            host.setActiveTools(mode.activeTools);
+    };
+    const startDefinitionMode = (workflowId: number, origin: "user_input" | "skill", userRequest: string, activation: DefinitionActivation = "definition", templatePath?: string, skillPath?: string) => {
+        const activeTools = host.getActiveTools();
+        addEvent(workflowId, "definition_mode_started", { origin, userRequest, activation, templatePath, skillPath, activeTools });
+        host.setActiveTools(definitionTools(activation));
+    };
+    const definitionEvaluationSent = (workflowId: number) => Boolean(db.prepare("SELECT 1 FROM workflow_events WHERE workflow_id = ? AND phase = 'definition_mode_evaluated' LIMIT 1").get(workflowId));
+    const harnessEventExists = (workflowId: number, phase: string) => Boolean(db.prepare("SELECT 1 FROM workflow_harness_events WHERE session_id = ? AND (workflow_id = ? OR workflow_id IS NULL) AND phase = ? LIMIT 1").get(session(), workflowId, phase));
+    const definitionAnnouncementSent = (workflowId: number) => Boolean(db.prepare("SELECT 1 FROM workflow_events WHERE workflow_id = ? AND phase = 'definition_mode_announced' LIMIT 1").get(workflowId));
+    const announceDefinitionMode = (workflowId: number) => {
+        const mode = definitionMode(workflowId);
+        if (!mode || definitionAnnouncementSent(workflowId))
+            return undefined;
+        const template = mode.activation === "template";
+        addEvent(workflowId, "definition_mode_announced", { activation: mode.activation, templatePath: mode.templatePath });
+        const content = template
+            ? mode.origin === "skill"
+                ? `Preparing workflow #${workflowId} from the template specified by the required Skill.`
+                : `Preparing workflow #${workflowId} from template: ${mode.templatePath}`
+            : `Workflow #${workflowId} created — defining ordered tasks.`;
+        return { customType: "sequential-workflow-created", content, display: true, details: { workflowId, origin: mode.origin, activation: mode.activation, templatePath: mode.templatePath } };
+    };
+    const createPendingWorkflow = (origin: "user_input" | "skill", evidence: string, reasoning: string) => {
+        const existing = pendingWorkflow();
+        if (existing)
+            return existing;
+        const inserted = db.prepare("INSERT INTO workflows(title, source, status, session_id) VALUES (?, ?, 'pending_definition', ?)").run("Pending workflow definition", `Sequential Workflow requirement detected from ${origin}.`, session());
+        const workflowId = Number(inserted.lastInsertRowid);
+        audit("requirement_detected", { origin, evidence, message: `Sequential Workflow requirement detected from ${origin === "skill" ? "a required Skill" : "the user request"}.` }, origin, workflowId);
+        audit("requirement_classified_required", { requiresSequentialWorkflow: true, reasoning, message: "Sequential Workflow is required for this request." }, origin, workflowId);
+        save([...stack(), workflowId]);
+        return workflowId;
+    };
+    const cancelPendingWorkflowByUser = (reason: string) => {
+        const id = pendingWorkflow();
+        if (!id)
+            return false;
+        restoreDefinitionTools(id);
+        db.prepare("UPDATE workflows SET status='cancelled', updated_at=CURRENT_TIMESTAMP WHERE id=?").run(id);
+        addEvent(id, "cancelled_by_user", { reason });
+        save(stack().filter((workflowId) => workflowId !== id));
+        return true;
+    };
+    const explicitUserOverride = (text: string) => /\b(?:skip|ignore|cancel|end|stop|do not (?:use|create)|don't (?:use|create)|continue manually|manual(?:mente)?|cancelar|encerrar|parar|ignorar|n[aã]o (?:use|crie)|sem (?:usar|criar)|seguir manualmente)\b/iu.test(text);
     const checkpoint = () => {
         const id = focus();
         const t = id ? task(id) : undefined;
@@ -61,12 +169,42 @@ export function workflowHarness(host: ExtensionAPI, db: DatabaseSync) {
         queue = next.catch(() => undefined);
         return next;
     };
-    let namedFailure = false;
+    const templateCandidates = async () => {
+        const directory = join(process.env.PI_CODING_AGENT_DIR ?? join(homedir(), ".pi", "agent"), "sequential_workflow_templates");
+        try {
+            return (await readdir(directory, { withFileTypes: true })).filter(entry => entry.isFile() && entry.name.endsWith(".json")).map(entry => ({ id: entry.name.slice(0, -5), title: entry.name.slice(0, -5), source: join(directory, entry.name) }));
+        } catch { return []; }
+    };
+    const messageText = (content: unknown) => typeof content === "string" ? content : Array.isArray(content) ? content.map((part: any) => part.text ?? "").join("") : "";
+    const classifyRequirement = async (ctx: ExtensionContext, origin: "user_input" | "skill", evidence: string, userRequest: string): Promise<RequirementDecision> => {
+        const templates = await templateCandidates();
+        const branch = ctx.sessionManager.getBranch();
+        if (origin === "user_input") {
+            const conversationHistory = branch
+                .filter((entry: any) => entry.type === "message" && (entry.message?.role === "user" || entry.message?.role === "assistant"))
+                .map((entry: any) => ({ role: entry.message.role as "user" | "assistant", content: messageText(entry.message.content) }))
+                .filter((entry: { content: string }) => !!entry.content.trim())
+                .slice(-12);
+            // Depending on Pi's event ordering, the current message may already be
+            // in the branch. It belongs only in userLastMessage, never twice.
+            const last = conversationHistory.at(-1);
+            if (last?.role === "user" && last.content === userRequest)
+                conversationHistory.pop();
+            return evaluateWorkflowRequirement(ctx, { origin, userLastMessage: userRequest, conversationHistory, templates });
+        }
+        return evaluateWorkflowRequirement(ctx, {
+            origin,
+            evidence,
+            userRequest,
+            recentUserMessages: branch.filter((entry: any) => entry.type === "message" && entry.message?.role === "user").slice(-4).map((entry: any) => messageText(entry.message.content)),
+            templates,
+        });
+    };
     const assertOperation = (name: string, params: any) => {
-        if (namedFailure && (name === "sequential_workflow_create" || name.endsWith("create_from_template")))
-            throw new Error("Named activation failed; a new user request is required before creating a replacement.");
         if (params.workflowId !== undefined && name !== "sequential_workflow_cancel")
             own(params.workflowId);
+        if (name.endsWith("evaluate") && requirementBlock())
+            throw new Error("Configured workflow evaluation is unresolved; manual evaluation is blocked.");
         if (name.endsWith("record_result") || name.endsWith("evaluate")) {
             if (focus() !== params.workflowId)
                 throw new Error("Only the focused workflow can advance. Use /workflow-focus explicitly.");
@@ -80,29 +218,128 @@ export function workflowHarness(host: ExtensionAPI, db: DatabaseSync) {
             }
         }
         if (name === "sequential_workflow_create" || name.endsWith("create_from_template")) {
-            if (params.parentWorkflowId !== undefined)
-                own(params.parentWorkflowId);
-            if (params.parentTaskId !== undefined) {
-                const t = db.prepare("SELECT * FROM workflow_tasks WHERE id = ?").get(params.parentTaskId) as any;
-                if (!t || own(t.workflow_id).id !== focus() || task(t.workflow_id)?.id !== t.id)
-                    throw new Error("Child must belong to the current focused task.");
-            }
-            else if (focus() !== undefined)
+            const pending = pendingWorkflow();
+            const mode = definitionMode(pending);
+            if (pending && mode && name !== definitionCreationTool(mode.activation))
+                throw new Error(`Definition mode requires ${definitionCreationTool(mode.activation)}.`);
+            if (focus() !== undefined && pendingWorkflow() === undefined)
                 throw new Error("Suspend the current workflow with /workflow-suspend before creating an independent execution.");
         }
+        if (name === "sequential_workflow_create_subworkflow") {
+            const t = db.prepare("SELECT * FROM workflow_tasks WHERE id = ?").get(params.parentTaskId) as any;
+            if (!t || t.workflow_id !== params.parentWorkflowId || own(t.workflow_id).id !== focus() || task(t.workflow_id)?.id !== t.id)
+                throw new Error("A subworkflow must belong to the current focused task.");
+            if (t.type !== "workflow" || t.status !== "running")
+                throw new Error("A subworkflow requires a running workflow task.");
+        }
     };
+    host.registerMessageRenderer("sequential-workflow-evaluation", (message, { outputPad }, theme) => {
+        const box = new Box(outputPad, 0);
+        box.addChild(new Text(`${theme.fg("muted", "Evaluating Sequential Workflow requirement")}\n${theme.fg("dim", String(message.content))}`, 0, 0));
+        return box;
+    });
+    host.registerMessageRenderer("sequential-workflow-created", (message, { outputPad }, theme) => {
+        const workflowId = (message.details as any)?.workflowId;
+        const box = new Box(outputPad, 0);
+        box.addChild(new Text(`${theme.fg("muted", "Planning Sequential Workflow")}${workflowId ? ` #${workflowId}` : ""}\n${theme.fg("dim", String(message.content))}`, 0, 0));
+        return box;
+    });
+    host.registerMessageRenderer("sequential-workflow-harness", (message, { outputPad }, theme) => {
+        const details = (message.details ?? {}) as { phase?: string; workflowId?: number; taskId?: number; taskPosition?: number; evaluator?: string; model?: string; reasoning?: string };
+        const workflow = details.workflowId ? `Workflow #${details.workflowId}` : "Sequential Workflow";
+        const task = details.taskPosition ? ` · Task #${details.taskPosition}` : "";
+        const phase = details.phase ?? "";
+        const presentation: Record<string, { title: string; color: "accent" | "success" | "warning" | "error" | "muted" }> = {
+            requirement_check_started: { title: "Evaluating requirement", color: "accent" },
+            requirement_classified_required: { title: "Workflow required", color: "accent" },
+            requirement_classified_not_required: { title: "Workflow not required", color: "success" },
+            requirement_classified_uncertain: { title: "Decision uncertain", color: "warning" },
+            requirement_classified_unavailable: { title: "Evaluator unavailable", color: "error" },
+            requirement_classified_invalid_response: { title: "Invalid evaluator response", color: "error" },
+            requirement_classified_error: { title: "Requirement evaluation failed", color: "error" },
+            evaluation_blocked: { title: "Work blocked", color: "error" },
+            definition_mode_started: { title: "Defining workflow", color: "accent" },
+            workflow_hydrated: { title: "Workflow ready", color: "success" },
+            task_evaluation_accept: { title: "Task accepted", color: "success" },
+            task_evaluation_retry: { title: "Task will be retried", color: "warning" },
+            task_evaluation_fail: { title: "Terminal failure", color: "error" },
+            task_evaluation_uncertain: { title: "Task evaluation uncertain", color: "warning" },
+            task_evaluation_unavailable: { title: "Task evaluator unavailable", color: "error" },
+            task_evaluation_invalid_response: { title: "Invalid task response", color: "error" },
+            task_evaluation_error: { title: "Task evaluation failed", color: "error" },
+            workflow_completed: { title: "Workflow completed", color: "success" },
+            workflow_cancelled: { title: "Workflow cancelled", color: "warning" },
+        };
+        const current = presentation[phase] ?? { title: "Workflow update", color: "muted" as const };
+        const header = `${workflow}${task} · ${current.title}`;
+        const metadata = [details.evaluator, details.model].filter(Boolean).join(" · ");
+        const body = [theme.fg(current.color, header), theme.fg("dim", String(message.content)), metadata ? theme.fg("muted", `Evaluator: ${metadata}`) : ""].filter(Boolean).join("\n");
+        const box = new Box(outputPad, 0);
+        box.addChild(new Text(body, 0, 0));
+        return box;
+    });
     const tools = new Map<string, any>();
+    const rawTools = new Map<string, any>();
+    const restoreTaskAfterUnavailableEvaluation = (workflowId: number, taskId: number, type: string) => {
+        const taskStatus = type === "collect" ? "awaiting_user" : "running";
+        const workflowStatus = type === "collect" ? "awaiting_user" : "running";
+        db.prepare("UPDATE workflow_tasks SET status = ?, updated_at = CURRENT_TIMESTAMP WHERE id = ? AND workflow_id = ? AND status = 'evaluating'").run(taskStatus, taskId, workflowId);
+        db.prepare("UPDATE workflows SET status = ?, updated_at = CURRENT_TIMESTAMP WHERE id = ? AND status = 'evaluating'").run(workflowStatus, workflowId);
+    };
+    const automaticTaskEvaluation = async (ctx: ExtensionContext, workflowId: number, taskId: number, result: string) => {
+        const current = task(workflowId);
+        if (!current?.criteria || current.id !== taskId)
+            return undefined;
+        const item = row(workflowId);
+        const decision = await evaluateWorkflowTask(ctx, { workflow: { title: item?.title ?? "", source: item?.source ?? "" }, task: { type: current.type, instruction: current.instruction, criteria: current.criteria }, result });
+        if (!decision)
+            return undefined;
+        const message = decision.outcome === "accept" ? `Task #${current.position} accepted by the configured evaluator.` : decision.outcome === "retry" ? `Task #${current.position} will be retried.` : decision.outcome === "fail" ? `Task #${current.position} ended with a terminal failure; workflow failed.` : `Task #${current.position} evaluation is unresolved; work remains blocked.`;
+        audit(`task_evaluation_${decision.outcome}`, { taskId, taskPosition: current.position, ...decision, message }, undefined, workflowId, true);
+        if (!["accept", "retry", "fail"].includes(decision.outcome)) {
+            restoreTaskAfterUnavailableEvaluation(workflowId, taskId, current.type);
+            blockEvaluation(decision.reasoning, decision as any, undefined, workflowId);
+            return decision;
+        }
+        const evaluate = rawTools.get("sequential_workflow_evaluate");
+        if (!evaluate)
+            throw new Error("Sequential Workflow evaluator is unavailable.");
+        const applied = await evaluate.execute("system-one-evaluation", { workflowId, taskId, outcome: decision.outcome, reasoning: decision.reasoning, decision: { evaluator: decision.evaluator, model: decision.model, confidence: decision.confidence, probabilities: decision.probabilities } }, ctx.signal, undefined, ctx);
+        if (applied.details?.next?.completed)
+            audit("workflow_completed", { evaluator: decision.evaluator, model: decision.model, message: `Workflow #${workflowId} completed.` }, undefined, workflowId, true);
+        return { ...decision, applied };
+    };
     const api = new Proxy(host, { get(target, key) {
             if (key !== "registerTool")
                 return Reflect.get(target, key);
             return (definition: any) => {
+                rawTools.set(definition.name, definition);
                 const wrapped = { ...definition, async execute(id: string, params: any, signal: any, update: any, ctx: ExtensionContext) {
                         return transaction(ctx, async () => {
                             assertOperation(definition.name, params);
+                            const pendingBefore = pendingWorkflow();
+                            const taskBefore = params.workflowId !== undefined ? task(params.workflowId) : undefined;
                             const result = await definition.execute(id, params, signal, update, ctx);
-                            if (definition.name === "sequential_workflow_create" || definition.name.endsWith("create_from_template")) {
-                                save([...stack(), result.details.workflowId]);
+                            if (definition.name === "sequential_workflow_create" || definition.name === "sequential_workflow_create_subworkflow" || definition.name.endsWith("create_from_template")) {
+                                const workflowId = result.details.workflowId as number;
+                                if (pendingBefore === workflowId)
+                                    restoreDefinitionTools(workflowId);
+                                save([...new Set([...stack(), workflowId])]);
+                                audit("workflow_hydrated", { message: `Workflow #${workflowId} created and ready for its current task.` }, undefined, workflowId, true);
+                            }
+                            if (definition.name === "sequential_workflow_record_result" && result.details?.needsEvaluation) {
+                                const automatic = await automaticTaskEvaluation(ctx, params.workflowId, params.taskId, params.result);
+                                if (automatic?.applied)
+                                    return automatic.applied;
+                            }
+                            if (definition.name === "sequential_workflow_evaluate" && result.details?.failed) {
+                                const phase = result.details.terminal ? "task_terminal_failed" : "failed_attempt_limit";
+                                audit(phase, { taskId: params.taskId, taskPosition: taskBefore?.position, message: result.details.terminal ? `Task #${taskBefore?.position ?? params.taskId} ended with a terminal failure; workflow failed.` : `Task #${taskBefore?.position ?? params.taskId} reached its retry limit; workflow failed.` }, undefined, params.workflowId, true);
                             }
+                            else if (definition.name === "sequential_workflow_evaluate" && (params.outcome === "retry" || params.accepted === false))
+                                audit("task_retry", { taskId: params.taskId, taskPosition: taskBefore?.position, message: `Task #${taskBefore?.position ?? params.taskId} will be retried.` }, undefined, params.workflowId, true);
+                            if ((definition.name === "sequential_workflow_evaluate" || definition.name === "sequential_workflow_record_result") && result.details?.next?.completed)
+                                audit("workflow_completed", { message: `Workflow #${params.workflowId} completed.` }, undefined, params.workflowId, true);
                             return result;
                         });
                     } };
@@ -110,46 +347,98 @@ export function workflowHarness(host: ExtensionAPI, db: DatabaseSync) {
                 host.registerTool(wrapped);
             };
         } });
-    let namedActivation = false;
     host.on("before_agent_start", (_event, ctx) => context.run(ctx, () => {
-        if (!namedActivation)
+        // Requirement checks are emitted immediately by the input/tool handler so
+        // their visible custom message is persisted before any model turn begins.
+        return;
+    }));
+    host.on("before_agent_start", (_event, ctx) => context.run(ctx, () => {
+        const pending = pendingWorkflow();
+        const mode = definitionMode(pending);
+        if (!pending || !mode || mode.origin !== "user_input" || definitionEvaluationSent(pending))
             return;
-        namedActivation = false;
-        const id = focus();
-        const t = id ? task(id) : undefined;
-        if (t?.type === "collect")
-            db.prepare("UPDATE workflow_collect_checkpoint SET user_entry_id=? WHERE task_id=?").run(userEntry(), t.id);
+        addEvent(pending, "definition_mode_evaluated", { requiresSequentialWorkflow: true });
+        return { message: { customType: "sequential-workflow-evaluation", content: "Sequential Workflow is required for this request.", display: true, details: { workflowId: pending, requiresSequentialWorkflow: true } } };
     }));
-    // Named activation is resolved before the model can invent a replacement plan.
-    host.on("input", async (event, ctx) => {
-        namedFailure = false;
-        const match = event.text.trim().match(/^(?:ative|execute|inicie|activate|run|start)\s+(?:(?:o|the)\s+)?sequential[ -]workflow\s+([\w.-]+)\s*$/i);
-        if (!match)
+    host.on("before_agent_start", (_event, ctx) => context.run(ctx, () => {
+        const pending = pendingWorkflow();
+        if (!pending)
             return;
-        try {
-            const result = await tools.get("sequential_workflow_create_from_template").execute("named-start", { path: match[1] }, undefined, undefined, ctx);
-            namedActivation = true;
-            return { action: "transform" as const, text: `${event.text}\n${result.content[0].text}\nThe named template was executed by the harness. Do not create another workflow; follow its current task.` };
+        const message = announceDefinitionMode(pending);
+        return message ? { message } : undefined;
+    }));
+    const workflowKeyword = /\b(?:sequential[\s-]workflow|workflow[\s-]sequencial|fluxo de trabalho sequencial)\b/i;
+    // A keyword starts semantic evaluation; the configured evaluator, rather than
+    // local verb matching, decides whether the user is requesting an execution.
+    const workflowKeywordDetected = (text: string) => workflowKeyword.test(text);
+    const skillRequiresWorkflowEvaluation = (content: string) => workflowKeywordDetected(content);
+    // Evaluation starts when a user message or a read Skill contains the keyword.
+    // The evaluator alone decides whether that evidence is an explicit request.
+    host.on("input", async (event, ctx) => context.run(ctx, async () => {
+        if (event.source === "extension")
+            return;
+        // An unavailable requirement evaluator must not permanently lock a session
+        // with no active workflow. A later user request is new evidence and can be
+        // evaluated normally if it explicitly requests a workflow.
+        if (event.source !== "extension" && focus() === undefined && requirementBlock()) {
+            clearRequirementBlock();
+            audit("requirement_block_released", { message: "A new user input released the unresolved Sequential Workflow evaluation block." }, "user_input");
         }
-        catch (error) {
-            namedFailure = true;
-            ctx.ui.notify(String(error), "error");
-            return { action: "transform" as const, text: `${event.text}\nNamed workflow activation failed: ${String(error)}. Report the failure; do not invent a substitute workflow.` };
+        const focused = focus();
+        const focusedTask = focused ? task(focused) : undefined;
+        const evaluationConfig = await workflowEvaluationConfig().catch(() => undefined);
+        if (evaluationConfig?.modelType === "system_one" && focused && focusedTask?.type === "collect" && focusedTask.status === "awaiting_user") {
+            const record = rawTools.get("sequential_workflow_record_result");
+            if (!record)
+                throw new Error("Sequential Workflow result recorder is unavailable.");
+            const recorded = await transaction(ctx, () => record.execute("system-one-collect", { workflowId: focused, taskId: focusedTask.id, phase: "collect", result: event.text }, ctx.signal, undefined, ctx));
+            if (recorded.details?.needsEvaluation)
+                await transaction(ctx, () => automaticTaskEvaluation(ctx, focused, focusedTask.id, event.text));
+            return { action: "continue" as const };
         }
-    });
+        if (pendingWorkflow() && explicitUserOverride(event.text))
+            await transaction(ctx, () => { cancelPendingWorkflowByUser(event.text); });
+        if (focus() !== undefined || !event.text.trim() || !workflowKeywordDetected(event.text))
+            return;
+        clearRequirementBlock();
+        audit("requirement_check_started", { message: "Checking whether Sequential Workflow is required…" }, "user_input", undefined, true);
+        const decision = await classifyRequirement(ctx, "user_input", event.text, event.text);
+        const message = decision.status === "required" ? "Sequential Workflow is required for this request." : decision.status === "not_required" ? "Sequential Workflow is not required for this request." : decision.status === "uncertain" ? "Sequential Workflow decision is uncertain; work remains blocked." : "Sequential Workflow requirement could not be classified.";
+        audit(`requirement_classified_${decision.status}`, { ...decision, requiresSequentialWorkflow: decision.status === "required", message }, "user_input", undefined, true);
+        if (decision.status !== "required") {
+            if (decision.status !== "not_required") await transaction(ctx, () => { blockEvaluation(decision.reasoning, decision as any, "user_input"); });
+            return;
+        }
+        await transaction(ctx, async () => {
+            if (focus() === undefined) {
+                const workflowId = createPendingWorkflow("user_input", event.text, decision.reasoning);
+                const template = decision.templateId ? (await templateCandidates()).find(candidate => candidate.id === decision.templateId) : undefined;
+                startDefinitionMode(workflowId, "user_input", event.text, decision.activation ?? "definition", template?.source);
+                audit("definition_mode_started", { evaluator: decision.evaluator, model: decision.model, message: `Sequential Workflow definition mode started for workflow #${workflowId}.` }, "user_input", workflowId);
+            }
+        });
+    }));
     let continuationKey = "";
     let continuations = 0;
     host.on("input", (event) => { if (event.source !== "extension")
         continuations = 0; });
+    host.on("agent_before_settle", (event, ctx) => context.run(ctx, () => {
+        const pending = pendingWorkflow();
+        if (pending && definitionMode(pending) && event.context.canContinue)
+            return { continue: true };
+    }));
     host.on("agent_end", (event, ctx) => context.run(ctx, () => {
         const last = event.messages.filter(m => m.role === "assistant").at(-1);
         if (last?.role === "assistant" && ["aborted", "error"].includes(last.stopReason))
             return;
         const id = focus();
+        const pending = pendingWorkflow();
+        if (pending && definitionMode(pending))
+            return;
         const t = id ? task(id) : undefined;
-        if (!t || t.status === "awaiting_user" || t.status === "waiting_subworkflow")
+        if (requirementBlock() || !pending && (!t || t.status === "awaiting_user" || t.status === "waiting_subworkflow" || t.status === "evaluating"))
             return;
-        const key = `${session()}:${id}:${t.id}:${t.status}:${t.attempts}`;
+        const key = pending ? `${session()}:${pending}:pending_definition` : `${session()}:${id}:${t.id}:${t.status}:${t.attempts}`;
         if (key !== continuationKey) {
             continuationKey = key;
             continuations = 0;
@@ -158,14 +447,56 @@ export function workflowHarness(host: ExtensionAPI, db: DatabaseSync) {
             ctx.ui.notify("Workflow remains pending: automatic continuation limit reached. Inspect the current task before resuming.", "warning");
             return;
         }
-        host.sendMessage({ customType: "sequential-workflow-state", display: false, content: `Workflow ${id}, task ${t.id} is still ${t.status}. Complete the current phase and record its transition; do not claim workflow completion.` }, { triggerTurn: true, deliverAs: "followUp" });
+        const content = pending
+            ? `Workflow ${pending} requires a definition. Do not perform work or use external tools. Create the focused pending workflow using the existing workflow creation tools.`
+            : `Workflow ${id}, task ${t.id} is still ${t.status}. Complete the current phase and record its transition; do not claim workflow completion.`;
+        host.sendMessage({ customType: "sequential-workflow-state", display: false, content }, { triggerTurn: true, deliverAs: "followUp" });
     }));
     // Pi preflights sibling calls before executing them. Allow only one call per
     // model turn while focused (including a create call that establishes focus).
     let dispatched = false;
+    const latestUserRequest = (ctx: ExtensionContext) => {
+        const content = ctx.sessionManager.getBranch().filter((entry: any) => entry.type === "message" && entry.message?.role === "user").at(-1)?.message?.content;
+        return typeof content === "string" ? content : Array.isArray(content) ? content.map((part: any) => part.text ?? "").join("") : "";
+    };
     host.on("turn_start", () => { dispatched = false; });
-    host.on("tool_call", (event, ctx) => context.run(ctx, () => {
+    host.on("tool_call", async (event, ctx) => context.run(ctx, async () => {
+        if (event.toolName === "read" && typeof event.input?.path === "string" && basename(event.input.path) === "SKILL.md" && focus() === undefined) {
+            try {
+                const path = resolve(ctx.cwd, event.input.path);
+                const content = await readFile(path, "utf8");
+                {
+                    if (skillRequiresWorkflowEvaluation(content)) {
+                    const userRequest = latestUserRequest(ctx);
+                    audit("requirement_check_started", { path, message: "Checking whether Sequential Workflow is required…" }, "skill", undefined, true);
+                    const decision = await classifyRequirement(ctx, "skill", content, userRequest);
+                    const message = decision.status === "required" ? "Sequential Workflow is required for this request." : decision.status === "not_required" ? "Sequential Workflow is not required for this request." : decision.status === "uncertain" ? "Sequential Workflow decision is uncertain; work remains blocked." : "Sequential Workflow requirement could not be classified.";
+                    audit(`requirement_classified_${decision.status}`, { path, ...decision, requiresSequentialWorkflow: decision.status === "required", message }, "skill", undefined, true);
+                    if (decision.status === "required") {
+                        await transaction(ctx, async () => {
+                            if (focus() === undefined) {
+                                const workflowId = createPendingWorkflow("skill", path, decision.reasoning);
+                                startDefinitionMode(workflowId, "skill", userRequest, decision.activation ?? "definition", undefined, path);
+                                audit("definition_mode_started", { path, message: `Sequential Workflow definition mode started for workflow #${workflowId}.` }, "skill", workflowId, true);
+                            }
+                        });
+                        // Preserve the normal read result. The next model decision receives
+                        // the Skill it requested plus the definition-mode system instruction.
+                        return;
+                    }
+                    else if (decision.status !== "not_required")
+                        await transaction(ctx, () => { blockEvaluation(decision.reasoning, decision as any, "skill"); });
+                    }
+                }
+            }
+            catch {
+                // The original read tool reports path and access errors.
+            }
+        }
         const id = focus();
+        const blockedRequirement = requirementBlock();
+        if (blockedRequirement && !["sequential_workflow_cancel", "sequential_workflow_status"].includes(event.toolName))
+            return { block: true, terminate: true, reason: `Sequential Workflow evaluation is unresolved: ${blockedRequirement.reason}` };
         if (id === undefined && !event.toolName.startsWith("sequential_workflow_create")) {
             dispatched = true;
             return;
@@ -174,6 +505,12 @@ export function workflowHarness(host: ExtensionAPI, db: DatabaseSync) {
             return { block: true, reason: "Sequential Workflow requires one tool call per model turn." };
         const t = id ? task(id) : undefined;
         const workflowTool = event.toolName.startsWith("sequential_workflow_");
+        const pending = pendingWorkflow();
+        const mode = definitionMode(pending);
+        if (pending && mode && !definitionTools(mode.activation).includes(event.toolName))
+            return { block: true, reason: `Definition mode permits only: ${definitionTools(mode.activation).join(", ")}.` };
+        if (pending !== undefined && !workflowTool && !mode)
+            return { block: true, reason: "Sequential Workflow creation is required before external tools may run." };
         if (t && !workflowTool && (t.type !== "action" || t.status !== "running"))
             return { block: true, reason: `Task ${t.id} is ${t.type}/${t.status}; external tools are blocked until the required workflow transition.` };
         try {
@@ -185,11 +522,40 @@ export function workflowHarness(host: ExtensionAPI, db: DatabaseSync) {
         }
         dispatched = true;
     }));
+    host.on("context_with_system", (event, ctx) => context.run(ctx, () => {
+        const workflowId = pendingWorkflow();
+        const mode = definitionMode(workflowId);
+        if (!workflowId || !mode)
+            return;
+        const messages = event.messages.filter((message: any) => !(message.role === "custom" && message.customType === "sequential-workflow-state"));
+        const creationTool = definitionCreationTool(mode.activation);
+        const creation = mode.origin === "skill" && mode.activation === "template"
+            ? "The Skill just read specifies the template. Use that template now."
+            : mode.activation === "template"
+                ? mode.templatePath ? `Use the explicitly requested template path ${mode.templatePath}.` : `Use the exact JSON template name explicitly required by the supplied Skill. A relative template name is relative to the directory containing ${mode.skillPath ?? "the Skill"}.`
+                : "Define the ordered workflow from the original request and the supplied Skill.";
+        const permitted = definitionTools(mode.activation).join(", ");
+        const instruction = { role: "system", content: `Sequential Workflow definition mode is active for workflow #${workflowId}. You MUST create or hydrate this workflow before performing the user's requested work. ${creation} The only permitted tools are: ${permitted}. Do not perform the requested operation, claim completion, use any other tool, or bypass workflow creation. When ready, make exactly one call to ${creationTool}; the harness will reject the other workflow creation route.` } as any;
+        // A Skill cutover must steer the immediate post-read continuation without
+        // replacing the Skill's normal tool result. Keep the steering message first.
+        if (mode.origin === "skill")
+            messages.unshift(instruction);
+        else
+            messages.push(instruction);
+        return { messages };
+    }));
     host.on("context", (event, ctx) => context.run(ctx, () => {
         const messages = event.messages.filter(m => !(m.role === "custom" && m.customType === "sequential-workflow-state"));
         const id = focus();
-        if (id !== undefined)
-            messages.push({ role: "custom", customType: "sequential-workflow-state", display: false, timestamp: Date.now(), content: `Session workflow focus: ${id}. Current task: ${JSON.stringify(task(id))}. Work only on this task. Pass workflowId and taskId for transitions. Collect requires a new user response. External tools are blocked outside a running Action. Use one tool per turn. User commands /workflow-suspend and /workflow-focus control focus.` });
+        if (id !== undefined) {
+            const pending = pendingWorkflow();
+            const mode = definitionMode(pending);
+            const creationTool = mode ? definitionCreationTool(mode.activation) : "sequential_workflow_create";
+            const templateHint = mode?.activation === "template" ? " Use the exact JSON template explicitly required by the supplied Skill." : "";
+            messages.push({ role: "custom", customType: "sequential-workflow-state", display: false, timestamp: Date.now(), content: pending
+                ? `Session workflow focus: ${pending}. This workflow is pending definition because Sequential Workflow creation is required. Do not perform work or use external tools. Create or initialize this focused workflow using ${creationTool}.${templateHint}`
+                : `Session workflow focus: ${id}. Current task: ${JSON.stringify(task(id))}. Work only on this task. Pass workflowId and taskId for transitions. Collect requires a new user response. External tools are blocked outside a running Action. Use one tool per turn. User commands /workflow-suspend and /workflow-focus control focus.` });
+        }
         return { messages };
     }));
     const command = (name: string, description: string, work: (args: string) => void) => host.registerCommand(name, { description, handler: async (args, ctx) => {
@@ -234,5 +600,5 @@ export function workflowHarness(host: ExtensionAPI, db: DatabaseSync) {
         }
         save(chain);
     });
-    return { api, session, own, transaction, context, checkpoint };
+    return { api, session, own, transaction, context, checkpoint, pendingWorkflow };
 }

package/extensions/pi-console-webui/app/[section]/page.tsx

@@ -1,7 +1,7 @@
 import { notFound } from "next/navigation";
 import { ConsolePage } from "@/components/console-page";
 import { sectionMetadata } from "@/lib/page-metadata";
-const sections = new Set(["chat", "profiles", "settings", "env", "soul", "context-memory", "guardrails", "skills", "tools", "packages", "pulses", "extensions", "applications", "api-server", "pi-console-webui", "skill-sources"]);
+const sections = new Set(["chat", "profiles", "settings", "model", "env", "soul", "context-memory", "guardrails", "skills", "tools", "packages", "pulses", "sequential-workflows", "extensions", "applications", "models", "api-server", "pi-console-webui", "skill-sources"]);
 export async function generateMetadata({ params, searchParams }: { params: Promise<{ section: string }>; searchParams: Promise<{ profile?: string }> }) {
   return sectionMetadata((await params).section, (await searchParams).profile);
 }

package/extensions/pi-console-webui/app/api/admin/models/route.ts

@@ -0,0 +1,22 @@
+import { NextResponse } from "next/server";
+import { authenticated } from "@/lib/auth";
+import { readModelsConfig, writeModelsConfig } from "@/lib/admin-models";
+
+export async function GET() {
+  if (!(await authenticated())) return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
+  try {
+    return NextResponse.json({ content: await readModelsConfig() });
+  } catch (error) {
+    return NextResponse.json({ error: error instanceof Error ? error.message : "Unable to read models.json" }, { status: 500 });
+  }
+}
+
+export async function PUT(request: Request) {
+  if (!(await authenticated())) return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
+  try {
+    const { content } = await request.json();
+    return NextResponse.json({ content: await writeModelsConfig(content) });
+  } catch (error) {
+    return NextResponse.json({ error: error instanceof Error ? error.message : "Invalid models.json" }, { status: 400 });
+  }
+}

package/extensions/pi-console-webui/app/globals.css

@@ -14,6 +14,9 @@ body:has(.terminal-page) { background: #0d1117; }
 .terminal-host .xterm { width: 100%; max-width: 100%; height: 100%; overflow: hidden; }
 .terminal-host .xterm-viewport { background-color: #0d1117 !important; }
 button, input, textarea, select { font: inherit; }
+/* Form labels are emphasized; entered and selected values remain regular weight. */
+label { font-weight: 600; }
+input, textarea, select, .cm-editor, .w-md-editor { font-weight: 400; }
 select, select option { background-color: #ffffff !important; }
 .bg-zinc-950, .bg-zinc-900 { background-color: #ffffff !important; }
 .bg-zinc-800 { background-color: #e4e4e7 !important; }