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

package/src/session/model-pricing.ts

@@ -1,69 +1,16 @@
-/** USD prices per 1,000,000 tokens (as of May 2026 — update when providers change rates). */
-interface IModelPrice {
-  inputPerMillion: number;
-  outputPerMillion: number;
-}
-
-const MODEL_PRICES: Record<string, IModelPrice> = {
-  // Anthropic Claude 4
-  'claude-opus-4-7': { inputPerMillion: 15, outputPerMillion: 75 },
-  'claude-opus-4-5': { inputPerMillion: 15, outputPerMillion: 75 },
-  'claude-sonnet-4-6': { inputPerMillion: 3, outputPerMillion: 15 },
-  'claude-sonnet-4-5': { inputPerMillion: 3, outputPerMillion: 15 },
-  'claude-haiku-4-5': { inputPerMillion: 0.8, outputPerMillion: 4 },
-  // Anthropic Claude 3
-  'claude-3-5-sonnet-20241022': { inputPerMillion: 3, outputPerMillion: 15 },
-  'claude-3-5-haiku-20241022': { inputPerMillion: 0.8, outputPerMillion: 4 },
-  'claude-3-opus-20240229': { inputPerMillion: 15, outputPerMillion: 75 },
-  // OpenAI
-  'gpt-4o': { inputPerMillion: 2.5, outputPerMillion: 10 },
-  'gpt-4o-mini': { inputPerMillion: 0.15, outputPerMillion: 0.6 },
-  o1: { inputPerMillion: 15, outputPerMillion: 60 },
-  'o1-mini': { inputPerMillion: 3, outputPerMillion: 12 },
-  o3: { inputPerMillion: 10, outputPerMillion: 40 },
-  'o3-mini': { inputPerMillion: 1.1, outputPerMillion: 4.4 },
-  // DeepSeek
-  'deepseek-chat': { inputPerMillion: 0.14, outputPerMillion: 0.28 },
-  'deepseek-reasoner': { inputPerMillion: 0.55, outputPerMillion: 2.19 },
-  // Google Gemini
-  'gemini-2.0-flash': { inputPerMillion: 0.1, outputPerMillion: 0.4 },
-  'gemini-2.0-flash-thinking': { inputPerMillion: 0.35, outputPerMillion: 3.5 },
-  'gemini-1.5-pro': { inputPerMillion: 1.25, outputPerMillion: 5 },
-  'gemini-1.5-flash': { inputPerMillion: 0.075, outputPerMillion: 0.3 },
-};
-
-const PATTERN_PRICES: Array<{ pattern: RegExp; price: IModelPrice }> = [
-  { pattern: /claude-opus/i, price: { inputPerMillion: 15, outputPerMillion: 75 } },
-  { pattern: /claude-sonnet/i, price: { inputPerMillion: 3, outputPerMillion: 15 } },
-  { pattern: /claude-haiku/i, price: { inputPerMillion: 0.8, outputPerMillion: 4 } },
-  { pattern: /gpt-4o-mini/i, price: { inputPerMillion: 0.15, outputPerMillion: 0.6 } },
-  { pattern: /gpt-4/i, price: { inputPerMillion: 2.5, outputPerMillion: 10 } },
-  { pattern: /deepseek/i, price: { inputPerMillion: 0.14, outputPerMillion: 0.28 } },
-  { pattern: /gemini-2/i, price: { inputPerMillion: 0.1, outputPerMillion: 0.4 } },
-  { pattern: /gemini-1/i, price: { inputPerMillion: 1.25, outputPerMillion: 5 } },
-];
-
-function lookupPrice(modelId: string): IModelPrice | undefined {
-  const exact = MODEL_PRICES[modelId];
-  if (exact) return exact;
-  for (const { pattern, price } of PATTERN_PRICES) {
-    if (pattern.test(modelId)) return price;
-  }
-  return undefined;
-}
+import { calculateModelCost } from '@robota-sdk/agent-core';
 
-/** Returns USD cost, or undefined if the model is not in the pricing table. */
+/**
+ * Returns USD cost, or undefined if the model is not in the pricing table.
+ * Delegates to the agent-core pricing SSOT (`calculateModelCost`); this package owns only the
+ * command-facing display helpers below.
+ */
 export function calculateCost(
   modelId: string,
   inputTokens: number,
   outputTokens: number,
 ): number | undefined {
-  const price = lookupPrice(modelId);
-  if (!price) return undefined;
-  return (
-    (inputTokens / 1_000_000) * price.inputPerMillion +
-    (outputTokens / 1_000_000) * price.outputPerMillion
-  );
+  return calculateModelCost(modelId, inputTokens, outputTokens);
 }
 
 /** Format a USD amount for display (e.g. "$0.0043"). */

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

@@ -15,11 +15,7 @@ import {
 } from './session-command.js';
 
 import type { ICommandModule, ISystemCommand } from '@robota-sdk/agent-framework';
