@robota-sdk/agent-command 3.0.0-beta.100

package/src/schedule/loop-command.ts

@@ -0,0 +1,427 @@
+/** Fixed or self-paced session-local repetition. */
+
+import { randomUUID } from 'node:crypto';
+
+import { selectAction } from '@robota-sdk/agent-core';
+import { isLoopStopVerb } from '@robota-sdk/agent-framework';
+
+import { jitterFixedLoop } from './loop-jitter.js';
+
+import type { IUserInteraction } from '@robota-sdk/agent-core';
+import type { IAgentJobHostContext } from '@robota-sdk/agent-framework';
+import type { ICommandResult, TCommandInvocationSource } 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 LOOP_LIFETIME_DAYS = LOOP_LIFETIME_MS / (HOURS_PER_DAY * 60 * SECONDS_PER_MINUTE * 1_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;
+}
+
+/**
+ * #3288 §1: who invoked `/loop`, and how to ask them. `ui` is the injected "ask the user" port
+ * (absent for a headless/automation host — see `ICommandHostUserInteraction`); `source` is the
+ * command's own invocation source. Defaults to `{ ui: undefined, source: 'user' }` when the caller
+ * omits it, matching every pre-existing (headless) call site: proceed unconfirmed, the same as
+ * before this gate existed.
+ */
+export interface ILoopInvocationContext {
+  readonly ui: IUserInteraction | undefined;
+  readonly source: TCommandInvocationSource;
+}
+
+const DEFAULT_INVOCATION: ILoopInvocationContext = { ui: undefined, source: 'user' };
+
+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 };
+  }
+  // One required space, then the rest verbatim (trimmed below): `\s+` before `[\s\S]+` split the
+  // same spaces two ways, which CodeQL reads as polynomial backtracking.
+  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;
+}
+
+function describeActiveLoops(
+  host: Pick<IAgentJobHostContext, 'listSchedules' | 'listSelfPacedLoops'>,
+): string {
+  const loops = activeLoops(host);
+  const selfPaced = activeSelfPacedLoops(host);
+  if (loops.length + selfPaced.length === 0) return 'No other active loops.';
+  return [
+    ...loops.map((task) => `- ${loopIdOf(task)} [${task.status}] ${task.label}`),
+    ...selfPaced.map((loop) => `- ${loop.loopId} [${loop.phase}] Loop: ${loop.instruction}`),
+  ].join('\n');
+}
+
+/** The plain refusal for a default-prompt loop with no one to ask — never a silent, unconfirmed start. */
+const HEADLESS_REFUSAL =
+  'A loop with the default maintenance prompt needs someone to confirm it. Start it from an ' +
+  'interactive session, or give the loop its own prompt: /loop <prompt>';
+
+/**
+ * #3288 §1: every form that falls back to the host's default maintenance prompt — bare `/loop` or an
+ * interval-only `/loop <N><s|m|h|d>` — keeps working on its own for up to 7 days: a standing
+ * commitment the operator never typed, gated the same way regardless of which form reached it.
+ * Returns the refusal/decline result to return in place of creating the loop, or `undefined` to
+ * proceed. A `source: 'model'` call is refused outright and never asks — the model must give its own
+ * prompt, or name `/loop` to the user (AGENTS.md: trust and permission-widening actions stay
+ * user-only, and a refusal names the command to suggest). A headless/automation host (no ask port —
+ * print mode, a scheduled run) is refused too, the same reason: a loop that can run for a week must
+ * not start without a person saying yes, and there is no one here to ask.
+ */
+async function confirmDefaultLoopStart(
+  host: Pick<IAgentJobHostContext, 'listSchedules' | 'listSelfPacedLoops'>,
+  invocation: ILoopInvocationContext,
+  instruction: string,
+): Promise<ICommandResult | undefined> {
+  if (invocation.source === 'model') {
+    return {
+      success: false,
+      message:
+        'Starting a loop with its built-in prompt needs a person to confirm it — ' +
+        'ask the user to run /loop, or give your own prompt with /loop <prompt>.',
+    };
+  }
+  const { ui } = invocation;
+  if (!ui) return { success: false, message: HEADLESS_REFUSAL };
+  const firstLine = instruction.split('\n')[0]!.trim() || instruction;
+  const response = await ui.ask(
+    selectAction(
+      'loop-start-default',
+      `Start a loop that keeps working on its own for up to ${LOOP_LIFETIME_DAYS} days? It will: ${firstLine}`,
+      [
+        { value: 'start', label: 'Start' },
+        { value: 'cancel', label: 'Cancel' },
+      ],
+      { description: describeActiveLoops(host) },
+    ),
+  );
+  if (response.type === 'answer' && response.values.includes('start')) return undefined;
+  return { success: true, message: 'Loop not started.' };
+}
+
+export async function executeLoopCommand(
+  host: Pick<IAgentJobHostContext, 'spawnScheduledWake' | 'listSchedules' | 'createSelfPacedLoop' | 'listSelfPacedLoops' | 'stopSelfPacedLoop'>,
+  cancelBackgroundTask: (taskId: string, reason: string) => Promise<void>,
+  args: string,
+  options: ILoopCommandOptions = {},
+  invocation: ILoopInvocationContext = DEFAULT_INVOCATION,
+): Promise<ICommandResult> {
+  const trimmed = args.trim();
+  if (trimmed === 'list') return listLoops(host, options);
+  if (isLoopStopVerb(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, invocation);
+}
+
+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,
+  invocation: ILoopInvocationContext = DEFAULT_INVOCATION,
+): 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.' };
+    }
+    if (useDefaultPrompt) {
+      const declined = await confirmDefaultLoopStart(host, invocation, instruction);
+      if (declined) return declined;
+    }
+    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);
+    }
+  }
+  // #3288 §1: an interval-only form (`/loop 5m`) that fell back to the host's default prompt is
+  // gated exactly like the bare form — it is the SAME standing commitment (up to 7 days, unattended),
+  // only on a fixed cadence instead of self-paced. An explicit prompt (`/loop 5m check the build`)
+  // never reaches here with `useDefaultPrompt` true, so it is never gated.
+  if (useDefaultPrompt) {
+    const declined = await confirmDefaultLoopStart(host, invocation, parsed.instruction);
+    if (declined) return declined;
+  }
+  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

