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

package/src/schedule/__tests__/monitor-model-permission-functional.test.ts

@@ -0,0 +1,126 @@
+/**
+ * A model-requested `/monitor` starts its command as a process, so the command is decided by the
+ * shell tool's own gate — the user's Bash/Shell rules — never by consent to `/monitor` itself.
+ */
+
+import { afterEach, describe, expect, it } from 'vitest';
+
+import { scriptedSession, type ScriptedSessionHarness } from '@robota-sdk/agent-framework/testing';
+
+import { createScheduleCommandModule } from '../schedule-command-module.js';
+
+import type { THooksConfig, TPermissionMode } from '@robota-sdk/agent-core';
+type ISandboxClient = NonNullable<Parameters<typeof scriptedSession>[0]['sandboxClient']>;
+
+/** A sandbox that would let every confined shell command run without a prompt. */
+const autoApprovingSandbox: ISandboxClient = {
+  filesystem: 'shared',
+  wrapCommand: (invocation) => invocation,
+  autoApproves: () => true,
+  run: () => Promise.reject(new Error('not used')),
+  readFile: () => Promise.reject(new Error('not used')),
+  writeFile: () => Promise.reject(new Error('not used')),
+};
+
+let harness: ScriptedSessionHarness | undefined;
+afterEach(async () => {
+  await harness?.dispose();
+  harness = undefined;
+});
+
+function session(options: {
+  permissionMode: TPermissionMode;
+  permissions?: { allow?: string[]; deny?: string[] };
+  hooks?: THooksConfig;
+  sandboxClient?: ISandboxClient;
+}): ScriptedSessionHarness {
+  harness = scriptedSession({
+    turns: [],
+    commandModules: [createScheduleCommandModule()],
+    backgroundTasks: true,
+    ...options,
+  });
+  return harness;
+}
+
+const MONITOR_ARGS = '"sleep 30" "ready" check the server';
+
+function monitorTasks(h: ScriptedSessionHarness) {
+  return h.session.listBackgroundTasks().filter((task) => task.kind === 'process');
+}
+
+describe('/monitor from the model is decided by the shell gate', () => {
+  it('a Bash deny rule refuses the monitored command, even under bypassPermissions', async () => {
+    const h = session({
+      permissionMode: 'bypassPermissions',
+      permissions: { deny: ['Bash(sleep *)'] },
+    });
+
+    const result = await h.session.executeModelCommand('monitor', MONITOR_ARGS);
+
+    expect(result?.success).toBe(false);
+    expect(result?.message).toContain('shell permission rules refused this command');
+    expect(monitorTasks(h)).toEqual([]);
+  });
+
+  it('an allow rule for a different command does not approve it', async () => {
+    // Plan mode refuses an execute call no allow rule matches, so a prompt cannot stand in for it.
+    const h = session({ permissionMode: 'plan', permissions: { allow: ['Bash(echo *)'] } });
+
+    const result = await h.session.executeModelCommand('monitor', MONITOR_ARGS);
+
+    expect(result?.success).toBe(false);
+    expect(monitorTasks(h)).toEqual([]);
+  });
+
+  it('starts the monitor when the shell rules allow that command', async () => {
+    const h = session({ permissionMode: 'plan', permissions: { allow: ['Bash(sleep *)'] } });
+
+    const result = await h.session.executeModelCommand('monitor', MONITOR_ARGS);
+
+    expect(result?.success).toBe(true);
+    expect(monitorTasks(h)).toHaveLength(1);
+  });
+
+  it('leaves the user-typed command to the user', async () => {
+    const h = session({
+      permissionMode: 'bypassPermissions',
+      permissions: { deny: ['Bash(sleep *)'] },
+    });
+
+    const result = await h.command('monitor', MONITOR_ARGS);
+
+    expect(result?.success).toBe(true);
+  });
+
+  it('never takes the sandbox auto-approval: the monitor does not run inside the sandbox', async () => {
+    // Default mode would auto-run a sandboxed shell command. The monitor's process is started by the
+    // background-task manager, outside the sandbox, so it falls to the ask path — and with no one
+    // to ask here, it is refused rather than started unconfined.
+    const h = session({ permissionMode: 'default', sandboxClient: autoApprovingSandbox });
+
+    const result = await h.session.executeModelCommand('monitor', MONITOR_ARGS);
+
+    expect(result?.success).toBe(false);
+    expect(monitorTasks(h)).toEqual([]);
+  });
+
+  it('runs the PreToolUse hooks, so a guardrail blocks the monitored command', async () => {
+    const h = session({
+      permissionMode: 'bypassPermissions',
+      hooks: {
+        PreToolUse: [
+          {
+            matcher: 'Shell',
+            hooks: [{ type: 'command', command: 'echo "no sleeping" >&2; exit 2' }],
+          },
+        ],
+      },
+    });
+
+    const result = await h.session.executeModelCommand('monitor', MONITOR_ARGS);
+
+    expect(result?.success).toBe(false);
+    expect(monitorTasks(h)).toEqual([]);
+  });
+});

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

