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

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

@@ -0,0 +1,197 @@
+import {
+  CLEAR_COMMAND_DESCRIPTION,
+  COST_COMMAND_DESCRIPTION,
+  RENAME_COMMAND_DESCRIPTION,
+  RESUME_COMMAND_DESCRIPTION,
+  VALIDATE_SESSION_COMMAND_DESCRIPTION,
+} from '@robota-sdk/agent-framework';
+
+import {
+  CD_COMMAND_DESCRIPTION,
+  executeCdCommand,
+  executeClearCommand,
+  executeCostCommand,
+  executeRenameCommand,
+  executeResumeCommand,
+  executeValidateSessionCommand,
+} from './session-command.js';
+import { createSystemCommandFromEntry } from '../command-module-utils.js';
+
+import type { ICommandModule, ISystemCommand } from '@robota-sdk/agent-framework';
+import type { ICommand, ICommandSource } from '@robota-sdk/agent-interface-command';
+
+export function createClearCommandEntry(): ICommand {
+  return {
+    name: 'clear',
+    displayName: 'Clear History',
+    description: CLEAR_COMMAND_DESCRIPTION,
+    source: 'session',
+    // User-only: wiping the conversation is the user's decision.
+    modelInvocable: false,
+    userInvocable: true,
+  };
+}
+
+export function createRenameCommandEntry(): ICommand {
+  return {
+    name: 'rename',
+    displayName: 'Rename Session',
+    description: RENAME_COMMAND_DESCRIPTION,
+    argumentHint: '<name>',
+    source: 'session',
+    // User-only: the session's name is the user's label; UI-only.
+    modelInvocable: false,
+    userInvocable: true,
+  };
+}
+
+export function createCdCommandEntry(): ICommand {
+  return {
+    name: 'cd',
+    displayName: 'Change Directory',
+    description: CD_COMMAND_DESCRIPTION,
+    argumentHint: '<directory>',
+    source: 'session',
+    // A move re-roots what every later tool call may touch; only the user decides it.
+    modelInvocable: false,
+    userInvocable: true,
+  };
+}
+
+export function createResumeCommandEntry(): ICommand {
+  return {
+    name: 'resume',
+    displayName: 'Resume Session',
+    description: RESUME_COMMAND_DESCRIPTION,
+    source: 'session',
+    // User-only: switching to another session is the user's decision.
+    modelInvocable: false,
+    userInvocable: true,
+  };
+}
+
+export function createCostCommandEntry(): ICommand {
+  return {
+    name: 'cost',
+    displayName: 'Session Cost',
+    description: COST_COMMAND_DESCRIPTION,
+    // Model-invocable for the read-only report only: the model can weigh cost before an expensive
+    // step. The monthly budget is the user's spending decision, so `budget` stays user-only.
+    modelDescription:
+      'Report this session’s token usage and estimated cost. Use it before an expensive step (a ' +
+      'large refactor, many subagents) or when the user asks what the session has cost. Returns ' +
+      'the message count, input/output token totals and the estimated USD cost, with the remaining ' +
+      'monthly budget when one is set. Setting or clearing the budget is the user’s decision: suggest `/cost budget <amount>`.',
+    argumentHint: '[budget [<amount>|clear]]',
+    // The bare `/cost` is the report, so choosing it from a menu runs it.
+    runsBare: true,
+    source: 'session',
+    modelInvocable: true,
+    userInvocable: true,
+    subcommands: [
+      {
+        name: 'budget',
+        description: 'Show, set, or clear the monthly budget',
+        argumentHint: '[<amount>|clear]',
+        source: 'session',
+        modelInvocable: false,
+      },
+    ],
+  };
+}
+
+export function createValidateSessionCommandEntry(): ICommand {
+  return {
+    name: 'validate-session',
+    displayName: 'Validate Session',
+    description: VALIDATE_SESSION_COMMAND_DESCRIPTION,
+    source: 'session',
+    // User-only: a diagnostic of the replay log for the user; nothing the model acts on.
+    modelInvocable: false,
+    userInvocable: true,
+  };
+}
+
+function createClearSystemCommand(): ISystemCommand {
+  const entry = createClearCommandEntry();
+  return createSystemCommandFromEntry(entry, {
+    requiresPermission: false,
+    lifecycle: 'inline',
+    execute: executeClearCommand,
+  });
+}
+
+function createRenameSystemCommand(): ISystemCommand {
+  const entry = createRenameCommandEntry();
+  return createSystemCommandFromEntry(entry, {
+    requiresPermission: false,
+    lifecycle: 'inline',
+    execute: executeRenameCommand,
+  });
+}
+
+function createCdSystemCommand(): ISystemCommand {
+  const entry = createCdCommandEntry();
+  return createSystemCommandFromEntry(entry, {
+    requiresPermission: false,
+    lifecycle: 'inline',
+    execute: executeCdCommand,
+  });
+}
+
+function createResumeSystemCommand(): ISystemCommand {
+  const entry = createResumeCommandEntry();
+  return createSystemCommandFromEntry(entry, {
+    requiresPermission: false,
+    lifecycle: 'inline',
+    execute: executeResumeCommand,
+  });
+}
+
+function createCostSystemCommand(): ISystemCommand {
+  const entry = createCostCommandEntry();
+  return createSystemCommandFromEntry(entry, {
+    requiresPermission: false,
+    lifecycle: 'inline',
+    execute: executeCostCommand,
+  });
+}
+
+function createValidateSessionSystemCommand(): ISystemCommand {
+  const entry = createValidateSessionCommandEntry();
+  return createSystemCommandFromEntry(entry, {
+    requiresPermission: false,
+    lifecycle: 'inline',
+    execute: executeValidateSessionCommand,
+  });
+}
+
+export class SessionCommandSource implements ICommandSource {
+  readonly name = 'session';
+
+  getCommands(): ICommand[] {
+    return [
+      createClearCommandEntry(),
+      createRenameCommandEntry(),
+      createCdCommandEntry(),
+      createResumeCommandEntry(),
+      createCostCommandEntry(),
+      createValidateSessionCommandEntry(),
+    ];
+  }
+}
+
+export function createSessionCommandModule(): ICommandModule {
+  return {
+    name: 'agent-command-session',
+    commandSources: [new SessionCommandSource()],
+    systemCommands: [
+      createClearSystemCommand(),
+      createRenameSystemCommand(),
+      createCdSystemCommand(),
+      createResumeSystemCommand(),
+      createCostSystemCommand(),
+      createValidateSessionSystemCommand(),
+    ],
+  };
+}

