@trevonistrevon/pi-loop 0.6.2 → 0.6.4

package/src/runtime/notification-runtime.ts

@@ -12,7 +12,7 @@ import {
   type ReducerNotification,
   reduceNotificationState,
 } from "../notification-reducer.js";
-import type { DynamicLoopState, Trigger } from "../types.js";
+import type { DynamicLoopState, Trigger, WorkflowRunState } from "../types.js";
 
 export interface LoopFireEvent {
   loopId: string;
@@ -21,8 +21,11 @@ export interface LoopFireEvent {
   timestamp: number;
   readOnly?: boolean;
   recurring?: boolean;
+  persistent?: boolean;
   autoTask?: boolean;
+  taskBacklog?: boolean;
   dynamic?: DynamicLoopState;
+  workflow?: WorkflowRunState;
 }
 
 export interface PendingNotification extends LoopFireEvent {
@@ -104,6 +107,24 @@ export function createNotificationRuntime(options: NotificationRuntimeOptions):
       ? "\n\nREAD-ONLY MODE — use only read tools (Read, TaskList, LoopList, MonitorList, etc.). No file writes, shell execution, or destructive changes."
       : "";
 
+    if (data.workflow) {
+      const state = data.workflow.definition.states[data.workflow.currentState];
+      const outcomes = Object.keys(state?.on ?? {});
+      const lines = [
+        `[pi-loop] Loop #${loopId} fired (workflow).${constraint}`,
+        `Goal: ${data.prompt || data.workflow.definition.initialState}`,
+        `State: ${data.workflow.currentState}`,
+      ];
+      if (state?.prompt) lines.push(`State instructions: ${state.prompt}`);
+      if (data.workflow.activeTaskId) lines.push(`Active task: #${data.workflow.activeTaskId}`);
+      if (outcomes.length > 0) lines.push(`Allowed outcomes: ${outcomes.join(", ")}`);
+      lines.push(
+        `Workflow lifecycle: Loop #${loopId} is an opt-in state controller. Do not call LoopDelete after this state.`,
+        "Before ending this turn, call WorkflowTransition exactly once with this workflow id and one allowed outcome. Include evidence for the branch decision. Terminal outcomes complete or pause the workflow automatically.",
+      );
+      return lines.join("\n");
+    }
+
     if (data.dynamic || (typeof data.trigger !== "string" && data.trigger?.type === "dynamic")) {
       const dynamic = data.dynamic;
       const lines = [
@@ -115,14 +136,22 @@ export function createNotificationRuntime(options: NotificationRuntimeOptions):
       if (dynamic?.metrics) lines.push(`Metrics: ${dynamic.metrics}`);
       if (dynamic?.doneCriteria) lines.push(`Done criteria: ${dynamic.doneCriteria}`);
       lines.push(
-        "Continue toward the goal. When done call LoopUpdate with status=\"completed\". If more work remains, call LoopUpdate with status=\"continue\" plus state/metrics. Omit nextInterval for idle-driven rewake; include nextInterval for a timed wake. If blocked, use status=\"paused\".",
+        `Loop lifecycle: Loop #${loopId} is the persistent controller for the overall goal. Do not call LoopDelete after this iteration.`,
+        "Before ending this turn, call LoopUpdate exactly once: use status=\"completed\" only when the overall goal and done criteria are satisfied; use status=\"continue\" when any work remains, with state/metrics and optional nextInterval; use status=\"paused\" only when genuinely blocked. Omit nextInterval for an idle-driven rewake.",
       );
       return lines.join("\n");
     }
 
+    const lifecycle = data.taskBacklog
+      ? `Backlog lifecycle: Loop #${loopId} is managed automatically. Do not call LoopDelete; when no pending tasks remain, report that and end this iteration.`
+      : (data.persistent ?? data.recurring)
+        ? `Loop lifecycle: Loop #${loopId} is recurring and remains active after this iteration. Do not call LoopDelete or pause it merely because this run finished, found no changes, or has no immediate work. Stop it only when the user or the loop prompt explicitly requires cancellation.`
+        : `Loop lifecycle: Loop #${loopId} is a one-shot wake and cleanup is automatic. Do not call LoopDelete.`;
+
     return [
       `[pi-loop] Loop #${loopId} fired (${triggerInfo}).${constraint}`,
       prompt,
+      lifecycle,
     ].join("\n");
   }
 
@@ -154,9 +183,12 @@ export function createNotificationRuntime(options: NotificationRuntimeOptions):
         loopId: notification.loopId,
         trigger: notification.trigger,
         recurring: notification.recurring,
+        persistent: notification.persistent,
         readOnly: notification.readOnly,
         autoTask: notification.autoTask,
+        taskBacklog: notification.taskBacklog,
         dynamic: notification.dynamic,
+        workflow: notification.workflow,
         timestamp: notification.timestamp,
       },
     }, {

package/src/runtime/session-runtime.ts

@@ -62,8 +62,11 @@ export function registerSessionRuntimeHooks(options: SessionRuntimeOptions): voi
     if (heartbeatTimer) return;
     heartbeatTimer = setInterval(() => {
       // Swallow pump failures so a transient error never surfaces as an
-      // unhandled rejection; the next tick retries.
-      void pumpLoops().catch(() => {});
+      // unhandled rejection; repaint still runs so cleared harness UI heals.
+      void pumpLoops()
+        .catch(() => {})
+        .then(() => widget.update())
+        .catch(() => {});
     }, HEARTBEAT_MS);
     heartbeatTimer.unref?.();
   }
