@justjoshn/pi-pstack 0.15.36-pi.11 → 0.15.36-pi.13

package/src/generate-image.ts

@@ -0,0 +1,98 @@
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { basename, extname, isAbsolute, join, resolve } from 'node:path';
+
+import { detectSupportedImageMimeTypeFromFile, type ExtensionAPI, type ExtensionContext } from '@earendil-works/pi-coding-agent';
+import { Type } from 'typebox';
+
+export const GENERATE_IMAGE = 'GenerateImage';
+
+const ASPECT_RATIOS = ['1:1', '4:3', '3:4', '16:9', '9:16'] as const;
+const EXTENSIONS: Record<string, string> = { 'image/png': '.png', 'image/jpeg': '.jpg', 'image/gif': '.gif', 'image/webp': '.webp' };
+
+// Cursor's GenerateImage rules: explicit requests only, no data charts, a concrete description, and no Markdown echo.
+const DESCRIPTION = [
+  'Generate an image file from a text description.',
+  '',
+  'Use this tool only when the user explicitly asks for an image; do not generate images just to be helpful. Do not use it for data-heavy visuals such as charts, plots, or tables; make those with code or the visualize tool.',
+  '',
+  'Describe the image concretely first: the subjects, layout, style, colors, any text, and constraints, in at least 6 words. A description of 3 words or fewer is rejected. Set aspect_ratio when the user asks for one, and pass reference images in reference_image_paths.',
+  'The result shows the generated image and names the saved file, so do not repeat the image as Markdown in your reply.',
+].join('\n');
+
+const Params = Type.Object({
+  description: Type.String({ description: 'A detailed description of the image, at least 6 words. Descriptions of 3 words or fewer are rejected.' }),
+  filename: Type.Optional(Type.String({ description: "Optional file name for the image, such as 'diagram.png', without a directory. Defaults to a timestamped name." })),
+  reference_image_paths: Type.Optional(Type.Array(Type.String(), { description: 'Optional paths of reference images to use as additional inputs.' })),
+  aspect_ratio: Type.Optional(Type.Enum(ASPECT_RATIOS, { type: 'string', description: 'Optional aspect ratio: "1:1", "4:3", "3:4", "16:9", or "9:16".' })),
+});
+
+type ImageBlock = { type: 'image'; data: string; mimeType: string };
+
+async function referenceImage(path: string, cwd: string): Promise<ImageBlock> {
+  const absolute = isAbsolute(path) ? path : resolve(cwd, path);
+  const mimeType = await detectSupportedImageMimeTypeFromFile(absolute);
+  if (mimeType === null) throw new Error(`reference_image_paths: ${absolute} is not a PNG, JPEG, GIF, or WebP image.`);
+  return { type: 'image', data: readFileSync(absolute).toString('base64'), mimeType };
+}
+
+/** The saved file name: the requested name without any directory, with the extension the image data has. */
+export function imageFileName(requested: string | undefined, mimeType: string, index: number, now: Date): string {
+  const extension = EXTENSIONS[mimeType] ?? '.png';
+  const base = requested === undefined || basename(requested).trim() === '' ? `image-${now.toISOString().replace(/[:.]/g, '-')}` : basename(requested, extname(requested));
+  return `${base}${index === 0 ? '' : `-${index + 1}`}${extension}`;
+}
+
+/** The first image model Pi can call with the configured credentials. */
+async function imageModel(ctx: ExtensionContext) {
+  const [model] = await ctx.modelRegistry.getAvailableOfType('image');
+  return model;
+}
+
+/** Cursor's GenerateImage on Pi's image models, offered when one is available. Images save to the session's artifacts folder. */
+export interface GenerateImageOptions {
+  artifactsDir: (ctx: ExtensionContext) => string;
+  /** False where the session may not write files: a readonly subagent, or plan mode. */
+  mayOffer: () => boolean;
+}
+
+export function registerGenerateImage(pi: ExtensionAPI, options: GenerateImageOptions): void {
+  pi.registerTool({
+    name: GENERATE_IMAGE,
+    label: 'Generate image',
+    description: DESCRIPTION,
+    promptSnippet: 'Generate an image file from a text description',
+    parameters: Params,
+    defaultActive: false,
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+    async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+      if (params.description.trim().split(/\s+/).length <= 3) throw new Error('Describe the image in at least 6 words. Descriptions of 3 words or fewer are rejected.');
+      const model = await imageModel(ctx);
+      if (model === undefined) throw new Error('No image model is available. Configure one, such as an OpenRouter image model, to generate images.');
+      const references = await Promise.all((params.reference_image_paths ?? []).map((path) => referenceImage(path, ctx.cwd)));
+      const text = params.aspect_ratio === undefined ? params.description.trim() : `${params.description.trim()}\n\nAspect ratio: ${params.aspect_ratio}.`;
+      const result = await ctx.modelRegistry.generateImages(model, { input: [{ type: 'text', text }, ...references] }, signal === undefined ? undefined : { signal });
+      if (result.stopReason !== 'stop') throw new Error(`Image generation failed: ${result.errorMessage ?? result.stopReason}`);
+      const images = result.output.filter((block): block is ImageBlock => block.type === 'image');
+      if (images.length === 0) throw new Error('The image model returned no image.');
+      const dir = options.artifactsDir(ctx);
+      mkdirSync(dir, { recursive: true });
+      const now = new Date();
+      const paths = images.map((image, index) => {
+        const path = join(dir, imageFileName(params.filename, image.mimeType, index, now));
+        writeFileSync(path, Buffer.from(image.data, 'base64'));
+        return path;
+      });
+      return {
+        content: [{ type: 'text' as const, text: `Generated ${paths.length === 1 ? 'an image' : `${paths.length} images`} with ${model.provider}/${model.id}, saved to ${paths.join(', ')}.` }, ...images],
+        details: { paths, model: `${model.provider}/${model.id}` },
+      };
+    },
+  });
+
+  // The tool is on only while an image model is available, as Cursor offers GenerateImage only where it can run.
+  pi.on('session_start', async (_event, ctx) => {
+    if (!options.mayOffer() || (await imageModel(ctx)) === undefined) return;
+    const active = pi.getActiveTools();
+    if (!active.includes(GENERATE_IMAGE)) pi.setActiveTools([...active, GENERATE_IMAGE]);
+  });
+}