package/src/session/session-command.ts

@@ -0,0 +1,272 @@
+import { confirmAction, isConfirmed } from '@robota-sdk/agent-core';
+import {
+  RENAME_COMMAND_USAGE,
+  clearConversationHistory,
+  createShowSessionPickerIntent,
+  createSessionRenameHostAction,
+  formatCommandSessionReplayValidationReport,
+  parseSessionNameArgument,
+  readCommandSessionInfo,
+  validateCommandSessionReplayLog,
+} from '@robota-sdk/agent-framework';
+
+import { calculateCost, formatTokens, formatUsd } from './model-pricing.js';
+
+import type {
+  ICommandCostBudgetAdapter,
+  ICommandHostAdapterAccess,
+  ICommandHostNoCapability,
+  ICommandHostSessionAccess,
+  ICommandHostUserInteraction,
+  ICommandHostWorkspace,
+  ISessionUsageRecord,
+} from '@robota-sdk/agent-framework';
+import type { ICommandResult } from '@robota-sdk/agent-interface-command';
+
+export const CLEAR_COMMAND_MESSAGE = 'Conversation cleared.';
+
+export const CD_COMMAND_DESCRIPTION = 'Move this session to another working directory';
+export const CD_COMMAND_USAGE = 'Usage: /cd <directory>';
+
+/**
+ * `/cd <directory>` (issue #3081) requests the host-executed move. The checks — no turn running, no
+ * live background task, the target exists, no `Cd(...)` deny rule — run where the session state is,
+ * when the host applies the action.
+ */
+export function executeCdCommand(_context: ICommandHostNoCapability, args: string): ICommandResult {
+  const path = args.trim();
+  if (path === '') return { success: false, message: CD_COMMAND_USAGE };
+  return { success: true, message: '', hostActions: [{ type: 'workspace-move', path }] };
+}
+
+export async function executeClearCommand(
+  context: ICommandHostSessionAccess & ICommandHostUserInteraction,
+  _args: string,
+): Promise<ICommandResult> {
+  // Confirm only when an interactive renderer is attached; with no human the explicit /clear proceeds.
+  const ui = context.getUserInteraction();
+  if (ui) {
+    const response = await ui.ask(confirmAction('clear', 'Clear conversation history?'));
+    if (!isConfirmed(response)) {
+      return { success: true, message: 'Clear cancelled.' };
+    }
+  }
+
+  // CMD-004 Stage E: the clear mutation runs host-side and the session broadcasts `history_cleared`
+  // to every attached surface — the result carries no separate notification.
+  clearConversationHistory(context);
+  return { success: true, message: CLEAR_COMMAND_MESSAGE };
+}
+
+export function executeRenameCommand(
+  _context: ICommandHostNoCapability,
+  args: string,
+): ICommandResult {
+  const name = parseSessionNameArgument(args);
+  if (name === undefined) {
+    return { success: false, message: RENAME_COMMAND_USAGE };
+  }
+
+  return {
+    success: true,
+    message: `Session renamed to "${name}".`,
+    data: { name },
+    hostActions: [createSessionRenameHostAction(name)],
+  };
+}
+
+export function executeResumeCommand(): ICommandResult {
+  return {
+    success: true,
+    message: 'Opening session picker...',
+    data: { triggerResumePicker: true },
+    uiIntents: [createShowSessionPickerIntent()],
+  };
+}
+
+type TCostCommandContext = ICommandHostSessionAccess &
+  ICommandHostWorkspace &
+  ICommandHostAdapterAccess;
+
+/**
+ * CMD-007 (issue #2058): the budget lives behind `ICommandCostBudgetAdapter`, composed by the shell.
+ * This package owns no path literal and no filesystem call for it any more — atomic/symlink-safe
+ * writing is the adapter's policy (agent-cli's file adapter keeps the O_NOFOLLOW guard).
+ */
+function costBudgetAdapter(context: TCostCommandContext): ICommandCostBudgetAdapter | undefined {
+  return context.getCommandHostAdapters?.().costBudget;
+}
+
+const BUDGET_UNAVAILABLE_MESSAGE =
+  'Budget persistence is not available on this host (no cost-budget adapter was composed).';
+
+/** What to tell the operator when the adapter refused the write; the adapter names the cause. */
+function describeBudgetWriteFailure(error: unknown): string {
+  return `Could not write the budget: ${error instanceof Error ? error.message : String(error)}`;
+}
+
+interface ICostTotals {
+  inputTokens: number;
+  outputTokens: number;
+  /** Absent when nothing could be priced. */
+  costUsd?: number;
+  /** Some usage could not be priced, so the cost is a lower bound. */
+  partial: boolean;
+  /** The models the cost was priced on. */
+  models: string[];
+}
+
+/**
+ * Total the session's usage records. A record priced on its own model (the advisor's) keeps that
+ * price; a main-thread record without one is priced on the session's model. A consulted model whose
+ * price is unknown is left unpriced rather than priced as the main model.
+ */
+function totalSessionUsage(
+  records: readonly ISessionUsageRecord[],
+  modelId: string | undefined,
+): ICostTotals | undefined {
+  if (records.length === 0) return undefined;
+  const totals: ICostTotals = { inputTokens: 0, outputTokens: 0, partial: false, models: [] };
+  const models = new Set<string>();
+  let cost = 0;
+  let priced = false;
+  for (const record of records) {
+    totals.inputTokens += record.promptTokens;
+    totals.outputTokens += record.completionTokens;
+    const consulted = record.source?.scope === 'tool';
+    const recordCost =
+      record.costUsd ??
+      (!consulted && modelId
+        ? calculateCost(modelId, record.promptTokens, record.completionTokens)
+        : undefined);
+    if (recordCost === undefined) {
+      totals.partial = true;
+      continue;
+    }
+    cost += recordCost;
+    priced = true;
+    models.add(consulted ? (record.source?.label ?? 'another model') : (modelId ?? 'main model'));
+  }
+  if (priced) totals.costUsd = cost;
+  totals.models = [...models];
+  return totals;
+}
+
+function buildCostOutput(context: TCostCommandContext): {
+  lines: string[];
+  data: Record<string, unknown>;
+} {
+  const session = context.getSession();
+  const sessionInfo = readCommandSessionInfo(context);
+  const modelId = session.getModelId();
+  const totals = totalSessionUsage(context.getSessionUsage(), modelId);
+  const lines: string[] = [
+    `Session:  ${sessionInfo.sessionId}`,
+    `Messages: ${sessionInfo.messageCount}`,
+  ];
+  const data: Record<string, unknown> = {
+    sessionId: sessionInfo.sessionId,
+    messageCount: sessionInfo.messageCount,
+  };
+
+  if (totals) {
+    lines.push(
+      `Tokens:   ${formatTokens(totals.inputTokens)} input  /  ${formatTokens(totals.outputTokens)} output`,
+    );
+    data.inputTokens = totals.inputTokens;
+    data.outputTokens = totals.outputTokens;
+
+    const cost = totals.costUsd;
+    if (cost !== undefined) {
+      const priced =
+        totals.models.length > 1 ? `mixed: ${totals.models.join(', ')}` : (totals.models[0] ?? '');
+      const note = totals.partial ? '; some usage could not be priced' : '';
+      lines.push(`Cost:     ${formatUsd(cost)}  (${priced}${note})`);
+      data.estimatedCostUsd = cost;
+      data.costModels = totals.models;
+      if (totals.partial) data.costPartial = true;
+
+      const budget = costBudgetAdapter(context)?.read();
+      if (budget?.monthly) {
+        const remaining = budget.monthly - cost;
+        const pct = Math.min(100, Math.round((cost / budget.monthly) * 100));
+        lines.push(
+          `Budget:   ${formatUsd(remaining)} remaining of ${formatUsd(budget.monthly)}/mo  (${pct}% used)`,
+        );
+        data.budgetMonthly = budget.monthly;
+        data.budgetRemainingUsd = remaining;
+      }
+    }
+  } else {
+    lines.push('Tokens:   not yet available (no turns completed)');
+  }
+
+  return { lines, data };
+}
+
+export function executeCostCommand(context: TCostCommandContext, args: string): ICommandResult {
+  const trimmed = args.trim();
+
+  if (trimmed.startsWith('budget')) {
+    const budgetArg = trimmed.slice('budget'.length).trim();
+    // Argument shape is judged before the host is asked for persistence: a malformed amount is a
+    // usage error on every host, not a symptom of the adapter that would have stored it.
+    const amount = budgetArg === 'clear' || budgetArg === '' ? undefined : parseFloat(budgetArg);
+    if (amount !== undefined && (!Number.isFinite(amount) || amount <= 0)) {
+      return {
+        success: false,
+        message: 'Usage: /cost budget <amount>  (e.g. /cost budget 5.00)',
+      };
+    }
+    const adapter = costBudgetAdapter(context);
+    if (adapter === undefined) return { success: false, message: BUDGET_UNAVAILABLE_MESSAGE };
+
+    if (budgetArg === 'clear') {
+      try {
+        adapter.clear();
+      } catch (error) {
+        return { success: false, message: describeBudgetWriteFailure(error) };
+      }
+      return { success: true, message: 'Monthly budget cleared.' };
+    }
+
+    if (budgetArg === '') {
+      const current = adapter.read();
+      if (!current?.monthly) {
+        return {
+          success: true,
+          message: 'No budget set. Use: /cost budget <amount>',
+        };
+      }
+      return { success: true, message: `Monthly budget: ${formatUsd(current.monthly)}` };
+    }
+
+    if (amount === undefined) return { success: false, message: BUDGET_UNAVAILABLE_MESSAGE };
+    try {
+      adapter.write({ monthly: amount });
+    } catch (error) {
+      return { success: false, message: describeBudgetWriteFailure(error) };
+    }
+    return { success: true, message: `Monthly budget set to ${formatUsd(amount)}.` };
+  }
+
+  const { lines, data } = buildCostOutput(context);
+  return { success: true, message: lines.join('\n'), data };
+}
+
+export function executeValidateSessionCommand(
+  context: ICommandHostSessionAccess & ICommandHostWorkspace,
+  _args: string,
+): ICommandResult {
+  const report = validateCommandSessionReplayLog(context);
+  return {
+    success: report.validation.ok,
+    message: formatCommandSessionReplayValidationReport(report),
+    data: {
+      logFile: report.logFile,
+      entryCount: report.entryCount,
+      issueCount: report.validation.issues.length,
+      ok: report.validation.ok,
+    },
+  };
+}

