@trevonistrevon/pi-loop 0.6.0 → 0.6.2

package/src/commands/loop-command.ts

@@ -3,13 +3,21 @@ import type {
   ExtensionCommandContext,
   ExtensionUIContext,
 } from "@earendil-works/pi-coding-agent";
-import { parseInterval } from "../loop-parse.js";
-import type { LoopEntry, Trigger } from "../types.js";
+import { formatTrigger } from "../loop-format.js";
+import { isValidCronExpression, parseInterval } from "../loop-parse.js";
+import type { DynamicLoopState, LoopEntry, Trigger } from "../types.js";
 
 interface LoopStoreLike {
   list(): LoopEntry[];
   get(id: string): LoopEntry | undefined;
-  create(trigger: Trigger, prompt: string, options?: Partial<LoopEntry>): LoopEntry;
+  create(trigger: Trigger, prompt: string, options: {
+    recurring: boolean;
+    autoTask?: boolean;
+    taskBacklog?: boolean;
+    readOnly?: boolean;
+    maxFires?: number;
+    dynamic?: Partial<DynamicLoopState>;
+  }): LoopEntry;
   pause(id: string): LoopEntry | undefined;
   resume(id: string): LoopEntry | undefined;
   delete(id: string): boolean;
@@ -25,35 +33,85 @@ export interface LoopCommandOptions {
   getStore: () => LoopStoreLike;
   getTriggerSystem: () => TriggerSystemLike;
   updateWidget: () => void;
+  onDynamicLoopActivated?: (entry: LoopEntry) => void;
 }
 
-export function registerLoopCommand(options: LoopCommandOptions): void {
-  const { pi, getStore, getTriggerSystem, updateWidget } = options;
+type LoopCommandRoute =
+  | { type: "menu" }
+  | { type: "event"; source: string; prompt: string }
+  | { type: "cron"; interval: string; prompt: string; notifyEvery: boolean }
+  | { type: "invalid-cron"; interval: string }
+  | { type: "missing-interval-prompt" }
+  | { type: "dynamic"; goal: string };
+
+function parseLoopCommandRoute(input: string): LoopCommandRoute {
+  const trimmed = input.trim();
+  if (!trimmed) return { type: "menu" };
+
+  const eventMatch = trimmed.match(/^(?:event|when)\s+(\S+)\s+(.+)$/i);
+  if (eventMatch?.[1] && eventMatch[2]) {
+    return { type: "event", source: eventMatch[1], prompt: eventMatch[2].trim() };
+  }
 
-  async function scheduleLoop(ui: ExtensionUIContext, prompt?: string) {
-    const p = prompt || await ui.input("Prompt (what should the agent check?)");
-    if (!p) return;
+  const parts = trimmed.split(/\s+/);
+  if (parts.length > 5) {
+    const interval = parts.slice(0, 5).join(" ");
+    const cronShaped = parts.slice(0, 5).every((part) => /^[\d*/,-]+$/.test(part));
+    if (cronShaped) {
+      if (!isValidCronExpression(interval)) return { type: "invalid-cron", interval };
+      return { type: "cron", interval, prompt: parts.slice(5).join(" "), notifyEvery: false };
+    }
+  }
 
-    const interval = await ui.input("Interval (e.g., 5m, 2h, 1d)");
-    if (!interval) return;
+  const intervalMatch = trimmed.match(/^(\d+\s*[smhdS]\b)/i);
+  if (intervalMatch) {
+    const interval = intervalMatch[1] ?? intervalMatch[0];
+    const prompt = trimmed.slice(intervalMatch[0].length).trim();
+    if (!prompt) return { type: "missing-interval-prompt" };
+    return { type: "cron", interval, prompt, notifyEvery: true };
+  }
 
+  return { type: "dynamic", goal: trimmed };
+}
+
+export function registerLoopCommand(options: LoopCommandOptions): void {
+  const { pi, getStore, getTriggerSystem, updateWidget, onDynamicLoopActivated } = options;
+
+  function createCronLoop(ui: ExtensionUIContext, interval: string, prompt: string, notifyEvery: boolean) {
+    let entry: LoopEntry | undefined;
     try {
       const parsed = parseInterval(interval);
       const trigger: Trigger = { type: "cron", schedule: parsed.cron };
-      const entry = getStore().create(trigger, p, { recurring: true });
+      entry = getStore().create(trigger, prompt, { recurring: true });
       getTriggerSystem().add(entry);
       updateWidget();
-      ui.notify(`Loop #${entry.id} created: every ${parsed.description}`, "info");
+      const cadence = notifyEvery ? `every ${parsed.description}` : parsed.description;
+      ui.notify(`Loop #${entry.id} created: ${cadence} — ${prompt.slice(0, 50)}`, "info");
     } catch (err: unknown) {
+      if (entry) {
+        getTriggerSystem().remove(entry.id);
+        getStore().delete(entry.id);
+        updateWidget();
+      }
       ui.notify((err as Error).message, "error");
     }
   }
 
-  async function eventLoop(ui: ExtensionUIContext, prompt?: string) {
+  async function scheduleLoop(ui: ExtensionUIContext, prompt?: string) {
+    const p = prompt || await ui.input("Prompt (what should the agent check?)");
+    if (!p) return;
+
+    const interval = await ui.input("Interval (e.g., 5m, 2h, 1d)");
+    if (!interval) return;
+
+    createCronLoop(ui, interval, p, true);
+  }
+
+  async function eventLoop(ui: ExtensionUIContext, prompt?: string, sourceOverride?: string) {
     const p = prompt || await ui.input("Prompt");
     if (!p) return;
 
-    const source = await ui.input("Pi event source (e.g., tool_execution_start, before_agent_start)");
+    const source = sourceOverride || await ui.input("Pi event source (e.g., tool_execution_start, before_agent_start)");
     if (!source) return;
 
     const trigger: Trigger = { type: "event", source };
@@ -63,6 +121,19 @@ export function registerLoopCommand(options: LoopCommandOptions): void {
     ui.notify(`Event loop #${entry.id} created: fires on "${source}"`, "info");
   }
 
+  function dynamicLoop(ui: ExtensionUIContext, goal: string) {
+    const trigger: Trigger = { type: "dynamic" };
+    const entry = getStore().create(trigger, goal, {
+      recurring: true,
+      maxFires: 20,
+      dynamic: { goal, iteration: 0 },
+    });
+    getTriggerSystem().add(entry);
+    updateWidget();
+    ui.notify(`Dynamic loop #${entry.id} created — ${goal.slice(0, 50)}`, "info");
+    onDynamicLoopActivated?.(entry);
+  }
+
   async function viewLoops(ui: ExtensionUIContext) {
     const loops = getStore().list();
     if (loops.length === 0) {
@@ -72,12 +143,7 @@ export function registerLoopCommand(options: LoopCommandOptions): void {
 
     const choices = loops.map((l) => {
       const icon = l.status === "active" ? "*" : l.status === "paused" ? "-" : "x";
-      const triggerDesc = l.trigger.type === "cron"
-        ? `cron: ${l.trigger.schedule}`
-        : l.trigger.type === "event"
-          ? `event: ${l.trigger.source}`
-          : `hybrid: ${l.trigger.cron}`;
-      return `${icon} #${l.id} [${l.status}] ${l.prompt.slice(0, 50)} (${triggerDesc})`;
+      return `${icon} #${l.id} [${l.status}] ${l.prompt.slice(0, 50)} (${formatTrigger(l.trigger, "command")})`;
     });
     choices.push("< Back");
 
@@ -109,10 +175,12 @@ export function registerLoopCommand(options: LoopCommandOptions): void {
           updateWidget();
           ui.notify(`Loop #${entry.id} paused`, "info");
         } else if (action === "* Resume") {
-          getStore().resume(entry.id);
-          getTriggerSystem().add(entry);
+          const resumed = getStore().resume(entry.id);
+          if (!resumed) return viewLoops(ui);
+          getTriggerSystem().add(resumed);
           updateWidget();
           ui.notify(`Loop #${entry.id} resumed`, "info");
+          if (resumed.trigger.type === "dynamic") onDynamicLoopActivated?.(resumed);
         }
       }
     }
@@ -127,12 +195,12 @@ export function registerLoopCommand(options: LoopCommandOptions): void {
   }
 
   pi.registerCommand("loop", {
-    description: "Create a repeating scheduled task: /loop [interval] [prompt]. E.g., /loop 5m check the deploy, /loop 30s am I still here",
+    description: "Create a loop. Use /loop [interval] [prompt] for scheduled loops, /loop event <source> <prompt> for event loops, or /loop <goal> for a dynamic goal loop.",
     handler: async (args: string, ctx: ExtensionCommandContext) => {
-      const trimmed = args.trim();
       const ui = ctx.ui;
+      const route = parseLoopCommandRoute(args);
 
-      if (!trimmed) {
+      if (route.type === "menu") {
         const choice = await ui.select("Loop", [
           "Create scheduled loop",
           "Create event-triggered loop",
@@ -147,37 +215,17 @@ export function registerLoopCommand(options: LoopCommandOptions): void {
         return settings(ui);
       }
 
-      const intervalMatch = trimmed.match(/^(\d+\s*[smhdS]\b)/i);
-      if (intervalMatch) {
-        const interval = intervalMatch[1] ?? intervalMatch[0];
-        const prompt = trimmed.slice(intervalMatch[0].length).trim();
-
-        if (!prompt) {
-          ui.notify("Provide a prompt after the interval, e.g., /loop 5m check the deploy", "warning");
-          return;
-        }
-
-        try {
-          const parsed = parseInterval(interval);
-          const trigger: Trigger = { type: "cron", schedule: parsed.cron };
-          const entry = getStore().create(trigger, prompt, { recurring: true });
-          getTriggerSystem().add(entry);
-          updateWidget();
-          ui.notify(`Loop #${entry.id} created: every ${parsed.description} — ${prompt.slice(0, 50)}`, "info");
-        } catch (err: unknown) {
-          ui.notify((err as Error).message, "error");
-        }
+      if (route.type === "event") return eventLoop(ui, route.prompt, route.source);
+      if (route.type === "cron") return createCronLoop(ui, route.interval, route.prompt, route.notifyEvery);
+      if (route.type === "invalid-cron") {
+        ui.notify(`Invalid cron expression: ${route.interval}`, "error");
         return;
       }
-
-      const choice = await ui.select("Loop mode", [
-        `Scheduled: "${trimmed.slice(0, 50)}"`,
-        `Event-triggered: "${trimmed.slice(0, 50)}"`,
-      ]);
-
-      if (!choice) return;
-      if (choice.startsWith("Event")) return eventLoop(ui, trimmed);
-      return scheduleLoop(ui, trimmed);
+      if (route.type === "missing-interval-prompt") {
+        ui.notify("Provide a prompt after the interval, e.g., /loop 5m check the deploy", "warning");
+        return;
+      }
+      return dynamicLoop(ui, route.goal);
     },
   });
 }

package/src/index.ts

@@ -4,13 +4,14 @@
  * Tools:
  *   LoopCreate    — Create a scheduled or event-triggered re-wake loop
  *   LoopList      — List all active loops with status and next-fire times
+ *   LoopUpdate    — Continue, pause, or complete a dynamic goal loop
  *   LoopDelete    — Delete or pause a loop by ID
  *   MonitorCreate — Start a background command that streams output via pi events
  *   MonitorList   — List running monitors
  *   MonitorStop   — Stop a running monitor
  *
  * Commands:
- *   /loop    — Schedule or manage re-wake loops: /loop [interval] [prompt]
+ *   /loop    — Schedule or manage re-wake loops, including /loop <goal>
  *   /tasks   — View or manage native fallback tasks when pi-tasks is absent
  */
 
@@ -67,15 +68,26 @@ export default function (pi: ExtensionAPI) {
     // Once pi-tasks owns the channels, any native store created during the
     // detection window is a shadow — never surface it in the status line.
     if (tasksAvailable || !nativeTaskStore) return { count: 0 };
-    const tasks = nativeTaskStore.list().filter(t => t.status === "pending" || t.status === "in_progress");
-    const active = tasks.find(t => t.status === "in_progress");
-    const next = tasks.find(t => t.status === "pending");
-    const focus = active
-      ? `active: ${active.subject.slice(0, 50)}`
-      : next
-        ? `next: ${next.subject.slice(0, 50)}`
+
+    let count = 0;
+    let activeSubject: string | undefined;
+    let nextSubject: string | undefined;
+    for (const task of nativeTaskStore.list()) {
+      if (task.status === "in_progress") {
+        count++;
+        activeSubject ??= task.subject;
+      } else if (task.status === "pending") {
+        count++;
+        nextSubject ??= task.subject;
+      }
+    }
+
+    const focus = activeSubject
+      ? `active: ${activeSubject.slice(0, 50)}`
+      : nextSubject
+        ? `next: ${nextSubject.slice(0, 50)}`
         : undefined;
-    return { count: tasks.length, focusText: focus };
+    return { count, focusText: focus };
   });
 
   scheduler = new CronScheduler(store, onLoopFire);
@@ -199,6 +211,9 @@ export default function (pi: ExtensionAPI) {
     deleteLoop: (id) => {
       store.delete(id);
     },
+    recordDeletionTombstone: (id, tombstone) => {
+      store.recordDeletionTombstone(id, tombstone);
+    },
     addTrigger: (entry) => {
       triggerSystem.add(entry);
     },
@@ -237,6 +252,17 @@ export default function (pi: ExtensionAPI) {
     }
     store.fire(entry.id);
 
+    const firedAt = Date.now();
+    const firedEntry = entry.trigger.type === "dynamic"
+      ? store.updateDynamic(entry.id, {
+          dynamic: {
+            awaitingUpdate: true,
+            nextWakeAt: undefined,
+            lastUpdatedAt: firedAt,
+          },
+        }) ?? entry
+      : entry;
+
     if (entry.autoTask) {
       autoCreateTask(entry).then((taskId) => {
         if (taskId) debug(`loop #${entry.id} → task #${taskId}`);
@@ -244,13 +270,14 @@ export default function (pi: ExtensionAPI) {
     }
 
     pi.events.emit("loop:fire", {
-      loopId: entry.id,
-      prompt: entry.prompt,
-      trigger: entry.trigger,
-      timestamp: Date.now(),
-      readOnly: entry.readOnly,
-      recurring: entry.recurring,
-      autoTask: entry.autoTask,
+      loopId: firedEntry.id,
+      prompt: firedEntry.prompt,
+      trigger: firedEntry.trigger,
+      timestamp: firedAt,
+      readOnly: firedEntry.readOnly,
+      recurring: firedEntry.recurring,
+      autoTask: firedEntry.autoTask,
+      dynamic: firedEntry.dynamic,
     });
   }
 
@@ -341,6 +368,9 @@ export default function (pi: ExtensionAPI) {
     updateWidget: () => {
       widget.update();
     },
+    onDynamicLoopActivated: (entry) => {
+      onLoopFire(entry);
+    },
   });
 
   // ── Native task tools (only when pi-tasks is absent) ──

package/src/loop-format.ts

@@ -0,0 +1,22 @@
+import type { Trigger } from "./types.js";
+
+export type TriggerFormatStyle = "command" | "create" | "list" | "notification";
+
+export function formatTrigger(trigger: Trigger | string, style: TriggerFormatStyle = "list"): string {
+  if (typeof trigger === "string") return trigger;
+
+  if (trigger.type === "cron") {
+    return style === "create" || style === "notification"
+      ? `schedule: ${trigger.schedule}`
+      : `cron: ${trigger.schedule}`;
+  }
+
+  if (trigger.type === "event") return `event: ${trigger.source}`;
+
+  if (trigger.type === "dynamic") return "dynamic";
+
+  if (style === "command") return `hybrid: ${trigger.cron}`;
+  if (style === "create") return `hybrid: cron ${trigger.cron} + event ${trigger.event.source}`;
+  if (style === "notification") return "hybrid";
+  return `hybrid: ${trigger.cron} + ${trigger.event.source}`;
+}

package/src/loop-parse.ts

@@ -53,10 +53,53 @@ function isFullCron(expr: string): boolean {
   return parts.length === 5;
 }
 
+function parseCronNumber(input: string, min: number, max: number): number | undefined {
+  if (!/^\d+$/.test(input)) return undefined;
+  const value = Number.parseInt(input, 10);
+  return value >= min && value <= max ? value : undefined;
+}
+
+function isValidCronField(field: string, min: number, max: number): boolean {
+  return field.split(",").every((part) => {
+    const [base, step, extra] = part.split("/");
+    if (extra !== undefined || base === undefined) return false;
+    if (step !== undefined && (parseCronNumber(step, 1, max - min + 1) === undefined)) return false;
+    if (base === "*") return true;
+
+    const range = base.split("-");
+    if (range.length === 1) return step === undefined && parseCronNumber(base, min, max) !== undefined;
+    if (range.length !== 2) return false;
+
+    const start = parseCronNumber(range[0] ?? "", min, max);
+    const end = parseCronNumber(range[1] ?? "", min, max);
+    return start !== undefined && end !== undefined && start <= end;
+  });
+}
+
+export function isValidCronExpression(expr: string): boolean {
+  const fields = expr.trim().split(/\s+/);
+  if (fields.length !== 5) return false;
+
+  const ranges = [
+    [0, 59],
+    [0, 23],
+    [1, 31],
+    [1, 12],
+    [0, 6],
+  ] as const;
+  return fields.every((field, index) => {
+    const range = ranges[index];
+    return range !== undefined && isValidCronField(field, range[0], range[1]);
+  });
+}
+
 export function parseInterval(input: string): { cron: string; description: string } {
   const trimmed = input.trim();
 
   if (isFullCron(trimmed)) {
+    if (!isValidCronExpression(trimmed)) {
+      throw new Error(`Invalid cron expression: ${trimmed}`);
+    }
     return { cron: trimmed, description: `cron: ${trimmed}` };
   }
 
@@ -80,7 +123,7 @@ export function parseInterval(input: string): { cron: string; description: strin
 
 export function cronToNextFire(cronExpr: string, fromDate: Date = new Date()): Date {
   const parts = cronExpr.trim().split(/\s+/);
-  if (parts.length !== 5) throw new Error(`Invalid cron expression: ${cronExpr}`);
+  if (!isValidCronExpression(cronExpr)) throw new Error(`Invalid cron expression: ${cronExpr}`);
 
   const [minF, hourF, dayF, monthF, dowF] = parts;
   if (

package/src/loop-reducer.ts

@@ -1,4 +1,4 @@
-import type { LoopEntry, Trigger } from "./types.js";
+import type { DynamicLoopState, LoopEntry, Trigger } from "./types.js";
 
 export const MAX_LOOP_EXPIRY_MS = 7 * 24 * 60 * 60 * 1000;
 
@@ -34,6 +34,7 @@ export type LoopReducerEvent =
       taskBacklog?: boolean;
       readOnly?: boolean;
       maxFires?: number;
+      dynamic?: Partial<DynamicLoopState>;
     };
   }
   | {
@@ -60,6 +61,18 @@ export type LoopReducerEvent =
       id: string;
       reason: "expires_at" | "resume_event_stale" | "already_completed_monitor";
     };
+  }
+  | {
+    type: "LOOP_DYNAMIC_UPDATED";
+    at: number;
+    source: ReducerSource;
+    entityType?: "loop";
+    entityId?: string;
+    payload: {
+      id: string;
+      prompt?: string;
+      dynamic: Partial<DynamicLoopState>;
+    };
   };
 
 export type LoopReducerEffect =
@@ -106,6 +119,18 @@ export function reduceLoopState(state: LoopReducerState, event: LoopReducerEvent
       readOnly: event.payload.readOnly,
       maxFires: event.payload.maxFires,
       fireCount: 0,
+      dynamic: event.payload.trigger.type === "dynamic" || event.payload.dynamic
+        ? {
+            goal: event.payload.dynamic?.goal ?? event.payload.prompt,
+            state: event.payload.dynamic?.state,
+            metrics: event.payload.dynamic?.metrics,
+            doneCriteria: event.payload.dynamic?.doneCriteria,
+            iteration: event.payload.dynamic?.iteration ?? 0,
+            nextWakeAt: event.payload.dynamic?.nextWakeAt,
+            awaitingUpdate: event.payload.dynamic?.awaitingUpdate ?? false,
+            lastUpdatedAt: event.payload.dynamic?.lastUpdatedAt ?? event.at,
+          }
+        : undefined,
     };
     next.loopsById[id] = loop;
     return {
@@ -150,6 +175,21 @@ export function reduceLoopState(state: LoopReducerState, event: LoopReducerEvent
     loop.updatedAt = event.at;
   }
 
+  if (event.type === "LOOP_DYNAMIC_UPDATED") {
+    loop.prompt = event.payload.prompt ?? loop.prompt;
+    loop.dynamic = {
+      goal: event.payload.dynamic.goal ?? loop.dynamic?.goal ?? loop.prompt,
+      state: event.payload.dynamic.state ?? loop.dynamic?.state,
+      metrics: event.payload.dynamic.metrics ?? loop.dynamic?.metrics,
+      doneCriteria: event.payload.dynamic.doneCriteria ?? loop.dynamic?.doneCriteria,
+      iteration: event.payload.dynamic.iteration ?? loop.dynamic?.iteration ?? 0,
+      nextWakeAt: "nextWakeAt" in event.payload.dynamic ? event.payload.dynamic.nextWakeAt : loop.dynamic?.nextWakeAt,
+      awaitingUpdate: event.payload.dynamic.awaitingUpdate ?? loop.dynamic?.awaitingUpdate ?? false,
+      lastUpdatedAt: event.payload.dynamic.lastUpdatedAt ?? event.at,
+    };
+    loop.updatedAt = event.at;
+  }
+
   next.loopsById[id] = loop;
   return {
     state: next,

package/src/monitor-manager.ts

@@ -211,7 +211,7 @@ export class MonitorManager {
     if (timeout > 0) {
       setTimeout(() => {
         if (bp.entry.status === "running") {
-          this.stop(id);
+          void this.stop(id, "timeout");
         }
       }, timeout);
     }
@@ -231,7 +231,7 @@ export class MonitorManager {
       .sort((a, b) => Number(a.id) - Number(b.id));
   }
 
-  async stop(id: string): Promise<boolean> {
+  async stop(id: string, reason: "manual" | "timeout" = "manual"): Promise<boolean> {
     const bp = this.processes.get(id);
     if (!bp || bp.entry.status !== "running") return false;
 
@@ -243,7 +243,7 @@ export class MonitorManager {
       entityId: id,
       payload: {
         id,
-        reason: "manual",
+        reason,
       },
     });
     this.schedulePrune(id);
@@ -261,6 +261,14 @@ export class MonitorManager {
       });
     });
 
+    if (reason === "timeout") {
+      this.pi.events.emit("monitor:error", {
+        monitorId: id,
+        error: `Timed out after ${bp.entry.timeout}ms`,
+        outputLines: bp.entry.outputLines,
+      });
+      for (const callback of bp.completionCallbacks) callback();
+    }
     bp.completionCallbacks = [];
     for (const resolve of bp.waiters) resolve();
     bp.waiters = [];
@@ -270,7 +278,7 @@ export class MonitorManager {
   onComplete(id: string, callback: () => void): boolean {
     const bp = this.processes.get(id);
     if (!bp) return false;
-    if (bp.entry.status === "completed") {
+    if (bp.entry.status === "completed" || bp.entry.status === "error") {
       callback();
       return true;
     }

package/src/notification-reducer.ts

@@ -1,3 +1,5 @@
+import type { DynamicLoopState } from "./types.js";
+
 type ReducerSource = "tool" | "command" | "scheduler" | "eventbus" | "monitor" | "session" | "coordinator" | "system";
 
 export interface ReducerNotification {
@@ -9,6 +11,7 @@ export interface ReducerNotification {
   recurring?: boolean;
   autoTask?: boolean;
   readOnly?: boolean;
+  dynamic?: DynamicLoopState;
 }
 
 export interface NotificationReducerState {

package/src/runtime/monitor-ondone-runtime.ts

@@ -62,7 +62,7 @@ export function createMonitorOnDoneRuntime(options: MonitorOnDoneRuntimeOptions)
 
     const monitor = monitorManager.get(monitorId);
     if (monitor && monitor.status !== "running") {
-      if (monitor.status === "completed") {
+      if (monitor.status === "completed" || monitor.status === "error") {
         deliver();
         return;
       }

package/src/runtime/notification-runtime.ts

@@ -5,13 +5,14 @@ import {
   type ReducerEvent,
   type ReducerHandler,
 } from "../coordinator.js";
+import { formatTrigger } from "../loop-format.js";
 import {
   type NotificationReducerEvent,
   type NotificationReducerState,
   type ReducerNotification,
   reduceNotificationState,
 } from "../notification-reducer.js";
-import type { Trigger } from "../types.js";
+import type { DynamicLoopState, Trigger } from "../types.js";
 
 export interface LoopFireEvent {
   loopId: string;
@@ -21,6 +22,7 @@ export interface LoopFireEvent {
   readOnly?: boolean;
   recurring?: boolean;
   autoTask?: boolean;
+  dynamic?: DynamicLoopState;
 }
 
 export interface PendingNotification extends LoopFireEvent {
@@ -94,13 +96,7 @@ export function createNotificationRuntime(options: NotificationRuntimeOptions):
   }
 
   function buildLoopFireMessage(data: LoopFireEvent): string {
-    const triggerInfo = typeof data.trigger === "string"
-      ? data.trigger
-      : data.trigger?.type === "cron"
-        ? `schedule: ${data.trigger.schedule}`
-        : data.trigger?.type === "event"
-          ? `event: ${data.trigger.source}`
-          : "hybrid";
+    const triggerInfo = formatTrigger(data.trigger, "notification");
 
     const loopId = data.loopId || "?";
     const prompt = data.prompt || "loop fired";
@@ -108,6 +104,22 @@ 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.dynamic || (typeof data.trigger !== "string" && data.trigger?.type === "dynamic")) {
+      const dynamic = data.dynamic;
+      const lines = [
+        `[pi-loop] Loop #${loopId} fired (dynamic).${constraint}`,
+        `Goal: ${dynamic?.goal ?? prompt}`,
+        `Iteration: ${dynamic?.iteration ?? 0}`,
+      ];
+      if (dynamic?.state) lines.push(`State: ${dynamic.state}`);
+      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\".",
+      );
+      return lines.join("\n");
+    }
+
     return [
       `[pi-loop] Loop #${loopId} fired (${triggerInfo}).${constraint}`,
       prompt,
@@ -144,6 +156,7 @@ export function createNotificationRuntime(options: NotificationRuntimeOptions):
         recurring: notification.recurring,
         readOnly: notification.readOnly,
         autoTask: notification.autoTask,
+        dynamic: notification.dynamic,
         timestamp: notification.timestamp,
       },
     }, {