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

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);
+    });
+  });
+}