@robota-sdk/agent-ui-terminal 3.0.0-beta.82 → 3.0.0-beta.83

package/src/wire-tui-client-commands.ts

@@ -0,0 +1,142 @@
+/**
+ * #3189: the commands that belong to the terminal the user sits at (`/shell`, `/editor`, `/theme`,
+ * `/keybindings`). A terminal attached to a workspace daemon runs these in its own process — on its
+ * own terminal, in its own working directory — and sends nothing to the daemon.
+ *
+ * The attached terminal routes by the set it is given here, never by the daemon's catalog, so an
+ * older daemon or a catalog that arrives late cannot send one of these commands to the daemon.
+ *
+ * The in-process session applies a command's host actions and emits its UI intents; here the
+ * terminal does both itself. The one host action these commands produce, the appearance settings
+ * patch, is written through the writer the composition root gives. Anything else is refused by name
+ * rather than skipped, because a command that asked for an action nobody performed would otherwise
+ * report success.
+ */
+import { SessionTerminalHandoffGate, isAppearanceSettingsPatch } from '@robota-sdk/agent-framework';
+
+import type {
+  ICommandHostTerminalHandoff,
+  ICommandHostWorkspace,
+} from '@robota-sdk/agent-framework';
+import type {
+  ICommandResult,
+  TAppearanceSettingsPatch,
+  TCommandUiIntent,
+} from '@robota-sdk/agent-interface-command';
+import type { ITerminalHandoff } from '@robota-sdk/agent-interface-session';
+
+/** What a client-run command may use: this terminal's handoff and working directory. */
+export type TTuiClientCommandHost = ICommandHostTerminalHandoff & ICommandHostWorkspace;
+
+/**
+ * A command this terminal runs itself. Declared here rather than imported: the command package's
+ * `createTerminalClientCommands` produces objects of this shape, and this package does not depend on
+ * the command package.
+ */
+export interface ITuiClientCommand {
+  readonly name: string;
+  execute(host: TTuiClientCommandHost, args: string): ICommandResult | Promise<ICommandResult>;
+}
+
+/** The client-run commands, and how this terminal writes what they change. */
+export interface ITuiClientCommands {
+  readonly commands: readonly ITuiClientCommand[];
+  /** Writes the appearance keys of the user's settings; resolves when written. */
+  writeAppearanceSettings(patch: TAppearanceSettingsPatch): void | Promise<void>;
+}
+
+/** A client command's answer: the result to show, and the screens it asked this terminal to open. */
+export interface ITuiClientCommandOutcome {
+  /** Host actions and UI intents are consumed: this carries only message, success and data. */
+  readonly result: ICommandResult;
+  /** Empty unless the command succeeded and every host action was applied. */
+  readonly uiIntents: readonly TCommandUiIntent[];
+}
+
+const APPEARANCE_PATCH = 'appearance-settings-patch';
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function refused(message: string): ITuiClientCommandOutcome {
+  return { result: { success: false, message }, uiIntents: [] };
+}
+
+/** The client command named `name`, or undefined when there is none or no set was given. */
+export function findTuiClientCommand(
+  commands: ITuiClientCommands | undefined,
+  name: string,
+): ITuiClientCommand | undefined {
+  return commands?.commands.find((command) => command.name === name);
+}
+
+/**
+ * Runs a client command and applies what it asks for on this terminal.
+ *
+ * A failed result passes through unchanged: its actions were never requested to run. Every host
+ * action is checked before any is written, so a result that carries an invalid patch or an action
+ * this terminal cannot perform writes nothing and becomes an explicit failure. A command that throws
+ * rejects, as it does in the in-process session.
+ */
+export async function runTuiClientCommand(
+  command: ITuiClientCommand,
+  args: string,
+  host: TTuiClientCommandHost,
+  writers: Pick<ITuiClientCommands, 'writeAppearanceSettings'>,
+): Promise<ITuiClientCommandOutcome> {
+  const result = await command.execute(host, args);
+  if (!result.success) return { result, uiIntents: [] };
+
+  const patches: TAppearanceSettingsPatch[] = [];
+  for (const action of result.hostActions ?? []) {
+    if (action.type !== APPEARANCE_PATCH) {
+      return refused(`Cannot apply '${action.type}' on this terminal.`);
+    }
+    if (!isAppearanceSettingsPatch(action.patch)) {
+      return refused(`Failed to apply '${APPEARANCE_PATCH}': invalid appearance settings patch`);
+    }
+    patches.push(action.patch);
+  }
+
+  for (const patch of patches) {
+    try {
+      await writers.writeAppearanceSettings(patch);
+    } catch (error) {
+      return refused(`Failed to apply '${APPEARANCE_PATCH}': ${errorMessage(error)}`);
+    }
+  }
+
+  return {
+    result: {
+      message: result.message,
+      success: result.success,
+      ...(result.data !== undefined ? { data: result.data } : {}),
+    },
+    uiIntents: result.uiIntents ?? [],
+  };
+}
+
+/**
+ * The host a client command runs against: this terminal's own handoff, behind the same gate the
+ * in-process session puts in front of it (one handoff at a time, and a refusal instead of a hang
+ * when there is no interactive terminal). Build it once per attached terminal, so that exclusivity
+ * spans every command it runs.
+ *
+ * Without a handoff, `canHandoffTerminal()` is false and `/shell` and `/editor` take their refusal
+ * path. Commands run here were typed by the user at this terminal, so the invocation source is
+ * always `'user'`.
+ */
+export function createTuiClientCommandHost(options: {
+  readonly terminalHandoff: ITerminalHandoff | undefined;
+  readonly cwd: string;
+}): TTuiClientCommandHost {
+  const gate = new SessionTerminalHandoffGate(options.terminalHandoff);
+  const { cwd } = options;
+  return {
+    canHandoffTerminal: () => gate.canHandoffTerminal(),
+    runWithTerminal: (fn) => gate.runWithTerminal(fn),
+    getCwd: () => cwd,
+    getCommandInvocationSource: () => 'user',
+  };
+}