@@ -0,0 +1,247 @@
+/**
+ * FLOW-005: `/schedule` + `/monitor` command surface.
+ * - parseScheduleSpec: relative delay → one-shot ISO; cron form; invalid input rejected.
+ * - executeScheduleCommand / executeMonitorCommand: build the wake request and spawn it.
+ */
+
+import { describe, expect, it, vi } from 'vitest';
+
+import { executeMonitorCommand, executeScheduleCommand } from '../schedule-command.js';
+import { createScheduleCommandModule } from '../schedule-command-module.js';
+import { parseScheduleSpec } from '../schedule-spec-parser.js';
+
+import type { IAgentJobHostContext } from '@robota-sdk/agent-framework';
+import { createTestAgentJobHost } from '@robota-sdk/agent-framework/testing';
+
+describe('in-session repeat command', () => {
+  it('exposes a user-visible loop command through the default schedule module', () => {
+    const module = createScheduleCommandModule();
+    const executable = module.systemCommands?.find((command) => command.name === 'loop');
+    const palette = module.commandSources?.flatMap((source) => source.getCommands())
+      .find((command) => command.name === 'loop');
+
+    expect(executable).toBeDefined();
+    expect(palette).toBeDefined();
+    expect(executable?.requiresPermission).toBe(true);
+    expect(executable?.modelInvocable).toBe(true);
+    expect(executable?.userInvocable).toBe(true);
+    expect(palette?.subcommands?.map(({ name }) => name)).toEqual(['list', 'stop']);
+    expect(palette?.subcommands).toEqual(executable?.subcommands);
+  });
+});
+
+function mockHost(): {
+  host: IAgentJobHostContext;
+  scheduled: ReturnType<typeof vi.fn>;
+  monitor: ReturnType<typeof vi.fn>;
+  listSchedules: ReturnType<typeof vi.fn>;
+  pauseSchedule: ReturnType<typeof vi.fn>;
+  resumeSchedule: ReturnType<typeof vi.fn>;
+  editSchedule: ReturnType<typeof vi.fn>;
+} {
+  const scheduled = vi.fn().mockResolvedValue({ id: 'task_sched' });
+  const monitor = vi.fn().mockResolvedValue({ id: 'task_mon' });
+  const listSchedules = vi.fn().mockReturnValue([
+    {
+      id: 'sched_1',
+      status: 'sleeping',
+      label: 'daily',
+      kind: 'scheduled',
+      nextFireAt: '2030-01-01T00:00:00.000Z',
+      schedule: { cronExpression: '0 0 * * *' },
+    },
+  ]);
+  const pauseSchedule = vi.fn().mockResolvedValue(undefined);
+  const resumeSchedule = vi.fn().mockResolvedValue(undefined);
+  const editSchedule = vi.fn().mockResolvedValue(undefined);
+  const host = createTestAgentJobHost({
+    spawnScheduledWake: scheduled,
+    spawnMonitorWake: monitor,
+    listSchedules,
+    pauseSchedule,
+    resumeSchedule,
+    editSchedule,
+  });
+  return { host, scheduled, monitor, listSchedules, pauseSchedule, resumeSchedule, editSchedule };
+}
+
+describe('parseScheduleSpec (FLOW-005)', () => {
+  it('parses a relative delay into a one-shot ISO timestamp', () => {
+    const result = parseScheduleSpec('in 5m summarize the logs', 0);
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.spec.recurring).toBe(false);
+    expect(result.spec.cronExpression).toBe(new Date(5 * 60_000).toISOString());
+    expect(result.spec.instruction).toBe('summarize the logs');
+  });
+
+  it('parses a quoted cron expression as recurring', () => {
+    const result = parseScheduleSpec('cron "0 9 * * *" run standup', 0);
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.spec.recurring).toBe(true);
+    expect(result.spec.cronExpression).toBe('0 9 * * *');
+    expect(result.spec.instruction).toBe('run standup');
+  });
+
+  it('rejects an invalid duration', () => {
+    expect(parseScheduleSpec('in 5x do X', 0).ok).toBe(false);
+  });
+
+  it('rejects a missing instruction', () => {
+    expect(parseScheduleSpec('in 5m', 0).ok).toBe(false);
+  });
+
+  it('rejects unrecognized input', () => {
+    expect(parseScheduleSpec('whenever you feel like it', 0).ok).toBe(false);
+  });
+});
+
+describe('executeScheduleCommand (FLOW-005)', () => {
+  it('TC-01: relative delay spawns a one-shot scheduled wake', async () => {
+    const { host, scheduled } = mockHost();
+    const now = 1_000_000;
+    const result = await executeScheduleCommand(host, 'in 1m summarize', now);
+
+    expect(result.success).toBe(true);
+    expect(scheduled).toHaveBeenCalledTimes(1);
+    expect(scheduled).toHaveBeenCalledWith(
+      expect.objectContaining({
+        cronExpression: new Date(now + 60_000).toISOString(),
+        agentInstruction: 'summarize',
+      }),
+    );
+  });
+
+  it('TC-02: cron form spawns a recurring scheduled wake', async () => {
+    const { host, scheduled } = mockHost();
+    const result = await executeScheduleCommand(host, 'cron "0 9 * * *" standup', Date.now());
+
+    expect(result.success).toBe(true);
+    expect(scheduled).toHaveBeenCalledWith(
+      expect.objectContaining({ cronExpression: '0 9 * * *', agentInstruction: 'standup' }),
+    );
+  });
+
+  it('TC-03: invalid input is rejected without spawning', async () => {
+    const { host, scheduled } = mockHost();
+    const result = await executeScheduleCommand(host, 'garbage', Date.now());
+
+    expect(result.success).toBe(false);
+    expect(scheduled).not.toHaveBeenCalled();
+  });
+
+  it('TC-04: monitor command spawns a process+match wake task', async () => {
+    const { host, monitor } = mockHost();
+    const result = await executeMonitorCommand(host, '"npm run dev" "ERROR" fix the failure');
+
+    expect(result.success).toBe(true);
+    expect(monitor).toHaveBeenCalledWith(
+      expect.objectContaining({
+        command: 'npm run dev',
+        matchPattern: 'ERROR',
+        agentInstruction: 'fix the failure',
+      }),
+    );
+  });
+});
+
+// SELFHOST-012 TC-05: /schedule list|pause|resume|edit dispatch (mirror /background); create stays default.
+describe('executeScheduleCommand — management subcommands (SELFHOST-012)', () => {
+  it('list returns the caller schedules with cadence + status, no create', async () => {
+    const { host, listSchedules, scheduled } = mockHost();
+    const result = await executeScheduleCommand(host, 'list', Date.now());
+    expect(result.success).toBe(true);
+    expect(listSchedules).toHaveBeenCalledOnce();
+    expect(result.message).toContain('sched_1');
+    expect(result.message).toContain('[sleeping]');
+    expect(result.message).toContain('0 0 * * *');
+    expect(scheduled).not.toHaveBeenCalled(); // list is not a create
+  });
+
+  it('pause <id> / resume <id> dispatch to the host lifecycle calls', async () => {
+    const { host, pauseSchedule, resumeSchedule } = mockHost();
+    const paused = await executeScheduleCommand(host, 'pause sched_1', Date.now());
+    expect(paused.success).toBe(true);
+    expect(pauseSchedule).toHaveBeenCalledWith('sched_1');
+
+    const resumed = await executeScheduleCommand(host, 'resume sched_1', Date.now());
+    expect(resumed.success).toBe(true);
+    expect(resumeSchedule).toHaveBeenCalledWith('sched_1');
+  });
+
+  it('edit <id> <spec> parses the spec and patches the schedule', async () => {
+    const { host, editSchedule } = mockHost();
+    const result = await executeScheduleCommand(
+      host,
+      'edit sched_1 cron "*/5 * * * *" ping',
+      Date.now(),
+    );
+    expect(result.success).toBe(true);
+    expect(editSchedule).toHaveBeenCalledWith('sched_1', {
+      cronExpression: '*/5 * * * *',
+      agentInstruction: 'ping',
+      label: 'Scheduled: ping',
+    });
+  });
+
+  // CMD-009: create → edit → list must render the EDITED instruction. The host double applies the
+  // patch the way `BackgroundTaskManager.editScheduledTask` does (pinned in agent-executor), so a
+  // command that omits `label` from the patch leaves the list showing the creation-time text.
+  it('list renders the edited instruction, not the one captured at creation (CMD-009)', async () => {
+    const schedules: Array<Record<string, unknown>> = [];
+    const host = createTestAgentJobHost({
+      spawnScheduledWake: vi.fn().mockImplementation((input: Record<string, unknown>) => {
+        const task = {
+          id: 'sched_x',
+          status: 'sleeping',
+          kind: 'scheduled',
+          label: input['label'],
+          schedule: {
+            cronExpression: input['cronExpression'],
+            agentInstruction: input['agentInstruction'],
+          },
+        };
+        schedules.push(task);
+        return Promise.resolve(task);
+      }),
+      listSchedules: vi.fn().mockImplementation(() => schedules),
+      editSchedule: vi.fn().mockImplementation((id: string, patch: Record<string, unknown>) => {
+        const { label, ...schedulePatch } = patch;
+        const task = schedules.find((s) => s['id'] === id);
+        if (task === undefined) throw new Error(`no schedule ${id}`);
+        task['schedule'] = { ...(task['schedule'] as Record<string, unknown>), ...schedulePatch };
+        if (label !== undefined) task['label'] = label;
+        return Promise.resolve();
+      }),
+    });
+
+    await executeScheduleCommand(host, 'cron "0 9 * * *" write the standup', 0);
+    await executeScheduleCommand(host, 'edit sched_x cron "0 10 * * *" file the report', 0);
+    const listed = await executeScheduleCommand(host, 'list', 0);
+
+    expect(listed.message).toContain('file the report');
+    expect(listed.message).not.toContain('write the standup');
+    expect(listed.message).toContain('0 10 * * *');
+  });
+
+  it('pause/resume/edit without an id is a usage error (no host call)', async () => {
+    const { host, pauseSchedule, editSchedule } = mockHost();
+    const p = await executeScheduleCommand(host, 'pause', Date.now());
+    expect(p.success).toBe(false);
+    expect(p.message).toContain('Usage:');
+    expect(pauseSchedule).not.toHaveBeenCalled();
+
+    const e = await executeScheduleCommand(host, 'edit sched_1', Date.now());
+    expect(e.success).toBe(false);
+    expect(editSchedule).not.toHaveBeenCalled();
+  });
+
+  it('a create spec (in/cron) still creates — subcommand keywords do not collide', async () => {
+    const { host, scheduled, pauseSchedule } = mockHost();
+    const result = await executeScheduleCommand(host, 'in 5m summarize', 0);
+    expect(result.success).toBe(true);
+    expect(scheduled).toHaveBeenCalledOnce();
+    expect(pauseSchedule).not.toHaveBeenCalled();
+  });
+});

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