package/src/index.ts

@@ -1,13 +1,15 @@
+import { basename } from 'node:path';
+
 import type { ExtensionAPI, ExtensionContext } from '@earendil-works/pi-coding-agent';
 import { getAgentDir } from '@earendil-works/pi-coding-agent';
 import { aliasInputResult, aliasTable, packageSkillNames } from './aliases.ts';
 import { registerAskQuestion } from './ask.ts';
 import { aliasAutocomplete } from './autocomplete.ts';
 import { childIdentity } from './child-env.ts';
+import { registerGenerateImage } from './generate-image.ts';
 import { registerLoop } from './loop.ts';
 import { registerMode } from './mode.ts';
 import { canAsk, isOneShot } from './modes.ts';
-import { createPathSkills } from './path-skills.ts';
 import { artifactsDir, PACKAGE_ROOT, projectsDir, rootStoreDir, rulePath, SKILLS_DIR, storeDir, subagentDir } from './paths.ts';
 import { registerPlanMode } from './plan.ts';
 import { registerReadonlyShell } from './readonly-shell.ts';
@@ -23,10 +25,14 @@ import { registerVisualize } from './visualize.ts';
 const WATCHDOG_MS = 1_000;
 const ORPHAN_EXIT_MS = 5_000;
 
-/** In a subagent, the agent definition body joins the system prompt as the agent's own instructions. */
+// What Cursor tells every subagent in a system reminder, minus its sentence about Cursor Canvas files.
+const SUBAGENT_REMINDER = 'You are running as a subagent under a parent agent. Do not spawn additional subagents unless requested by the user or by your instructions.';
+
+/** In a subagent, Cursor's subagent reminder, and the agent definition body as the agent's own instructions. */
 function agentSection(agents: readonly AgentDefinition[]): Record<string, string> {
+  if (childIdentity.depth === 0) return {};
   const prompt = agents.find((agent) => agent.type === childIdentity.agentType)?.prompt ?? '';
-  return prompt === '' ? {} : { pstack_agent: prompt };
+  return { pstack_subagent: SUBAGENT_REMINDER, ...(prompt === '' ? {} : { pstack_agent: prompt }) };
 }
 
 function hostSections(pi: ExtensionAPI, ctx: ExtensionContext, agents: readonly AgentDefinition[]): Record<string, string> {
@@ -97,9 +103,15 @@ export default function piPstack(pi: ExtensionAPI): void {
   });
 
   const mode = registerMode(pi);
