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

package/src/schedule/schedule-command.ts

@@ -0,0 +1,161 @@
+/**
+ * FLOW-005: `/schedule` and `/monitor` command executors — create agent-wake background tasks.
+ */
+
+import { MonitorCommandRefusedError } from '@robota-sdk/agent-framework';
+import { parseScheduleSpec } from './schedule-spec-parser.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 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 ? '…' : ''}`;
+}
+
+// SELFHOST-012: management subcommands over the existing scheduler. Create (FLOW-005) stays the default form —
+// a create spec always begins with `in`/`cron`, so these keywords never collide with it.
+const MANAGE_USAGE =
+  'Usage: /schedule list | pause <id> | resume <id> | edit <id> <spec>  (or a create spec: in <N><s|m|h|d> … | cron "<expr>" …)';
+
+/** One-line list view: id, status, cadence, label, and next-fire time. The `[status]` already conveys paused. */
+function formatScheduleList(schedules: IBackgroundTaskState[]): string {
+  if (schedules.length === 0) return 'No schedules.';
+  return schedules
+    .map((s) => {
+      // `listSchedules()` only ever returns scheduled-kind tasks; the kind check is what lets
+      // TypeScript narrow to the member that carries `schedule`/`nextFireAt` (#2079).
+      const cadence =
+        s.kind === 'scheduled' ? (s.schedule?.cronExpression ?? '(unknown)') : '(unknown)';
+      const when = s.kind === 'scheduled' && s.nextFireAt ? `next ${s.nextFireAt}` : '—';
+      return `- ${s.id} [${s.status}] ${cadence} — ${s.label} (${when})`;
+    })
+    .join('\n');
+}
+
+async function executeScheduleManagement(
+  host: IAgentJobHostContext,
+  action: string,
+  rest: string,
+  now: number,
+): Promise<ICommandResult | undefined> {
+  if (action === 'list') {
+    const schedules = host.listSchedules();
+    return {
+      message: formatScheduleList(schedules),
+      success: true,
+      data: { count: schedules.length },
+    };
+  }
+  if (action === 'pause' || action === 'resume') {
+    const id = rest.split(/\s+/)[0];
+    if (!id) return { message: MANAGE_USAGE, success: false };
+    if (action === 'pause') {
+      await host.pauseSchedule(id);
+      return { message: `Schedule paused: ${id}`, success: true, data: { taskId: id } };
+    }
+    await host.resumeSchedule(id);
+    return { message: `Schedule resumed: ${id}`, success: true, data: { taskId: id } };
+  }
+  if (action === 'edit') {
+    const idSpaceIdx = rest.indexOf(' ');
+    const id = idSpaceIdx === -1 ? rest : rest.slice(0, idSpaceIdx);
+    const spec = idSpaceIdx === -1 ? '' : rest.slice(idSpaceIdx + 1).trim();
+    if (!id || !spec) return { message: MANAGE_USAGE, success: false };
+    const parsed = parseScheduleSpec(spec, now);
+    if (!parsed.ok) return { message: parsed.error, success: false };
+    await host.editSchedule(id, {
+      cronExpression: parsed.spec.cronExpression,
+      agentInstruction: parsed.spec.instruction,
+      // CMD-009: `list` renders the label, so it must follow the instruction it summarizes.
+      label: labelFor('Scheduled', parsed.spec.instruction),
+    });
+    return {
+      message: `Schedule updated: ${id} (cron \`${parsed.spec.cronExpression}\`).`,
+      success: true,
+      data: { taskId: id, cronExpression: parsed.spec.cronExpression },
+    };
+  }
+  return undefined; // not a management subcommand — fall through to create
+}
+
+export async function executeScheduleCommand(
+  host: IAgentJobHostContext,
+  args: string,
+  now: number = Date.now(),
+): Promise<ICommandResult> {
+  const trimmed = args.trim();
+  const spaceIdx = trimmed.indexOf(' ');
+  const action = (spaceIdx === -1 ? trimmed : trimmed.slice(0, spaceIdx)).toLowerCase();
+  const rest = spaceIdx === -1 ? '' : trimmed.slice(spaceIdx + 1).trim();
+
+  const managed = await executeScheduleManagement(host, action, rest, now);
+  if (managed) return managed;
+
+  // Default: create (FLOW-005 form). On a parse failure also surface the management usage — a mistyped
+  // subcommand (e.g. `pasue <id>`) falls through here, and the create-only error hides list/pause/resume/edit.
+  const parsed = parseScheduleSpec(args, now);
+  if (!parsed.ok) return { message: `${parsed.error}\n${MANAGE_USAGE}`, 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 {
+  // `(\S.*)` — not `(.+)`: `\s+(.+)` is ambiguous (`.` also matches spaces), so a failing input
+  // runs in O(n^2). Requiring a non-space first character pins the split point after the greedy
+  // `\s+` and makes the match linear, without changing which inputs are accepted.
+  const match = /^["']([^"']+)["']\s+["']([^"']+)["']\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 };
+
+  let task: IBackgroundTaskState;
+  try {
+    task = await host.spawnMonitorWake({
+      label: labelFor('Monitor', parsed.instruction),
+      command: parsed.command,
+      matchPattern: parsed.matchPattern,
+      agentInstruction: parsed.instruction,
+    });
+  } catch (error) {
+    if (error instanceof MonitorCommandRefusedError) {
+      return { message: error.message, success: false };
+    }
+    throw error;
+  }
+
+  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,70 @@
+/**
+ * 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();
+    // `(\S.*)` — not `(.+)`: `\s+(.+)` is ambiguous (`.` also matches spaces), so a failing
+    // input runs in O(n^2). Requiring the instruction to start with a non-space pins the split
+    // point after the greedy `\s+`, making the match linear. Behaviour is unchanged because the
+    // greedy `\s+` already consumed every leading space and the capture is trimmed below.
+    const quoted = /^["']([^"']+)["']\s+(\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/__tests__/model-pricing.test.ts

@@ -0,0 +1,66 @@
+import { describe, expect, it } from 'vitest';
+import { calculateCost, formatTokens, formatUsd } from '../model-pricing.js';
+
+describe('calculateCost', () => {
+  it('returns exact cost for known Anthropic Sonnet model', () => {
+    const cost = calculateCost('claude-sonnet-4-5', 1_000_000, 1_000_000);
+    expect(cost).toBeCloseTo(3 + 15, 5);
+  });
+
+  it('returns exact cost for known Anthropic Opus model', () => {
+    const cost = calculateCost('claude-opus-4-7', 1_000_000, 1_000_000);
+    expect(cost).toBeCloseTo(15 + 75, 5);
+  });
+
+  it('calculates fractional token costs correctly', () => {
+    const cost = calculateCost('claude-sonnet-4-5', 45_000, 12_000);
+    expect(cost).toBeDefined();
+    expect(cost!).toBeCloseTo((45_000 / 1_000_000) * 3 + (12_000 / 1_000_000) * 15, 8);
+  });
+
+  it('falls back to pattern matching for claude-sonnet variant', () => {
+    const cost = calculateCost('claude-sonnet-99-99', 1_000_000, 0);
+    expect(cost).toBeCloseTo(3, 5);
+  });
+
+  it.each(['deepseek-v3-turbo', 'deepseek/deepseek-v4.1-flash-1017'])(
+    'leaves the cost of unregistered model %s unknown',
+    (model) => {
+      expect(calculateCost(model, 1_000_000, 0)).toBeUndefined();
+    },
+  );
+
+  it('returns undefined for completely unknown model', () => {
+    const cost = calculateCost('unknown-model-xyz-123', 1_000, 1_000);
+    expect(cost).toBeUndefined();
+  });
+
+  it('returns zero cost when both token counts are zero', () => {
+    const cost = calculateCost('claude-sonnet-4-5', 0, 0);
+    expect(cost).toBe(0);
+  });
+});
+
+describe('formatUsd', () => {
+  it('formats small amounts with 4 decimal places', () => {
+    expect(formatUsd(0.0043)).toBe('$0.0043');
+  });
+
+  it('formats sub-dollar amounts with 3 decimal places', () => {
+    expect(formatUsd(0.187)).toBe('$0.187');
+  });
+
+  it('formats dollar+ amounts with 2 decimal places', () => {
+    expect(formatUsd(1.24)).toBe('$1.24');
+  });
+});
+
+describe('formatTokens', () => {
+  it('formats token counts with comma separators', () => {
+    expect(formatTokens(45000)).toBe('45,000');
+  });
+
+  it('formats small counts without separator', () => {
+    expect(formatTokens(999)).toBe('999');
+  });
+});

package/src/session/__tests__/rename-host-persistence.test.ts

@@ -0,0 +1,72 @@
+/**
+ * CMD-004 Phase 2 (TC-10) — red-first `/rename` host-side persistence proof.
+ *
+ * Pre-Stage-B, `executeRenameCommand` only RETURNS the `session-renamed` effect and the mutation
+ * lives in the TUI renderer (`useSideEffects.ts` calls `interactiveSession.setName`), so a session
+ * with NO TUI attached renames nothing — these tests were recorded FAILING against that state
+ * (evidence in the spec's Evidence Log). Stage B makes the HOST execute the rename inside the
+ * `executeCommand` pipeline (direct-on-session action), strips the applied action from the returned
+ * result (so the TUI's duplicate application cannot fire — no double rename), and broadcasts
+ * `session_renamed` so every attached surface updates its title.
+ */
+
+import { describe, expect, it, vi } from 'vitest';
+import { InteractiveSession } from '@robota-sdk/agent-framework';
+import type { ISessionRenamedEvent } from '@robota-sdk/agent-interface-session';
+import { createSessionCommandModule } from '../session-command-module.js';
+
+function createRuntimeSession(): Record<string, unknown> {
+  return {
+    run: vi.fn().mockResolvedValue('answer'),
+    abort: vi.fn(),
+    clearHistory: vi.fn(),
+    getHistory: vi.fn().mockReturnValue([]),
+    injectMessage: vi.fn(),
+    getContextState: () => ({
+      maxTokens: 100,
+      usedTokens: 0,
+      usedPercentage: 0,
+      remainingPercentage: 100,
+    }),
+    getSessionId: () => 'session_rename_tc10',
+    getMessageCount: () => 0,
+    getSystemMessage: vi.fn().mockReturnValue('system'),
+    getToolSchemas: vi.fn().mockReturnValue([]),
+    getEventService: () => ({ subscribe: () => {}, unsubscribe: () => {} }),
+  };
+}
+
+describe('CMD-004 TC-10 — /rename persists host-side without any TUI handler', () => {
+  it('mutates the session name via executeCommand alone and broadcasts session_renamed', async () => {
+    const session = new InteractiveSession({
+      session: createRuntimeSession() as never,
+      commandModules: [createSessionCommandModule()],
+    });
+    const renamedEvents: ISessionRenamedEvent[] = [];
+    session.on('session_renamed', (event) => renamedEvents.push(event));
+
+    const result = await session.executeCommand('rename', 'My Renamed Session');
+
+    expect(result?.success).toBe(true);
+    expect(result?.message).toBe('Session renamed to "My Renamed Session".');
+    // The HOST executed the mutation — no surface handler involved (the defect this TC pins).
+    expect(session.getName()).toBe('My Renamed Session');
+    // Broadcast so every attached surface (incl. co-driving ones) updates its title.
+    expect(renamedEvents).toEqual([{ name: 'My Renamed Session' }]);
+    // The applied host action is CONSUMED from the returned result — no surface can double-apply it.
+    expect(result?.hostActions).toBeUndefined();
+  });
+
+  it('applies the rename exactly once (single-execution guard)', async () => {
+    const session = new InteractiveSession({
+      session: createRuntimeSession() as never,
+      commandModules: [createSessionCommandModule()],
+    });
+    const setNameSpy = vi.spyOn(session, 'setName');
+
+    await session.executeCommand('rename', 'once');
+
+    expect(setNameSpy).toHaveBeenCalledTimes(1);
+    expect(setNameSpy).toHaveBeenCalledWith('once');
+  });
+});