@brettinternet/pi-loop 0.1.3 → 0.1.4

package/README.md

@@ -1,6 +1,6 @@
 # pi-loop
 
-Run a prompt repeatedly, with a fresh session for every iteration.
+Run a prompt repeatedly, with a fresh session for every iteration. Each new session uses the model selected in the preceding session (including a custom non-default model); changing models mid-loop takes effect on the next iteration. If that model is unavailable, the loop pauses rather than falling back to the default.
 
 ```bash
 pi install npm:@brettinternet/pi-loop
@@ -35,3 +35,11 @@ Chain commands in the prompt:
 ```
 
 Built-in interactive commands cannot be chained.
+
+While a loop is active, every child command receives its stable run ID as `PI_LOOP_RUN_ID`:
+
+```text
+PI_LOOP_RUN_ID=3992f183-e054-4068-a13e-11281d1747e2
+```
+
+The value is always the full UUID, remains unchanged across every iteration and replacement session in that loop, and differs between independent loops. When the loop ends or its session closes, pi-loop restores the previous value or removes the variable if it was previously unset.

package/index.ts

@@ -11,6 +11,7 @@ import { Type } from "typebox";
 
 export const LOOP_STATE_ENTRY = "pi-loop-state-v1";
 export const LOOP_WIDGET_KEY = "pi-loop";
+export const LOOP_RUN_ID_ENV = "PI_LOOP_RUN_ID";
 export const LOOP_USAGE =
   "usage: /loop <positive-count> [--delay <duration>] <prompt> | /loop for <duration> --delay <duration> <prompt> | /loop <positive-count> | /loop <+|-><count> | /loop time <duration> | /loop delay <duration> | /loop prompt <text> | /loop append <text> | /loop status | /loop pause | /loop resume | /loop next | /loop end";
 
@@ -47,6 +48,7 @@ export interface LoopState {
   pausedAt?: number;
   ownerSessionId?: string;
   ownerSessionFile?: string;
+  model?: { provider: string; id: string };
 }
 
 export type ParsedLoopCommand =
@@ -64,12 +66,41 @@ export type ParsedLoopCommand =
   | { kind: "next" }
   | { kind: "end" }
   | { kind: "continue"; runId: string; iteration: number }
-  | { kind: "pause"; runId: string; iteration: number };
+  | { kind: "pause"; runId: string; iteration: number }
+  | { kind: "restoreModel"; runId: string; iteration: number };
 
 const ACTIVE_STATUSES = new Set<LoopStatus>(["active", "pausing", "stopping"]);
 const VISIBLE_STATUSES = new Set<LoopStatus>(["active", "pausing", "stopping", "paused"]);
 const TERMINAL_STATUSES = new Set<LoopStatus>(["completed", "stopped", "inactive"]);
 
