@robota-sdk/agent-command 3.0.0-beta.79 → 3.0.0-beta.82

package/src/schedule/__tests__/schedule-redos.test.ts

@@ -0,0 +1,81 @@
+/**
+ * SEC-003 (`js/polynomial-redos`): `/schedule cron` and `/monitor` argument parsing must stay
+ * linear in the length of their argument string.
+ *
+ * Both commands are declared `modelInvocable: true` (see `schedule-command-module.ts`), so the
+ * argument string is composed by the model — a prompt-injected model can therefore choose it.
+ * The pre-fix regexes used `\s+(.+)$`; because `.` also matches a space, the split point between
+ * `\s+` and `(.+)` was ambiguous and a non-matching argument was rejected in O(n^2). Measured
+ * pre-fix on the inputs below: ~17s (`/schedule cron`) and ~15s (`/monitor`); post-fix, <1ms.
+ */
+
+import { describe, expect, it, vi } from 'vitest';
+
+import { executeMonitorCommand } from '../schedule-command.js';
+import { parseScheduleSpec } from '../schedule-spec-parser.js';
+
+import type { IAgentJobHostContext } from '@robota-sdk/agent-framework';
+import { createTestAgentJobHost } from '@robota-sdk/agent-framework/testing';
+
+/** Long enough that the quadratic path takes >10s while the linear path stays sub-millisecond. */
+const PUMP_LENGTH = 200_000;
+
+/** Generous versus the <1ms the linear parse costs, and versus the >10s the quadratic one did. */
+const BUDGET_MS = 250;
+
+function elapsedMs(run: () => void): number {
+  const started = performance.now();
+  run();
+  return performance.now() - started;
+}
+
+describe('schedule argument parsing is not polynomial-ReDoS-able', () => {
+  it('rejects a pumped `cron` spec in linear time', () => {
+    // Rejected because `(.+)$` cannot cross the newline, which is what forces the full backtrack.
+    const hostile = `cron "* * * * *"${' '.repeat(PUMP_LENGTH)}a\nb`;
+
+    const took = elapsedMs(() => {
+      const result = parseScheduleSpec(hostile, 0);
+      expect(result.ok).toBe(false);
+    });
+
+    expect(took).toBeLessThan(BUDGET_MS);
+  });
+
+  it('rejects pumped `/monitor` arguments in linear time', async () => {
+    const host = createTestAgentJobHost();
+    const hostile = `"cmd" "pattern"${' '.repeat(PUMP_LENGTH)}a\nb`;
+
+    const started = performance.now();
+    const result = await executeMonitorCommand(host, hostile);
+    const took = performance.now() - started;
+
+    expect(result.success).toBe(false);
+    expect(took).toBeLessThan(BUDGET_MS);
+  });
+
+  it('still parses well-formed specs identically', () => {
+    const parsed = parseScheduleSpec('cron "0 9 * * *"   send the digest  ', 0);
+
+    expect(parsed).toEqual({
+      ok: true,
+      spec: { cronExpression: '0 9 * * *', instruction: 'send the digest', recurring: true },
+    });
+  });
+
+  it('still parses well-formed `/monitor` arguments identically', async () => {
+    const spawnMonitorWake = vi.fn().mockResolvedValue({ id: 'job-1' });
+    const host = createTestAgentJobHost({ spawnMonitorWake });
+
+    const result = await executeMonitorCommand(host, '  "pnpm build" "error"   report it  ');
+
+    expect(result.success).toBe(true);
+    expect(spawnMonitorWake).toHaveBeenCalledWith(
+      expect.objectContaining({
+        command: 'pnpm build',
+        matchPattern: 'error',
+        agentInstruction: 'report it',
+      }),
+    );
+  });
+});

package/src/schedule/index.ts