package/src/wire-tui-projection.ts

@@ -0,0 +1,136 @@
+/**
+ * Pure projections from session-protocol frames into what the TUI renders, for a terminal attached to
+ * a session over the wire. Kept apart from the channel so each is testable without a connection.
+ */
+
+import { OWNER_DRIVER_ID } from '@robota-sdk/agent-interface-session';
+
+import type { IHistoryEntry } from '@robota-sdk/agent-core';
+import type {
+  ICommand,
+  ICommandListEntry,
+  ICommandSkillListEntry,
+  ICommandSubcommandEntry,
+} from '@robota-sdk/agent-interface-command';
+import type { IWireHistoryEntry } from '@robota-sdk/agent-transport/client';
+
+/**
+ * The transcript names a prompt by the driver that sent it, and "You" for the operator. Over the wire
+ * this terminal is a driver the host named, so its own prompts are shown as the operator's.
+ */
+export function displayDriverId(
+  driverId: string | undefined,
+  ownDriverId: string | undefined,
+): string | undefined {
+  return driverId !== undefined && driverId === ownDriverId ? OWNER_DRIVER_ID : driverId;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Who this terminal is on the wire: the driver id the host gave it, and when it attached. The host
+ * numbers the terminals attached to it from one each time it starts, and a prompt keeps its driver id
+ * in the stored history, so an entry from before this terminal attached may carry the same id for
+ * another terminal. Only what this terminal could have sent is shown as the user's.
+ */
+export interface IOwnDriver {
+  readonly driverId: string;
+  /** Milliseconds since the epoch. */
+  readonly since: number;
+}
+
+/**
+ * A chat entry's `data` is the message itself, whose own `timestamp` also crossed as a string. Any
+ * ISO string is accepted: a resumed session sends strings for what was a `Date` in memory.
+ */
+function reviveChatMessage(data: unknown, ownDriverId: string | undefined): unknown {
+  if (!isRecord(data)) return data;
+  let revived = data;
+  if (typeof data['timestamp'] === 'string') {
+    revived = { ...revived, timestamp: new Date(data['timestamp']) };
+  }
+  const metadata = data['metadata'];
+  if (ownDriverId !== undefined && isRecord(metadata) && metadata['driverId'] === ownDriverId) {
+    revived = { ...revived, metadata: { ...metadata, driverId: OWNER_DRIVER_ID } };
+  }
+  return revived;
+}
+
+/**
+ * The session's history as the TUI holds it: timestamps back to `Date`s. Only a chat entry's `data`
+ * is a message; an event entry's is the event as recorded, and is left as it came.
+ */
+export function toHistoryEntries(
+  entries: readonly IWireHistoryEntry[],
+  own: IOwnDriver | undefined,
+): IHistoryEntry[] {
+  return entries.map((entry) => {
+    const timestamp = new Date(entry.timestamp);
+    if (entry.category !== 'chat' || entry.data === undefined) return { ...entry, timestamp };
+    const ownDriverId =
+      own !== undefined && timestamp.getTime() >= own.since ? own.driverId : undefined;
+    return { ...entry, timestamp, data: reviveChatMessage(entry.data, ownDriverId) };
+  });
+}
+
+/** A subcommand as the `/` menu offers it after its command's name. */
+function toSubcommand(subcommand: ICommandSubcommandEntry): ICommand {
+  return {
+    name: subcommand.name,
+    description: subcommand.description,
+    source: 'builtin',
+    ...(subcommand.displayName !== undefined ? { displayName: subcommand.displayName } : {}),
+    ...(subcommand.argumentHint !== undefined ? { argumentHint: subcommand.argumentHint } : {}),
+  };
+}
+
+/** What the `/` menu offers: the host's commands, then the skills a user may invoke. */
+export function toCommandCatalog(
+  commands: readonly ICommandListEntry[],
+  skills: readonly ICommandSkillListEntry[],
+): ICommand[] {
+  return [
+    ...commands.map((command): ICommand => ({
+      name: command.name,
+      description: command.description,
+      source: 'builtin',
+      modelInvocable: command.modelInvocable,
+      ...(command.displayName !== undefined ? { displayName: command.displayName } : {}),
+      ...(command.example !== undefined ? { example: command.example } : {}),
+      ...(command.argumentHint !== undefined ? { argumentHint: command.argumentHint } : {}),
+      ...(command.subcommands !== undefined && command.subcommands.length > 0
+        ? { subcommands: command.subcommands.map(toSubcommand) }
+        : {}),
+    })),
+    ...skills
+      .filter((skill) => skill.userInvocable)
+      .map((skill): ICommand => ({
+        name: skill.name,
+        description: skill.description,
+        source: skill.source,
+        modelInvocable: skill.modelInvocable,
+        userInvocable: skill.userInvocable,
+        ...(skill.argumentHint !== undefined ? { argumentHint: skill.argumentHint } : {}),
+        ...(skill.context !== undefined ? { context: skill.context } : {}),
+        ...(skill.agent !== undefined ? { agent: skill.agent } : {}),
+      })),
+  ];
+}
+
+/** A command's subcommands, found by name as the in-process command registry finds them. */
+export function findSubcommands(catalog: readonly ICommand[], commandName: string): ICommand[] {
+  const lower = commandName.toLowerCase();
+  const command = catalog.find(
+    (entry) => entry.name.toLowerCase() === lower && entry.subcommands !== undefined,
+  );
+  return command?.subcommands ?? [];
+}
+
+/** The same prefix match the in-process command registry applies. */
+export function filterCommandCatalog(catalog: readonly ICommand[], filter?: string): ICommand[] {
+  if (!filter) return [...catalog];
+  const lower = filter.toLowerCase();
+  return catalog.filter((command) => command.name.toLowerCase().startsWith(lower));
+}