@computesdk/pi-loops 1.0.4 → 1.0.5

package/extensions/loop.ts

@@ -123,6 +123,8 @@ export type ToolDef<P = any> = {
   outputSchema?: any;
   /** One line for the default system prompt's "Available tools" section: without it Pi omits the tool there. */
   promptSnippet?: string;
+  /** Rules for the Guidelines section, shown only while this tool is active. Workflow belongs here, not in the snippet. */
+  promptGuidelines?: string[];
   /** `model-only` for the tools that ask the user or orchestrate: never callable from scripts. */
   exposure?: "direct" | "model-only" | "codemode" | "deferred" | "hidden";
   /** "sequential" for tools that share in-memory state, so one message's calls cannot interleave. */
@@ -133,6 +135,8 @@ export type ToolDef<P = any> = {
   renderCall?: (args: any, theme: any) => any;
   renderResult?: (result: any, options: { expanded: boolean; isPartial: boolean }, theme: any) => any;
 };
+/** Resolve a model spec against the registry captured while the ctx was alive. */
+export type ModelPicker = (spec?: string | null) => Model;
 /** A candidate for the judge: a checked-out directory at a commit. */
 export type Candidate = { label: string; dir: string; commit: string; fresh?: boolean };
 /** One round of a run. */
@@ -366,16 +370,16 @@ export async function stopAll() { shuttingDown = true; const all = [...active];
  * *extension* adds (rather than one built into Pi) is unknown inside it and its credential cannot be resolved. Say that
  * instead of pi's "No API key found", which points at /login and sends people the wrong way.
  */
-function explainAuth(e: unknown, role: string, spec: string | null, ctx: Ctx): unknown {
+function explainAuth(e: unknown, role: string, spec: string | null, registry?: ModelRegistryLike): unknown {
   const provider = errText(e).match(/No API key found for ([\w.-]+)/)?.[1]?.replace(/\.+$/, ""); // pi ends the sentence with a period
   if (!provider) return e;
   // the host can see a model on that provider (so this session is missing something the host has), not a bare missing login
-  const hostKnows = (ctx.modelRegistry?.getAvailable?.() ?? []).some((m) => (m as { provider?: string }).provider === provider);
+  const hostKnows = (registry?.getAvailable?.() ?? []).some((m) => (m as { provider?: string }).provider === provider);
   if (!hostKnows) return e;
   return new Error(`the ${role} cannot run on ${spec ?? provider}: "${provider}" is a Pi extension's provider, and a one-shot ${role} session loads no extensions, so it has no credentials there — give the ${role} a provider built into Pi (attempts can still use ${provider}).`, { cause: e });
 }
 
-async function oneShot({ role, model, content, cwd, ctx, settings, meter, signal }: { role: string; model?: string | null; content: any; cwd: string; ctx: Ctx; settings: LoopSettings; meter?: Meter; signal?: AbortSignal }) {
+async function oneShot({ role, model, content, cwd, pick, registry, settings, meter, signal }: { role: string; model?: string | null; content: any; cwd: string; pick: ModelPicker; registry?: ModelRegistryLike; settings: LoopSettings; meter?: Meter; signal?: AbortSignal }) {
   const agentDir = getAgentDir();
   const spec = model ?? settings.models[role] ?? null;
   const agent = loadAgent(role, { cwd, agentDir });
@@ -388,15 +392,15 @@ async function oneShot({ role, model, content, cwd, ctx, settings, meter, signal
     // "no extensions" would also drop the *providers* extensions add (anything not built into Pi), and an unregistered
     // provider has no credentials. Copy the host's registrations over: config only, no extension code runs, still no tools.
     const known = new Set(services.modelRuntime.getRegisteredProviderIds());
-    for (const id of ctx.modelRegistry?.getRegisteredProviderIds?.() ?? []) {
+    for (const id of registry?.getRegisteredProviderIds?.() ?? []) {
       if (known.has(id)) continue;
-      const config = ctx.modelRegistry?.getRegisteredProviderConfig?.(id);
+      const config = registry?.getRegisteredProviderConfig?.(id);
       if (config) { services.modelRuntime.registerProvider(id, config as any); continue; }
-      const native = ctx.modelRegistry?.getRegisteredNativeProvider?.(id); // a provider built with createProvider, not config
+      const native = registry?.getRegisteredNativeProvider?.(id); // a provider built with createProvider, not config
       if (native) services.modelRuntime.registerNativeProvider(native as any);
     }
     // creating the session resolves the credential too, so it belongs inside this try: that is where an unusable provider shows up
-    const { session: created } = await createAgentSessionFromServices({ services, sessionManager: SessionManager.inMemory(cwd), model: pickModel(ctx, spec ?? agent.model), noTools: "all" });
+    const { session: created } = await createAgentSessionFromServices({ services, sessionManager: SessionManager.inMemory(cwd), model: pick(spec ?? agent.model), noTools: "all" });
     session = track(created);
     const { text, images } = flattenParts(content);
     signal?.addEventListener("abort", onAbort, { once: true });
@@ -409,7 +413,7 @@ async function oneShot({ role, model, content, cwd, ctx, settings, meter, signal
       if (last?.stopReason === "error") throw new Error(last.errorMessage || `${role} errored`);
     }
     return parseJson(session.getLastAssistantText());
-  } catch (e) { throw explainAuth(e, role, spec, ctx); }
+  } catch (e) { throw explainAuth(e, role, spec, registry); }
   finally {
     signal?.removeEventListener("abort", onAbort);
     if (session) {
@@ -421,14 +425,14 @@ async function oneShot({ role, model, content, cwd, ctx, settings, meter, signal
 }
 
 /* ---------- an attempt: forked session + worktree + style agent ---------- */
-async function runAttempt({ state, style, n, dir, cwd, ctx, settings, model, meter, sessionDir, src, signal, onProgress, live }: { state: State; style: string; n: number; dir: string; cwd: string; ctx: PickCtx; settings: LoopSettings; model?: string | null; meter?: Meter; sessionDir?: string; src?: string | null; signal?: AbortSignal; onProgress: (progress: any) => void; live?: any }): Promise<Attempt> {
+async function runAttempt({ state, style, n, dir, cwd, pick, settings, model, meter, sessionDir, src, signal, onProgress, live }: { state: State; style: string; n: number; dir: string; cwd: string; pick: ModelPicker; settings: LoopSettings; model?: string | null; meter?: Meter; sessionDir?: string; src?: string | null; signal?: AbortSignal; onProgress: (progress: any) => void; live?: any }): Promise<Attempt> {
   const agentDir = getAgentDir();
   const agent = loadAgent(style, { cwd, agentDir });
   const fork = state.best.session ?? src;
   const sessionManager = fork && fs.existsSync(fork) ? SessionManager.forkFrom(fork, dir, sessionDir) : SessionManager.create(dir, sessionDir);
   const loader = new DefaultResourceLoader({ cwd: dir, agentDir, noExtensions: true, noPromptTemplates: true, noThemes: true, appendSystemPrompt: [agent.body] });
   await loader.reload();
-  const picked = pickModel(ctx, model ?? settings.models[style] ?? agent.model);
+  const picked = pick(model ?? settings.models[style] ?? agent.model);
   const { session: created } = await createAgentSession({ cwd: dir, agentDir, model: picked, tools: agent.tools?.length ? agent.tools : undefined, resourceLoader: loader, sessionManager });
   const session = track(created);
   live?.attempts.set(`R${n}-${style}`, session);
@@ -832,12 +836,20 @@ export default function loopsExtension(pi: Pi): void {
   });
   // state is module-scoped, so a session that starts after one has shut down must not inherit its latch
   pi.on?.("session_start", async () => { shuttingDown = false; RUNS.clear(); });
-  pi.on?.("session_shutdown", async () => { shuttingDown = true; for (const r of RUNS.values()) r.ctrl.abort(); await stopAll(); });
+  pi.on?.("session_shutdown", async () => {
+    shuttingDown = true;
+    const runs = [...RUNS.values()];
+    for (const r of runs) r.ctrl.abort();
+    // disposing the session invalidates the ctx, so the runs must be finished before this returns, not just aborted
+    await Promise.allSettled(runs.map((r) => r.promise));
+    await stopAll();
+  });
   async function run(params: LoopParamsIn, signal: AbortSignal | undefined, onUpdate: ((update: any) => void) | undefined, ctx: Ctx, live: any) {
     const cwd = ctx.cwd;
+    const hasUI = ctx.hasUI ?? false; // a getter on the ctx proxy: stale after replacement, so read it once
     let settings = loopSettings(pi, cwd);
     const chosen = Object.keys(settings.models).some((k) => k !== "pool");
-    if (!params.from && !chosen && ctx.hasUI && (ctx.modelRegistry?.getAvailable?.() ?? []).length > 1) {
+    if (!params.from && !chosen && hasUI && (ctx.modelRegistry?.getAvailable?.() ?? []).length > 1) {
       const r = await pickModels(ctx, { reason: "First loop here" });
       if (r && "error" in r) throw new Error(r.error);
       if (r && "models" in r) settings = { ...settings, models: { ...settings.models, ...r.models } };
@@ -872,7 +884,7 @@ export default function loopsExtension(pi: Pi): void {
     if (SELF_SHOT.test(state.build ?? "")) findChrome();
     // a visual round is only as good as the eyes on it: refuse a judge (or panel member) that cannot see the screenshots
     if (judgedOnScreenshots(state)) {
-      const asModel = (spec: string | null | undefined) => { try { return pickModel(ctx, spec); } catch { return null; } }; // an unavailable model reports itself later
+      const asModel = (spec: string | null | undefined) => { try { return pick(spec); } catch { return null; } }; // an unavailable model reports itself later
       const panelOn = settings.council !== false && settings.judgePanel !== false && (models.council?.length ?? 0) > 1;
       const problem = visionProblem([
         { role: "judge", key: "judge", spec: models.judge, model: asModel(models.judge) },
@@ -888,21 +900,27 @@ export default function loopsExtension(pi: Pi): void {
     const runDir = path.join(cwd, STATE_DIR, state.id);
     // every nested model call in this round — attempts, judge samples, council — adds to one meter, reported as the result's `usage`
     const meter = newMeter();
-    // a TUI call returns as soon as the round starts, and session replacement invalidates the old ctx: capture what the
-    // background run needs as plain data now (the model registry is the one shared object that stays valid)
+    // A TUI call returns as soon as the round starts, and `ctx` is a getter proxy that throws once the session is
+    // replaced (`runner.assertActive()`), so the background run holds only values read while it is still alive: the
+    // model registry object itself, the session paths, and the status sink. `bindUI` rebinds the new session's UI,
+    // so the old one is not touched after a switch.
     const sessionDir = ctx.sessionManager?.getSessionDir?.();
     const sessionFile = ctx.sessionManager?.getSessionFile?.() ?? null;
-    const setStatus = (text?: string) => { try { ctx.ui.setStatus?.("loops", text); } catch {} };
+    const pickCtx: PickCtx = { cwd, model: ctx.model, modelRegistry: ctx.modelRegistry, ui: ctx.ui };
+    const pick: ModelPicker = (spec) => pickModel(pickCtx, spec);
+    const statusSink = ctx.ui;
+    let alive = true;
+    const setStatus = (text?: string) => { if (alive) { try { statusSink.setStatus?.("loops", text); } catch {} } };
     const details: Details = { run: state.id, kind: state.kind, round: null, judge: null, attempts: [], phase: "starting" };
     if (live) { live.id = state.id; live.state = state; live.details = details; live.cwd = cwd; live.started?.(); }
     const push = (phase?: string) => { details.phase = phase ?? details.phase; if (live) setStatus(`${state.id} r${details.round ?? "?"} · ${details.phase}`); onUpdate?.({ content: [{ type: "text", text: `${state.id} r${details.round ?? "?"} · ${details.phase}\n${details.attempts.map((a) => `  ${a.style.padEnd(5)} ${a.status.padEnd(8)} ${a.tool ? `[${a.tool}] ` : ""}${a.tools} tools, ${a.tokens} tok${a.text ? ` — ${a.text.split("\n").pop()?.slice(0, 80) ?? ""}` : ""}`).join("\n")}` }], details: structuredClone(details) }); };
-    const askModel = (role: string, i: number = 0) => (content: any) => oneShot({ role, model: role === "council" ? (models.council ?? [])[i % (models.council?.length || 1)] : models[role], content, cwd, ctx, settings, meter, signal });
-    const askAs = (role: string, model?: string | null) => (content: any) => oneShot({ role, model, content, cwd, ctx, settings, meter, signal });
+    const askModel = (role: string, i: number = 0) => (content: any) => oneShot({ role, model: role === "council" ? (models.council ?? [])[i % (models.council?.length || 1)] : models[role], content, cwd, pick, registry: pickCtx.modelRegistry, settings, meter, signal });
+    const askAs = (role: string, model?: string | null) => (content: any) => oneShot({ role, model, content, cwd, pick, registry: pickCtx.modelRegistry, settings, meter, signal });
     // the judge panel: every council model (the attempts' models) scores every candidate, labels blind; the judge model keeps vetoes and the head-to-head
     const panel = settings.council !== false && settings.judgePanel !== false && (models.council?.length ?? 0) > 1 ? (models.council ?? []).map((m) => ({ name: shortModel(m), ask: askAs("judge", m) })) : undefined;
     state.models = { ...Object.fromEntries(STYLES.map((st) => [st, models[st]])), judge: models.judge, council: models.council, spread: models.spread };
     const needsYou = async (title: string, options: string[], fallback: string): Promise<string> => {
-      if (ctx.hasUI && !live) { const r = await ctx.ui.select(title, options); return r ?? fallback; }
+      if (hasUI && !live) { const r = await ctx.ui.select(title, options); return r ?? fallback; }
       return fallback;
     };
 
@@ -934,7 +952,7 @@ export default function loopsExtension(pi: Pi): void {
         try { git(cwd, "worktree", "remove", "-f", dir); } catch {}
         git(cwd, "worktree", "add", "-q", "-f", "-B", branch, dir, round.from ?? state.baseCommit);
         const slot = details.attempts.find((a) => a.style === style)!;
-        const r = await runAttempt({ state, style, n, dir, cwd, ctx, settings, model: models[style], meter, sessionDir, src: sessionFile, signal, live, onProgress: (p) => { Object.assign(slot, p); push(); } });
+        const r = await runAttempt({ state, style, n, dir, cwd, pick, settings, model: models[style], meter, sessionDir, src: sessionFile, signal, live, onProgress: (p) => { Object.assign(slot, p); push(); } });
         Object.assign(slot, { status: r.status, tool: null, text: r.summary || r.error || "" }); push();
         return { ...r, branch, dir: path.relative(cwd, dir) };
       }));
@@ -1017,7 +1035,7 @@ export default function loopsExtension(pi: Pi): void {
         else judge.why = `${judge.why} (your pick ${live.pick} was not a passing attempt)`;
         live.pick = null;
       }
-      if (ctx.hasUI && !live && takeable.length) {
+      if (hasUI && !live && takeable.length) {
         for (;;) {
           const others = takeable.filter((a) => a.label !== judge.pick);
           const opts = [`Keep ${judge.pick}${judge.pick === "CURRENT" ? " (nothing beat it)" : " (judge's pick)"}`, ...others.map((a) => `Take ${a.label} instead`), ...valid.map((a) => `Show ${a.label}'s diff`), ...valid.filter((a) => a.session).map((a) => `Open ${a.label}'s session after the run`)];
@@ -1063,7 +1081,11 @@ export default function loopsExtension(pi: Pi): void {
 
   pi.registerTool?.({
     name: "loop", exposure: "model-only", executionMode: "sequential",
-    promptSnippet: "run hill-climbing rounds: three forked attempts in git worktrees, a judge keeps the best", annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true },
+    promptSnippet: "run hill-climbing rounds: three forked attempts in git worktrees, a judge keeps the best",
+    promptGuidelines: [
+      "When the ask is comparative — make this faster, improve this, which of these is better — prefer `loop` over editing by hand: it forks attempts into their own worktrees and a judge keeps the best, and your checkout is untouched until `loop_apply`.",
+      "Give a `loop` round a `bench` when a number can be measured, and `routes` when the goal is what a page looks like; without either it is judged on the diffs.",
+    ], annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true },
     label: "loop",
     outputSchema: LoopResult,
     description: "Run hill-climbing round(s) on the current git repo: three forked attempt sessions (safe/bold/wild agents) in their own worktrees, a judge keeps the best. Bench mode when `bench` is set (each attempt sets up and measures itself; a judge agent re-measures every candidate, reads the diffs and vetoes rule breaks); visual mode otherwise (`build` writes `shots`, a judge panel scores them). `from` continues a run from its last judged round.",
@@ -1083,12 +1105,13 @@ export default function loopsExtension(pi: Pi): void {
         if (!choice?.startsWith("Approve")) return notRun("discuss", "Not run. Discuss the spec with me in chat (what is unclear, what should be different), then call loop again when we agree.");
       }
       if (!ctx.hasUI || params.wait) return run(params, signal, onUpdate, ctx, null);
+      const ui = ctx.ui; // the object, held by value: the ctx getter throws once the session is replaced
       const live: any = { id: null, state: null, details: null, cwd: ctx.cwd, attempts: new Map(), pick: null, last: null, error: null, ctrl: new AbortController(), startedAt: Date.now() };
       const started = new Promise((resolve) => { live.started = resolve; });
       live.promise = run(params, live.ctrl.signal, (u) => { live.last = u; }, ctx, live).then(
         (r) => { try { pi.sendUserMessage?.(r.content, { deliverAs: "followUp" }); } catch {} },
         (e) => { live.error = e; if (live.id) { try { pi.sendUserMessage?.(`Loop ${live.id} failed: ${e.message}`, { deliverAs: "followUp" }); } catch {} } }
-      ).finally(() => { if (live.id) RUNS.delete(live.id); live.started?.(); try { ctx.ui.setStatus?.("loops", undefined); } catch {} });
+      ).finally(() => { if (live.id) RUNS.delete(live.id); live.started?.(); try { ui.setStatus?.("loops", undefined); } catch {} });
       await started;
       if (!live.id) throw live.error ?? new Error("the loop did not start");
       RUNS.set(live.id, live);
@@ -1123,13 +1146,13 @@ export default function loopsExtension(pi: Pi): void {
     } });
   pi.registerTool?.({ name: "loop_status", promptSnippet: "progress of a loop round running in the background", outputSchema: StatusResult, annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false }, label: "loop_status", description: "Progress of a loop round running in the background: phase, each attempt's status, tools and tokens.", parameters: Type.Object({ id: idParam }),
     async execute(_id, p) { const r = liveRun(p.id); return { content: r.last?.content ?? [{ type: "text", text: `${r.id} starting` }], details: r.details, structuredContent: { run: r.id, phase: String(r.details?.phase ?? "starting") } }; } });
-  pi.registerTool?.({ name: "loop_talk", promptSnippet: "tell a running attempt something", executionMode: "sequential", annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true }, label: "loop_talk", description: "Tell a running attempt something (R1-bold, or just bold): delivered into its session as a steering message it acts on next.", parameters: Type.Object({ attempt: Type.String(), message: Type.String(), id: idParam }),
+  pi.registerTool?.({ name: "loop_talk", promptSnippet: "tell a running attempt something", executionMode: "sequential", annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false }, label: "loop_talk", description: "Tell a running attempt something (R1-bold, or just bold): delivered into its session as a steering message it acts on next.", parameters: Type.Object({ attempt: Type.String(), message: Type.String(), id: idParam }),
     async execute(_id, p) { const r = liveRun(p.id); const key = findAttempt(r, p.attempt); if (!key) throw new Error(`${p.attempt} is not running (running: ${[...r.attempts.keys()].join(", ") || "none"})`); await r.attempts.get(key).steer(`Message from the person running this loop: ${p.message}`); return said(`told ${key}: ${p.message}`); } });
   pi.registerTool?.({ name: "loop_rule", promptSnippet: "add a rule a running loop must follow", executionMode: "sequential", annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false }, label: "loop_rule", description: "Add a rule to a running loop: every running attempt is told now, the judge enforces it from this round on, and it stays for later rounds.", parameters: Type.Object({ rule: Type.String(), id: idParam }),
     async execute(_id, p) { const r = liveRun(p.id); if (!r.state.rules.includes(p.rule)) { r.state.rules.push(p.rule); if (r.state.rubric) addRule(r.state.rubric, p.rule); saveState(r.cwd, r.state); } await Promise.allSettled([...r.attempts.values()].map((s) => s.steer(`New rule for this loop, from the person running it: ${p.rule}`))); return said(`rule added: ${p.rule} (told ${r.attempts.size} running attempt${r.attempts.size === 1 ? "" : "s"})`); } });
   pi.registerTool?.({ name: "loop_pick", promptSnippet: "keep a specific attempt as the winner yourself", executionMode: "sequential", annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false }, label: "loop_pick", description: "Decide the running round yourself: when the judge is done, keep this attempt (R1-wild, or just wild; or CURRENT) as the best if its check passes, whatever the judge scored.", parameters: Type.Object({ attempt: Type.String(), id: idParam }),
     async execute(_id, p) { const r = liveRun(p.id); r.pick = p.attempt; return said(`when round ${r.details?.round ?? "?"} of ${r.id} is judged, ${p.attempt} is kept`); } });
-  pi.registerTool?.({ name: "loop_apply", promptSnippet: "take a run's best into the checkout (tracked files only)", outputSchema: ApplyResult, executionMode: "sequential", annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false }, label: "loop_apply", description: "Take a run's best into the checkout: checks out the winner's changed tracked files from its commit and commits them (files it added or deleted are listed, not applied). Default: this session's last run.", parameters: Type.Object({ id: idParam }),
+  pi.registerTool?.({ name: "loop_apply", promptSnippet: "take a run's best into the checkout (tracked files only)", outputSchema: ApplyResult, executionMode: "sequential", promptGuidelines: ["`loop_apply` takes the winner's changed *tracked* files as one commit; files it added or deleted are listed, not applied — copy those yourself if the round needs them."], annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false }, label: "loop_apply", description: "Take a run's best into the checkout: checks out the winner's changed tracked files from its commit and commits them (files it added or deleted are listed, not applied). Default: this session's last run.", parameters: Type.Object({ id: idParam }),
     async execute(_id, p, _signal, _onUpdate, ctx) {
       const mine = !p.id || p.id === "last" ? sessionRuns(ctx).find((id) => fs.existsSync(stateFile(ctx.cwd, id))) : null;
       const state = loadState(ctx.cwd, mine ?? p.id);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@computesdk/pi-loops",
-  "version": "1.0.4",
+  "version": "1.0.5",
   "description": "Hill-climbing loops as Pi units: one `loop` tool, style agents, forked attempt sessions in git worktrees, a judge keeps the best.",
   "keywords": [
     "pi-package",