@@ -1,9 +1,12 @@
 export {
   createScheduleCommandEntry,
   createMonitorCommandEntry,
+  createLoopCommandEntry,
   createScheduleCommandModule,
   ScheduleCommandSource,
 } from './schedule-command-module.js';
 export { executeScheduleCommand, executeMonitorCommand } from './schedule-command.js';
+export { executeLoopCommand } from './loop-command.js';
+export type { ILoopCommandOptions } from './loop-command.js';
 export { parseScheduleSpec } from './schedule-spec-parser.js';
 export type { IScheduleSpec, TScheduleParseResult } from './schedule-spec-parser.js';

package/src/schedule/loop-command.ts

@@ -0,0 +1,333 @@
+/** Fixed or self-paced session-local repetition. */
+
+import { randomUUID } from 'node:crypto';
+
+import { jitterFixedLoop } from './loop-jitter.js';
+
+import type { IAgentJobHostContext } from '@robota-sdk/agent-framework';
+import type { ICommandResult } from '@robota-sdk/agent-interface-command';
+import type { IBackgroundTaskState } from '@robota-sdk/agent-interface-execution';
+
+const LOOP_LABEL = 'Loop: ';
+const SECONDS_PER_MINUTE = 60;
+const HOURS_PER_DAY = 24;
+const MAX_LABEL_LENGTH = 48;
+const MAX_ACTIVE_LOOPS = 3;
+const LOOP_LIFETIME_MS = 7 * 24 * 60 * 60_000;
+const MAX_DEFAULT_PROMPT_LENGTH = 4_096;
+const pendingCreates = new WeakMap<object, number>();
+const TRAILING_UNITS = new Set([
+  'second', 'seconds', 'minute', 'minutes', 'hour', 'hours', 'day', 'days', 's', 'm', 'h', 'd',
+]);
+const USAGE =
+  'Usage: /loop [<prompt>] | /loop <N><s|m|h|d> [<prompt>] | /loop <prompt> every <N> <unit> | /loop list | /loop stop <id>. Bare and interval-only forms require a host maintenance prompt.';
+
+export interface ILoopCommandOptions {
+  /** Product-host-owned maintenance text, used only when the operator omits a prompt. */
+  defaultPrompt?: string;
+  /** Re-read the project/user default for each new loop; an explicit prompt never calls this. */
+  resolveDefaultPrompt?: () => string;
+  /** Host kill switch; listing and stopping existing loops remain available. */
+  disabled?: boolean;
+}
+
+const UNIT_MS: Record<string, number> = {
+  s: 1_000,
+  m: 60_000,
+  h: 3_600_000,
+  d: 86_400_000,
+};
+
+interface ILoopCadence {
+  cronExpression: string;
+  milliseconds: number;
+  description: string;
+}
+
+const CADENCES: ILoopCadence[] = [
+  ...divisors(SECONDS_PER_MINUTE).map((n) => ({
+    cronExpression: n === SECONDS_PER_MINUTE ? '0 * * * * *' : `*/${n} * * * * *`,
+    milliseconds: n * UNIT_MS.s!,
+    description: `${n}s`,
+  })),
+  ...divisors(SECONDS_PER_MINUTE)
+    .filter((n) => n > 1)
+    .map((n) => ({
+      cronExpression: n === SECONDS_PER_MINUTE ? '0 0 * * * *' : `0 */${n} * * * *`,
+      milliseconds: n * UNIT_MS.m!,
+      description: `${n}m`,
+    })),
+  ...divisors(HOURS_PER_DAY)
+    .filter((n) => n > 1)
+    .map((n) => ({
+      cronExpression: n === HOURS_PER_DAY ? '0 0 0 * * *' : `0 0 */${n} * * *`,
+      milliseconds: n * UNIT_MS.h!,
+      description: `${n}h`,
+    })),
+];
+
+function divisors(maximum: number): number[] {
+  return Array.from({ length: maximum }, (_, index) => index + 1).filter(
+    (value) => maximum % value === 0,
+  );
+}
+
+function parseDuration(amountText: string, unit: string): number | undefined {
+  const amount = Number(amountText);
+  const multiplier = UNIT_MS[unit];
+  if (!Number.isSafeInteger(amount) || amount <= 0 || multiplier === undefined) return undefined;
+  const milliseconds = amount * multiplier;
+  return Number.isSafeInteger(milliseconds) && milliseconds <= UNIT_MS.d ? milliseconds : undefined;
+}
+
+function parseTrailingInterval(args: string): { instruction: string; amount: string; unit: string } | undefined {
+  let cursor = args.length;
+  while (cursor > 0 && /[a-z]/i.test(args[cursor - 1]!)) cursor -= 1;
+  const unit = args.slice(cursor).toLowerCase();
+  if (!TRAILING_UNITS.has(unit)) return undefined;
+  while (cursor > 0 && /\s/u.test(args[cursor - 1]!)) cursor -= 1;
+  const amountEnd = cursor;
+  while (cursor > 0 && args.charCodeAt(cursor - 1) >= 48 && args.charCodeAt(cursor - 1) <= 57) cursor -= 1;
+  if (cursor === amountEnd) return undefined;
+  const amount = args.slice(cursor, amountEnd);
+  const spaceAfterEvery = cursor;
+  while (cursor > 0 && /\s/u.test(args[cursor - 1]!)) cursor -= 1;
+  if (cursor === spaceAfterEvery || args.slice(cursor - 5, cursor).toLowerCase() !== 'every') return undefined;
+  cursor -= 5;
+  const spaceBeforeEvery = cursor;
+  while (cursor > 0 && /\s/u.test(args[cursor - 1]!)) cursor -= 1;
+  if (cursor === spaceBeforeEvery) return undefined;
+  const instruction = args.slice(0, cursor).trim();
+  return instruction ? { instruction, amount, unit } : undefined;
+}
+
+function parseCreate(
+  args: string,
+  defaultPrompt: string | undefined,
+): { instruction: string; requestedMs: number } | undefined {
+  const boundedDefault =
+    defaultPrompt && defaultPrompt.length <= MAX_DEFAULT_PROMPT_LENGTH
+      ? defaultPrompt.trim()
+      : undefined;
+  if (args === '') return undefined;
+  const intervalOnly = /^(\d+)(s|m|h|d)$/i.exec(args);
+  if (intervalOnly && boundedDefault) {
+    const requestedMs = parseDuration(intervalOnly[1]!, intervalOnly[2]!.toLowerCase());
+    return requestedMs === undefined ? undefined : { instruction: boundedDefault, requestedMs };
+  }
+  const leading = /^(\d+)(s|m|h|d)\s+([\s\S]+)$/i.exec(args);
+  if (leading) {
+    const instruction = leading[3]!.trim();
+    const requestedMs = parseDuration(leading[1]!, leading[2]!.toLowerCase());
+    if (instruction && requestedMs !== undefined && !parseTrailingInterval(instruction)) {
+      return { instruction, requestedMs };
+    }
+    return undefined;
+  }
+
+  const trailing = parseTrailingInterval(args);
+  if (!trailing) return undefined;
+  const requestedMs = parseDuration(trailing.amount, trailing.unit[0]!);
+  return requestedMs !== undefined ? { instruction: trailing.instruction, requestedMs } : undefined;
+}
+
+function chooseCadence(requestedMs: number): ILoopCadence {
+  // Calendar-aligned cron steps cannot express every duration. Choose the first step that is
+  // never more frequent than requested, and report the normalization to the caller.
+  return CADENCES.find((cadence) => cadence.milliseconds >= requestedMs)!;
+}
+
+function activeLoops(host: Pick<IAgentJobHostContext, 'listSchedules'>): IBackgroundTaskState[] {
+  return host
+    .listSchedules()
+    .filter(
+      (task) =>
+        task.metadata?.['sessionLoop'] === true &&
+        task.metadata?.['sessionLoopSelfPaced'] !== true &&
+        task.status !== 'cancelled' &&
+        task.status !== 'completed' &&
+        task.status !== 'failed',
+    );
+}
+
+function activeSelfPacedLoops(host: Pick<IAgentJobHostContext, 'listSelfPacedLoops'>) {
+  return (host.listSelfPacedLoops?.() ?? []).filter(
+    (loop) => loop.phase !== 'stopped' && loop.phase !== 'expired',
+  );
+}
+
+function loopIdOf(task: IBackgroundTaskState): string {
+  const id = task.metadata?.['sessionLoopId'];
+  // Loops created before stable ids were introduced keep their runtime id as the stop handle.
+  return typeof id === 'string' && id.length > 0 ? id : task.id;
+}
+
+export async function executeLoopCommand(
+  host: Pick<IAgentJobHostContext, 'spawnScheduledWake' | 'listSchedules' | 'createSelfPacedLoop' | 'listSelfPacedLoops' | 'stopSelfPacedLoop'>,
+  cancelBackgroundTask: (taskId: string, reason: string) => Promise<void>,
+  args: string,
+  options: ILoopCommandOptions = {},
+): Promise<ICommandResult> {
+  const trimmed = args.trim();
+  if (trimmed === 'list') return listLoops(host, options);
+  if (/^stop(?:\s|$)/.test(trimmed)) return stopLoop(host, cancelBackgroundTask, trimmed);
+
+  if (options.disabled) {
+    return { success: false, message: 'Session loops are disabled by the host.' };
+  }
+  return createLoop(host, trimmed, options);
+}
+
+function listLoops(
+  host: Pick<IAgentJobHostContext, 'listSchedules' | 'listSelfPacedLoops'>,
+  options: ILoopCommandOptions,
+): ICommandResult {
+  const loops = activeLoops(host);
+  const selfPaced = activeSelfPacedLoops(host);
+  const header = options.disabled ? 'Session loops are disabled by the host.\n' : '';
+  return {
+    success: true,
+    message:
+      header +
+      (loops.length + selfPaced.length === 0
+        ? 'No active loops.'
+        : [
+            ...loops.map((task) => `- ${loopIdOf(task)} [${task.status}] ${task.label}`),
+            ...selfPaced.map((loop) =>
+              `- ${loop.loopId} [${loop.phase}] Loop: ${loop.instruction}` +
+              (loop.phase === 'waiting' && loop.delaySeconds !== undefined && loop.reason
+                ? ` — next ${loop.delaySeconds}s: ${loop.reason}`
+                : ''),
+            ),
+          ].join('\n')),
+    data: { count: loops.length + selfPaced.length },
+  };
+}
+
+async function stopLoop(
+  host: Pick<IAgentJobHostContext, 'listSchedules' | 'listSelfPacedLoops' | 'stopSelfPacedLoop'>,
+  cancelBackgroundTask: (taskId: string, reason: string) => Promise<void>,
+  args: string,
+): Promise<ICommandResult> {
+  const match = /^stop\s+(\S+)$/.exec(args);
+  if (!match) return { success: false, message: USAGE };
+  const selfPaced = activeSelfPacedLoops(host).find((loop) => loop.loopId === match[1]);
+  if (selfPaced) {
+    if (!host.stopSelfPacedLoop) return { success: false, message: 'This host cannot stop self-paced loops.' };
+    await host.stopSelfPacedLoop(selfPaced.loopId, 'Loop stopped by user');
+    return {
+      success: true,
+      message: `Loop stopped: ${selfPaced.loopId}. An already-running turn may finish.`,
+      data: { loopId: selfPaced.loopId },
+    };
+  }
+  const task = activeLoops(host).find((candidate) => loopIdOf(candidate) === match[1]);
+  if (!task) return { success: false, message: `Active loop not found: ${match[1]}` };
+  await cancelBackgroundTask(task.id, 'Loop stopped by user');
+  return {
+    success: true,
+    message: `Loop stopped: ${loopIdOf(task)}. An already-running turn may finish.`,
+    data: { loopId: loopIdOf(task), taskId: task.id },
+  };
+}
+
+async function createLoop(
+  host: Pick<IAgentJobHostContext, 'spawnScheduledWake' | 'listSchedules' | 'createSelfPacedLoop' | 'listSelfPacedLoops'>,
+  args: string,
+  options: ILoopCommandOptions,
+): Promise<ICommandResult> {
+  const useDefaultPrompt = args === '' || /^\d+(s|m|h|d)$/i.test(args);
+  let defaultPrompt = options.defaultPrompt;
+  if (useDefaultPrompt && options.resolveDefaultPrompt) {
+    try {
+      defaultPrompt = options.resolveDefaultPrompt();
+    } catch (error) {
+      return { success: false, message: `Default loop prompt could not be loaded: ${error instanceof Error ? error.message : String(error)}` };
+    }
+  }
+  const parsed = parseCreate(args, defaultPrompt);
+  if (!parsed) {
+    if (/^\d+[a-z](?:\s|$)/i.test(args) || parseTrailingInterval(args)) {
+      return { success: false, message: USAGE };
+    }
+    const instruction = (args || defaultPrompt || '').trim();
+    if (!instruction || (args === '' && instruction.length > MAX_DEFAULT_PROMPT_LENGTH)) {
+      return { success: false, message: USAGE };
+    }
+    if (!host.createSelfPacedLoop) {
+      return { success: false, message: 'Self-paced loops require a persistent interactive session.' };
+    }
+    const pending = pendingCreates.get(host) ?? 0;
+    if (activeLoops(host).length + activeSelfPacedLoops(host).length + pending >= MAX_ACTIVE_LOOPS) {
+      return { success: false, message: `At most ${MAX_ACTIVE_LOOPS} active loops are allowed. Stop one before creating another.` };
+    }
+    pendingCreates.set(host, pending + 1);
+    try {
+      const loop = useDefaultPrompt
+        ? await host.createSelfPacedLoop(instruction, { useDefaultPrompt: true })
+        : await host.createSelfPacedLoop(instruction);
+      return {
+        success: true,
+        message: `Self-paced loop ${loop.loopId} started. It will choose a 1–60 minute delay after each iteration and expires ${loop.expiresAt}. Stop with /loop stop ${loop.loopId}.`,
+        data: { loopId: loop.loopId, expiresAt: loop.expiresAt },
+      };
+    } finally {
+      const remaining = (pendingCreates.get(host) ?? 1) - 1;
+      if (remaining === 0) pendingCreates.delete(host);
+      else pendingCreates.set(host, remaining);
+    }
+  }
+  const pending = pendingCreates.get(host) ?? 0;
+  if (activeLoops(host).length + activeSelfPacedLoops(host).length + pending >= MAX_ACTIVE_LOOPS) {
+    return {
+      success: false,
+      message: `At most ${MAX_ACTIVE_LOOPS} active loops are allowed. Stop one before creating another.`,
+    };
+  }
+  const cadence = chooseCadence(parsed.requestedMs);
+  const label = `${LOOP_LABEL}${parsed.instruction.slice(0, MAX_LABEL_LENGTH)}`;
+  const loopId = `loop_${randomUUID()}`;
+  const jitter = jitterFixedLoop(loopId, cadence);
+  const nowMs = Date.now();
+  const firstAllowedAt = new Date(nowMs + parsed.requestedMs).toISOString();
+  const expiresAt = new Date(nowMs + LOOP_LIFETIME_MS).toISOString();
+  pendingCreates.set(host, pending + 1);
+  let task: IBackgroundTaskState;
+  try {
+    task = await host.spawnScheduledWake({
+      label,
+      cronExpression: jitter.cronExpression,
+      agentInstruction: parsed.instruction,
+      sessionLoop: true,
+      sessionLoopId: loopId,
+      ...(useDefaultPrompt ? { sessionLoopDefaultPrompt: true } : {}),
+      sessionLoopFirstAllowedAt: firstAllowedAt,
+      sessionLoopExpiresAt: expiresAt,
+    });
+  } finally {
+    const remaining = (pendingCreates.get(host) ?? 1) - 1;
+    if (remaining === 0) pendingCreates.delete(host);
+    else pendingCreates.set(host, remaining);
+  }
+  const rounded = cadence.milliseconds !== parsed.requestedMs ? ' (rounded up)' : '';
+  // `spawnScheduledWake` always spawns a scheduled-kind task; the kind check lets TypeScript
+  // narrow to the member that carries `nextFireAt` (#2079).
+  const nextFire =
+    task.kind === 'scheduled' && task.nextFireAt && task.nextFireAt >= firstAllowedAt
+      ? ` Next fire: ${task.nextFireAt}.`
+      : '';
+  return {
+    success: true,
+    message: `Loop ${loopId} uses a ${cadence.description}${rounded} local-clock step with stable offset +${jitter.jitterSeconds}s; elapsed gaps can change with daylight saving. First eligible at or after ${firstAllowedAt}.${nextFire} Expires: ${expiresAt}. Stop with /loop stop ${loopId}.`,
+    data: {
+      loopId,
+      taskId: task.id,
+      requestedMs: parsed.requestedMs,
+      cadenceLabel: cadence.description,
+      cronExpression: jitter.cronExpression,
+      jitterSeconds: jitter.jitterSeconds,
+      firstAllowedAt,
+      expiresAt,
+    },
+  };
+}

