@trevonistrevon/pi-loop 0.6.2 → 0.6.4

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## [0.6.4](https://github.com/trvon/pi-loop/compare/pi-loop-v0.6.3...pi-loop-v0.6.4) (2026-07-22)
+
+
+### Features
+
+* **ui:** render compact status cards ([02925ae](https://github.com/trvon/pi-loop/commit/02925ae2af1404fd86f8daab4f5ecef3782550e3))
+* **workflow:** add state loop foundation ([2fddbe9](https://github.com/trvon/pi-loop/commit/2fddbe904cf3b413618572b8488e8aa9357590cd))
+* **workflow:** add task-driven state loops ([f174211](https://github.com/trvon/pi-loop/commit/f1742117a66c9700b08427aa6528234546f5b9cc))
+
+
+### Bug Fixes
+
+* **deps:** raise Pi security baseline ([5f538cf](https://github.com/trvon/pi-loop/commit/5f538cfb44cbb5e254ec87b5cd35f6ece1535fda))
+
+## [0.6.3](https://github.com/trvon/pi-loop/compare/pi-loop-v0.6.2...pi-loop-v0.6.3) (2026-07-17)
+
+
+### Bug Fixes
+
+* **loop:** prevent premature self-deletion ([6049e15](https://github.com/trvon/pi-loop/commit/6049e1599d9c6c1ab99a9eada72ec75307f25ca1))
+* **ui:** restore loop status after resets ([da580f0](https://github.com/trvon/pi-loop/commit/da580f0d2f5ac414bc3cd884e27b757decd44b5d))
+
 ## [0.6.2](https://github.com/trvon/pi-loop/compare/pi-loop-v0.6.1...pi-loop-v0.6.2) (2026-07-17)
 
 

package/README.md

@@ -38,7 +38,7 @@ MonitorStop monitorId="1"
 
 ## What it provides
 
-- Cron, event, hybrid, and dynamic goal loops
+- Cron, event, hybrid, dynamic goal, and opt-in workflow loops
 - Idle-safe agent re-wakes with dynamic-loop restart/session-switch recovery
 - Background command monitoring with buffered output and `onDone` wakes
 - Optional `pi-tasks` integration and a native task fallback
@@ -50,7 +50,8 @@ MonitorStop monitorId="1"
 |---|---|
 | `/loop` | Create or manage scheduled, event, and dynamic goal loops |
 | `/tasks` | Manage native fallback tasks when `pi-tasks` is absent |
-| `LoopCreate`, `LoopList`, `LoopUpdate`, `LoopDelete` | Create and control loops |
+| `LoopCreate`, `LoopList`, `LoopUpdate`, `LoopDelete` | Create and control ordinary loops |
+| `WorkflowCreate`, `WorkflowList`, `WorkflowTransition` | Create and advance opt-in task-driven workflows |
 | `MonitorCreate`, `MonitorList`, `MonitorStop` | Run and inspect background commands |
 | `TaskCreate`, `TaskList`, `TaskUpdate`, `TaskDelete` | Native fallback task management |
 

package/dist/api.d.ts

@@ -8,4 +8,5 @@ export { type HandleRpcOptions, handleRpc, PROTOCOL_VERSION, RpcError, type RpcE
 export { NATIVE_TASKS_PROVIDER } from "./runtime/native-task-rpc.js";
 export { resolveLoopStorePath, resolveTaskStorePath } from "./runtime/scope.js";
 export { TaskStore } from "./task-store.js";
-export type { TaskEntry, TaskStatus, TaskStoreData } from "./task-types.js";
+export type { TaskEntry, TaskStatus, TaskStoreData, TaskWorkflowLink } from "./task-types.js";
+export type { WorkflowDefinition, WorkflowRunState, WorkflowStateDefinition, WorkflowTaskDefinition, WorkflowTerminalStatus, WorkflowTransitionRecord, } from "./types.js";

package/dist/index.js

@@ -116,6 +116,10 @@ export default function (pi) {
         onDetectionSettled: () => {
             tasksDetectionSettled = true;
         },
+        isDetectionSettled: () => tasksDetectionSettled,
+        onNativeTaskCompleted: () => {
+            widget.update();
+        },
         debug,
     });
     // The RPC server registers at init (not behind the 6s tool-fallback timer) so
@@ -181,7 +185,9 @@ export default function (pi) {
             timestamp: Date.now(),
             readOnly: entry.readOnly,
             recurring: false,
+            persistent: entry.recurring,
             autoTask: true,
+            taskBacklog: entry.taskBacklog,
         });
         return true;
     }
@@ -250,8 +256,11 @@ export default function (pi) {
             timestamp: firedAt,
             readOnly: firedEntry.readOnly,
             recurring: firedEntry.recurring,
+            persistent: firedEntry.recurring,
             autoTask: firedEntry.autoTask,
+            taskBacklog: firedEntry.taskBacklog,
             dynamic: firedEntry.dynamic,
+            workflow: firedEntry.workflow,
         });
     }
     // ── Session lifecycle ──
@@ -311,6 +320,11 @@ export default function (pi) {
         },
         maybeBootstrapTaskLoop,
         isTaskSystemReady: () => tasksAvailable || nativeTasksRegistered,
+        onDynamicLoopActivated: (entry) => {
+            onLoopFire(entry);
+        },
+        createWorkflowTask: (entry) => taskRuntime.createWorkflowTask(entry),
+        completeWorkflowTask: (taskId) => taskRuntime.completeWorkflowTask(taskId),
     });
     function handleMonitorDoneLoop(doneLoop, monitorId) {
         monitorOnDoneRuntime.register(doneLoop, monitorId);

package/dist/loop-reducer.d.ts

@@ -1,4 +1,4 @@
-import type { DynamicLoopState, LoopEntry, Trigger } from "./types.js";
+import type { DynamicLoopState, LoopEntry, Trigger, WorkflowDefinition } from "./types.js";
 export declare const MAX_LOOP_EXPIRY_MS: number;
 /**
  * Whether a loop has reached its fire cap. Single source of truth for the
@@ -27,6 +27,7 @@ export type LoopReducerEvent = {
         readOnly?: boolean;
         maxFires?: number;
         dynamic?: Partial<DynamicLoopState>;
+        workflow?: WorkflowDefinition;
     };
 } | {
     type: "LOOP_PAUSED" | "LOOP_RESUMED" | "LOOP_FIRED" | "LOOP_DELETED" | "LOOP_MAX_FIRES_REACHED" | "LOOP_BACKLOG_EMPTY";
@@ -58,6 +59,28 @@ export type LoopReducerEvent = {
         prompt?: string;
         dynamic: Partial<DynamicLoopState>;
     };
+} | {
+    type: "LOOP_WORKFLOW_TRANSITION";
+    at: number;
+    source: ReducerSource;
+    entityType?: "loop";
+    entityId?: string;
+    payload: {
+        id: string;
+        outcome: string;
+        evidence?: string;
+        activeTaskId?: string;
+    };
+} | {
+    type: "LOOP_WORKFLOW_TASK_SET";
+    at: number;
+    source: ReducerSource;
+    entityType?: "loop";
+    entityId?: string;
+    payload: {
+        id: string;
+        taskId?: string;
+    };
 };
 export type LoopReducerEffect = {
     type: "PERSIST_LOOP";

package/dist/loop-reducer.js

@@ -1,3 +1,4 @@
+import { createWorkflowRun, transitionWorkflowRun } from "./workflow-reducer.js";
 export const MAX_LOOP_EXPIRY_MS = 7 * 24 * 60 * 60 * 1000;
 /**
  * Whether a loop has reached its fire cap. Single source of truth for the
@@ -44,6 +45,7 @@ export function reduceLoopState(state, event) {
                     lastUpdatedAt: event.payload.dynamic?.lastUpdatedAt ?? event.at,
                 }
                 : undefined,
+            workflow: event.payload.workflow ? createWorkflowRun(event.payload.workflow, event.at) : undefined,
         };
         next.loopsById[id] = loop;
         return {
@@ -94,6 +96,35 @@ export function reduceLoopState(state, event) {
         };
         loop.updatedAt = event.at;
     }
+    if (event.type === "LOOP_WORKFLOW_TRANSITION") {
+        if (!loop.workflow)
+            return { state, effects: [] };
+        const result = transitionWorkflowRun(loop.workflow, {
+            outcome: event.payload.outcome,
+            evidence: event.payload.evidence,
+            activeTaskId: event.payload.activeTaskId,
+        }, event.at);
+        if (!result.applied)
+            return { state, effects: [] };
+        loop.workflow = result.run;
+        loop.dynamic = {
+            goal: loop.dynamic?.goal ?? loop.prompt,
+            state: result.run.currentState,
+            metrics: loop.dynamic?.metrics,
+            doneCriteria: loop.dynamic?.doneCriteria,
+            iteration: (loop.dynamic?.iteration ?? 0) + 1,
+            nextWakeAt: undefined,
+            awaitingUpdate: false,
+            lastUpdatedAt: event.at,
+        };
+        loop.updatedAt = event.at;
+    }
+    if (event.type === "LOOP_WORKFLOW_TASK_SET") {
+        if (!loop.workflow)
+            return { state, effects: [] };
+        loop.workflow = { ...loop.workflow, activeTaskId: event.payload.taskId };
+        loop.updatedAt = event.at;
+    }
     next.loopsById[id] = loop;
     return {
         state: next,

package/dist/notification-reducer.d.ts

@@ -1,4 +1,4 @@
-import type { DynamicLoopState } from "./types.js";
+import type { DynamicLoopState, WorkflowRunState } from "./types.js";
 type ReducerSource = "tool" | "command" | "scheduler" | "eventbus" | "monitor" | "session" | "coordinator" | "system";
 export interface ReducerNotification {
     key: string;
@@ -7,9 +7,12 @@ export interface ReducerNotification {
     timestamp: number;
     trigger: unknown;
     recurring?: boolean;
+    persistent?: boolean;
     autoTask?: boolean;
+    taskBacklog?: boolean;
     readOnly?: boolean;
     dynamic?: DynamicLoopState;
+    workflow?: WorkflowRunState;
 }
 export interface NotificationReducerState {
     notificationsByKey: Record<string, ReducerNotification>;

package/dist/runtime/notification-runtime.d.ts

@@ -1,5 +1,5 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import type { DynamicLoopState, Trigger } from "../types.js";
+import type { DynamicLoopState, Trigger, WorkflowRunState } from "../types.js";
 export interface LoopFireEvent {
     loopId: string;
     prompt: string;
@@ -7,8 +7,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 {
     key: string;

package/dist/runtime/notification-runtime.js

@@ -50,6 +50,23 @@ export function createNotificationRuntime(options) {
         const constraint = data.readOnly
             ? "\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 = [
@@ -63,12 +80,18 @@ export function createNotificationRuntime(options) {
                 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\".");
+            lines.push(`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");
     }
     function buildPendingNotification(data) {
@@ -97,9 +120,12 @@ export function createNotificationRuntime(options) {
                 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/dist/runtime/session-runtime.js

@@ -15,8 +15,11 @@ export function registerSessionRuntimeHooks(options) {
             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?.();
     }
@@ -45,7 +48,6 @@ export function registerSessionRuntimeHooks(options) {
             getStore().expireEventLoops(sessionStartedAt);
             getTriggerSystem().start();
             ensureHeartbeat();
-            widget.update();
         }
     }
     async function pumpLoops() {
@@ -66,6 +68,15 @@ export function registerSessionRuntimeHooks(options) {
         }
         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/dist/runtime/task-backlog-runtime.d.ts

@@ -2,7 +2,7 @@ import type { TaskStore } from "../task-store.js";
 import type { LoopDeletionTombstoneInput, LoopEntry, Trigger } from "../types.js";
 import { type LoopAutodeletedPayload, type TaskBacklogEmptyPayload } from "./loop-events.js";
 export declare const AUTO_TASK_WORKER_THRESHOLD = 5;
-export declare 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 declare 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[];
     createLoop: (trigger: Trigger, prompt: string, options: {

package/dist/runtime/task-backlog-runtime.js

@@ -2,7 +2,7 @@ import { createCoordinator, } from "../coordinator.js";
 import { reduceTaskBacklogEvent, } from "../task-backlog-coordinator.js";
 import { buildLoopAutodeletedPayload, buildTaskBacklogEmptyPayload, } 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 function createTaskBacklogRuntime(options) {
     const { getLoops, createLoop, deleteLoop, recordDeletionTombstone, addTrigger, removeTrigger, updateWidget, hasPendingTasks, bootstrapTaskLoop, triggerHasEventSource, emitLoopAutodeleted, emitTaskBacklogEmpty, debug, } = options;
     function isAutoTaskWorkerLoop(entry) {

package/dist/runtime/task-events.d.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" | "tasks:started" | "tasks:completed" | "tasks:reopened" | "tasks:updated" | "tasks:deleted";
 export interface NativeTaskEventPayload {
     taskId: string;
@@ -11,5 +11,6 @@ export interface NativeTaskEventPayload {
     updatedAt: number;
     completedAt?: number;
     metadata?: Record<string, unknown>;
+    workflow?: TaskWorkflowLink;
 }
 export declare function emitNativeTaskEvent(pi: ExtensionAPI, name: NativeTaskEventName, entry: TaskEntry, previousStatus?: TaskStatus): void;

package/dist/runtime/task-events.js

@@ -9,5 +9,6 @@ export function emitNativeTaskEvent(pi, name, entry, previousStatus) {
         updatedAt: entry.updatedAt,
         completedAt: entry.completedAt,
         metadata: entry.metadata,
+        workflow: entry.workflow,
     });
 }

package/dist/runtime/task-rpc.d.ts

@@ -7,7 +7,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). */
@@ -17,6 +19,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>;
 }

package/dist/runtime/task-rpc.js

@@ -4,7 +4,7 @@ import { rpcCall } from "../rpc/cross-extension-rpc.js";
 import { NATIVE_TASKS_PROVIDER } from "./native-task-rpc.js";
 import { emitNativeTaskEvent } from "./task-events.js";
 export function createTaskRuntimeBridge(options) {
-    const { pi, isTasksAvailable, setTasksAvailable, getNativeTaskStore, onNativeTaskCreated, onNativeTasksPruned, onDetectionStarted, onDetectionSettled, debug, } = options;
+    const { pi, isTasksAvailable, setTasksAvailable, getNativeTaskStore, onNativeTaskCreated, onNativeTaskCompleted, onNativeTasksPruned, isDetectionSettled, onDetectionStarted, onDetectionSettled, debug, } = options;
     let detectionEpoch = 0;
     function checkTasksVersion() {
         // Not rpcProbe: pi-loop's own native server also answers this ping, and a
@@ -62,6 +62,65 @@ export function createTaskRuntimeBridge(options) {
         onNativeTaskCreated?.(nativeTaskStore);
         return task.id;
     }
+    async function createWorkflowTask(entry) {
+        const workflow = entry.workflow;
+        if (!workflow)
+            return undefined;
+        const state = workflow.definition.states[workflow.currentState];
+        if (!state?.task || state.terminal)
+            return undefined;
+        const link = {
+            loopId: entry.id,
+            stateId: workflow.currentState,
+            transitionSeq: workflow.transitionSeq,
+        };
+        const metadata = { workflow: link };
+        if (isTasksAvailable()) {
+            try {
+                const reply = await rpcCall(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) {
+        if (isTasksAvailable()) {
+            try {
+                await rpcCall(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() {
         if (isTasksAvailable()) {
             // -1 is this bridge's "unknown" sentinel, consumed by notification-runtime;
@@ -96,6 +155,8 @@ export function createTaskRuntimeBridge(options) {
     return {
         checkTasksVersion,
         autoCreateTask,
+        createWorkflowTask,
+        completeWorkflowTask,
         hasPendingTasks,
         cleanDoneTasks,
     };

package/dist/store.d.ts

@@ -1,6 +1,7 @@
 import { type LoopReducerEvent, type LoopReducerState } 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 { type WorkflowTransitionInput } from "./workflow-reducer.js";
 export declare class LoopStore extends ReducerBackedStore<LoopEntry, LoopReducerState, LoopReducerEvent, LoopStoreData> {
     private tombstones;
     constructor(listIdOrPath?: string);
@@ -11,6 +12,7 @@ export declare class LoopStore extends ReducerBackedStore<LoopEntry, LoopReducer
         readOnly?: boolean;
         maxFires?: number;
         dynamic?: Partial<DynamicLoopState>;
+        workflow?: WorkflowDefinition;
     }): LoopEntry;
     pause(id: string): LoopEntry | undefined;
     resume(id: string): LoopEntry | undefined;
@@ -26,6 +28,13 @@ export declare class LoopStore extends ReducerBackedStore<LoopEntry, LoopReducer
         prompt?: string;
         dynamic: Partial<DynamicLoopState>;
     }): LoopEntry | undefined;
+    transitionWorkflow(id: string, input: WorkflowTransitionInput): {
+        entry?: LoopEntry;
+        applied: boolean;
+        error?: string;
+        terminal?: WorkflowTerminalStatus;
+    };
+    setWorkflowActiveTask(id: string, taskId?: string): LoopEntry | undefined;
     getDeletionTombstone(id: string): LoopDeletionTombstone | undefined;
     recordDeletionTombstone(id: string, input: LoopDeletionTombstoneInput): LoopDeletionTombstone | undefined;
     delete(id: string): boolean;

package/dist/store.js

@@ -2,6 +2,7 @@ import { homedir } from "node:os";
 import { join } from "node:path";
 import { reduceLoopState } from "./loop-reducer.js";
 import { ReducerBackedStore } from "./reducer-backed-store.js";
+import { transitionWorkflowRun, validateWorkflowDefinition } from "./workflow-reducer.js";
 const LOOPS_DIR = join(homedir(), ".pi", "loops");
 const MAX_LOOPS = 25;
 const TOMBSTONE_TTL_MS = 10 * 60 * 1000;
@@ -22,6 +23,13 @@ export class LoopStore extends ReducerBackedStore {
             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",
@@ -37,6 +45,7 @@ export class LoopStore extends ReducerBackedStore {
                     readOnly: opts.readOnly,
                     maxFires: opts.maxFires,
                     dynamic: opts.dynamic,
+                    workflow: opts.workflow,
                 },
             });
             return this.entries.get(String(this.nextId - 1));
@@ -142,6 +151,48 @@ export class LoopStore extends ReducerBackedStore {
             return this.entries.get(id);
         });
     }
+    transitionWorkflow(id, input) {
+        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, taskId) {
+        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) {
         const tombstone = this.tombstones.get(id);
         if (!tombstone)

package/dist/task-reducer.d.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;
     tasksById: Record<string, TaskEntry>;
@@ -13,6 +13,7 @@ export type TaskReducerEvent = {
         subject: string;
         description: string;
         metadata?: Record<string, unknown>;
+        workflow?: TaskWorkflowLink;
     };
 } | {
     type: "TASK_STARTED" | "TASK_COMPLETED" | "TASK_REOPENED" | "TASK_DELETED";

package/dist/task-reducer.js

@@ -16,6 +16,7 @@ export function reduceTaskState(state, event) {
             createdAt: event.at,
             updatedAt: event.at,
             metadata: event.payload.metadata,
+            workflow: event.payload.workflow,
         };
         next.tasksById[id] = task;
         return {

package/dist/task-store.d.ts

@@ -1,9 +1,9 @@
 import { ReducerBackedStore } from "./reducer-backed-store.js";
 import { 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";
 export declare class TaskStore extends ReducerBackedStore<TaskEntry, TaskReducerState, TaskReducerEvent, TaskStoreData> {
     constructor(listIdOrPath?: string);
-    create(subject: string, description: string, metadata?: Record<string, unknown>): TaskEntry;
+    create(subject: string, description: string, metadata?: Record<string, unknown>, workflow?: TaskWorkflowLink): TaskEntry;
     start(id: string): TaskEntry | undefined;
     complete(id: string): TaskEntry | undefined;
     reopen(id: string): TaskEntry | undefined;

package/dist/task-store.js

@@ -15,7 +15,7 @@ export class TaskStore extends ReducerBackedStore {
             deserialize: (data) => ({ nextId: data.nextId, entries: new Map(data.tasks.map((t) => [t.id, t])) }),
         }, listIdOrPath);
     }
-    create(subject, description, metadata) {
+    create(subject, description, metadata, workflow) {
         return this.withLock(() => {
             if (this.entries.size >= MAX_TASKS) {
                 throw new Error(`Maximum of ${MAX_TASKS} tasks reached. Delete some before creating new ones.`);
@@ -26,7 +26,7 @@ export class TaskStore extends ReducerBackedStore {
                 at: now,
                 source: "tool",
                 entityType: "task",
-                payload: { subject, description, metadata },
+                payload: { subject, description, metadata, workflow },
             });
             return this.entries.get(String(this.nextId - 1));
         });

package/dist/task-types.d.ts

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