@@ -0,0 +1,184 @@
+/**
+ * FLOW-005: the `/schedule` + `/monitor` command module — surfaces agent-wake scheduling
+ * 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,
+  ICommandHostAgentJobs,
+  ICommandModule,
+  ISystemCommand,
+} from '@robota-sdk/agent-framework';
+import type { ICommand, ICommandResult, ICommandSource } from '@robota-sdk/agent-interface-command';
+
+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 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 (`<prompt>`: each ' +
+  'iteration chooses its next delay or stops). Use it when the user asks for recurring work in ' +
+  'this session, and always give your own prompt: any form that would fall back to the host\'s ' +
+  'default maintenance prompt — bare `/loop` or an interval alone (`<N><s|m|h|d>`) — needs a ' +
+  'person to confirm it and is always refused for you, whether or not one is attached. `list` ' +
+  'shows active loops; `stop <id>` ends one, even mid-turn. Returns the loop id and its next fire ' +
+  'time, the loop list, or a refusal naming the command to suggest.';
+
+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,
+  };
+}
+
+export function createMonitorCommandEntry(): ICommand {
+  return {
+    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,
+    argumentHint: entry.argumentHint,
+    lifecycle: 'inline',
+    execute: (context, args): Promise<ICommandResult> =>
+      executeScheduleCommand(getAgentHostContext(context), args),
+  };
+}
+
+function createMonitorSystemCommand(): ISystemCommand {
+  const entry = createMonitorCommandEntry();
+  return {
+    name: entry.name,
+    displayName: entry.displayName,
+    description: entry.description,
+    ...(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,
+    lifecycle: 'inline',
+    execute: (context, args): Promise<ICommandResult> =>
+      executeMonitorCommand(getAgentHostContext(context), args),
+  };
+}
+
+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,
+        { ui: context.getUserInteraction(), source: context.getCommandInvocationSource() },
+      ),
+  };
+}
+
+export class ScheduleCommandSource implements ICommandSource {
+  readonly name = 'schedule';
+
+  getCommands(): ICommand[] {
+    return [createScheduleCommandEntry(), createMonitorCommandEntry(), createLoopCommandEntry()];
+  }
+}
+
+export function createScheduleCommandModule(options: ILoopCommandOptions = {}): ICommandModule {
+  return {
+    name: 'agent-command-schedule',
+    commandSources: [new ScheduleCommandSource()],
+    systemCommands: [
+      createScheduleSystemCommand(),
+      createMonitorSystemCommand(),
+      createLoopSystemCommand(options),
+    ],
+    sessionRequirements: ['runtime'],
+  };
+}