-  const plan = registerPlanMode(pi);
+  const plan = registerPlanMode(pi, {
+    ...(childIdentity.buildPlan === undefined ? {} : { buildPlan: childIdentity.buildPlan }),
+    setTodos: (items, ctx) => todos.replace(items, ctx),
+    buildInWorker: (planFile, request) => task.startBackground(`Build ${basename(planFile)}`, request, { environment: 'cloud', buildPlan: planFile }),
+  });
   registerVisualize(pi, { artifactsDir: (ctx) => artifactsDir(ctx.cwd, ctx.sessionManager.getSessionId()) });
-  const task = registerTask(pi, { agents, depth: childIdentity.depth, planMode: plan.enabled });
+  registerGenerateImage(pi, { artifactsDir: (ctx) => artifactsDir(ctx.cwd, ctx.sessionManager.getSessionId()), mayOffer: () => !childIdentity.readonly && !plan.enabled() });
+  const ownType = agents.find((agent) => agent.type === childIdentity.agentType);
+  const task = registerTask(pi, { agents, depth: childIdentity.depth, canSpawn: childIdentity.depth < 2 && ownType?.spawns !== false, planMode: plan.enabled });
   registerAgentStatus(pi);
   registerSubscriptions(pi, {
     runFresh: async (prompt, name, meta) => {
@@ -111,26 +123,22 @@ export default function piPstack(pi: ExtensionAPI): void {
     },
   });
   const loop = registerLoop(pi, { hasPendingWork: task.hasBackgroundWork });
-  const todos = registerTodoWrite(pi);
-  const pathSkills = createPathSkills(pi);
+  const todos = registerTodoWrite(pi, childIdentity.readonly ? {} : { onWrite: plan.syncTodos });
   registerAskQuestion(pi);
   if (childIdentity.parentPid !== undefined) watchParent(pi, childIdentity.parentPid);
   if (childIdentity.readonly) registerReadonlyShell(pi);
 
   pi.on('before_agent_start', (event, ctx) => {
-    const modeText = mode.section();
     const loopText = loop.section();
     const planText = plan.section();
     const todoText = todos.section();
-    const pathSkillText = pathSkills.section();
     Object.assign(
       event.systemPromptOptions.sections,
       hostSections(pi, ctx, agents),
-      modeText === undefined ? {} : { pstack_mode: modeText },
+      mode.sections(),
       loopText === undefined ? {} : { pstack_loop: loopText },
       planText === undefined ? {} : { pstack_plan: planText },
       todoText === undefined ? {} : { pstack_todos: todoText },
-      pathSkillText === undefined ? {} : { pstack_path_skills: pathSkillText },
     );
   });
 

package/src/loop.ts

@@ -1,5 +1,7 @@
+import { randomUUID } from 'node:crypto';
+
 import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext } from '@earendil-works/pi-coding-agent';
-import { Type } from 'typebox';
+import { type Static, Type } from 'typebox';
 import { isOneShot } from './modes.ts';
 
 const DAY_MS = 86_400_000;
@@ -30,19 +32,16 @@ function delayOf(text: string): number {
   return ms;
 }
 
-export type LoopCommand = { kind: 'status' } | { kind: 'stop' } | { kind: 'start'; prompt: string; intervalMs?: number } | { kind: 'error'; message: string };
+export type LoopCommand = { kind: 'status' } | { kind: 'stop'; loopId?: string } | { kind: 'start'; prompt: string; intervalMs?: number } | { kind: 'error'; message: string };
 