+const LOOP_ENVIRONMENT_STATE_KEY = "__piLoopRunEnvironmentV1";
+type LoopEnvironmentState = { runId: string; originalValue: string | undefined };
+
+function environmentState(): LoopEnvironmentState | undefined {
+  return (globalThis as Record<string, unknown>)[LOOP_ENVIRONMENT_STATE_KEY] as LoopEnvironmentState | undefined;
+}
+
+function exposeLoopRunId(runId: string): void {
+  const active = environmentState();
+  if (active) {
+    active.runId = runId;
+  } else {
+    (globalThis as Record<string, unknown>)[LOOP_ENVIRONMENT_STATE_KEY] = {
+      runId,
+      originalValue: process.env[LOOP_RUN_ID_ENV],
+    } satisfies LoopEnvironmentState;
+  }
+  process.env[LOOP_RUN_ID_ENV] = runId;
+}
+
+function restoreLoopRunId(expectedRunId?: string): void {
+  const active = environmentState();
+  if (!active || (expectedRunId !== undefined && active.runId !== expectedRunId)) return;
+  if (active.originalValue === undefined) delete process.env[LOOP_RUN_ID_ENV];
+  else process.env[LOOP_RUN_ID_ENV] = active.originalValue;
+  delete (globalThis as Record<string, unknown>)[LOOP_ENVIRONMENT_STATE_KEY];
+}
+
 type ArgumentCompletion = { value: string; label: string; description?: string };
 
 function completeArguments(
@@ -312,7 +343,7 @@ export function parseLoopCommand(args: string): ParsedLoopCommand {
   // These commands are only emitted by the extension itself. Keeping them in
   // the same dispatcher gives boundary transitions command-only session APIs
   // while preventing user input from accidentally looking like one.
-  if (first === "__continue" || first === "__pause") {
+  if (first === "__continue" || first === "__pause" || first === "__restore_model") {
     const fields = rest.split(/\s+/).filter(Boolean);
     if (fields.length !== 2 || !/^[A-Za-z0-9_-]+$/.test(fields[0])) {
       throw new Error("invalid internal loop command");
@@ -323,7 +354,9 @@ export function parseLoopCommand(args: string): ParsedLoopCommand {
     }
     return first === "__continue"
       ? { kind: "continue", runId: fields[0], iteration }
-      : { kind: "pause", runId: fields[0], iteration };
+      : first === "__pause"
+        ? { kind: "pause", runId: fields[0], iteration }
+        : { kind: "restoreModel", runId: fields[0], iteration };
   }
 
   if (/^[+\-]\d/.test(first)) {
@@ -411,6 +444,12 @@ export function parseLoopState(value: unknown): LoopState | undefined {
   if (value.pausedAt !== undefined && !isNonNegativeInteger(value.pausedAt)) return undefined;
   if (value.ownerSessionId !== undefined && typeof value.ownerSessionId !== "string") return undefined;
   if (value.ownerSessionFile !== undefined && typeof value.ownerSessionFile !== "string") return undefined;
+  const model = value.model;
+  if (
+    model !== undefined &&
+    (!isRecord(model) || typeof model.provider !== "string" || !model.provider ||
+      typeof model.id !== "string" || !model.id)
+  ) return undefined;
 
   return {
     version: 1,
@@ -430,6 +469,9 @@ export function parseLoopState(value: unknown): LoopState | undefined {
     ...(value.pausedAt !== undefined ? { pausedAt: value.pausedAt } : {}),
     ...(value.ownerSessionId ? { ownerSessionId: value.ownerSessionId } : {}),
     ...(value.ownerSessionFile ? { ownerSessionFile: value.ownerSessionFile } : {}),
+    ...(isRecord(model) && typeof model.provider === "string" && typeof model.id === "string"
+      ? { model: { provider: model.provider, id: model.id } }
+      : {}),
   };
 }
 
@@ -612,9 +654,19 @@ export default function loopExtension(pi: ExtensionAPI): void {
     return runState;
   }
 
+  function syncLoopEnvironment(state: LoopState | undefined): void {
+    const runId = state?.runId;
+    if (state && statusIsVisible(state)) {
+      exposeLoopRunId(state.runId);
+      return;
+    }
+    if (!transitionInFlight) restoreLoopRunId(runId);
+  }
+
   function persist(ctx: Pick<ExtensionAPI, "appendEntry">, state: LoopState): void {
     ctx.appendEntry(LOOP_STATE_ENTRY, state);
     runState = state;
+    syncLoopEnvironment(state);
     reportHerdrBlocked(state);
   }
 
@@ -885,6 +937,7 @@ export default function loopExtension(pi: ExtensionAPI): void {
 
   function transferState(state: LoopState, manager: SessionManager): LoopState {
     const transferred = stateForSession({ ...state, status: "active" }, sessionIdentity(manager));
+    exposeLoopRunId(transferred.runId);
     manager.appendCustomEntry(LOOP_STATE_ENTRY, transferred);
     return transferred;
   }
@@ -893,9 +946,17 @@ export default function loopExtension(pi: ExtensionAPI): void {
     replacement: ReplacementContext,
     state: LoopState,
   ): Promise<void> {
-    // The new extension instance restores this entry in before_agent_start.
-    // This callback still owns the command context, so it is the safe place to
-    // start the turn after the replacement is complete.
+    // The replacement owns the new extension runtime. Restore its model before
+    // starting a turn, rather than using the invalidated previous runtime.
+    if (state.model) {
+      await replacement.sendUserMessage(
+        `/loop __restore_model ${state.runId} ${state.currentIteration}`,
+        { expandPromptTemplates: true },
+      );
+      if (replacement.model?.provider !== state.model.provider || replacement.model.id !== state.model.id) {
+        throw new Error(`loop model unavailable: ${state.model.provider}/${state.model.id}`);
+      }
+    }
     if (replacement.hasUI) showWidget(replacement, state);
     if (state.endsAt !== undefined && Date.now() >= state.endsAt) {
       await replacement.sendUserMessage(
@@ -908,6 +969,7 @@ export default function loopExtension(pi: ExtensionAPI): void {
   }
 
   async function replaceForIteration(ctx: ExtensionCommandContext, next: LoopState): Promise<void> {
+    exposeLoopRunId(next.runId);
     clearContinuationWait();
     clearRetryWait();
     clearRecoveryTimer();
@@ -1068,6 +1130,7 @@ export default function loopExtension(pi: ExtensionAPI): void {
     } = state;
     const next: LoopState = {
       ...withoutPause,
+      ...(ctx.model ? { model: { provider: ctx.model.provider, id: ctx.model.id } } : {}),
       currentIteration: state.currentIteration + 1,
       remainingBudget: state.endsAt === undefined ? nextBudget - 1 : 0,
       pendingRetune: null,
@@ -1119,6 +1182,16 @@ export default function loopExtension(pi: ExtensionAPI): void {
       return;
     }
 
+    if (parsed.kind === "restoreModel") {
+      const state = currentState(ctx);
+      if (!state || state.runId !== parsed.runId || state.currentIteration !== parsed.iteration || !state.model) return;
+      const model = ctx.modelRegistry.find(state.model.provider, state.model.id);
+      if (!model || !(await pi.setModel(model))) {
+        throw new Error(`loop model unavailable: ${state.model.provider}/${state.model.id}`);
+      }
+      return;
+    }
+
     if (parsed.kind === "pause") {
       const state = currentState(ctx);
       if (!state || state.runId !== parsed.runId || state.currentIteration !== parsed.iteration || !statusIsActive(state)) return;
@@ -1402,6 +1475,7 @@ export default function loopExtension(pi: ExtensionAPI): void {
       status: "active",
       retryCount: 0,
       phase: "running",
+      ...(ctx.model ? { model: { provider: ctx.model.provider, id: ctx.model.id } } : {}),
       ...(timed ? { endsAt: Date.now() + parsed.duration } : {}),
       ...(contextIdentity(ctx).id ? { ownerSessionId: contextIdentity(ctx).id } : {}),
       ...(contextIdentity(ctx).file ? { ownerSessionFile: contextIdentity(ctx).file } : {}),
@@ -1454,6 +1528,7 @@ export default function loopExtension(pi: ExtensionAPI): void {
     const loaded = latestStateFromContext(ctx);
     const owned = loaded && stateBelongsToContext(loaded, ctx) ? loaded : undefined;
     runState = owned;
+    syncLoopEnvironment(owned);
     reportHerdrBlocked(owned);
     if (!owned || owned.status === "inactive") clearWidget(ctx);
     else renderWidget(ctx, owned);
@@ -1533,6 +1608,7 @@ export default function loopExtension(pi: ExtensionAPI): void {
     const loaded = latestStateFromContext(ctx);
     const owned = loaded && stateBelongsToContext(loaded, ctx) ? loaded : undefined;
     runState = owned;
+    syncLoopEnvironment(owned);
     reportHerdrBlocked(owned);
     if (!owned || owned.status === "inactive") clearWidget(ctx);
     else renderWidget(ctx, owned);
@@ -1553,6 +1629,7 @@ export default function loopExtension(pi: ExtensionAPI): void {
         // Shutdown may already have detached the runtime's append action.
       }
     }
+    if (event.reason !== "reload" && !transitionInFlight) restoreLoopRunId(loaded?.runId);
     reportHerdrBlocked(undefined);
     clearWidget(ctx);
     currentSessionManagerRef = undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brettinternet/pi-loop",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "Run a prompt repeatedly in fresh Pi sessions",
   "type": "module",
   "license": "MIT",