package/src/schedule/loop-jitter.ts

@@ -0,0 +1,41 @@
+import { createHash } from 'node:crypto';
+
+/** Fixed loops are spread across a stable wall-clock slot; self-paced delays are not jittered. */
+export function jitterFixedLoop(
+  loopId: string,
+  cadence: { description: string; milliseconds: number; cronExpression: string },
+): { cronExpression: string; jitterSeconds: number } {
+  const maxSeconds = Math.floor(Math.min(30 * 60, cadence.milliseconds / 2_000));
+  const hash = createHash('sha256').update(loopId).digest().readUInt32BE(0);
+  const jitterSeconds = hash % (maxSeconds + 1);
+  if (jitterSeconds === 0) return { cronExpression: cadence.cronExpression, jitterSeconds };
+
+  const match = /^(\d+)(s|m|h)$/.exec(cadence.description);
+  if (!match) throw new Error('Unsupported fixed-loop cadence for jitter.');
+  const step = Number(match[1]);
+  const unit = match[2];
+  const second = jitterSeconds % 60;
+  const minute = Math.floor(jitterSeconds / 60);
+  if (unit === 's') {
+    return {
+      cronExpression: step === 60
+        ? `${jitterSeconds} * * * * *`
+        : `${jitterSeconds}-59/${step} * * * * *`,
+      jitterSeconds,
+    };
+  }
+  if (unit === 'm') {
+    return {
+      cronExpression: step === 60
+        ? `${second} ${minute} * * * *`
+        : `${second} ${minute}-59/${step} * * * *`,
+      jitterSeconds,
+    };
+  }
+  return {
+    cronExpression: step === 24
+      ? `${second} ${minute} 0 * * *`
+      : `${second} ${minute} */${step} * * *`,
+    jitterSeconds,
+  };
+}