@@ -92,7 +95,6 @@ export function registerSessionRuntimeHooks(options: SessionRuntimeOptions): voi
       getStore().expireEventLoops(sessionStartedAt);
       getTriggerSystem().start();
       ensureHeartbeat();
-      widget.update();
     }
   }
 
@@ -110,6 +112,16 @@ export function registerSessionRuntimeHooks(options: SessionRuntimeOptions): voi
     getScheduler().pump(Date.now(), (entry) => !pendingTasks.has(entry.id));
   }
 
+  pi.on("session_start", async (_event, ctx) => {
+    setLatestCtx(ctx);
+    setSessionId(ctx.sessionManager.getSessionId());
+    widget.setUICtx(ctx.ui);
+    upgradeStoreIfNeeded(ctx);
+    ensureHeartbeat();
+    showPersistedLoops();
+    widget.update();
+  });
+
   pi.on("turn_start", async (_event, ctx) => {
     setLatestCtx(ctx);
     setSessionId(ctx.sessionManager.getSessionId());

package/src/runtime/task-backlog-runtime.ts

@@ -17,7 +17,7 @@ import {
 } from "./loop-events.js";
 
 export const AUTO_TASK_WORKER_THRESHOLD = 5;
-export const AUTO_TASK_WORKER_PROMPT = "Run TaskList, pick next pending task, mark it in_progress, implement it, run validation, complete it. If no pending tasks remain, call LoopDelete on your own loop ID.";
+export const AUTO_TASK_WORKER_PROMPT = "Run TaskList, pick next pending task, mark it in_progress, implement it, run validation, and complete it. If no pending tasks remain, report that and end this iteration; pi-loop manages the worker lifecycle automatically.";
 
 export interface TaskBacklogRuntimeOptions {
   getLoops: () => LoopEntry[];

package/src/runtime/task-events.ts

@@ -1,5 +1,5 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import type { TaskEntry, TaskStatus } from "../task-types.js";
+import type { TaskEntry, TaskStatus, TaskWorkflowLink } from "../task-types.js";
 
 export type NativeTaskEventName =
   | "tasks:created"
@@ -19,6 +19,7 @@ export interface NativeTaskEventPayload {
   updatedAt: number;
   completedAt?: number;
   metadata?: Record<string, unknown>;
+  workflow?: TaskWorkflowLink;
 }
 
 export function emitNativeTaskEvent(
@@ -37,5 +38,6 @@ export function emitNativeTaskEvent(
     updatedAt: entry.updatedAt,
     completedAt: entry.completedAt,
     metadata: entry.metadata,
+    workflow: entry.workflow,
   } satisfies NativeTaskEventPayload);
 }

package/src/runtime/task-rpc.ts

@@ -7,9 +7,11 @@ import {
   type PingReply,
   replyChannel,
   TASKS_RPC,
+  type UpdateTaskReply,
 } from "../rpc/channels.js";
 import { type RpcReply, rpcCall } from "../rpc/cross-extension-rpc.js";
 import type { TaskStore } from "../task-store.js";
+import type { TaskWorkflowLink } from "../task-types.js";
 import type { LoopEntry } from "../types.js";
 import { NATIVE_TASKS_PROVIDER } from "./native-task-rpc.js";
 import { emitNativeTaskEvent } from "./task-events.js";
@@ -20,7 +22,9 @@ export interface TaskRuntimeBridgeOptions {
   setTasksAvailable: (available: boolean) => void;
   getNativeTaskStore: () => TaskStore | undefined;
   onNativeTaskCreated?: (taskStore: TaskStore) => void;
+  onNativeTaskCompleted?: (taskStore: TaskStore) => Promise<void> | void;
   onNativeTasksPruned?: (taskStore: TaskStore) => Promise<void> | void;
+  isDetectionSettled?: () => boolean;
   /** Called when a detection window opens. */
   onDetectionStarted?: () => void;
   /** Called when a detection window closes (provider found or probe timed out). */
@@ -31,6 +35,8 @@ export interface TaskRuntimeBridgeOptions {
 export interface TaskRuntimeBridge {
   checkTasksVersion(): void;
   autoCreateTask(entry: LoopEntry): Promise<string | undefined>;
+  createWorkflowTask(entry: LoopEntry): Promise<string | undefined>;
+  completeWorkflowTask(taskId: string): Promise<boolean>;
   hasPendingTasks(): Promise<number>;
   cleanDoneTasks(): Promise<void>;
 }
@@ -42,7 +48,9 @@ export function createTaskRuntimeBridge(options: TaskRuntimeBridgeOptions): Task
     setTasksAvailable,
     getNativeTaskStore,
     onNativeTaskCreated,
+    onNativeTaskCompleted,
     onNativeTasksPruned,
+    isDetectionSettled,
     onDetectionStarted,
     onDetectionSettled,
     debug,
@@ -105,6 +113,62 @@ export function createTaskRuntimeBridge(options: TaskRuntimeBridgeOptions): Task
     return task.id;
   }
 
+  async function createWorkflowTask(entry: LoopEntry): Promise<string | undefined> {
+    const workflow = entry.workflow;
+    if (!workflow) return undefined;
+    const state = workflow.definition.states[workflow.currentState];
+    if (!state?.task || state.terminal) return undefined;
+
+    const link: TaskWorkflowLink = {
+      loopId: entry.id,
+      stateId: workflow.currentState,
+      transitionSeq: workflow.transitionSeq,
+    };
+    const metadata = { workflow: link };
+    if (isTasksAvailable()) {
+      try {
+        const reply = await rpcCall<CreateTaskReply>(pi.events, TASKS_RPC.create, {
+          subject: state.task.subject,
+          description: state.task.description,
+          metadata,
+        }, 5000);
+        return reply.id;
+      } catch {
+        return undefined;
+      }
+    }
+
+    if (isDetectionSettled && !isDetectionSettled()) return undefined;
+    const nativeTaskStore = getNativeTaskStore();
+    if (!nativeTaskStore) return undefined;
+    const task = nativeTaskStore.create(state.task.subject, state.task.description, metadata, link);
+    emitNativeTaskEvent(pi, "tasks:created", task);
+    onNativeTaskCreated?.(nativeTaskStore);
+    return task.id;
+  }
+
+  async function completeWorkflowTask(taskId: string): Promise<boolean> {
+    if (isTasksAvailable()) {
+      try {
+        await rpcCall<UpdateTaskReply>(pi.events, TASKS_RPC.update, { id: taskId, status: "completed" }, 5000);
+        return true;
+      } catch {
+        return false;
+      }
+    }
+
+    const nativeTaskStore = getNativeTaskStore();
+    const existing = nativeTaskStore?.get(taskId);
+    if (!nativeTaskStore || !existing) return false;
+    if (existing.status === "completed") return true;
+
+    const completed = nativeTaskStore.complete(taskId);
+    if (!completed) return false;
+    emitNativeTaskEvent(pi, "tasks:completed", completed, existing.status);
+    await onNativeTaskCompleted?.(nativeTaskStore);
+    return true;
+  }
+
   async function hasPendingTasks(): Promise<number> {
     if (isTasksAvailable()) {
       // -1 is this bridge's "unknown" sentinel, consumed by notification-runtime;
@@ -140,6 +204,8 @@ export function createTaskRuntimeBridge(options: TaskRuntimeBridgeOptions): Task
   return {
     checkTasksVersion,
     autoCreateTask,
+    createWorkflowTask,
+    completeWorkflowTask,
     hasPendingTasks,
     cleanDoneTasks,
   };

package/src/store.ts

@@ -2,7 +2,8 @@ import { homedir } from "node:os";
 import { join } from "node:path";
 import { type LoopReducerEvent, type LoopReducerState, reduceLoopState } from "./loop-reducer.js";
 import { ReducerBackedStore } from "./reducer-backed-store.js";
-import type { DynamicLoopState, LoopDeletionTombstone, LoopDeletionTombstoneInput, LoopEntry, LoopStoreData, Trigger } from "./types.js";
+import type { DynamicLoopState, LoopDeletionTombstone, LoopDeletionTombstoneInput, LoopEntry, LoopStoreData, Trigger, WorkflowDefinition, WorkflowTerminalStatus } from "./types.js";
+import { transitionWorkflowRun, validateWorkflowDefinition, type WorkflowTransitionInput } from "./workflow-reducer.js";
 
 const LOOPS_DIR = join(homedir(), ".pi", "loops");
 const MAX_LOOPS = 25;
@@ -25,11 +26,16 @@ export class LoopStore extends ReducerBackedStore<LoopEntry, LoopReducerState, L
     );
   }
 
-  create(trigger: Trigger, prompt: string, opts: { recurring: boolean; autoTask?: boolean; taskBacklog?: boolean; readOnly?: boolean; maxFires?: number; dynamic?: Partial<DynamicLoopState> }): LoopEntry {
+  create(trigger: Trigger, prompt: string, opts: { recurring: boolean; autoTask?: boolean; taskBacklog?: boolean; readOnly?: boolean; maxFires?: number; dynamic?: Partial<DynamicLoopState>; workflow?: WorkflowDefinition }): LoopEntry {
     return this.withLock(() => {
       if (this.entries.size >= MAX_LOOPS) {
         throw new Error(`Maximum of ${MAX_LOOPS} loops reached. Delete some before creating new ones.`);
       }
+      if (opts.workflow) {
+        if (trigger.type !== "dynamic") throw new Error("Workflow loops require a dynamic trigger.");
+        const validationError = validateWorkflowDefinition(opts.workflow);
+        if (validationError) throw new Error(`Invalid workflow: ${validationError}`);
+      }
       const now = Date.now();
       this.applyReducerEvent({
         type: "LOOP_CREATED",
@@ -45,6 +51,7 @@ export class LoopStore extends ReducerBackedStore<LoopEntry, LoopReducerState, L
           readOnly: opts.readOnly,
           maxFires: opts.maxFires,
           dynamic: opts.dynamic,
+          workflow: opts.workflow,
         },
       });
       return this.entries.get(String(this.nextId - 1))!;
@@ -154,6 +161,48 @@ export class LoopStore extends ReducerBackedStore<LoopEntry, LoopReducerState, L
     });
   }
 
+  transitionWorkflow(id: string, input: WorkflowTransitionInput): { entry?: LoopEntry; applied: boolean; error?: string; terminal?: WorkflowTerminalStatus } {
+    return this.withLock(() => {
+      const entry = this.entries.get(id);
+      if (!entry) return { applied: false, error: `Loop #${id} not found` };
+      if (!entry.workflow) return { applied: false, error: `Loop #${id} is not a workflow loop` };
+
+      const result = transitionWorkflowRun(entry.workflow, input, Date.now());
+      if (!result.applied) return { applied: false, error: result.error };
+
+      this.applyReducerEvent({
+        type: "LOOP_WORKFLOW_TRANSITION",
+        at: result.run.stateEnteredAt,
+        source: "tool",
+        entityType: "loop",
+        entityId: id,
+        payload: {
+          id,
+          outcome: input.outcome,
+          evidence: input.evidence,
+          activeTaskId: input.activeTaskId,
+        },
+      });
+      return { entry: this.entries.get(id), applied: true, terminal: result.terminal };
+    });
+  }
+
+  setWorkflowActiveTask(id: string, taskId?: string): LoopEntry | undefined {
+    return this.withLock(() => {
+      const entry = this.entries.get(id);
+      if (!entry?.workflow) return undefined;
+      this.applyReducerEvent({
+        type: "LOOP_WORKFLOW_TASK_SET",
+        at: Date.now(),
+        source: "tool",
+        entityType: "loop",
+        entityId: id,
+        payload: { id, taskId },
+      });
+      return this.entries.get(id);
+    });
+  }
+
   getDeletionTombstone(id: string): LoopDeletionTombstone | undefined {
     const tombstone = this.tombstones.get(id);
     if (!tombstone) return undefined;

package/src/task-reducer.ts

@@ -1,4 +1,4 @@
-import type { TaskEntry } from "./task-types.js";
+import type { TaskEntry, TaskWorkflowLink } from "./task-types.js";
 
 export interface TaskReducerState {
   nextId: number;
@@ -16,6 +16,7 @@ export type TaskReducerEvent =
       subject: string;
       description: string;
       metadata?: Record<string, unknown>;
+      workflow?: TaskWorkflowLink;
     };
   }
   | {
@@ -87,6 +88,7 @@ export function reduceTaskState(state: TaskReducerState, event: TaskReducerEvent
       createdAt: event.at,
       updatedAt: event.at,
       metadata: event.payload.metadata,
+      workflow: event.payload.workflow,
     };
     next.tasksById[id] = task;
     return {

package/src/task-store.ts

@@ -2,7 +2,7 @@ import { homedir } from "node:os";
 import { join } from "node:path";
 import { ReducerBackedStore } from "./reducer-backed-store.js";
 import { reduceTaskState, type TaskReducerEvent, type TaskReducerState } from "./task-reducer.js";
-import type { TaskEntry, TaskStoreData } from "./task-types.js";
+import type { TaskEntry, TaskStoreData, TaskWorkflowLink } from "./task-types.js";
 
 const TASKS_DIR = join(homedir(), ".pi", "tasks");
 const MAX_TASKS = 200;
@@ -22,7 +22,7 @@ export class TaskStore extends ReducerBackedStore<TaskEntry, TaskReducerState, T
     );
   }
 
-  create(subject: string, description: string, metadata?: Record<string, unknown>): TaskEntry {
+  create(subject: string, description: string, metadata?: Record<string, unknown>, workflow?: TaskWorkflowLink): TaskEntry {
     return this.withLock(() => {
       if (this.entries.size >= MAX_TASKS) {
         throw new Error(`Maximum of ${MAX_TASKS} tasks reached. Delete some before creating new ones.`);
@@ -33,7 +33,7 @@ export class TaskStore extends ReducerBackedStore<TaskEntry, TaskReducerState, T
         at: now,
         source: "tool",
         entityType: "task",
-        payload: { subject, description, metadata },
+        payload: { subject, description, metadata, workflow },
       });
       return this.entries.get(String(this.nextId - 1))!;
     });

package/src/task-types.ts

@@ -1,5 +1,11 @@
 export type TaskStatus = "pending" | "in_progress" | "completed";
 
+export interface TaskWorkflowLink {
+  loopId: string;
+  stateId: string;
+  transitionSeq: number;
+}
+
 export interface TaskEntry {
   id: string;
   subject: string;
@@ -9,6 +15,7 @@ export interface TaskEntry {
   updatedAt: number;
   completedAt?: number;
   metadata?: Record<string, unknown>;
+  workflow?: TaskWorkflowLink;
 }
 
 export interface TaskStoreData {