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

package/src/preset/__tests__/preset-command-module.test.ts

@@ -0,0 +1,138 @@
+import { describe, expect, it, vi } from 'vitest';
+import { listPresets } from '@robota-sdk/agent-preset';
+import type { ICommandHostContext, ICommandSessionRuntime } from '@robota-sdk/agent-framework';
+import { createPresetCommandModule, executePresetCommand } from '../index.js';
+
+function createSessionRuntime(overrides?: Partial<ICommandSessionRuntime>): ICommandSessionRuntime {
+  return {
+    clearHistory: () => undefined,
+    compact: async () => undefined,
+    getContextState: () => ({
+      maxTokens: 100,
+      usedTokens: 10,
+      usedPercentage: 10,
+      remainingPercentage: 90,
+    }),
+    getPermissionMode: () => 'default',
+    setPermissionMode: () => undefined,
+    getSessionId: () => 'session_1',
+    getMessageCount: () => 0,
+    getSessionAllowedTools: () => [],
+    getAutoCompactThreshold: () => false,
+    getFullHistory: () => [],
+    getHistory: () => [],
+    ...overrides,
+  };
+}
+
+function createCommandHostContext(
+  runtime: ICommandSessionRuntime,
+  overrides?: Partial<ICommandHostContext>,
+): ICommandHostContext {
+  return {
+    getSession: () => runtime,
+    getContextState: () => ({
+      maxTokens: 100,
+      usedTokens: 10,
+      usedPercentage: 10,
+      remainingPercentage: 90,
+    }),
+    getAutoCompactThreshold: () => 0.8,
+    compactContext: async () => undefined,
+    getCwd: () => '/workspace',
+    listEditCheckpoints: () => [],
+    restoreEditCheckpoint: async () => ({
+      target: {
+        id: 'checkpoint_1',
+        sessionId: 'session_1',
+        sequence: 1,
+        prompt: 'edit',
+        createdAt: '2026-05-03T00:00:00.000Z',
+        fileCount: 0,
+      },
+      restoredCheckpointCount: 1,
+      restoredFileCount: 0,
+      removedCheckpointCount: 0,
+    }),
+    rollbackEditCheckpoint: async () => ({
+      target: {
+        id: 'checkpoint_1',
+        sessionId: 'session_1',
+        sequence: 1,
+        prompt: 'edit',
+        createdAt: '2026-05-03T00:00:00.000Z',
+        fileCount: 0,
+      },
+      restoredCheckpointCount: 1,
+      restoredFileCount: 0,
+      removedCheckpointCount: 0,
+    }),
+    getUsedMemoryReferences: () => [],
+    recordMemoryEvent: () => undefined,
+    listBackgroundTasks: () => [],
+    readBackgroundTaskLog: async (taskId) => ({ taskId, lines: [] }),
+    cancelBackgroundTask: async () => undefined,
+    closeBackgroundTask: async () => undefined,
+    ...overrides,
+  };
+}
+
+describe('preset command module', () => {
+  it('exposes a single preset system command (structure)', () => {
+    const module = createPresetCommandModule();
+    expect(module.systemCommands?.map((command) => command.name)).toContain('preset');
+  });
+
+  it('TC-01: lists every preset and marks the active one', () => {
+    const runtime = createSessionRuntime({ getActivePresetId: () => 'autonomous-builder' });
+    const context = createCommandHostContext(runtime);
+
+    const result = executePresetCommand(context, '');
+
+    expect(result.success).toBe(true);
+    for (const preset of listPresets()) {
+      expect(result.message).toContain(preset.id);
+    }
+    // The active preset is marked with the `* ` prefix.
+    expect(result.message).toContain('* autonomous-builder');
+    expect(result.message).not.toContain('* default');
+    expect(result.data?.active).toBe('autonomous-builder');
+  });
+
+  it('TC-02: switches to a valid preset and drives the live re-apply seams', () => {
+    const setActivePresetId = vi.fn();
+    const setPermissionMode = vi.fn();
+    const applyModelOptions = vi.fn();
+    const runtime = createSessionRuntime({
+      setActivePresetId,
+      setPermissionMode,
+      applyModelOptions,
+    });
+    const context = createCommandHostContext(runtime);
+
+    const result = executePresetCommand(context, 'careful-reviewer');
+
+    expect(result.success).toBe(true);
+    expect(result.message).toBe('Switched to preset: careful-reviewer');
+    expect(result.data?.preset).toBe('careful-reviewer');
+    expect(setActivePresetId).toHaveBeenCalledWith('careful-reviewer');
+    // careful-reviewer resolves autonomy ask-first → default permission posture (PRESET-012)
+    // and effort high → applyModelOptions (PRESET-013).
+    expect(setPermissionMode).toHaveBeenCalledWith('default');
+    expect(applyModelOptions).toHaveBeenCalledWith(expect.objectContaining({ effort: 'high' }));
+  });
+
+  it('TC-04: rejects an unknown preset id without switching', () => {
+    const setActivePresetId = vi.fn();
+    const runtime = createSessionRuntime({ setActivePresetId });
+    const context = createCommandHostContext(runtime);
+
+    const result = executePresetCommand(context, '__nope__');
+
+    expect(result.success).toBe(false);
+    for (const preset of listPresets()) {
+      expect(result.message).toContain(preset.id);
+    }
+    expect(setActivePresetId).not.toHaveBeenCalled();
+  });
+});