-/** The longest trailing phrase that parses as a duration, such as `5m`, `every 10 minutes`, or `1 hour 30 minutes`. */
-function trailingInterval(text: string): { prompt: string; intervalMs: number } | undefined {
-  const tokens = text.split(/\s+/);
-  for (let take = Math.min(6, tokens.length); take >= 1; take -= 1) {
-    const intervalMs = parseDuration(tokens.slice(-take).join(' '));
+function edgeInterval(text: string, edge: 'leading' | 'trailing'): { prompt: string; intervalMs: number } | undefined {
+  const tokens = [...text.matchAll(/\S+/g)];
+  for (let take = tokens.length; take >= 1; take -= 1) {
+    const start = edge === 'leading' ? 0 : (tokens[tokens.length - take]?.index ?? 0);
+    const end = edge === 'trailing' ? text.length : (tokens[take - 1]?.index ?? 0) + (tokens[take - 1]?.[0].length ?? 0);
+    const intervalMs = parseDuration(text.slice(start, end));
     if (intervalMs === undefined) continue;
-    const prompt = tokens
-      .slice(0, -take)
-      .join(' ')
-      .replace(/\s+every$/i, '')
-      .trim();
+    const prompt = (edge === 'leading' ? text.slice(end) : text.slice(0, start).replace(/\s+every\s*$/i, '')).trim();
     return { prompt, intervalMs };
   }
   return undefined;
@@ -51,20 +50,13 @@ function trailingInterval(text: string): { prompt: string; intervalMs: number }
 export function parseLoopArgs(args: string): LoopCommand {
   const trimmed = args.trim();
   if (trimmed === '') return { kind: 'status' };
-  if (trimmed === 'stop' || trimmed === 'off') return { kind: 'stop' };
-  const [, first = '', rest = ''] = /^(\S+)\s*([\s\S]*)$/.exec(trimmed) ?? [];
-  const leadMs = parseDuration(first) ?? (first.toLowerCase() === 'every' ? parseDuration(rest.split(/\s+/)[0] ?? '') : undefined);
-  if (leadMs !== undefined) {
-    if (leadMs > MAX_DELAY_MS) return { kind: 'error', message: TOO_LONG };
-    const after = first.toLowerCase() === 'every' ? rest.split(/\s+/).slice(1).join(' ') : rest;
-    return after.trim() === '' ? { kind: 'error', message: '/loop needs a prompt: /loop [interval] <prompt>' } : { kind: 'start', prompt: after.trim(), intervalMs: leadMs };
-  }
-  // Cursor accepts the interval at either end, including `every 10 minutes`, so both ends are tried before treating it as a prompt.
-  const trailing = trailingInterval(trimmed);
-  if (trailing !== undefined) {
-    if (trailing.intervalMs > MAX_DELAY_MS) return { kind: 'error', message: TOO_LONG };
-    if (trailing.prompt === '') return { kind: 'error', message: '/loop needs a prompt: /loop [interval] <prompt>' };
-    return { kind: 'start', prompt: trailing.prompt, intervalMs: trailing.intervalMs };
+  const stop = /^(?:stop|off)(?:\s+(\S+))?$/.exec(trimmed);
+  if (stop !== null) return { kind: 'stop', ...(stop[1] === undefined ? {} : { loopId: stop[1] }) };
+  const interval = edgeInterval(trimmed, 'leading') ?? edgeInterval(trimmed, 'trailing');
+  if (interval !== undefined) {
+    if (interval.intervalMs > MAX_DELAY_MS) return { kind: 'error', message: TOO_LONG };
+    if (interval.prompt === '') return { kind: 'error', message: '/loop needs a prompt: /loop [interval] <prompt>' };
+    return { kind: 'start', ...interval };
   }
   return { kind: 'start', prompt: trimmed };
 }
@@ -75,6 +67,8 @@ interface Loop {
   iteration: number;
   nextWakeMs?: number;
   timer?: ReturnType<typeof setTimeout>;
+  /** A wake came due while a run was going; it fires once when that run settles. */
+  due?: boolean;
 }
 
 const formatMs = (ms: number) => (ms % 86_400_000 === 0 ? `${ms / 86_400_000}d` : ms % 3_600_000 === 0 ? `${ms / 3_600_000}h` : ms % 60_000 === 0 ? `${ms / 60_000}m` : `${Math.round(ms / 1_000)}s`);
@@ -107,39 +101,45 @@ function createLoopController(pi: ExtensionAPI, options: LoopOptions) {
     clear();
     notify(ctx, `Loop stopped: ${reason}`);
   };
-  const fire = (first = false) => {
+  const run = () => {
     if (loop === undefined) return;
-    // A scheduled tick that lands mid-run is skipped rather than queued, so one long run cannot leave a pile of stale ticks.
-    if (!first && lastCtx !== undefined && !lastCtx.isIdle()) {
-      if (loop.intervalMs !== undefined) loop = { ...loop, timer: setTimeout(fire, loop.intervalMs) };
-      return;
-    }
-    const { timer: _timer, nextWakeMs: _wake, ...rest } = loop;
-    loop = { ...rest, iteration: rest.iteration + 1 };
+    loop = { ...loop, iteration: loop.iteration + 1, due: false };
     // Expansion lets a loop run a skill or template each time.
-    pi.sendUserMessage(loop.prompt, { expandPromptTemplates: true });
-    // A fixed loop is wall-clock from each fire, like the reference's sleep loop: a long run does not push the next tick out.
-    if (loop.intervalMs !== undefined) loop = { ...loop, timer: setTimeout(fire, loop.intervalMs) };
+    pi.sendUserMessage(loop.prompt, { expandPromptTemplates: true, deliverAs: 'followUp' });
+  };
+  /**
+   * A timer fired. A fixed loop keeps its wall-clock cadence, like Cursor's sleep-and-echo shell loop, so a long run
+   * does not push the next tick out. A wake that lands while a run is going is delivered once that run settles, as
+   * Cursor's monitored shell output notifies after the turn, and several such wakes fire once, not once each.
+   */
+  const tick = () => {
+    if (loop === undefined) return;
+    const { timer: _spent, nextWakeMs: _wake, ...rest } = loop;
+    loop = rest.intervalMs === undefined ? rest : { ...rest, timer: setTimeout(tick, rest.intervalMs) };
+    if (lastCtx !== undefined && !lastCtx.isIdle()) loop = { ...loop, due: true };
+    else run();
   };
   const settled = (ctx: ExtensionContext, aborted: boolean) => {
     lastCtx = ctx;
     if (loop === undefined) return;
     if (aborted) return stop(ctx, 'the run was aborted.');
+    if (loop.due === true) return run();
     if (loop.timer !== undefined) return;
     if (loop.intervalMs !== undefined) {
       // An armed fixed loop has no timer yet; its first tick waits for this turn to end.
-      loop = { ...loop, timer: setTimeout(fire, loop.intervalMs) };
+      loop = { ...loop, timer: setTimeout(tick, loop.intervalMs) };
       return;
     }
     const delay = loop.nextWakeMs;
-    if (delay !== undefined) loop = { ...loop, timer: setTimeout(fire, delay) };
+    if (delay !== undefined) loop = { ...loop, timer: setTimeout(tick, delay) };
     else if (!options.hasPendingWork()) stop(ctx, 'the agent scheduled no next wake.');
   };
   const start = (ctx: ExtensionContext, prompt: string, intervalMs: number | undefined) => {
     if (loop !== undefined) stop(ctx, 'replaced by a new /loop.');
     lastCtx = ctx;
     loop = { prompt, iteration: 0, ...(intervalMs === undefined ? {} : { intervalMs }) };
-    fire(true);
+    run();
+    if (loop.intervalMs !== undefined) loop = { ...loop, timer: setTimeout(tick, loop.intervalMs) };
   };
   /** An agent arms a loop mid-turn, so its first run waits for this turn to settle and then for the first delay. */
   const arm = (ctx: ExtensionContext, prompt: string, schedule: { intervalMs: number } | { firstWakeMs: number }) => {
@@ -159,31 +159,77 @@ function createLoopController(pi: ExtensionAPI, options: LoopOptions) {
     loop = { ...rest, nextWakeMs: delayMs };
   };
   const section = () => (loop === undefined ? undefined : loopSection(loop));
-  return { notify, stop, settled, start, arm, status, wake, clear, section, active: () => loop !== undefined };
+  return { stop, settled, start, arm, status, wake, clear, section, prompt: () => loop?.prompt, active: () => loop !== undefined };
+}
+
+function createLoopRegistry(pi: ExtensionAPI, options: LoopOptions) {
+  const controllers = new Map<string, ReturnType<typeof createLoopController>>();
+  const entries = () => {
+    for (const [id, controller] of controllers) if (!controller.active()) controllers.delete(id);
+    return [...controllers];
+  };
+  const choose = (loopId?: string, prompt?: string) => {
+    const active = entries();
+    const existing = active.find(([id, controller]) => (loopId !== undefined ? id === loopId : prompt !== undefined ? controller.prompt() === prompt : active.length === 1));
+    if (existing !== undefined) return { loopId: existing[0], controller: existing[1] };
+    if (loopId !== undefined) throw new Error(`No running loop has id "${loopId}". /loop lists running loops.`);
+    if (prompt !== undefined) {
+      const id = randomUUID();
+      const controller = createLoopController(pi, options);
+      controllers.set(id, controller);
+      return { loopId: id, controller };
+    }
+    if (active.length === 0) throw new Error('No loop is running.');
+    throw new Error(`Several loops are running. Pass loop_id to choose one, or use /loop stop <id>. Running loops:\n${active.map(([id, controller]) => `${id} ${controller.status()}`).join('\n')}`);
+  };
+  const status = () => {
+    const active = entries();
+    if (active.length === 0) return 'No loop is running. Usage: /loop [interval] <prompt>, with the interval at either end; /loop stop ends one.';
+    return active.map(([id, controller]) => (active.length === 1 ? controller.status() : `${id} ${controller.status()}`)).join('\n');
+  };
+  const section = () => {
+    const active = entries();
+    if (active.length === 0) return undefined;
+    if (active.length === 1) return active[0]?.[1].section();
+    return [...active.map(([id, controller]) => `Loop ${id} runs ${JSON.stringify(controller.prompt())}.\n${controller.section()}`), 'Several loops are running. Pass loop_id with wake_in or stop so only the intended loop changes.'].join(
+      '\n\n',
+    );
+  };
+  return { choose, entries, status, section };
 }
 
 type LoopController = ReturnType<typeof createLoopController>;
+type LoopRegistry = ReturnType<typeof createLoopRegistry>;
 
 const ONE_SHOT = '/loop needs an interactive or RPC session; print and JSON runs exit when the agent settles.';
 
-function handleLoopCommand(controller: LoopController, args: string, ctx: ExtensionCommandContext): void {
+function handleLoopCommand(registry: LoopRegistry, args: string, ctx: ExtensionCommandContext): void {
   const command = parseLoopArgs(args);
-  if (command.kind === 'status') controller.notify(ctx, controller.status());
-  else if (command.kind === 'stop') controller.stop(ctx, 'stopped by /loop stop.');
-  else if (command.kind === 'error') controller.notify(ctx, command.message);
-  else if (isOneShot(ctx.mode)) process.stderr.write(`${ONE_SHOT}\n`);
-  else controller.start(ctx, command.prompt, command.intervalMs);
+  try {
+    if (command.kind === 'status') ctx.ui.notify(registry.status(), 'info');
+    else if (command.kind === 'stop') registry.choose(command.loopId).controller.stop(ctx, 'stopped by /loop stop.');
+    else if (command.kind === 'error') ctx.ui.notify(command.message, 'error');
+    else if (isOneShot(ctx.mode)) process.stderr.write(`${ONE_SHOT}\n`);
+    else registry.choose(undefined, command.prompt).controller.start(ctx, command.prompt, command.intervalMs);
+  } catch (error) {
+    ctx.ui.notify(error instanceof Error ? error.message : String(error), 'error');
+  }
 }
 
 const LoopParams = Type.Object({
-  prompt: Type.Optional(Type.String({ description: 'Start (or replace) a loop that sends this prompt each run. It may be a skill or template command such as /poteto-mode <task>.' })),
+  loop_id: Type.Optional(Type.String({ description: 'Loop ID from an earlier Loop result. Required to wake, stop, or replace one loop when several are running. Omit with a new prompt to start an independent loop.' })),
+  prompt: Type.Optional(
+    Type.String({
+      description:
+        'Start a loop that sends this prompt each run. A different prompt starts an independent loop; the same prompt or an explicit loop_id replaces its earlier schedule. It may be a skill or template command such as /poteto-mode <task>.',
+    }),
+  ),
   interval: Type.Optional(Type.String({ description: 'With prompt: a fixed cadence such as 30m or 1h; the first run starts that long after this turn ends.' })),
   wake_in: Type.Optional(Type.String({ description: 'With prompt: the first run of an agent-paced loop. Alone: the next run of the running agent-paced loop. A duration such as 10m, at most 24d.' })),
   stop: Type.Optional(Type.Boolean({ description: 'End the loop once its goal is met.' })),
 });
 
-function loopToolText(controller: LoopController, params: { prompt?: string; interval?: string; wake_in?: string; stop?: boolean }, ctx: ExtensionContext): string {
-  if (isOneShot(ctx.mode)) throw new Error(`${ONE_SHOT} Do the work now instead of scheduling it.`);
+function loopToolText(controller: LoopController, params: Static<typeof LoopParams>, ctx: ExtensionContext): string {
   if (params.stop === true) {
     if (!controller.active()) throw new Error('No loop is running.');
     controller.stop(ctx, 'the agent ended it.');
@@ -207,32 +253,39 @@ function loopToolText(controller: LoopController, params: { prompt?: string; int
   return `Next loop run in ${formatMs(delay)}, after this turn ends.`;
 }
 
-function registerLoopTool(pi: ExtensionAPI, controller: LoopController): void {
+function registerLoopTool(pi: ExtensionAPI, registry: LoopRegistry): void {
   pi.registerTool({
     name: 'Loop',
     label: 'Loop',
-    description: '/loop for you: start a loop that re-sends a prompt at a fixed interval or at wakes you pick, schedule the next wake of an agent-paced loop, or stop the loop once its goal is met. Use it when a playbook says to arm /loop.',
+    description:
+      '/loop for you: start an independent loop that re-sends a prompt at a fixed interval or at wakes you pick, schedule its next wake, or stop it once its goal is met. Use it when a playbook says to arm /loop. Each result names the loop ID. With several loops running, pass loop_id to wake or stop the intended loop.',
     promptSnippet: 'Start a /loop, schedule its next wake, or stop it',
     parameters: LoopParams,
     annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false },
     async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
-      return { content: [{ type: 'text', text: loopToolText(controller, params, ctx) }], details: undefined };
+      if (isOneShot(ctx.mode)) throw new Error(`${ONE_SHOT} Do the work now instead of scheduling it.`);
+      const { loopId, controller } = registry.choose(params.loop_id, params.prompt);
+      return { content: [{ type: 'text', text: `${loopToolText(controller, params, ctx)}\nLoop ID: ${loopId}` }], details: { loopId } };
     },
   });
 }
 
 /** /loop: run a prompt at a fixed interval, or at wakes the agent picks, until stopped. */
 export function registerLoop(pi: ExtensionAPI, options: LoopOptions): { section: () => string | undefined } {
-  const controller = createLoopController(pi, options);
+  const registry = createLoopRegistry(pi, options);
   pi.on('session_start', (_event, ctx) => {
     if (isOneShot(ctx.mode)) pi.setActiveTools(pi.getActiveTools().filter((name) => name !== 'Loop'));
   });
-  pi.on('agent_settled', (event, ctx) => controller.settled(ctx, event.aborted));
-  pi.on('session_shutdown', () => controller.clear());
+  pi.on('agent_settled', (event, ctx) => {
+    for (const [, controller] of registry.entries()) controller.settled(ctx, event.aborted);
+  });
+  pi.on('session_shutdown', () => {
+    for (const [, controller] of registry.entries()) controller.clear();
+  });
   pi.registerCommand('loop', {
-    description: 'Run a prompt repeatedly: /loop [interval] <prompt>, interval either end and like 30s, 5m, 1h, every 10 minutes (at most 24d); /loop stop',
-    handler: async (args, ctx) => handleLoopCommand(controller, args, ctx),
+    description: 'Run independent prompts repeatedly: /loop [interval] <prompt>, interval either end and like 30s, 5m, 1h, every 10 minutes (at most 24d); /loop lists them; /loop stop [id] stops one',
+    handler: async (args, ctx) => handleLoopCommand(registry, args, ctx),
   });
-  registerLoopTool(pi, controller);
-  return { section: controller.section };
+  registerLoopTool(pi, registry);
+  return { section: registry.section };
 }