package/src/schedule/schedule-command-module.ts

@@ -3,38 +3,57 @@
  * and process monitoring to users (and the model as tools).
  */
 
+import { executeLoopCommand } from './loop-command.js';
 import { executeMonitorCommand, executeScheduleCommand } from './schedule-command.js';
 
+import type { ILoopCommandOptions } from './loop-command.js';
 import type {
   IAgentJobHostContext,
-  ICommandHostContext,
+  ICommandHostAgentJobs,
   ICommandModule,
   ISystemCommand,
 } from '@robota-sdk/agent-framework';
-import type {
-  ICommand,
-  ICommandResult,
-  ICommandSource,
-} from '@robota-sdk/agent-interface-transport';
+import type { ICommand, ICommandResult, ICommandSource } from '@robota-sdk/agent-interface-command';
 
-function getAgentHostContext(context: ICommandHostContext): IAgentJobHostContext {
-  const cap = context.getAgentJobCapability?.();
+function getAgentHostContext(context: ICommandHostAgentJobs): IAgentJobHostContext {
+  const cap = context.getAgentJobCapability();
   if (!cap) throw new Error('Scheduling requires an active agent runtime.');
   return cap;
 }
 
 const SCHEDULE_DESCRIPTION =
-  'Schedule the agent to wake and run an instruction on a timer (one-shot or cron).';
-const SCHEDULE_ARGUMENT_HINT = 'in <N><s|m|h|d> <instruction>  |  cron "<expr>" <instruction>';
+  'Schedule the agent to wake on a timer, and manage schedules (list / pause / resume / edit).';
+const SCHEDULE_ARGUMENT_HINT =
+  'in <N><s|m|h|d> <instruction> | cron "<expr>" <instruction> | list | pause <id> | resume <id> | edit <id> <spec>';
 const MONITOR_DESCRIPTION =
   'Watch a process’s output and wake the agent when a line matches a pattern.';
 const MONITOR_ARGUMENT_HINT = '"<command>" "<pattern>" <instruction>';
 
+// Model-invocable, all three: waking itself later, watching a process and repeating a prompt are the
+// model's own pacing. `/monitor` starts a process, so the model's command is decided by the shell
+// tool's own gate (see the system command below) — never a way around a Bash/Shell rule.
+const SCHEDULE_MODEL_DESCRIPTION =
+  'Wake yourself later with an instruction. Use it when work must wait (a deploy, a long build, a ' +
+  'reply) instead of polling: `in <N><s|m|h|d> <instruction>` or `cron "<expr>" <instruction>`; ' +
+  '`list`, `pause`, `resume` and `edit` manage existing schedules. Returns the schedule id, or the ' +
+  'schedule list.';
+const MONITOR_MODEL_DESCRIPTION =
+  'Run a command in the background and wake yourself when a line of its output matches a pattern. ' +
+  'Use it to wait for a server to start, a test to fail or a log line to appear instead of polling. ' +
+  'The command is allowed, refused or asked about by the same permission rules as a shell tool ' +
+  'call. Returns the monitor task id, or a refusal naming what the user must allow.';
+const LOOP_MODEL_DESCRIPTION =
+  'Repeat a prompt on a fixed cadence (`<N><s|m|h|d> [prompt]`) or self-paced (bare or prompt ' +
+  'only: each iteration chooses its next delay or stops). Use it when the user asks for recurring ' +
+  'work in this session. `list` shows active loops; `stop <id>` ends one. Returns the loop id and ' +
+  'its next fire time, or the loop list.';
+
 export function createScheduleCommandEntry(): ICommand {
   return {
     name: 'schedule',
     displayName: 'Schedule Wake',
     description: SCHEDULE_DESCRIPTION,
+    modelDescription: SCHEDULE_MODEL_DESCRIPTION,
     source: 'schedule',
     argumentHint: SCHEDULE_ARGUMENT_HINT,
     modelInvocable: true,
@@ -46,18 +65,42 @@ export function createMonitorCommandEntry(): ICommand {
     name: 'monitor',
     displayName: 'Monitor Process',
     description: MONITOR_DESCRIPTION,
+    modelDescription: MONITOR_MODEL_DESCRIPTION,
     source: 'schedule',
     argumentHint: MONITOR_ARGUMENT_HINT,
     modelInvocable: true,
   };
 }
 
+export function createLoopCommandEntry(): ICommand {
+  return {
+    name: 'loop',
+    displayName: 'Repeat Prompt',
+    description:
+      'Repeat a prompt on a fixed cadence or let each iteration choose its next delay; list or stop active loops.',
+    modelDescription: LOOP_MODEL_DESCRIPTION,
+    source: 'schedule',
+    argumentHint: '[prompt] | <N><s|m|h|d> [prompt] | <prompt> every <N> <unit> | list | stop <id>',
+    modelInvocable: true,
+    subcommands: [
+      { name: 'list', description: 'List active loops', source: 'schedule' },
+      {
+        name: 'stop',
+        description: 'Stop an active loop',
+        source: 'schedule',
+        argumentHint: '<id>',
+      },
+    ],
+  };
+}
+
 function createScheduleSystemCommand(): ISystemCommand {
   const entry = createScheduleCommandEntry();
   return {
     name: entry.name,
     displayName: entry.displayName,
     description: entry.description,
+    ...(entry.modelDescription !== undefined ? { modelDescription: entry.modelDescription } : {}),
     requiresPermission: false,
     userInvocable: true,
     modelInvocable: true,
@@ -74,7 +117,13 @@ function createMonitorSystemCommand(): ISystemCommand {
     name: entry.name,
     displayName: entry.displayName,
     description: entry.description,
-    requiresPermission: false,
+    ...(entry.modelDescription !== undefined ? { modelDescription: entry.modelDescription } : {}),
+    // It starts a process, so it is never treated as read-only (a remote read-only policy refuses
+    // it). The MODEL's call is not asked about by the command's name: the host decides the
+    // monitored command as a shell tool call (hooks, Bash/Shell rules, the mode and the prompt, never
+    // the sandbox's auto-approval), so one "always allow" of `/monitor` never approves another command.
+    requiresPermission: true,
+    modelRequiresPermission: false,
     userInvocable: true,
     modelInvocable: true,
     argumentHint: entry.argumentHint,
@@ -84,19 +133,48 @@ function createMonitorSystemCommand(): ISystemCommand {
   };
 }
 
+function createLoopSystemCommand(options: ILoopCommandOptions): ISystemCommand {
+  const entry = createLoopCommandEntry();
+  return {
+    name: entry.name,
+    displayName: entry.displayName,
+    description: entry.description,
+    ...(entry.modelDescription !== undefined ? { modelDescription: entry.modelDescription } : {}),
+    // A static conservative classification keeps remote read-only policies from admitting
+    // create/stop through this mixed read/write command; list is gated too.
+    requiresPermission: true,
+    userInvocable: true,
+    modelInvocable: true,
+    argumentHint: entry.argumentHint,
+    subcommands: entry.subcommands,
+    lifecycle: 'inline',
+    execute: (context, args): Promise<ICommandResult> =>
+      executeLoopCommand(
+        getAgentHostContext(context),
+        (taskId, reason) => context.cancelBackgroundTask(taskId, reason),
+        args,
+        options,
+      ),
+  };
+}
+
 export class ScheduleCommandSource implements ICommandSource {
   readonly name = 'schedule';
 
   getCommands(): ICommand[] {
-    return [createScheduleCommandEntry(), createMonitorCommandEntry()];
+    return [createScheduleCommandEntry(), createMonitorCommandEntry(), createLoopCommandEntry()];
   }
 }
 
-export function createScheduleCommandModule(): ICommandModule {
+export function createScheduleCommandModule(options: ILoopCommandOptions = {}): ICommandModule {
   return {
     name: 'agent-command-schedule',
     commandSources: [new ScheduleCommandSource()],
-    systemCommands: [createScheduleSystemCommand(), createMonitorSystemCommand()],
+    systemCommands: [
+      createScheduleSystemCommand(),
+      createMonitorSystemCommand(),
+      createLoopSystemCommand(options),
+    ],
     sessionRequirements: ['agent-runtime'],
   };
 }