package/src/preset/index.ts

@@ -0,0 +1,6 @@
+export {
+  createPresetCommandEntry,
+  createPresetCommandModule,
+  PresetCommandSource,
+} from './preset-command-module.js';
+export { executePresetCommand } from './preset-command.js';

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

@@ -0,0 +1,79 @@
+import { listPresets } from '@robota-sdk/agent-preset';
+
+import { executePresetCommand } from './preset-command.js';
+
+import type { ICommandModule, ISystemCommand } from '@robota-sdk/agent-framework';
+import type {
+  ICommand,
+  ICommandInteractionHint,
+  ICommandSource,
+} from '@robota-sdk/agent-interface-transport';
+
+const PRESET_COMMAND_DESCRIPTION = 'List presets or switch the active preset';
+const PRESET_ARGUMENT_HINT = 'list | <preset-id>';
+
+/** Build one subcommand per registered preset id (mirrors the permission-mode subcommands). */
+function buildPresetSubcommands(source = 'preset'): ICommand[] {
+  return listPresets().map((preset) => ({
+    name: preset.id,
+    description: preset.description,
+    source,
+  }));
+}
+
+export function createPresetCommandEntry(): ICommand {
+  return {
+    name: 'preset',
+    displayName: 'Agent Preset',
+    description: PRESET_COMMAND_DESCRIPTION,
+    source: 'preset',
+    argumentHint: PRESET_ARGUMENT_HINT,
+    subcommands: buildPresetSubcommands('preset'),
+    modelInvocable: false,
+  };
+}
+
+function createPresetSystemCommand(): ISystemCommand {
+  const entry = createPresetCommandEntry();
+  return {
+    name: entry.name,
+    displayName: entry.displayName,
+    description: entry.description,
+    requiresPermission: false,
+    userInvocable: true,
+    modelInvocable: false,
+    argumentHint: entry.argumentHint,
+    subcommands: entry.subcommands,
+    lifecycle: 'inline',
+    execute: executePresetCommand,
+  };
+}
+
+export class PresetCommandSource implements ICommandSource {
+  readonly name = 'preset';
+
+  getCommands(): ICommand[] {
+    return [createPresetCommandEntry()];
+  }
+}
+
+const PRESET_INTERACTION_HINTS: Record<string, ICommandInteractionHint> = {
+  preset: {
+    type: 'pick',
+    getItems: () =>
+      buildPresetSubcommands().map((sub) => ({
+        label: sub.name,
+        value: sub.name,
+        description: sub.description,
+      })),
+  },
+};
+
+export function createPresetCommandModule(): ICommandModule {
+  return {
+    name: 'agent-command-preset',
+    commandSources: [new PresetCommandSource()],
+    systemCommands: [createPresetSystemCommand()],
+    interactionHints: PRESET_INTERACTION_HINTS,
+  };
+}

package/src/preset/preset-command.ts