package/src/settings/index.ts

@@ -0,0 +1,7 @@
+// @robota-sdk/agent-command-settings
+
+export {
+  createSettingsCommandModule,
+  createSettingsCommandEntry,
+  SettingsCommandSource,
+} from './settings-command-module.js';

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

@@ -0,0 +1,47 @@
+import type { ICommandModule, ISystemCommand } from '@robota-sdk/agent-framework';
+import type { ICommand, ICommandSource } from '@robota-sdk/agent-interface-command';
+
+export function createSettingsCommandEntry(): ICommand {
+  return {
+    name: 'settings',
+    displayName: 'Settings',
+    description: 'Open settings — language, output style, preset, permissions and more',
+    source: 'settings',
+    // User-only: opens a screen; nothing here is a model action.
+    modelInvocable: false,
+  };
+}
+
+function createSettingsSystemCommand(): ISystemCommand {
+  const entry = createSettingsCommandEntry();
+  return {
+    name: entry.name,
+    displayName: entry.displayName,
+    description: entry.description,
+    requiresPermission: false,
+    userInvocable: true,
+    modelInvocable: false,
+    lifecycle: 'inline',
+    execute: async () => ({
+      success: true,
+      message: 'Opening settings...',
+      uiIntents: [{ type: 'show-settings' as const }],
+    }),
+  };
+}
+
+export class SettingsCommandSource implements ICommandSource {
+  readonly name = 'settings';
+
+  getCommands(): ICommand[] {
+    return [createSettingsCommandEntry()];
+  }
+}
+
+export function createSettingsCommandModule(): ICommandModule {
+  return {
+    name: 'agent-command-settings',
+    commandSources: [new SettingsCommandSource()],
+    systemCommands: [createSettingsSystemCommand()],
+  };
+}

