@pi-unipi/workflow 2.4.0 → 2.5.0

package/README.md

@@ -128,6 +128,14 @@ Skills define:
 
 The agent reads the skill, executes the steps, and produces artifacts in the `.unipi/` directory.
 
+## Workflow Sandbox
+
+Each workflow activates a command-specific sandbox for the duration of its agent run. The sandbox blocks disallowed tool calls by name (for example, `write`, `edit`, or `bash` in read-only workflows) without changing Pi's active tool list. Keeping the provider tool schemas and their order unchanged makes the workflow prefix cache-stable.
+
+Sandbox instructions are stored as hidden, append-only `unipi-workflow-sandbox-snapshot` messages rather than being injected into the system prompt. An active snapshot explicitly supersedes older snapshots. After the workflow completes at `agent_end`, the next agent start appends an inactive snapshot when needed so stale restrictions no longer apply. Sessions that have never activated a workflow do not receive a marker.
+
+The sandbox preserves the existing command-level semantics; skill instructions still define narrower write locations and setup-only shell usage where applicable.
+
 ## Directory Structure
 
 ```

package/commands.ts

@@ -8,7 +8,7 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { readFileSync, readdirSync, existsSync, statSync } from "fs";
 import { join, basename } from "path";
-import { UNIPI_PREFIX, WORKFLOW_COMMANDS, getToolsForCommand, getSandboxLevel, type SandboxLevel } from "@pi-unipi/core";
+import { UNIPI_PREFIX, WORKFLOW_COMMANDS, type UnipiWorkflowEvent } from "@pi-unipi/core";
 
 type CompletionItem = { value: string; label: string; description: string };
 
@@ -16,12 +16,10 @@ type CompletionItem = { value: string; label: string; description: string };
 export interface WorkflowCommandOptions {
   /** Check if ralph module is detected */
   isRalphDetected: () => boolean;
-  /** Get current active tool names */
-  getActiveTools: () => string[];
-  /** Set active tools with sandbox level */
-  setActiveTools: (tools: string[], level: SandboxLevel) => void;
-  /** Save tools for later restore */
-  saveTools: (tools: string[]) => void;
+  /** Begin one workflow lifecycle and activate its sandbox. */
+  activateSandbox: (event: UnipiWorkflowEvent) => boolean;
+  /** Roll back lifecycle and sandbox state after dispatch failure. */
+  abortWorkflow: () => void;
 }
 
 /** Command definition */
@@ -402,14 +400,17 @@ export function registerWorkflowCommands(
         return null;
       },
       handler: async (args, ctx) => {
-        // Apply sandbox — save current tools, set command's tools
-        const currentTools = options.getActiveTools();
-        options.saveTools(currentTools);
-        const sandboxTools = getToolsForCommand(cmd.name, currentTools);
-        const sandboxLevel = getSandboxLevel(cmd.name);
-        options.setActiveTools([...sandboxTools], sandboxLevel);
-
-        // Load skill content from SKILL.md
+        const workflowEvent: UnipiWorkflowEvent = {
+          command: cmd.name,
+          fullCommand: `/${fullCommand}`,
+          args: args?.trim() ?? "",
+        };
+        if (!options.activateSandbox(workflowEvent)) {
+          if (ctx.hasUI) ctx.ui.notify("Another UniPi workflow is still active", "warning");
+          return;
+        }
+
+        // Load skill content from SKILL.md.
         let skillContent = "";
         try {
           const skillPath = join(
@@ -419,33 +420,34 @@ export function registerWorkflowCommands(
           );
           skillContent = readFileSync(skillPath, "utf-8");
         } catch {
-          // Skill file not found — continue without it
+          // Skill file not found — continue without it.
         }
 
-        // Build skill invocation message
         let message = `Execute the ${cmd.skillName} workflow.`;
 
-        // Add args if provided
         if (args?.trim()) {
           message += `\n\nArguments: ${args.trim()}`;
         }
 
-        // Add ralph hint if applicable
         if (cmd.ralphHint && options.isRalphDetected()) {
           message += `\n\n💡 ${cmd.ralphHint}`;
         }
 
-        // Inject skill content as context
         if (skillContent) {
           message += `\n\n<skill_content>\n${skillContent}\n</skill_content>`;
         }
 
-        // Send as user message to trigger skill processing
-        pi.sendUserMessage(message, { deliverAs: "followUp" });
+        // Any synchronous dispatch failure must not leave a phantom workflow
+        // lifecycle or sandbox behind.
+        try {
+          pi.sendUserMessage(message, { deliverAs: "followUp" });
+        } catch (error) {
+          options.abortWorkflow();
+          throw error;
+        }
 
         if (ctx.hasUI) {
           ctx.ui.notify(`Running /${fullCommand}`, "info");
-          // Update extension status with active command name
           const ralphStatus = options.isRalphDetected() ? "✓ rl" : "○ rl";
           ctx.ui.setStatus("unipi-workflow", `⚡ wf:${cmd.name} ${ralphStatus}`);
         }

package/index.ts

@@ -1,15 +1,18 @@
 /**
  * @unipi/workflow — Structured development workflow commands
  *
- * Registers 13 commands that dispatch to skills for LLM instruction.
- * Emits MODULE_READY event for inter-module discovery.
- * Detects @unipi/ralph presence for loop integration.
- * Applies sandbox (tool filtering) per command.
+ * Registers workflow commands that dispatch to skills for LLM instruction.
+ * Emits MODULE_READY for inter-module discovery and detects @unipi/ralph.
+ * Enforces workflow sandboxes without changing Pi's active tool schemas.
  */
 
 import { dirname } from "node:path";
 import { fileURLToPath } from "node:url";
-import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import {
+  buildSessionContext,
+  type ExtensionAPI,
+  type SessionEntry,
+} from "@earendil-works/pi-coding-agent";
 import {
   UNIPI_EVENTS,
   MODULES,
@@ -17,114 +20,209 @@ import {
   emitEvent,
   getPackageVersion,
   initUnipiDirs,
-  type SandboxLevel,
   getBlockedToolsForLevel,
+  getSandboxLevel,
+  isToolAllowed,
+  type SandboxLevel,
 } from "@pi-unipi/core";
 import { registerWorkflowCommands } from "./commands.js";
+import { WorkflowLifecycle } from "./lifecycle.js";
 
 /** Package version (read from package.json at load time) */
 const VERSION = getPackageVersion(dirname(fileURLToPath(import.meta.url)));
 
-/** Whether ralph module is detected */
-let ralphDetected = false;
+export const WORKFLOW_SANDBOX_SNAPSHOT_TYPE = "unipi-workflow-sandbox-snapshot";
+
+interface WorkflowSandboxSnapshotDetails {
+  active: boolean;
+  command?: string;
+  level?: SandboxLevel;
+}
+
+interface EffectiveSandboxSnapshot {
+  content: unknown;
+  details?: WorkflowSandboxSnapshotDetails;
+}
+
+function sandboxRestrictions(level: SandboxLevel): string[] {
+  const common = [
+    "Do not attempt to call tools blocked by name.",
+    "If the user requests an action that requires a blocked tool, explain that the workflow sandbox does not allow it.",
+  ];
 
-/** Saved tools before sandbox was applied (for restore) */
-let savedTools: string[] | null = null;
+  if (level === "brainstorm") {
+    return [
+      "The write tool is restricted to .unipi/docs/specs/ only.",
+      "Use bash only for specific setup operations such as git init or mkdir; use grep, find, and ls for discovery instead of bash.",
+      ...common,
+    ];
+  }
+
+  if (level === "write_unipi") {
+    return [
+      "The write tool is restricted to .unipi/docs/ only (specs and plans).",
+      "Use grep, find, and ls for file discovery instead of guessing filenames.",
+      "Bash is blocked; use read, write, edit, grep, find, and ls only.",
+      ...common,
+    ];
+  }
+
+  return common;
+}
+
+/** Build a persistent snapshot that explicitly invalidates earlier sandbox state. */
+function formatActiveSandboxSnapshot(command: string, level: SandboxLevel): string {
+  const blocked = getBlockedToolsForLevel(level);
+  const blockedLine = blocked.length > 0
+    ? blocked.join(", ")
+    : "none";
+
+  return [
+    "# UniPi Workflow Sandbox Snapshot",
+    "This snapshot supersedes all prior UniPi workflow sandbox snapshots; use only this snapshot for workflow sandbox status and restrictions.",
+    "Status: active",
+    `Workflow: /unipi:${command}`,
+    `Sandbox level: ${level}`,
+    `Blocked tool names: ${blockedLine}`,
+    "Pi's provider tool schemas and tool order remain unchanged. Calls to blocked tool names are rejected by the workflow sandbox.",
+    ["Restrictions:", ...sandboxRestrictions(level).map((restriction) => `- ${restriction}`)].join("\n"),
+  ].join("\n\n");
+}
+
+function formatInactiveSandboxSnapshot(): string {
+  return [
+    "# UniPi Workflow Sandbox Snapshot",
+    "This snapshot supersedes all prior UniPi workflow sandbox snapshots; use only this snapshot for workflow sandbox status and restrictions.",
+    "Status: inactive",
+    "No UniPi workflow sandbox is active. Prior workflow sandbox restrictions no longer apply.",
+  ].join("\n\n");
+}
 
-/** Whether sandbox is currently active */
-let sandboxActive = false;
+function latestEffectiveSandboxSnapshot(
+  branch: SessionEntry[],
+): EffectiveSandboxSnapshot | undefined {
+  const messages = buildSessionContext(branch).messages;
+  for (let index = messages.length - 1; index >= 0; index--) {
+    const message = messages[index];
+    if (message.role === "custom" && message.customType === WORKFLOW_SANDBOX_SNAPSHOT_TYPE) {
+      return {
+        content: message.content,
+        details: message.details as WorkflowSandboxSnapshotDetails | undefined,
+      };
+    }
+  }
+  return undefined;
+}
 
-/** Current sandbox level (null = no sandbox) */
-let currentSandboxLevel: SandboxLevel | null = null;
+/** Find state that may survive only as prose inside a compaction summary. */
+function latestHistoricalSandboxSnapshot(
+  branch: SessionEntry[],
+): EffectiveSandboxSnapshot | undefined {
+  for (let index = branch.length - 1; index >= 0; index--) {
+    const entry = branch[index];
+    if (entry.type === "custom_message" && entry.customType === WORKFLOW_SANDBOX_SNAPSHOT_TYPE) {
+      return {
+        content: entry.content,
+        details: entry.details as WorkflowSandboxSnapshotDetails | undefined,
+      };
+    }
+  }
+  return undefined;
+}
 
-/** Current active tools after sandbox filtering */
-let currentSandboxTools: string[] | null = null;
+function isActiveSnapshot(snapshot: EffectiveSandboxSnapshot): boolean {
+  if (typeof snapshot.details?.active === "boolean") return snapshot.details.active;
+  return typeof snapshot.content === "string" && snapshot.content.includes("Status: active");
+}
 
 export default function (pi: ExtensionAPI) {
+  const workflowLifecycle = new WorkflowLifecycle();
+  let ralphDetected = false;
+  let sandboxCommand: string | null = null;
 
-  // Register all workflow commands
   registerWorkflowCommands(pi, {
     isRalphDetected: () => ralphDetected,
-    getActiveTools: () => pi.getActiveTools(),
-    setActiveTools: (tools: string[], level: SandboxLevel) => {
-      pi.setActiveTools(tools);
-      sandboxActive = true;
-      currentSandboxLevel = level;
-      currentSandboxTools = tools;
+    activateSandbox: (event) => {
+      if (!workflowLifecycle.start(event)) return false;
+      sandboxCommand = event.command;
+      emitEvent(pi, UNIPI_EVENTS.WORKFLOW_START, event);
+      return true;
     },
-    saveTools: (tools: string[]) => {
-      savedTools = tools;
+    abortWorkflow: () => {
+      sandboxCommand = null;
+      workflowLifecycle.reset();
     },
   });
 
-  // Block tool calls that violate sandbox
+  // Keep tool schemas/order stable and enforce only the existing blocked names.
   pi.on("tool_call", async (event, _ctx) => {
-    if (!sandboxActive || !currentSandboxLevel) return;
+    if (!sandboxCommand) return;
 
-    const allowed = currentSandboxTools ?? [];
-    if (!allowed.includes(event.toolName)) {
+    const level = getSandboxLevel(sandboxCommand);
+    if (!isToolAllowed(level, event.toolName)) {
+      const blocked = getBlockedToolsForLevel(level);
       return {
         block: true,
-        reason: `Tool "${event.toolName}" is not allowed in ${currentSandboxLevel} sandbox. Allowed: ${allowed.join(", ")}`,
+        reason: `Tool "${event.toolName}" is not allowed in ${level} sandbox. Blocked: ${blocked.join(", ")}`,
       };
     }
   });
 
-  // Inject sandbox constraints into system prompt so LLM knows its limits
-  pi.on("before_agent_start", async (event, _ctx) => {
-    if (!sandboxActive || !currentSandboxLevel) return;
-
-    const allowed = currentSandboxTools ?? pi.getActiveTools();
-    const blocked = getBlockedToolsForLevel(currentSandboxLevel);
+  // Persist hidden append-only sandbox state without mutating the system prompt.
+  pi.on("before_agent_start", async (_event, ctx) => {
+    const branch = ctx.sessionManager.getBranch();
+    const latest = latestEffectiveSandboxSnapshot(branch);
+    const historical = latestHistoricalSandboxSnapshot(branch);
 
-    const blockedLine = blocked.length > 0
-      ? `\nBlocked tools: ${blocked.join(", ")} — removed from your tool list.`
-      : "\nNo tools were blocked by this sandbox.";
-    const base = `\n\n<sandbox>\nSandbox mode: ${currentSandboxLevel}.\nAvailable tools: ${allowed.join(", ")}.${blockedLine}`;
+    if (sandboxCommand) {
+      const level = getSandboxLevel(sandboxCommand);
+      const content = formatActiveSandboxSnapshot(sandboxCommand, level);
+      if (latest?.content === content) return undefined;
 
-    if (currentSandboxLevel === "brainstorm") {
       return {
-        systemPrompt:
-          event.systemPrompt +
-          base +
-          `\nThe write tool is available but restricted to .unipi/docs/specs/ only.\nbash is available ONLY for specific setup use case (e.g., git init, mkdir). Do NOT use bash for reading files or listing directories — use grep, find, ls instead.\nDo NOT attempt to call blocked tools. Do NOT output tool call XML for them.\nIf the user requests an action that requires a blocked tool, respond that you do not have access.\n</sandbox>`,
+        message: {
+          customType: WORKFLOW_SANDBOX_SNAPSHOT_TYPE,
+          content,
+          display: false,
+          details: {
+            active: true,
+            command: sandboxCommand,
+            level,
+          } satisfies WorkflowSandboxSnapshotDetails,
+        },
       };
     }
 
-    if (currentSandboxLevel === "write_unipi") {
-      return {
-        systemPrompt:
-          event.systemPrompt +
-          base +
-          `\nWrite tool is restricted to .unipi/docs/ only (specs and plans).\nUse grep, find, ls for file discovery — do NOT guess filenames.\nbash is blocked — use read, write, edit, grep, find, ls only.\nDo NOT attempt to call blocked tools. Do NOT output tool call XML for them.\nIf the user requests an action that requires a blocked tool, respond that you do not have access.\n</sandbox>`,
-      };
-    }
+    // A clean session gets no marker. Only an effective active snapshot needs
+    // an append-only inactive successor after agent_end completes the workflow.
+    const prior = latest ?? historical;
+    if (!prior || !isActiveSnapshot(prior)) return undefined;
 
     return {
-      systemPrompt:
-        event.systemPrompt +
-        base +
-        `\nDo NOT attempt to call blocked tools. Do NOT output tool call XML for them.\nIf the user requires an action that requires a blocked tool, respond that you do not have access.\n</sandbox>`,
+      message: {
+        customType: WORKFLOW_SANDBOX_SNAPSHOT_TYPE,
+        content: formatInactiveSandboxSnapshot(),
+        display: false,
+        details: {
+          active: false,
+        } satisfies WorkflowSandboxSnapshotDetails,
+      },
     };
   });
 
-  // Restore tools when agent finishes
-  pi.on("agent_end", async (_event, _ctx) => {
-    if (sandboxActive && savedTools) {
-      pi.setActiveTools(savedTools);
-      savedTools = null;
-      sandboxActive = false;
-      currentSandboxLevel = null;
-      currentSandboxTools = null;
-    }
+  // Pi 0.80.2 compatibility: agent_end remains the workflow completion boundary.
+  pi.on("agent_end", async (event, _ctx) => {
+    const completedWorkflow = workflowLifecycle.complete(event.messages);
+    if (!completedWorkflow) return;
+
+    sandboxCommand = null;
+    emitEvent(pi, UNIPI_EVENTS.WORKFLOW_END, completedWorkflow);
   });
 
-  // Announce module presence on session start
+  // Announce module presence on session start.
   pi.on("session_start", async (_event, ctx) => {
-    // Initialize .unipi directory structure
     initUnipiDirs();
 
-    // Emit MODULE_READY
     emitEvent(pi, UNIPI_EVENTS.MODULE_READY, {
       name: MODULES.WORKFLOW,
       version: VERSION,
@@ -132,36 +230,29 @@ export default function (pi: ExtensionAPI) {
       tools: [],
     });
 
-    // Listen for ralph module
     if (!ralphDetected) {
       try {
-        // Check if ralph tools exist (indicates @unipi/ralph is loaded)
         const allTools = pi.getAllTools();
-        ralphDetected = allTools.some((t) => t.name === "ralph_start");
+        ralphDetected = allTools.some((tool) => tool.name === "ralph_start");
       } catch {
-        // Ignore — ralph not present
+        // Ignore — ralph not present.
       }
     }
 
-    // Show workflow status in UI
     if (ctx.hasUI) {
       const ralphStatus = ralphDetected ? "✓ rl" : "○ rl";
       ctx.ui.setStatus("unipi-workflow", `⚡ wf ${ralphStatus}`);
     }
   });
 
-  // Listen for ralph module ready event
   pi.events.on(UNIPI_EVENTS.MODULE_READY, (data) => {
     const event = data as { name?: string };
-    if (event?.name === MODULES.RALPH) {
-      ralphDetected = true;
-    }
+    if (event?.name === MODULES.RALPH) ralphDetected = true;
   });
 
-  // Clean up on shutdown
   pi.on("session_shutdown", async () => {
     ralphDetected = false;
-    savedTools = null;
-    sandboxActive = false;
+    sandboxCommand = null;
+    workflowLifecycle.reset();
   });
 }

package/lifecycle.ts

@@ -0,0 +1,43 @@
+import type { UnipiWorkflowEvent } from "@pi-unipi/core";
+
+interface WorkflowMessage {
+  role: string;
+  stopReason?: string;
+}
+
+export interface CompletedWorkflowEvent extends UnipiWorkflowEvent {
+  success: boolean;
+  durationMs: number;
+}
+
+/** Single-active workflow lifecycle state shared by slash handlers and agent_end. */
+export class WorkflowLifecycle {
+  private active: (UnipiWorkflowEvent & { startedAt: number }) | null = null;
+
+  constructor(private readonly now: () => number = Date.now) {}
+
+  start(event: UnipiWorkflowEvent): boolean {
+    if (this.active) return false;
+    this.active = { ...event, startedAt: this.now() };
+    return true;
+  }
+
+  complete(messages: WorkflowMessage[]): CompletedWorkflowEvent | undefined {
+    if (!this.active) return undefined;
+    const workflow = this.active;
+    this.active = null;
+    const finalAssistant = [...messages].reverse().find((message) => message.role === "assistant");
+    const success = finalAssistant?.stopReason !== "error" && finalAssistant?.stopReason !== "aborted";
+    return {
+      command: workflow.command,
+      fullCommand: workflow.fullCommand,
+      args: workflow.args,
+      success,
+      durationMs: this.now() - workflow.startedAt,
+    };
+  }
+
+  reset(): void {
+    this.active = null;
+  }
+}

package/package.json

@@ -1,11 +1,14 @@
 {
   "name": "@pi-unipi/workflow",
-  "version": "2.4.0",
+  "version": "2.5.0",
   "description": "Structured development workflow commands for Pi coding agent",
   "type": "module",
   "main": "index.ts",
   "license": "MIT",
   "author": "Neuron Mr White",
+  "scripts": {
+    "test": "npx bun test lifecycle.test.ts tests"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/Neuron-Mr-White/unipi.git",
@@ -19,6 +22,7 @@
   ],
   "files": [
     "*.ts",
+    "!*.test.ts",
     "skills/**/*",
     "README.md"
   ],
@@ -26,7 +30,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@pi-unipi/core": "2.4.0"
+    "@pi-unipi/core": "2.5.0"
   },
   "peerDependencies": {
     "@earendil-works/pi-ai": "^0.80.0",