@@ -0,0 +1,58 @@
+import { applyPresetToSession } from '@robota-sdk/agent-framework';
+import { getPreset, listPresets, resolvePreset } from '@robota-sdk/agent-preset';
+
+import type { ICommandHostContext } from '@robota-sdk/agent-framework';
+import type { ICommandResult } from '@robota-sdk/agent-interface-transport';
+
+/** Default active preset id reported when the runtime has no recorded active preset. */
+const DEFAULT_ACTIVE_PRESET_ID = 'default';
+
+/** Read the active preset id from the session, defaulting when the optional seam is absent. */
+function readActivePresetId(context: ICommandHostContext): string {
+  return context.getSession().getActivePresetId?.() ?? DEFAULT_ACTIVE_PRESET_ID;
+}
+
+/** Build the `/preset` listing: one line per preset, marking the active one with a `*` prefix. */
+function formatPresetList(active: string): string {
+  const lines = listPresets().map((preset) => {
+    const marker = preset.id === active ? '* ' : '  ';
+    return `${marker}${preset.id} — ${preset.title}: ${preset.description}`;
+  });
+  return ['Available presets:', ...lines].join('\n');
+}
+
+/** Build the rejection message for an unknown preset id, listing the valid ids. */
+function formatUnknownPresetMessage(id: string): string {
+  const ids = listPresets()
+    .map((preset) => preset.id)
+    .join(', ');
+  return `Unknown preset: ${id}. Available: ${ids}`;
+}
+
+export function executePresetCommand(context: ICommandHostContext, args: string): ICommandResult {
+  const id = args.trim().split(/\s+/)[0];
+
+  if (id === undefined || id.length === 0 || id === 'list') {
+    const active = readActivePresetId(context);
+    return {
+      message: formatPresetList(active),
+      success: true,
+      data: { presets: listPresets(), active },
+    };
+  }
+
+  if (getPreset(id) === undefined) {
+    return {
+      message: formatUnknownPresetMessage(id),
+      success: false,
+    };
+  }
+
+  const resolved = resolvePreset(id);
+  applyPresetToSession(context, id, resolved);
+  return {
+    message: `Switched to preset: ${id}`,
+    success: true,
+    data: { preset: id },
+  };
+}

package/src/provider/provider-command-execution.ts

@@ -7,11 +7,10 @@ import { createSetupFlow, createProviderSetupInteraction } from './provider-comm
 import { formatProviderSetupChoiceLabel } from './provider-setup-flow.js';
 
 import type {
-  ICommandInteraction,
-  ICommandResult,
   IProviderCommandModuleOptions,
   IProviderProfileSettings,
 } from '@robota-sdk/agent-framework';
