@robota-sdk/agent-command 3.0.0-beta.73 → 3.0.0-beta.74

package/src/reset/reset-command.ts

@@ -1,4 +1,5 @@
-import type { ICommandHostContext, ICommandResult } from '@robota-sdk/agent-framework';
+import type { ICommandHostContext } from '@robota-sdk/agent-framework';
+import type { ICommandResult } from '@robota-sdk/agent-interface-transport';
 
 export function executeResetCommand(_context: ICommandHostContext, _args: string): ICommandResult {
   return {

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

@@ -6,12 +6,8 @@ import {
 
 import { executeRewindCommand } from './rewind-command.js';
 
-import type {
-  ICommand,
-  ICommandModule,
-  ICommandSource,
-  ISystemCommand,
-} from '@robota-sdk/agent-framework';
+import type { ICommandModule, ISystemCommand } from '@robota-sdk/agent-framework';
+import type { ICommand, ICommandSource } from '@robota-sdk/agent-interface-transport';
 
 export function createRewindCommandEntry(): ICommand {
   return {

package/src/rewind/rewind-command.ts

@@ -7,11 +7,11 @@ import {
 
 import type {
   ICommandHostContext,
-  ICommandResult,
   IEditCheckpointInspection,
   IEditCheckpointRestoreResult,
   IEditCheckpointSummary,
 } from '@robota-sdk/agent-framework';
+import type { ICommandResult } from '@robota-sdk/agent-interface-transport';
 
 const SUBCOMMAND_INDEX = 0;
 const CHECKPOINT_ID_INDEX = 1;

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

@@ -0,0 +1,107 @@
+/**
+ * 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 { parseScheduleSpec } from '../schedule-spec-parser.js';
+
+import type { IAgentJobHostContext } from '@robota-sdk/agent-framework';
+
+function mockHost(): {
+  host: IAgentJobHostContext;
+  scheduled: ReturnType<typeof vi.fn>;
+  monitor: ReturnType<typeof vi.fn>;
+} {
+  const scheduled = vi.fn().mockResolvedValue({ id: 'task_sched' });
+  const monitor = vi.fn().mockResolvedValue({ id: 'task_mon' });
+  const host = {
+    spawnScheduledWake: scheduled,
+    spawnMonitorWake: monitor,
+  } as unknown as IAgentJobHostContext;
+  return { host, scheduled, monitor };
+}
+
+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',
+      }),
+    );
+  });
+});

package/src/schedule/index.ts

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

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

@@ -0,0 +1,102 @@
+/**
+ * FLOW-005: the `/schedule` + `/monitor` command module — surfaces agent-wake scheduling
+ * and process monitoring to users (and the model as tools).
+ */
+
+import { executeMonitorCommand, executeScheduleCommand } from './schedule-command.js';
+
+import type {
+  IAgentJobHostContext,
+  ICommandHostContext,
+  ICommandModule,
+  ISystemCommand,
+} from '@robota-sdk/agent-framework';
+import type {
+  ICommand,
+  ICommandResult,
+  ICommandSource,
+} from '@robota-sdk/agent-interface-transport';
+
+function getAgentHostContext(context: ICommandHostContext): 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>';
+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>';
+
+export function createScheduleCommandEntry(): ICommand {
+  return {
+    name: 'schedule',
+    displayName: 'Schedule Wake',
+    description: SCHEDULE_DESCRIPTION,
+    source: 'schedule',
+    argumentHint: SCHEDULE_ARGUMENT_HINT,
+    modelInvocable: true,
+  };
+}
+
+export function createMonitorCommandEntry(): ICommand {
+  return {
+    name: 'monitor',
+    displayName: 'Monitor Process',
+    description: MONITOR_DESCRIPTION,
+    source: 'schedule',
+    argumentHint: MONITOR_ARGUMENT_HINT,
+    modelInvocable: true,
+  };
+}
+
+function createScheduleSystemCommand(): ISystemCommand {
+  const entry = createScheduleCommandEntry();
+  return {
+    name: entry.name,
+    displayName: entry.displayName,
+    description: entry.description,
+    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,
+    requiresPermission: false,
+    userInvocable: true,
+    modelInvocable: true,
+    argumentHint: entry.argumentHint,
+    lifecycle: 'inline',
+    execute: (context, args): Promise<ICommandResult> =>
+      executeMonitorCommand(getAgentHostContext(context), args),
+  };
+}
+
+export class ScheduleCommandSource implements ICommandSource {
+  readonly name = 'schedule';
+
+  getCommands(): ICommand[] {
+    return [createScheduleCommandEntry(), createMonitorCommandEntry()];
+  }
+}
+
+export function createScheduleCommandModule(): ICommandModule {
+  return {
+    name: 'agent-command-schedule',
+    commandSources: [new ScheduleCommandSource()],
+    systemCommands: [createScheduleSystemCommand(), createMonitorSystemCommand()],
+    sessionRequirements: ['agent-runtime'],
+  };
+}

package/src/schedule/schedule-command.ts

@@ -0,0 +1,72 @@
+/**
+ * FLOW-005: `/schedule` and `/monitor` command executors — create agent-wake background tasks.
+ */
+
+import { parseScheduleSpec } from './schedule-spec-parser.js';
+
+import type { IAgentJobHostContext } from '@robota-sdk/agent-framework';
+import type { ICommandResult } from '@robota-sdk/agent-interface-transport';
+
+const MAX_LABEL_LENGTH = 48;
+
+function labelFor(prefix: string, instruction: string): string {
+  const snippet = instruction.slice(0, MAX_LABEL_LENGTH);
+  return `${prefix}: ${snippet}${instruction.length > MAX_LABEL_LENGTH ? '…' : ''}`;
+}
+
+export async function executeScheduleCommand(
+  host: IAgentJobHostContext,
+  args: string,
+  now: number = Date.now(),
+): Promise<ICommandResult> {
+  const parsed = parseScheduleSpec(args, now);
+  if (!parsed.ok) return { message: parsed.error, success: false };
+
+  const { cronExpression, instruction, recurring } = parsed.spec;
+  const task = await host.spawnScheduledWake({
+    label: labelFor('Scheduled', instruction),
+    cronExpression,
+    agentInstruction: instruction,
+  });
+
+  const when = recurring ? `cron \`${cronExpression}\`` : `once at ${cronExpression}`;
+  return {
+    message: `Scheduled wake (${when}): "${instruction}" — task ${task.id}.`,
+    success: true,
+    data: { taskId: task.id, cronExpression, recurring },
+  };
+}
+
+const MONITOR_USAGE = 'Usage: /monitor "<command>" "<pattern>" <instruction>';
+
+/** Parse `"<command>" "<pattern>" <instruction>` (quotes may be single or double). */
+function parseMonitorArgs(
+  args: string,
+): { command: string; matchPattern: string; instruction: string } | null {
+  const match = /^["']([^"']+)["']\s+["']([^"']+)["']\s+(.+)$/.exec(args.trim());
+  if (!match) return null;
+  const instruction = match[3]!.trim();
+  if (instruction.length === 0) return null;
+  return { command: match[1]!, matchPattern: match[2]!, instruction };
+}
+
+export async function executeMonitorCommand(
+  host: IAgentJobHostContext,
+  args: string,
+): Promise<ICommandResult> {
+  const parsed = parseMonitorArgs(args);
+  if (!parsed) return { message: MONITOR_USAGE, success: false };
+
+  const task = await host.spawnMonitorWake({
+    label: labelFor('Monitor', parsed.instruction),
+    command: parsed.command,
+    matchPattern: parsed.matchPattern,
+    agentInstruction: parsed.instruction,
+  });
+
+  return {
+    message: `Monitoring \`${parsed.command}\` for /${parsed.matchPattern}/ — task ${task.id}.`,
+    success: true,
+    data: { taskId: task.id, matchPattern: parsed.matchPattern },
+  };
+}

package/src/schedule/schedule-spec-parser.ts

@@ -0,0 +1,66 @@
+/**
+ * FLOW-005: parse the `<when>` portion of `/schedule` into a cron expression croner accepts.
+ *
+ * Two forms:
+ *   in <N><unit> <instruction>     — one-shot, fires once at now + duration (s|m|h|d)
+ *   cron "<expr>" <instruction>    — recurring, a standard cron expression
+ */
+
+export interface IScheduleSpec {
+  cronExpression: string;
+  instruction: string;
+  recurring: boolean;
+}
+
+export type TScheduleParseResult = { ok: true; spec: IScheduleSpec } | { ok: false; error: string };
+
+const DURATION_MS: Record<string, number> = {
+  s: 1_000,
+  m: 60_000,
+  h: 3_600_000,
+  d: 86_400_000,
+};
+
+const USAGE =
+  'Usage: /schedule in <N><s|m|h|d> <instruction>  |  /schedule cron "<expr>" <instruction>';
+
+export function parseScheduleSpec(args: string, now: number): TScheduleParseResult {
+  const trimmed = args.trim();
+  if (trimmed.length === 0) return { ok: false, error: USAGE };
+
+  if (trimmed.startsWith('in ')) {
+    const rest = trimmed.slice(3).trim();
+    const spaceIdx = rest.indexOf(' ');
+    if (spaceIdx === -1) return { ok: false, error: `Missing instruction. ${USAGE}` };
+    const durationToken = rest.slice(0, spaceIdx);
+    const instruction = rest.slice(spaceIdx + 1).trim();
+    const match = /^(\d+)(s|m|h|d)$/.exec(durationToken);
+    if (!match) return { ok: false, error: `Invalid duration "${durationToken}". ${USAGE}` };
+    if (instruction.length === 0) return { ok: false, error: `Missing instruction. ${USAGE}` };
+    const ms = parseInt(match[1]!, 10) * DURATION_MS[match[2]!]!;
+    return {
+      ok: true,
+      spec: {
+        cronExpression: new Date(now + ms).toISOString(),
+        instruction,
+        recurring: false,
+      },
+    };
+  }
+
+  if (trimmed.startsWith('cron ')) {
+    const rest = trimmed.slice(5).trim();
+    const quoted = /^["']([^"']+)["']\s+(.+)$/.exec(rest);
+    if (!quoted) {
+      return { ok: false, error: `cron form needs a quoted expression. ${USAGE}` };
+    }
+    const instruction = quoted[2]!.trim();
+    if (instruction.length === 0) return { ok: false, error: `Missing instruction. ${USAGE}` };
+    return {
+      ok: true,
+      spec: { cronExpression: quoted[1]!.trim(), instruction, recurring: true },
+    };
+  }
+
+  return { ok: false, error: USAGE };
+}

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

@@ -14,13 +14,12 @@ import {
   executeValidateSessionCommand,
 } from './session-command.js';
 
+import type { ICommandModule, ISystemCommand } from '@robota-sdk/agent-framework';
 import type {
   ICommand,
   ICommandInteractionHint,
-  ICommandModule,
   ICommandSource,
-  ISystemCommand,
-} from '@robota-sdk/agent-framework';
+} from '@robota-sdk/agent-interface-transport';
 
 export function createClearCommandEntry(): ICommand {
   return {

package/src/session/session-command.ts

@@ -14,7 +14,8 @@ import {
 
 import { calculateCost, formatTokens, formatUsd } from './model-pricing.js';
 
-import type { ICommandHostContext, ICommandResult } from '@robota-sdk/agent-framework';
+import type { ICommandHostContext } from '@robota-sdk/agent-framework';
+import type { ICommandResult } from '@robota-sdk/agent-interface-transport';
 
 export const CLEAR_COMMAND_MESSAGE = 'Conversation cleared.';
 

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

@@ -1,9 +1,5 @@
-import type {
-  ICommand,
-  ICommandModule,
-  ICommandSource,
-  ISystemCommand,
-} from '@robota-sdk/agent-framework';
+import type { ICommandModule, ISystemCommand } from '@robota-sdk/agent-framework';
+import type { ICommand, ICommandSource } from '@robota-sdk/agent-interface-transport';
 
 export function createSettingsCommandEntry(): ICommand {
   return {

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

@@ -2,12 +2,8 @@ import { SkillCommandSource } from '@robota-sdk/agent-framework';
 
 import { executeSkillsCommand, SKILLS_COMMAND_DESCRIPTION } from './skills-command.js';
 
-import type {
-  ICommand,
-  ICommandModule,
-  ICommandSource,
-  ISystemCommand,
-} from '@robota-sdk/agent-framework';
+import type { ICommandModule, ISystemCommand } from '@robota-sdk/agent-framework';
+import type { ICommand, ICommandSource } from '@robota-sdk/agent-interface-transport';
 
 export interface ISkillsCommandModuleOptions {
   readonly cwd: string;

package/src/skills/skills-command.ts

@@ -1,8 +1,5 @@
-import type {
-  ICommandHostContext,
-  ICommandResult,
-  ICommandSkillListEntry,
-} from '@robota-sdk/agent-framework';
+import type { ICommandHostContext, ICommandSkillListEntry } from '@robota-sdk/agent-framework';
+import type { ICommandResult } from '@robota-sdk/agent-interface-transport';
 
 export const SKILLS_COMMAND_DESCRIPTION =
   'Skill command. Before following a matching registered skill from the system prompt Skills section, invoke the projected skills command tool with args "<skill-name> [args]". Without arguments, list registered skills. With a skill name, activate that skill. Slash syntax is a UI input/display concern; the SDK command identity is "skills".';

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

@@ -6,12 +6,8 @@ import {
 
 import { executeStatusLineCommand } from './statusline-command.js';
 
-import type {
-  ICommand,
-  ICommandModule,
-  ICommandSource,
-  ISystemCommand,
-} from '@robota-sdk/agent-framework';
+import type { ICommandModule, ISystemCommand } from '@robota-sdk/agent-framework';
+import type { ICommand, ICommandSource } from '@robota-sdk/agent-interface-transport';
 
 export function createStatusLineCommandEntry(): ICommand {
   return {

package/src/statusline/statusline-command.ts

@@ -1,10 +1,10 @@
 import { DEFAULT_STATUS_LINE_COMMAND_SETTINGS } from '@robota-sdk/agent-framework';
 
+import type { ICommandHostContext } from '@robota-sdk/agent-framework';
 import type {
-  ICommandHostContext,
   ICommandResult,
   TStatusLineCommandSettingsPatch,
-} from '@robota-sdk/agent-framework';
+} from '@robota-sdk/agent-interface-transport';
 
 interface IStatusLineCommandSuccessAction {
   success: true;

package/src/user-local/user-local-command-module.ts

@@ -4,12 +4,8 @@ import {
   executeUserLocalCommand,
 } from './user-local-command.js';
 
-import type {
-  ICommand,
-  ICommandModule,
-  ICommandSource,
-  ISystemCommand,
-} from '@robota-sdk/agent-framework';
+import type { ICommandModule, ISystemCommand } from '@robota-sdk/agent-framework';
+import type { ICommand, ICommandSource } from '@robota-sdk/agent-interface-transport';
 
 export function createUserLocalCommandEntry(): ICommand {
   return {

package/src/user-local/user-local-command.ts

@@ -3,7 +3,8 @@ import { inspectUserLocalStorage } from '@robota-sdk/agent-framework';
 import { USER_LOCAL_COMMAND_USAGE } from './user-local-command-constants.js';
 import { executeMemoryCommand } from './user-local-memory-command.js';
 
-import type { ICommandHostContext, ICommandResult } from '@robota-sdk/agent-framework';
+import type { ICommandHostContext } from '@robota-sdk/agent-framework';
+import type { ICommandResult } from '@robota-sdk/agent-interface-transport';
 export {
   USER_LOCAL_COMMAND_ARGUMENT_HINT,
   USER_LOCAL_COMMAND_DESCRIPTION,

package/src/user-local/user-local-memory-command.ts

@@ -8,7 +8,8 @@ import {
 
 import { USER_LOCAL_COMMAND_USAGE } from './user-local-command-constants.js';
 
-import type { ICommandResult, TUserLocalMemoryCategory } from '@robota-sdk/agent-framework';
+import type { TUserLocalMemoryCategory } from '@robota-sdk/agent-framework';
+import type { ICommandResult } from '@robota-sdk/agent-interface-transport';
 
 export interface IUserLocalMemoryCommandArgs {
   readonly action?: string;