@robota-sdk/agent-ui-terminal 3.0.0-beta.100

package/src/__tests__/pty/screen-reader-mode.ptytest.ts

@@ -0,0 +1,228 @@
+/**
+ * CLI-2004 TC-11 / TC-12 — screen-reader mode on the BUILT CLI binary, in a real PTY.
+ *
+ * This is the only level at which the claim can be checked. A screen reader has no `aria-live`: the
+ * ONLY channel to it is which bytes land in the terminal buffer, so a component test asserting on a
+ * frame is asserting on something the reader never sees. Here the transcript is the evidence.
+ *
+ * TC-11 pairs the positive with the DEFAULT-OFF proof deliberately: the same fixture, the same
+ * binary, one flag apart. Without the negative half, "no box-drawing characters" would also pass if
+ * the fixture happened to render none.
+ *
+ * Runs under `test:pty` against the built CLI (`pnpm build` first).
+ */
+
+import { mkdtempSync, rmSync, realpathSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+
+import { spawnTui, writeTuiProviderSettings } from './pty-driver.js';
+
+import type { IPtySession } from './pty-driver.js';
+
+const FIXTURES = join(dirname(fileURLToPath(import.meta.url)), 'fixtures');
+const REPLAY_FIXTURE = join(FIXTURES, 'replay-conversation.jsonl');
+
+/** Every box-drawing glyph the TUI draws chrome with, in one class. */
+const BOX_DRAWING = /[│─╭╮╰╯┌┐└┘]/u;
+
+/** OSC 133 prompt-start — the mark a terminal turns into jump-to-previous-turn. */
+const OSC_133_PROMPT_START = '\x1b]133;A';
+
+/** How long one `waitFor` may block, and how long a whole case may take, on a loaded CI runner. */
+const WAIT_MS = 30_000;
+const CASE_TIMEOUT_MS = 90_000;
+
+/**
+ * Mark the isolated HOME as already onboarded. TC-12 asserts on the FIRST line the process writes,
+ * and the first-run welcome is a separate concern with its own onboarding copy — a returning user
+ * is the case where "the first line confirms the mode" is the claim being made.
+ */
+function markOnboarded(homeDir: string): void {
+  writeFileSync(join(homeDir, 'state', 'onboarded'), new Date().toISOString());
+}
+
+describe('CLI-2004 screen-reader mode through the real binary', () => {
+  let projectDir: string;
+  let session: IPtySession | undefined;
+
+  beforeEach(() => {
+    projectDir = realpathSync(mkdtempSync(join(tmpdir(), 'agent-screenreader-pty-')));
+    writeTuiProviderSettings(projectDir);
+  });
+
+  afterEach(async () => {
+    await session?.disposeAsync();
+    session = undefined;
+    rmSync(projectDir, { recursive: true, force: true });
+  });
+
+  it(
+    'TC-11: --screen-reader emits no box-drawing chrome, role labels, and OSC 133 marks',
+    async () => {
+      session = spawnTui({
+        projectDir,
+        homeDir: join(projectDir, 'home'),
+        args: ['--session-log', REPLAY_FIXTURE, '--screen-reader'],
+        // The waits are exercised by their own unit test; a real one here only slows the fixture.
+        env: { PRODUCT_SCREEN_READER_STARTUP_QUIET_MS: '0' },
+      });
+
+      await session.waitFor(/Type a message or \/help/, WAIT_MS);
+      await session.sendKeys('hello');
+      await session.pressEnter();
+      await session.waitFor(/REPLAYED_ANSWER_42/, WAIT_MS);
+      await session.waitFor(/Type a message or \/help/, WAIT_MS);
+
+      const snapshot = session.snapshot();
+      const raw = session.raw();
+
+      // The transcript is labelled by ROLE, not by vendor.
+      expect(snapshot).toContain('assistant:');
+      expect(snapshot).toContain('you:');
+      expect(snapshot).toContain('REPLAYED_ANSWER_42');
+
+      // Not one box-drawing character reaches the terminal.
+      expect(snapshot).not.toMatch(BOX_DRAWING);
+
+      // The turn boundary is marked for terminals that navigate by it.
+      expect(raw).toContain(OSC_133_PROMPT_START);
+    },
+    CASE_TIMEOUT_MS,
+  );
+});
+
+describe('CLI-2004 the same fixture with the mode off', () => {
+  let projectDir: string;
+  let session: IPtySession | undefined;
+
+  beforeEach(() => {
+    projectDir = realpathSync(mkdtempSync(join(tmpdir(), 'agent-screenreader-pty-')));
+    writeTuiProviderSettings(projectDir);
+  });
+
+  afterEach(async () => {
+    await session?.disposeAsync();
+    session = undefined;
+    rmSync(projectDir, { recursive: true, force: true });
+  });
+
+  it(
+    'TC-11: the SAME fixture without the flag still renders the bordered UI (default-off)',
+    async () => {
+      session = spawnTui({
+        projectDir,
+        homeDir: join(projectDir, 'home'),
+        args: ['--session-log', REPLAY_FIXTURE],
+        env: { PRODUCT_TURN_MARKS: '1' },
+      });
+
+      await session.waitFor(/Type a message or \/help/, WAIT_MS);
+      await session.sendKeys('hello');
+      await session.pressEnter();
+      await session.waitFor(/REPLAYED_ANSWER_42/, WAIT_MS);
+
+      const snapshot = session.snapshot();
+
+      expect(snapshot).toMatch(BOX_DRAWING);
+      expect(snapshot).toContain('You:');
+      expect(snapshot).not.toContain('[Screen reader mode:');
+      expect(session.raw()).not.toContain(OSC_133_PROMPT_START);
+    },
+    CASE_TIMEOUT_MS,
+  );
+});
+
+describe('configured turn-mark override through the real binary', () => {
+  let projectDir: string;
+  let session: IPtySession | undefined;
+
+  beforeEach(() => {
+    projectDir = realpathSync(mkdtempSync(join(tmpdir(), 'agent-turn-marks-pty-')));
+    writeTuiProviderSettings(projectDir);
+  });
+
+  afterEach(async () => {
+    await session?.disposeAsync();
+    rmSync(projectDir, { recursive: true, force: true });
+  });
+
+  for (const [label, env, expected] of [
+    ['WezTerm default', { TERM_PROGRAM: 'WezTerm' }, false],
+    ['WezTerm opt-in', { TERM_PROGRAM: 'WezTerm', PRODUCT_TURN_MARKS: '1' }, true],
+    ['TTY kill switch', { PRODUCT_TURN_MARKS: '0' }, false],
+  ] as const) {
+    it(
+      `${label} ${expected ? 'emits' : 'withholds'} OSC 133`,
+      async () => {
+        session = spawnTui({
+          projectDir,
+          homeDir: join(projectDir, 'home'),
+          args: ['--screen-reader'],
+          env: { ...env, PRODUCT_SCREEN_READER_STARTUP_QUIET_MS: '0' },
+        });
+        await session.waitFor(/Type a message or \/help/, WAIT_MS);
+        expect(session.raw().includes(OSC_133_PROMPT_START)).toBe(expected);
+      },
+      CASE_TIMEOUT_MS,
+    );
+  }
+});
+
+describe('CLI-2004 the channel the mode was enabled through', () => {
+  let projectDir: string;
+  let session: IPtySession | undefined;
+
+  beforeEach(() => {
+    projectDir = realpathSync(mkdtempSync(join(tmpdir(), 'agent-screenreader-pty-')));
+    writeTuiProviderSettings(projectDir);
+  });
+
+  afterEach(async () => {
+    await session?.disposeAsync();
+    session = undefined;
+    rmSync(projectDir, { recursive: true, force: true });
+  });
+
+  it(
+    'TC-12: PRODUCT_SCREEN_READER=1 with no flag announces the env channel first',
+    async () => {
+      markOnboarded(join(projectDir, 'home'));
+      session = spawnTui({
+        projectDir,
+        homeDir: join(projectDir, 'home'),
+        env: { PRODUCT_SCREEN_READER: '1', PRODUCT_SCREEN_READER_STARTUP_QUIET_MS: '0' },
+      });
+
+      await session.waitFor(/Type a message or \/help/, WAIT_MS);
+
+      expect(session.snapshot().trimStart().startsWith('[Screen reader mode: on via env]')).toBe(
+        true,
+      );
+    },
+    CASE_TIMEOUT_MS,
+  );
+
+  it(
+    'TC-12: --screen-reader beats PRODUCT_SCREEN_READER=0 and says so',
+    async () => {
+      markOnboarded(join(projectDir, 'home'));
+      session = spawnTui({
+        projectDir,
+        homeDir: join(projectDir, 'home'),
+        args: ['--screen-reader'],
+        env: { PRODUCT_SCREEN_READER: '0', PRODUCT_SCREEN_READER_STARTUP_QUIET_MS: '0' },
+      });
+
+      await session.waitFor(/Type a message or \/help/, WAIT_MS);
+
+      expect(session.snapshot().trimStart().startsWith('[Screen reader mode: on via flag]')).toBe(
+        true,
+      );
+    },
+    CASE_TIMEOUT_MS,
+  );
+});

package/src/__tests__/pty/session-attach.ptytest.ts

@@ -0,0 +1,182 @@
+/**
+ * `the CLI session attach command` end to end on the BUILT binary, in a real terminal: start a supervised
+ * session, attach and confirm on the controlling terminal, submit, detach with `/exit`, see it still
+ * running, attach again read-only and find the earlier prompt, detach with Ctrl-C, peek from
+ * `session view` and land back in the view, then stop it.
+ *
+ * The provider points at a closed local port, so the submitted turn fails without any network call
+ * leaving this machine. `XDG_RUNTIME_DIR` is a short directory so the control socket path fits.
+ *
+ * Runs under `test:pty` against the built CLI (`pnpm --filter @robota-sdk/agent-cli build` first).
+ */
+
+import { execFileSync, spawnSync } from 'node:child_process';
+import { mkdirSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { afterEach, describe, expect, it } from 'vitest';
+
+import { createIsolatedHome, createPtyEnv } from './isolated-home.js';
+import { spawnPty } from './spawn-pty.js';
+
+import type { IPtyRunSession } from './spawn-pty.js';
+
+const REPO_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '../../../../..');
+const AGENT_BIN = join(REPO_ROOT, 'packages/agent-cli/bin/agent.cjs');
+const WAIT_MS = 20_000;
+
+const cleanups: (() => void)[] = [];
+afterEach(() => {
+  for (const cleanup of cleanups.splice(0).reverse()) cleanup();
+});
+
+function agent(
+  args: readonly string[],
+  cwd: string,
+  env: NodeJS.ProcessEnv,
+): { status: number | null; stdout: string; stderr: string } {
+  const result = spawnSync(process.execPath, [AGENT_BIN, ...args], {
+    cwd,
+    env,
+    encoding: 'utf8',
+    timeout: WAIT_MS,
+  });
+  return { status: result.status, stdout: result.stdout, stderr: result.stderr };
+}
+
+function attach(id: string, cwd: string, env: NodeJS.ProcessEnv, observe = false): IPtyRunSession {
+  const session = spawnPty({
+    command: process.execPath,
+    args: [AGENT_BIN, 'session', 'attach', id, ...(observe ? ['--observe'] : [])],
+    cwd,
+    env,
+  });
+  cleanups.push(() => session.dispose());
+  return session;
+}
+
+describe('the CLI session attach command on the built binary', () => {
+  it('attaches, submits, detaches without stopping the session, and re-attaches', async () => {
+    const project = realpathSync(mkdtempSync(join(tmpdir(), 'agent-attach-pty-')));
+    // `/tmp` rather than the platform temp directory: the control socket path must stay short.
+    const runtime = mkdtempSync('/tmp/rsa-');
+    cleanups.push(() => rmSync(project, { recursive: true, force: true }));
+    cleanups.push(() => rmSync(runtime, { recursive: true, force: true }));
+    const home = createIsolatedHome();
+    const stateRoot = join(runtime, 's');
+    mkdirSync(stateRoot, { recursive: true });
+    writeFileSync(join(stateRoot, 'onboarded'), new Date().toISOString(), 'utf8');
+    writeFileSync(
+      join(stateRoot, 'settings.json'),
+      JSON.stringify({
+        currentProvider: 'anthropic',
+        providers: {
+          anthropic: {
+            type: 'anthropic',
+            model: 'claude-test-model',
+            apiKey: 'pty-dummy-key',
+            baseURL: 'http://127.0.0.1:9',
+          },
+        },
+      }),
+      'utf8',
+    );
+    const env = createPtyEnv({
+      HOME: home,
+      XDG_RUNTIME_DIR: runtime,
+      PRODUCT_USER_STATE_DIR: stateRoot,
+      PRODUCT_CACHE_DIR: join(runtime, 'c'),
+      PRODUCT_LOG_DIR: join(runtime, 'l'),
+    });
+
+    // Workspace trust is recorded for a repository, as a user would grant it before a background start.
+    const git = (...args: string[]): void => {
+      execFileSync('git', args, { cwd: project, env, stdio: ['ignore', 'ignore', 'pipe'] });
+    };
+    git('init', '-q', '-b', 'main');
+    git('config', 'user.name', 'Attach Fixture');
+    git('config', 'user.email', 'attach@example.invalid');
+    writeFileSync(join(project, 'README.md'), 'fixture\n');
+    git('add', '--', 'README.md');
+    git('commit', '-q', '-m', 'chore: fixture');
+    const trusted = agent(['trust', '--yes'], project, env);
+    expect(trusted.status, trusted.stderr).toBe(0);
+    const started = agent(
+      ['session', 'start', '--background', '--name', 'pty-attach'],
+      project,
+      env,
+    );
+    expect(started.status, started.stderr).toBe(0);
+    const id = /Supervised session: ([0-9a-f-]{36})/u.exec(started.stdout)?.[1];
+    expect(id).toBeDefined();
+    cleanups.push(() => {
+      agent(['session', 'stop', id!], project, env);
+    });
+
+    const drive = attach(id!, project, env);
+    await drive.waitFor('Attach? Type yes', WAIT_MS);
+    expect(drive.snapshot()).toContain('drive (send prompts, answer its questions)');
+    await drive.sendKeys('yes');
+    await drive.pressEnter();
+    await drive.waitFor('Type a message or /help', WAIT_MS);
+    await drive.sendKeys('hello from the pty');
+    await drive.pressEnter();
+    await drive.waitFor('Last turn failed', WAIT_MS);
+    await drive.sendKeys('/exit');
+    await drive.pressEnter();
+    expect(await drive.expectExit(WAIT_MS)).toBe(0);
+
+    const listed = agent(['session', 'list', '--format', 'json'], project, env);
+    const supervised = (
+      JSON.parse(listed.stdout) as {
+        supervised: { sessions: { id: string; liveness: string; control: string }[] };
+      }
+    ).supervised.sessions;
+    expect(supervised).toContainEqual(
+      expect.objectContaining({ id, liveness: 'alive', control: 'available' }),
+    );
+
+    const observe = attach(id!, project, env, true);
+    await observe.waitFor('Attach? Type yes', WAIT_MS);
+    expect(observe.snapshot()).toContain('observe (read only)');
+    await observe.sendKeys('yes');
+    await observe.pressEnter();
+    await observe.waitFor('Observing — read only', WAIT_MS);
+    await observe.waitFor('hello from the pty', WAIT_MS);
+    observe.write('\x03');
+    expect(await observe.expectExit(WAIT_MS)).toBe(0);
+    const afterObserve = agent(['session', 'list', '--format', 'json'], project, env);
+    const remaining = (
+      JSON.parse(afterObserve.stdout) as {
+        supervised: { sessions: { id: string; liveness: string; control: string }[] };
+      }
+    ).supervised.sessions;
+    expect(remaining).toContainEqual(
+      expect.objectContaining({ id, liveness: 'alive', control: 'available' }),
+    );
+
+    // From the session view: peek at the row, confirm there, detach, and land back in the view.
+    const view = spawnPty({
+      command: process.execPath,
+      args: [AGENT_BIN, 'session', 'view'],
+      cwd: project,
+      env,
+    });
+    cleanups.push(() => view.dispose());
+    await view.waitFor('a Attach  p Peek', WAIT_MS);
+    view.write('p');
+    await view.waitFor('to observe (read only)?', WAIT_MS);
+    view.write('y');
+    await view.waitFor('Observing — read only', WAIT_MS);
+    await view.waitFor('hello from the pty', WAIT_MS);
+    const beforeDetach = view.outputOffset();
+    view.write('\x1d');
+    await view.waitForSince(beforeDetach, 'Background sessions across projects', WAIT_MS);
+    view.write('q');
+    expect(await view.expectExit(WAIT_MS)).toBe(0);
+
+    expect(agent(['session', 'stop', id!], project, env).status).toBe(0);
+  }, 120_000);
+});

package/src/__tests__/pty/settings-screen.ptytest.ts

@@ -0,0 +1,49 @@
+/**
+ * CMD-004 Phase 2 Stage C (TC-04): `/settings` still opens the settings screen — now rendered from
+ * the requester-routed `ui_intent` session event (the legacy `settings-tui-requested` effect
+ * branch is deleted from the TUI). Observed through a real PTY against the BUILT CLI binary
+ * (`pnpm --filter @robota-sdk/agent-cli build`).
+ */
+
+import { mkdtempSync, rmSync, realpathSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+
+import { spawnTui, writeTuiProviderSettings } from './pty-driver.js';
+
+import type { IPtySession } from './pty-driver.js';
+
+describe('/settings opens the settings screen via ui_intent (CMD-004 Stage C)', () => {
+  let projectDir: string;
+  let session: IPtySession | undefined;
+
+  beforeEach(() => {
+    projectDir = realpathSync(mkdtempSync(join(tmpdir(), 'agent-settings-pty-')));
+    writeTuiProviderSettings(projectDir);
+  });
+
+  afterEach(async () => {
+    await session?.disposeAsync();
+    session = undefined;
+    rmSync(projectDir, { recursive: true, force: true });
+  });
+
+  it('renders the transports settings screen and Esc returns to the prompt', async () => {
+    session = spawnTui({ projectDir, homeDir: join(projectDir, 'home') });
+    await session.waitFor(/Type a message or \/help/);
+
+    await session.sendKeys('/settings');
+    await session.pressEnter();
+
+    // The settings screen opened — from the ui_intent event, not a legacy effect branch.
+    await session.waitFor(/Settings › Transports/, 20_000);
+    expect(session.snapshot()).toContain('Settings › Transports');
+
+    // Esc closes the screen and returns to the idle prompt.
+    const mark = session.outputOffset();
+    session.pressEscape();
+    await session.waitForSince(mark, /Type a message or \/help/, 20_000);
+  }, 60_000);
+});

package/src/__tests__/pty/spawn-pty.test.ts

@@ -0,0 +1,120 @@
+/**
+ * TEST-007: self-test for the TUI-owned PTY harness (relocated internally by BOUNDARY-2655).
+ *
+ * Drives a trivial process (no fixture needed) through `spawnPty` to pin the harness contract:
+ * `waitFor` resolves on a printed marker, `expectExit` returns the real exit code, and
+ * `snapshot()`/`raw()` capture output. The terminal-handoff suites (in agent-ui-terminal) are the
+ * harness's real-world consumers; this guards the harness itself.
+ *
+ * HARNESS-025 adds the HOME-isolation contract: a PTY child must never receive the developer's real
+ * `HOME`, or the suite silently depends on whatever is in that home directory.
+ */
+import { existsSync, readdirSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+
+import { afterEach, describe, expect, it } from 'vitest';
+
+import { createIsolatedHome, createPtyEnv } from './isolated-home.js';
+import { spawnPty } from './spawn-pty.js';
+
+import type { IPtyRunSession } from './spawn-pty.js';
+
+const PACKAGE_DIR = fileURLToPath(new URL('../../..', import.meta.url));
+const sessions: IPtyRunSession[] = [];
+
+afterEach(() => {
+  for (const session of sessions.splice(0)) session.dispose();
+});
+
+describe('spawnPty harness self-test', () => {
+  it('waits for a marker and reports the real exit code', async () => {
+    const session = spawnPty({
+      command: process.execPath,
+      args: ['-e', 'process.stdout.write("MARKER_OK\\n"); setTimeout(() => process.exit(3), 50);'],
+      cwd: PACKAGE_DIR,
+      env: createPtyEnv(),
+    });
+    sessions.push(session);
+
+    await session.waitFor('MARKER_OK', 5_000);
+    expect(session.snapshot()).toContain('MARKER_OK');
+    expect(await session.expectExit(5_000)).toBe(3);
+  });
+
+  it('paces sent keys and reads them back from the child', async () => {
+    const session = spawnPty({
+      command: 'sh',
+      args: ['-c', 'IFS= read -r line; printf "ECHO:[%s]\\n" "$line"'],
+      cwd: PACKAGE_DIR,
+      env: createPtyEnv(),
+    });
+    sessions.push(session);
+
+    await session.sendKeys('abc', 10);
+    session.write('\r');
+    await session.waitFor('ECHO:[abc]', 5_000);
+    expect(await session.expectExit(5_000)).toBe(0);
+  });
+});
+
+describe('PTY HOME isolation', () => {
+  /** Ask the child to report the HOME it actually sees, so the assertion is on the child's view. */
+  function spawnHomeReporter(env?: NodeJS.ProcessEnv): IPtyRunSession {
+    const session = spawnPty({
+      command: 'sh',
+      args: ['-c', 'printf "CHILD_HOME:[%s]\\n" "$HOME"'],
+      cwd: PACKAGE_DIR,
+      ...(env ? { env } : {}),
+    });
+    sessions.push(session);
+    return session;
+  }
+
+  function readReportedHome(snapshot: string): string {
+    const match = /CHILD_HOME:\[([^\]]*)\]/.exec(snapshot);
+    if (match?.[1] === undefined) throw new Error(`child never reported HOME:\n${snapshot}`);
+    return match[1];
+  }
+
+  it('does not hand the real HOME to a child when no env is supplied', async () => {
+    const realHome = process.env['HOME'];
+    expect(
+      realHome,
+      'the test host must have a HOME for this assertion to mean anything',
+    ).toBeTruthy();
+
+    const session = spawnHomeReporter();
+    await session.waitFor('CHILD_HOME:[', 5_000);
+    await session.expectExit(5_000);
+
+    const childHome = readReportedHome(session.snapshot());
+    expect(childHome).not.toBe(realHome);
+    expect(childHome.startsWith(tmpdir())).toBe(true);
+  });
+
+  it('hands the child the isolated HOME built by createPtyEnv', async () => {
+    const env = createPtyEnv();
+    const session = spawnHomeReporter(env);
+    await session.waitFor('CHILD_HOME:[', 5_000);
+    await session.expectExit(5_000);
+
+    expect(readReportedHome(session.snapshot())).toBe(env['HOME']);
+    expect(env['HOME']).not.toBe(process.env['HOME']);
+  });
+
+  it('creates an EMPTY home directory, so no user config can leak in', () => {
+    const home = createIsolatedHome();
+    expect(existsSync(home)).toBe(true);
+    expect(readdirSync(home)).toEqual([]);
+    expect(home).not.toBe(process.env['HOME']);
+  });
+
+  it('lets an override customize the env without reintroducing the real HOME', () => {
+    const env = createPtyEnv({ EDITOR: 'sh /tmp/fake-editor.sh' });
+    expect(env['EDITOR']).toBe('sh /tmp/fake-editor.sh');
+    expect(env['TERM']).toBe('xterm-256color');
+    expect(env['PATH']).toBe(process.env['PATH']);
+    expect(env['HOME']).not.toBe(process.env['HOME']);
+  });
+});