+import type { ICommandInteraction, ICommandResult } from '@robota-sdk/agent-interface-transport';
 
 export async function executeProviderCommand(
   args: string,

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

@@ -1,14 +1,16 @@
 import { executeProviderCommand } from './provider-command-execution.js';
 
 import type {
-  ICommand,
-  ICommandInteractionHint,
   ICommandModule as TCommandModule,
-  ICommandSource,
   IProviderCommandModuleOptions,
   IProviderCommandSettingsAdapter,
   ISystemCommand as TSystemCommand,
 } from '@robota-sdk/agent-framework';
+import type {
+  ICommand,
+  ICommandInteractionHint,
+  ICommandSource,
+} from '@robota-sdk/agent-interface-transport';
 export type { IProviderCommandModuleOptions, IProviderCommandSettingsAdapter };
 
 function buildProviderSubcommands(): ICommand[] {

package/src/provider/provider-command-profile-lifecycle.ts

@@ -6,11 +6,8 @@ import {
 
 import { formatProviderChoiceLabel } from './provider-command-profile-operations.js';
 
-import type {
-  ICommandInteraction,
-  ICommandResult,
-  IProviderCommandModuleOptions,
-} from '@robota-sdk/agent-framework';
+import type { IProviderCommandModuleOptions } from '@robota-sdk/agent-framework';
+import type { ICommandInteraction, ICommandResult } from '@robota-sdk/agent-interface-transport';
 
 const YES = 'yes';
 const MAX_DUPLICATE_PROFILE_SUFFIX = 1000;

package/src/provider/provider-command-profile-operations.ts

@@ -14,12 +14,11 @@ import { createProviderSetupFlow, submitProviderSetupValue } from './provider-se
 
 import type { IProviderSetupFlowState } from './provider-setup-flow.js';
 import type {
-  ICommandInteraction,
-  ICommandResult,
   IProviderCommandModuleOptions,
   IProviderProfileSettings,
   IProviderSetupInput,
 } from '@robota-sdk/agent-framework';
+import type { ICommandInteraction, ICommandResult } from '@robota-sdk/agent-interface-transport';
 
 export function formatProviderChoiceLabel(
   name: string,
@@ -110,7 +109,7 @@ function getProviderProfileSetupValues(profile: IProviderProfileSettings): {
   };
 }
 
-export function createProviderEditInteraction(
+function createProviderEditInteraction(
   flow: IProviderSetupFlowState,
   profileName: string,
   options: IProviderCommandModuleOptions,

package/src/provider/provider-command-profile.ts

@@ -11,11 +11,10 @@ import {
 } from './provider-command-profile-operations.js';
 
 import type {
-  ICommandInteraction,
-  ICommandResult,
   IProviderCommandModuleOptions,
   IProviderProfileSettings,
 } from '@robota-sdk/agent-framework';
+import type { ICommandInteraction, ICommandResult } from '@robota-sdk/agent-interface-transport';
 
 const ACTION_SWITCH = 'switch';
 const ACTION_EDIT = 'edit';

package/src/provider/provider-command-setup.ts

@@ -10,12 +10,14 @@ import {
 
 import type { IProviderSetupFlowState } from './provider-setup-flow.js';
 import type {
-  ICommandInteraction,
-  ICommandResult,
   IProviderCommandModuleOptions,
   IProviderSetupInput,
-  TCommandInteractionPrompt,
 } from '@robota-sdk/agent-framework';
+import type {
+  ICommandInteraction,
+  ICommandResult,
+  TCommandInteractionPrompt,
+} from '@robota-sdk/agent-interface-transport';
 
 const PROVIDER_RESTART_EFFECT = {
   type: 'session-restart-requested',
@@ -59,7 +61,7 @@ export function toProviderSetupStepPrompt(
   };
 }
 
-export function toProviderSetupPromptDescription(
+function toProviderSetupPromptDescription(
   flow: IProviderSetupFlowState,
 ): { description: string } | Record<string, never> {
   const description = formatProviderSetupHelpLinks(flow.setupHelpLinks);
@@ -89,7 +91,7 @@ function submitProviderSetupInteractionValue(
   };
 }
 
-export function completeProviderSetup(
+function completeProviderSetup(
   input: IProviderSetupInput,
   options: IProviderCommandModuleOptions,
 ): ICommandResult {

package/src/provider/provider-startup.ts

@@ -2,9 +2,11 @@ import { join } from 'node:path';
 
 import {
   checkSettingsDocument,
+  ProviderConfigError,
   readMergedProviderSettings,
   readSettings,
   writeSettings,
+  resolveEnvDefaultProvider,
   resolveSettingsPathForScope,
   getProviderSettingsPaths,
   applyProviderConfiguration,
@@ -30,6 +32,8 @@ export interface IProviderStartupContext {
 export interface IEnsureProviderConfigOptions {
   formatError: (defs: readonly IProviderDefinition[]) => string;
   isInteractive?: () => boolean;
+  /** Environment map for env-default synthesis (test seam, default: process.env). */
+  env?: Record<string, string | undefined>;
 }
 
 export async function runProviderStartupSetup(
@@ -80,9 +84,17 @@ export async function ensureProviderConfig(
   if (checkSettingsDocument(selectedSettings, providerDefinitions) === 'valid') {
     return;
   }
+  // Zero-config startup: a recognized provider env key with complete definition defaults
+  // makes setup unnecessary — resolution will synthesize an env-default config.
+  if (
+    ctx.provider === undefined &&
+    resolveEnvDefaultProvider(providerDefinitions, options.env) !== undefined
+  ) {
+    return;
+  }
   const checkInteractive = options.isInteractive ?? (() => false);
   if (!checkInteractive()) {
-    throw new Error(options.formatError(providerDefinitions));
+    throw new ProviderConfigError(options.formatError(providerDefinitions));
   }
   await runProviderStartupSetup(
     cwd,
@@ -95,7 +107,7 @@ export async function ensureProviderConfig(
   const updatedSettings =
     ctx.provider !== undefined ? { ...updated, currentProvider: ctx.provider } : updated;
   if (checkSettingsDocument(updatedSettings, providerDefinitions) !== 'valid') {
-    throw new Error(options.formatError(providerDefinitions));
+    throw new ProviderConfigError(options.formatError(providerDefinitions));
   }
 }
 

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

@@ -1,11 +1,7 @@
 import { executeResetCommand } from './reset-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';
 
 const RESET_COMMAND_DESCRIPTION = 'Delete settings';
 

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';