package/src/shell/__tests__/resolve-shell-host.test.ts

@@ -0,0 +1,11 @@
+import { describe, expect, it } from 'vitest';
+
+import { resolveShell } from '../resolve-shell.js';
+
+describe('interactive shell host selection', () => {
+  it('keeps the executable and argument family together', () => {
+    const shell = resolveShell('C:\\Windows\\System32\\cmd.exe');
+    expect(shell.command).toBe('C:\\Windows\\System32\\cmd.exe');
+    expect(shell.commandArgs('echo ok')).toEqual(['/d', '/s', '/c', 'echo ok']);
+  });
+});

package/src/shell/__tests__/shell-command-functional.test.ts

@@ -0,0 +1,118 @@
+/**
+ * TERM-003: `/shell` — framework functional test.
+ *
+ * Drives the command through a REAL InteractiveSession (scripted provider) with an injected fake
+ * terminal-handoff capability: the command routes a one-shot shell command through `runWithTerminal`
+ * (suspend → spawn shell with inherited stdio → restore) and reports its exit code; and is
+ * unavailable when no interactive terminal exists. (Real interactive input is manual — TERM-002.)
+ */
+import { afterEach, describe, expect, it } from 'vitest';
+
+import { scriptedSession, type ScriptedSessionHarness } from '@robota-sdk/agent-framework/testing';
+
+import { createShellCommandModule } from '../shell-command-module.js';
+
+import type { ITerminalHandoff } from '@robota-sdk/agent-interface-session';
+
+const TEST_TIMEOUT = 20_000;
+
+function fakeHandoff(canHandoff: boolean): ITerminalHandoff & { readonly events: string[] } {
+  const events: string[] = [];
+  return {
+    events,
+    canHandoffTerminal: canHandoff,
+    async runWithTerminal<T>(fn: () => Promise<T>): Promise<T> {
+      events.push('suspend');
+      try {
+        return await fn();
+      } finally {
+        events.push('restore');
+      }
+    },
+  };
+}
+
+let h: ScriptedSessionHarness | undefined;
+afterEach(async () => {
+  await h?.dispose();
+  h = undefined;
+});
+
+describe('/shell command (framework functional)', () => {
+  it(
+    'uses the host-selected executable captured by its module',
+    async () => {
+      if (process.platform === 'win32') return;
+      const previousShell = process.env['SHELL'];
+      process.env['SHELL'] = '/bin/false';
+      try {
+        h = scriptedSession({
+          turns: [{ text: 'unused' }],
+          terminalHandoff: fakeHandoff(true),
+          commandModules: [createShellCommandModule('/bin/bash')],
+        });
+        const result = await h.command('shell', 'exit 0');
+        expect(result?.success).toBe(true);
+      } finally {
+        if (previousShell === undefined) delete process.env['SHELL'];
+        else process.env['SHELL'] = previousShell;
+      }
+    },
+    TEST_TIMEOUT,
+  );
+
+  it(
+    'runs a one-shot command through the handoff and returns exit code 0',
+    async () => {
+      const handoff = fakeHandoff(true);
+      h = scriptedSession({
+        turns: [{ text: 'unused' }],
+        terminalHandoff: handoff,
+        commandModules: [createShellCommandModule()],
+      });
+
+      const result = await h.command('shell', 'exit 0');
+
+      expect(result?.success).toBe(true);
+      expect((result?.data as { exitCode: number }).exitCode).toBe(0);
+      // The command went through the transport handoff (suspend → run → restore).
+      expect(handoff.events).toEqual(['suspend', 'restore']);
+    },
+    TEST_TIMEOUT,
+  );
+
+  it(
+    'reports a non-zero exit code from the child',
+    async () => {
+      const handoff = fakeHandoff(true);
+      h = scriptedSession({
+        turns: [{ text: 'unused' }],
+        terminalHandoff: handoff,
+        commandModules: [createShellCommandModule()],
+      });
+
+      const result = await h.command('shell', 'exit 3');
+
+      expect(result?.success).toBe(false);
+      expect((result?.data as { exitCode: number }).exitCode).toBe(3);
+    },
+    TEST_TIMEOUT,
+  );
+
+  it(
+    'is unavailable when there is no interactive terminal',
+    async () => {
+      // No terminalHandoff injected → canHandoffTerminal() is false.
+      h = scriptedSession({
+        turns: [{ text: 'unused' }],
+        commandModules: [createShellCommandModule()],
+      });
+
+      const result = await h.command('shell', 'exit 0');
+
+      expect(result?.success).toBe(false);
+      expect(result?.message).toMatch(/unavailable/i);
+    },
+    TEST_TIMEOUT,
+  );
+});