@@ -0,0 +1,114 @@
+/**
+ * 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.
+ * `/loop`'s leading interval had the same `\s+([\s\S]+)$` shape and is held to the same bound.
+ */
+
+import { describe, expect, it, vi } from 'vitest';
+
+import { executeLoopCommand } from '../loop-command.js';
+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',
+      }),
+    );
+  });
+
+  it('parses a pumped leading-interval `/loop` in linear time', async () => {
+    // The shape CodeQL named for `\s+([\s\S]+)$`: an interval, then a long run of whitespace.
+    const spawnScheduledWake = vi.fn();
+    const host = createTestAgentJobHost({ spawnScheduledWake });
+    const hostile = `0s\t${'\t\t'.repeat(PUMP_LENGTH)}x`;
+
+    const started = performance.now();
+    const result = await executeLoopCommand(host, vi.fn(), hostile);
+    const took = performance.now() - started;
+
+    expect(result.success).toBe(false);
+    expect(spawnScheduledWake).not.toHaveBeenCalled();
+    expect(took).toBeLessThan(BUDGET_MS);
+  });
+
+  it.each([
+    ['5m check the build', 'check the build'],
+    ['5m \t\n  check   the build  ', 'check   the build'],
+    ['5M\ncheck', 'check'],
+  ])('still reads a leading-interval `/loop` identically: %j', async (args, instruction) => {
+    const spawnScheduledWake = vi.fn().mockResolvedValue({ id: 'loop_1' });
+    const host = createTestAgentJobHost({ spawnScheduledWake });
+
+    const result = await executeLoopCommand(host, vi.fn(), args);
+
+    expect(result.success).toBe(true);
+    expect(spawnScheduledWake).toHaveBeenCalledWith(
+      expect.objectContaining({ agentInstruction: instruction }),
+    );
+  });
+});

package/src/schedule/index.ts

@@ -0,0 +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';