-import type {
-  ICommand,
-  ICommandInteractionHint,
-  ICommandSource,
-} from '@robota-sdk/agent-interface-transport';
+import type { ICommand, ICommandSource } from '@robota-sdk/agent-interface-transport';
 
 export function createClearCommandEntry(): ICommand {
   return {
@@ -155,10 +151,6 @@ export class SessionCommandSource implements ICommandSource {
   }
 }
 
-const SESSION_INTERACTION_HINTS: Record<string, ICommandInteractionHint> = {
-  clear: { type: 'confirm', message: 'Clear conversation history?' },
-};
-
 export function createSessionCommandModule(): ICommandModule {
   return {
     name: 'agent-command-session',
@@ -170,6 +162,5 @@ export function createSessionCommandModule(): ICommandModule {
       createCostSystemCommand(),
       createValidateSessionSystemCommand(),
     ],
-    interactionHints: SESSION_INTERACTION_HINTS,
   };
 }

package/src/session/session-command.ts

@@ -1,6 +1,7 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 
+import { confirmAction, isConfirmed } from '@robota-sdk/agent-core';
 import {
   RENAME_COMMAND_USAGE,
   clearConversationHistory,
@@ -19,7 +20,19 @@ import type { ICommandResult } from '@robota-sdk/agent-interface-transport';
 
 export const CLEAR_COMMAND_MESSAGE = 'Conversation cleared.';
 
-export function executeClearCommand(context: ICommandHostContext, _args: string): ICommandResult {
+export async function executeClearCommand(
+  context: ICommandHostContext,
+  _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.' };
+    }
+  }
+
   clearConversationHistory(context);
   return {
     success: true,

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

@@ -0,0 +1,96 @@
+/**
+ * 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-transport';
+
+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(
+    '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(): IResolvedShell {
+  const shell = resolvePlatformShell();
+  return {
+    command: shell.command,
+    interactiveArgs: shell.interactiveArgs,
+    commandArgs: (cmd: string) => shell.commandArgs(cmd),
+  };
+}

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

@@ -0,0 +1,47 @@
+/**
+ * TERM-003: `/shell` command module — a framework-level consumer of the terminal-handoff capability.
+ */
+import { executeShellCommand, SHELL_COMMAND_DESCRIPTION } from './shell-command.js';
+
+import type { ICommandModule, ISystemCommand } from '@robota-sdk/agent-framework';
+import type { ICommand, ICommandSource } from '@robota-sdk/agent-interface-transport';
+
+export function createShellCommandEntry(): ICommand {
+  return {
+    name: 'shell',
+    displayName: 'Shell',
+    description: SHELL_COMMAND_DESCRIPTION,
+    source: 'shell',
+    modelInvocable: false,
+  };
+}
+
+function createShellSystemCommand(): ISystemCommand {
+  const entry = createShellCommandEntry();
+  return {
+    name: entry.name,
+    displayName: entry.displayName,
+    description: entry.description,
+    requiresPermission: true,
+    userInvocable: true,
+    modelInvocable: false,
+    lifecycle: 'inline',
+    execute: executeShellCommand,
+  };
+}
+
+export class ShellCommandSource implements ICommandSource {
+  readonly name = 'shell';
+
+  getCommands(): ICommand[] {
+    return [createShellCommandEntry()];
+  }
+}
+
+export function createShellCommandModule(): ICommandModule {
+  return {
+    name: 'agent-command-shell',
+    commandSources: [new ShellCommandSource()],
+    systemCommands: [createShellSystemCommand()],
+  };
+}

package/src/shell/shell-command.ts

@@ -0,0 +1,44 @@
+/**
+ * TERM-003: `/shell` — hand the real terminal to an interactive subshell (or run a single command
+ * interactively), then return to the agent session. Uses the framework terminal-handoff capability;
+ * the shell choice goes through the `resolveShell()` seam (macOS/Linux first).
+ */
+import { resolveShell } from './resolve-shell.js';
+import { spawnInherited } from './spawn-inherited.js';
+
+import type { ICommandHostContext } from '@robota-sdk/agent-framework';
+import type { ICommandResult } from '@robota-sdk/agent-interface-transport';
+
+export const SHELL_COMMAND_DESCRIPTION =
+  'Drop to an interactive shell (or run `/shell <command>` interactively), then return to the agent.';
+
+export async function executeShellCommand(
+  context: ICommandHostContext,
+  args: string,
+): Promise<ICommandResult> {
+  if (context.canHandoffTerminal?.() !== true || context.runWithTerminal === undefined) {
+    return {
+      message: 'An interactive shell is unavailable here (no interactive terminal).',
+      success: false,
+    };
+  }
+
+  const shell = resolveShell();
+  const cwd = context.getCwd();
+  const command = args.trim();
+
+  const exitCode = await context.runWithTerminal(async () =>
+    command.length > 0
+      ? spawnInherited(shell.command, shell.commandArgs(command), cwd)
+      : spawnInherited(shell.command, shell.interactiveArgs, cwd),
+  );
+
+  return {
+    message:
+      command.length > 0
+        ? `Command exited (code ${exitCode}).`
+        : `Shell session ended (code ${exitCode}).`,
+    success: exitCode === 0,
+    data: { exitCode },
+  };
+}

package/src/shell/spawn-inherited.ts

@@ -0,0 +1,32 @@
+/**
+ * Pure-Node spawn with the real terminal inherited (interactive input + output). Used inside a
+ * terminal-handoff `runWithTerminal(fn)` — the framework/transport own the suspend/restore; this just
+ * runs the child attached to the real TTY and resolves with its exit code.
+ */
+import { spawn } from 'node:child_process';
+import { constants } from 'node:os';
+
+export function spawnInherited(
+  command: string,
+  args: readonly string[],
+  cwd: string,
+): Promise<number> {
+  return new Promise<number>((resolve, reject) => {
+    const child = spawn(command, [...args], { cwd, stdio: 'inherit', env: process.env });
+    child.on('error', reject);
+    child.on('exit', (code, signal) => {
+      // RUNTIME-53: a signal-terminated child reports code=null; resolving 0 there is a false
+      // success. Translate to the shell convention 128 + signal number so callers see the failure.
+      if (code !== null) {
+        resolve(code);
+        return;
+      }
+      if (signal) {
+        const signalNumber = constants.signals[signal as keyof typeof constants.signals];
+        resolve(128 + (signalNumber ?? 0));
+        return;
+      }
+      resolve(0);
+    });
+  });
+}