package/src/shell/index.ts

@@ -0,0 +1,8 @@
+export { resolveShell, type IResolvedShell } from './resolve-shell.js';
+export { spawnInherited } from './spawn-inherited.js';
+export { executeShellCommand, SHELL_COMMAND_DESCRIPTION } from './shell-command.js';
+export {
+  ShellCommandSource,
+  createShellCommandEntry,
+  createShellCommandModule,
+} from './shell-command-module.js';

package/src/shell/resolve-shell.ts

@@ -0,0 +1,25 @@
+/**
+ * TERM-003 shell-selection seam, now backed by the cross-platform SSOT resolver in agent-core
+ * (TERM-008). Keep all shell choice behind this function so the call sites never change; the
+ * per-platform logic (POSIX `$SHELL`/`sh`, Windows PowerShell) lives once in `resolvePlatformShell`.
+ */
+import { resolvePlatformShell } from '@robota-sdk/agent-core';
+
+export interface IResolvedShell {
+  /** Executable to spawn. */
+  command: string;
+  /** Args for an interactive shell session (drop-to-shell). */
+  interactiveArgs: readonly string[];
+  /** Args to run a single command string non-interactively. */
+  commandArgs(command: string): readonly string[];
+}
+
+/** Resolve the interactive shell for the current platform via the agent-core SSOT resolver. */
+export function resolveShell(executable?: string): IResolvedShell {
+  const shell = resolvePlatformShell({ executable });
+  return {
+    command: shell.command,
+    interactiveArgs: shell.interactiveArgs,
+    commandArgs: (cmd: string) => shell.commandArgs(cmd),
+  };
+}