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

package/src/__tests__/pty/flow-2006-deep-link.ptytest.ts

@@ -0,0 +1,320 @@
+/**
+ * FLOW-2006 TC-09 — the three user-execution scenarios on the BUILT binary.
+ *
+ * Scenario 1 runs in a real PTY: a link opens the trusted fixture repository with the prompt in the
+ * composer, unsent, labelled as external, and only Enter submits it. Scenarios 2 and 3 are process
+ * runs: every malformed or configuration-bearing link, and every untrusted or unrecorded target, is
+ * refused on stderr with a non-zero exit and no session.
+ *
+ * Runs under `test:pty` against the built CLI (`pnpm --filter @robota-sdk/agent-cli build` first).
+ */
+
+import { execFileSync, spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import {
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  readdirSync,
+  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, beforeEach, describe, expect, it } from 'vitest';
+
+import { spawnTui } from './pty-driver.js';
+
+import type { IPtySession } from './pty-driver.js';
+
+const REPO_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '../../../../..');
+const AGENT_BIN = join(REPO_ROOT, 'packages/agent-cli/bin/agent.cjs');
+const CLI_NAME = 'fixture-agent';
+const PROTOCOL_SCHEME = 'fixture-agent';
+const WAIT_MS = 20_000;
+const CASE_TIMEOUT_MS = 120_000;
+const PROMPT = 'Summarize the README in one sentence';
+
+interface IFixture {
+  root: string;
+  home: string;
+  trusted: string;
+  untrusted: string;
+  elsewhere: string;
+  userStateRoot: string;
+  env: NodeJS.ProcessEnv;
+}
+
+function writeProviderSettings(home: string): void {
+  const dir = join(home, 'state');
+  mkdirSync(dir, { recursive: true });
+  // Skip the first-run welcome: it is an onboarding screen, not what this scenario observes.
+  writeFileSync(join(dir, 'onboarded'), new Date().toISOString(), 'utf8');
+  writeFileSync(
+    join(dir, 'settings.json'),
+    JSON.stringify({
+      currentProvider: 'anthropic',
+      providers: {
+        anthropic: { type: 'anthropic', model: 'claude-test-model', apiKey: 'pty-dummy-key' },
+      },
+    }),
+    'utf8',
+  );
+}
+
+function initRepo(path: string, env: NodeJS.ProcessEnv): void {
+  mkdirSync(path, { recursive: true });
+  const run = (...args: string[]): void => {
+    execFileSync('git', args, { cwd: path, env, stdio: ['ignore', 'ignore', 'pipe'] });
+  };
+  run('init', '-q', '-b', 'main');
+  run('config', 'user.name', 'Scenario Fixture');
+  run('config', 'user.email', 'scenario@example.invalid');
+  writeFileSync(join(path, 'README.md'), 'fixture\n');
+  run('add', '--', 'README.md');
+  run('commit', '-q', '-m', 'chore: fixture');
+}
+
+function makeFixture(): IFixture {
+  const root = realpathSync(mkdtempSync(join(tmpdir(), 'agent-flow2006-')));
+  const home = join(root, 'home');
+  mkdirSync(home, { recursive: true });
+  writeProviderSettings(home);
+  const userStateRoot = join(home, 'state');
+  const env: NodeJS.ProcessEnv = {
+    PATH: process.env['PATH'] ?? '',
+    HOME: home,
+    PRODUCT_ID: CLI_NAME,
+    PRODUCT_DISPLAY_NAME: 'Fixture Agent',
+    PRODUCT_CLI_NAME: CLI_NAME,
+    PRODUCT_ENV_PREFIX: 'FIXTURE_AGENT_',
+    PRODUCT_PACKAGE_SCOPE: '@fixture-agent',
+    PRODUCT_APP_ID: 'org.example.fixture-agent',
+    PRODUCT_PROTOCOL_SCHEME: PROTOCOL_SCHEME,
+    PRODUCT_TELEMETRY_SERVICE_NAME: 'fixture-agent',
+    PRODUCT_DAEMON_NAMESPACE: 'fixture-agent-daemon',
+    PRODUCT_DESKTOP_EXECUTABLE: 'fixture-robota',
+    PRODUCT_MCP_CLIENT_NAME: 'fixture-agent-client',
+    PRODUCT_MODEL_TOOL_PREFIX: 'fixture_agent_command_',
+    PRODUCT_PROMPT_TAG: 'fixture_agent_references',
+    PRODUCT_EDITOR_TEMP_PREFIX: 'fixture-agent-editor-',
+    PRODUCT_USER_STATE_DIR: userStateRoot,
+    PRODUCT_PROJECT_STATE_DIR: '.fixture-agent',
+    PRODUCT_CACHE_DIR: join(userStateRoot, 'cache'),
+    PRODUCT_LOG_DIR: join(userStateRoot, 'logs'),
+    PRODUCT_BROWSER_NAMESPACE: 'fixture-agent-browser',
+    PRODUCT_BROWSER_CREDENTIAL_DATABASE: 'fixture-agent-credentials',
+    PRODUCT_CREDENTIAL_SERVICE: 'org.example.fixture-agent.credentials',
+    PRODUCT_CRYPTO_NAMESPACE: 'fixture-agent-crypto',
+    SECURITY_MASTER_KEY_DERIVATION_PATH: '[123,0]',
+    TERM: 'xterm-256color',
+    GIT_CONFIG_NOSYSTEM: '1',
+    GIT_CONFIG_GLOBAL: join(home, 'gitconfig'),
+  };
+  writeFileSync(join(home, 'gitconfig'), '[commit]\n\tgpgsign = false\n');
+  const fixture: IFixture = {
+    root,
+    home,
+    trusted: join(root, 'trusted'),
+    untrusted: join(root, 'untrusted'),
+    elsewhere: join(root, 'elsewhere'),
+    userStateRoot,
+    env,
+  };
+  initRepo(fixture.trusted, env);
+  initRepo(fixture.untrusted, env);
+  mkdirSync(fixture.elsewhere, { recursive: true });
+  // Grant trust to the one repository a link is allowed to open.
+  const granted = spawnSync(process.execPath, [AGENT_BIN, 'trust', '--yes'], {
+    cwd: fixture.trusted,
+    env,
+    encoding: 'utf8',
+  });
+  if (granted.status !== 0) throw new Error(`trust --yes failed: ${granted.stderr}`);
+  return fixture;
+}
+
+function link(fixture: IFixture, extra = ''): string {
+  return `${PROTOCOL_SCHEME}://open?v=1&prompt=${encodeURIComponent(PROMPT)}&cwd=${fixture.trusted}${extra}`;
+}
+
+/** Run the fixture CLI's `open` command as a process, headless — used for the refusal scenarios. */
+function openHeadless(
+  fixture: IFixture,
+  url: string,
+  cwd = fixture.elsewhere,
+): ReturnType<typeof spawnSync> {
+  return spawnSync(process.execPath, [AGENT_BIN, 'open', url], {
+    cwd,
+    env: { ...fixture.env, TERM: 'dumb' },
+    encoding: 'utf8',
+    timeout: 60_000,
+  });
+}
+
+/**
+ * What an interactive session leaves behind under HOME: one `peers/*.peer.json` per run. A refusal
+ * that started no session leaves this listing untouched, which is how the refusal scenarios prove
+ * "no session was started" without watching the process.
+ */
+function sessionRecords(home: string): readonly string[] {
+  try {
+    return readdirSync(join(home, 'state', 'peers')).sort();
+  } catch {
+    return [];
+  }
+}
+
+/** The trust store's bytes — a refused link must not add, remove or touch a grant. */
+function trustStoreDigest(home: string): string {
+  return createHash('sha256')
+    .update(readFileSync(join(home, 'state', 'workspace-trust.json')))
+    .digest('hex');
+}
+
+/**
+ * Every malformed or configuration-bearing link, each paired with the word its refusal must name —
+ * the FIRST rule it breaks, so a refusal that merely says the link is invalid fails the case.
+ */
+function malformedLinks(fixture: IFixture): readonly (readonly [string, string])[] {
+  return [
+    [link(fixture, '&provider=anthropic'), 'provider'],
+    [link(fixture, `&prompt=${encodeURIComponent('second')}`), 'more than once'],
+    [`${PROTOCOL_SCHEME}://open?prompt=hi&cwd=${fixture.trusted}`, 'no `v`'],
+    [`${PROTOCOL_SCHEME}://open?v=2&prompt=hi&cwd=${fixture.trusted}`, 'version 1'],
+    [
+      `${PROTOCOL_SCHEME}://open?v=1&prompt=${encodeURIComponent('/mode bypassPermissions')}&cwd=${fixture.trusted}`,
+      'not a command',
+    ],
+    [`${PROTOCOL_SCHEME}://open?v=1&prompt=hi&cwd=relative/path`, 'absolute'],
+    [`${PROTOCOL_SCHEME}://open?v=1&prompt=hi&cwd=${fixture.trusted}/../untrusted`, '`..`'],
+    [`${PROTOCOL_SCHEME}://open?v=1&prompt=hi&cwd=${join(fixture.root, 'absent')}`, 'does not exist'],
+  ];
+}
+
+describe('configured open deep link through the CLI binary (FLOW-2006 TC-09)', () => {
+  let fixture: IFixture | undefined;
+  let session: IPtySession | undefined;
+
+  beforeEach(() => {
+    fixture = makeFixture();
+  });
+
+  afterEach(async () => {
+    await session?.disposeAsync();
+    session = undefined;
+    if (fixture) rmSync(fixture.root, { recursive: true, force: true });
+    fixture = undefined;
+  });
+
+  it(
+    'Scenario 1: the link opens the trusted repository with the prompt prefilled, inert and labelled',
+    async () => {
+      const current = fixture;
+      if (!current) throw new Error('fixture');
+      session = spawnTui({
+        projectDir: current.elsewhere,
+        homeDir: current.home,
+        args: ['open', link(current), '--name', 'flow2006'],
+        env: current.env as Record<string, string>,
+      });
+
+      // The PREFILLED TEXT is the arrival signal, not the empty-composer placeholder (which never
+      // renders once there is text) and not `Idle` or the notice — both of those are already on the
+      // screen one frame before the composer itself is drawn.
+      await session.waitFor(new RegExp(PROMPT), WAIT_MS);
+      await session.waitFor(/Idle/, WAIT_MS);
+      const first = session.snapshot();
+      // The prompt is in the composer, the provenance is visible, and nothing was sent.
+      expect(first).toContain(PROMPT);
+      expect(first).toContain('Prompt from an external link');
+      expect(first).not.toMatch(/Thinking|Interrupting/);
+      // The link changed the directory: the status line names the fixture repository's branch.
+      expect(first).toContain('git: main');
+
+      // Enter submits exactly that text: it leaves the composer and becomes the user message.
+      const since = session.outputOffset();
+      await session.pressEnter();
+      await session.waitForSince(since, new RegExp(PROMPT), WAIT_MS);
+
+      const run = spawnSync('git', ['log', '--oneline'], {
+        cwd: current.trusted,
+        env: current.env,
+        encoding: 'utf8',
+      });
+      expect(run.stdout.trim().split('\n')).toHaveLength(1);
+    },
+    CASE_TIMEOUT_MS,
+  );
+
+  it(
+    'Scenario 2: every malformed or configuration-bearing link is refused with no session',
+    () => {
+      const current = fixture;
+      if (!current) throw new Error('fixture');
+      const recordsBefore = sessionRecords(current.home);
+      const settingsBefore = readFileSync(join(current.userStateRoot, 'settings.json'), 'utf8');
+      const cases = malformedLinks(current);
+      for (const [url, expected] of cases) {
+        const result = openHeadless(current, url);
+        expect(result.status, url).toBe(1);
+        expect(`${result.stderr}`, url).toContain(expected);
+        expect(`${result.stdout}`, url).not.toContain('Type a message');
+      }
+      // A SECOND LINK after the first is refused — the argv-appending shape the platforms document.
+      const twoArgs = spawnSync(
+        process.execPath,
+        [AGENT_BIN, 'open', link(current), link(current)],
+        {
+          cwd: current.elsewhere,
+          env: { ...current.env, TERM: 'dumb' },
+          encoding: 'utf8',
+        },
+      );
+      expect(twoArgs.status).toBe(1);
+      expect(`${twoArgs.stderr}`).toContain('exactly one link');
+
+      // Nothing was started and nothing was configured: no session record appeared, and the
+      // settings the `/mode bypassPermissions` link tried to reach are byte-identical.
+      expect(sessionRecords(current.home)).toEqual(recordsBefore);
+      expect(readFileSync(join(current.userStateRoot, 'settings.json'), 'utf8')).toBe(
+        settingsBefore,
+      );
+    },
+    CASE_TIMEOUT_MS,
+  );
+
+  it(
+    'Scenario 3: an untrusted directory and an unrecorded slug are refused, and nothing is cloned',
+    () => {
+      const current = fixture;
+      if (!current) throw new Error('fixture');
+      const digestBefore = trustStoreDigest(current.home);
+      const untrusted = openHeadless(
+        current,
+        `${PROTOCOL_SCHEME}://open?v=1&prompt=hi&cwd=${current.untrusted}`,
+      );
+      expect(untrusted.status).toBe(1);
+      expect(`${untrusted.stderr}`).toContain(`${CLI_NAME} trust --yes`);
+
+      const slug = openHeadless(current, `${PROTOCOL_SCHEME}://open?v=1&prompt=hi&repo=nobody/not-a-clone`);
+      expect(slug.status).toBe(1);
+      expect(`${slug.stderr}`).toContain('nobody/not-a-clone');
+      expect(`${slug.stderr}`).not.toContain('cloning');
+
+      // A refused link grants nothing and records nothing: the untrusted repository is still
+      // untrusted and the store is byte-identical to what it was before the two invocations.
+      const status = spawnSync(process.execPath, [AGENT_BIN, 'trust', 'status'], {
+        cwd: current.untrusted,
+        env: current.env,
+        encoding: 'utf8',
+      });
+      expect(`${status.stdout}`).toContain('untrusted');
+      expect(trustStoreDigest(current.home)).toBe(digestBefore);
+    },
+    CASE_TIMEOUT_MS,
+  );
+});

package/src/__tests__/pty/ime-cursor-tmux.ptytest.ts

@@ -0,0 +1,211 @@
+/**
+ * CLI-062 — the one matrix cell where a REAL terminal emulator answers back.
+ *
+ * Every other cell reads the cursor out of the byte stream our own VT interpreter replays. tmux is
+ * a full, independent terminal emulator that can be driven headlessly AND queried: it runs the
+ * built CLI binary in a real pane, receives the Korean keystrokes through its own input path,
+ * and then reports where ITS state machine put the hardware cursor
+ * (`#{cursor_x}` / `#{cursor_y}` / `#{cursor_flag}`). That makes this the strongest available
+ * confirmation short of macOS hardware: a second implementation agrees the cursor sits on the
+ * input row at the composition column — which is the cell an OS IME anchors its window to.
+ *
+ * Skipped when tmux is not installed; `PRODUCT_TMUX_BIN` overrides the binary. GitHub's ubuntu
+ * runner images ship tmux, so this runs in CI rather than quietly evaporating there.
+ */
+
+import { execFileSync, spawnSync } from 'node:child_process';
+import {
+  chmodSync,
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  rmSync,
+  writeFileSync,
+  realpathSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import korean from '../__fixtures__/korean-text.json';
+
+import { fixtureProductEnvironment } from './isolated-home.js';
+
+const REPO_ROOT = resolve(__dirname, '../../../../..');
+const AGENT_BIN = join(REPO_ROOT, 'packages/agent-cli/bin/agent.cjs');
+const GIT_BIN =
+  (process.env['PATH'] ?? '/usr/bin:/bin')
+    .split(':')
+    .map((directory) => join(directory, 'git'))
+    .find((candidate) => existsSync(candidate)) ?? '/usr/bin/git';
+const COLS = 80;
+const COMPOSITION = korean.greetingFirstTwoSyllables;
+const COMPOSITION_WIDTH = 4;
+
+function resolveTmux(): string | undefined {
+  const override = process.env['PRODUCT_TMUX_BIN'];
+  if (override !== undefined && override !== '') return override;
+  const which = spawnSync('sh', ['-c', 'command -v tmux'], { encoding: 'utf8' });
+  const found = which.stdout.trim();
+  return found === '' ? undefined : found;
+}
+
+const TMUX = resolveTmux();
+
+interface ITmuxProbe {
+  cursorX: number;
+  cursorY: number;
+  /** tmux's own DECTCEM view: is the hardware cursor visible in the pane? */
+  cursorVisible: boolean;
+  pane: string[];
+}
+
+interface ITmuxRun {
+  root: string;
+  socket: string;
+}
+
+/** Run the CLI inside a real tmux pane and ask tmux where the cursor ended up. */
+function runInTmux(run: ITmuxRun, rows: number, imeCursor: string | undefined): ITmuxProbe {
+  const tmux = TMUX!;
+  const projectDir = join(run.root, 'proj');
+  const homeDir = join(run.root, 'home');
+  mkdirSync(projectDir, { recursive: true });
+  mkdirSync(join(homeDir, 'state'), { recursive: true });
+  writeFileSync(join(homeDir, 'state/onboarded'), new Date().toISOString(), 'utf8');
+  writeFileSync(
+    join(homeDir, 'state/settings.json'),
+    JSON.stringify({
+      currentProvider: 'anthropic',
+      providers: {
+        anthropic: { type: 'anthropic', model: 'claude-test-model', apiKey: 'tmux-dummy-key' },
+      },
+    }),
+    'utf8',
+  );
+
+  // A wrapper keeps the pane's env explicit (never inheriting real provider keys) while letting
+  // tmux itself set TERM/TERM_PROGRAM for the pane — the handshake under test.
+  const wrapper = join(run.root, 'wrap.sh');
+  const imeAssignment = imeCursor === undefined ? '' : `PRODUCT_IME_CURSOR=${imeCursor} `;
+  const productAssignments = Object.entries(fixtureProductEnvironment(homeDir))
+    .map(([key, value]) => `${key}='${value.replaceAll("'", "'\\''")}'`)
+    .join(' ');
+  const fixtureEnv = {
+    PATH: process.env['PATH'] || '/usr/bin:/bin:/opt/homebrew/bin',
+    HOME: homeDir,
+    ...fixtureProductEnvironment(homeDir),
+  };
+  execFileSync(GIT_BIN, ['init', '-q', '-b', 'main'], { cwd: projectDir });
+  execFileSync(
+    GIT_BIN,
+    [
+      '-c',
+      'user.name=PTY Fixture',
+      '-c',
+      'user.email=pty@example.invalid',
+      'commit',
+      '--allow-empty',
+      '-q',
+      '-m',
+      'fixture',
+    ],
+    { cwd: projectDir, env: fixtureEnv },
+  );
+  execFileSync(process.execPath, [AGENT_BIN, 'trust', '--yes'], {
+    cwd: projectDir,
+    env: fixtureEnv,
+  });
+  writeFileSync(
+    wrapper,
+    [
+      '#!/bin/sh',
+      `cd "${projectDir}"`,
+      `exec env -i PATH="$PATH" HOME="${homeDir}" TERM="$TERM" TERM_PROGRAM="$TERM_PROGRAM" ${productAssignments} ${imeAssignment}` +
+        `"${process.execPath}" "${AGENT_BIN}" --name tmux-fixture`,
+      '',
+    ].join('\n'),
+    'utf8',
+  );
+  chmodSync(wrapper, 0o755);
+
+  const tmuxCall = (...args: string[]): string =>
+    execFileSync(tmux, ['-S', run.socket, ...args], { encoding: 'utf8' });
+
+  tmuxCall('new-session', '-d', '-x', String(COLS), '-y', String(rows), wrapper);
+
+  const deadline = Date.now() + 40_000;
+  let pane = '';
+  while (Date.now() < deadline) {
+    pane = tmuxCall('capture-pane', '-p');
+    if (pane.includes('Type a message')) break;
+    sleepSync(250);
+  }
+  expect(pane, 'the CLI never reached the prompt inside tmux').toContain('Type a message');
+  sleepSync(400);
+
+  tmuxCall('send-keys', '-l', COMPOSITION);
+  sleepSync(1500);
+
+  const [x = '', y = '', flag = ''] = tmuxCall(
+    'display-message',
+    '-p',
+    '#{cursor_x} #{cursor_y} #{cursor_flag}',
+  )
+    .trim()
+    .split(' ');
+  return {
+    cursorX: Number.parseInt(x, 10),
+    cursorY: Number.parseInt(y, 10),
+    cursorVisible: flag === '1',
+    pane: tmuxCall('capture-pane', '-p').split('\n'),
+  };
+}
+
+/** Deliberate synchronous wait: tmux is driven through blocking CLI calls, not an event loop. */
+function sleepSync(ms: number): void {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+describe.skipIf(TMUX === undefined)(
+  'CLI-062 terminal matrix — tmux, a real emulator reporting its own cursor',
+  () => {
+    let run: ITmuxRun;
+
+    beforeEach(() => {
+      const root = realpathSync(mkdtempSync(join(tmpdir(), 'agent-tmux-ime-')));
+      run = { root, socket: join(root, 'sock') };
+    });
+
+    afterEach(() => {
+      if (TMUX !== undefined) {
+        spawnSync(TMUX, ['-S', run.socket, 'kill-server'], { stdio: 'ignore' });
+      }
+      rmSync(run.root, { recursive: true, force: true });
+    });
+
+    it('24-row pane: tmux reports the cursor VISIBLE on the input row at the composition column', () => {
+      const probe = runInTmux(run, 24, undefined);
+      const inputRow = probe.pane.findIndex((line) => line.includes(`> ${COMPOSITION}`));
+      expect(inputRow, `no input row in pane:\n${probe.pane.join('\n')}`).toBeGreaterThanOrEqual(0);
+
+      expect(probe.cursorVisible).toBe(true);
+      expect(probe.cursorY).toBe(inputRow);
+      expect(probe.cursorX).toBe(probe.pane[inputRow]!.indexOf('> ') + 2 + COMPOSITION_WIDTH);
+    }, 90_000);
+
+    it('5-row pane (frame ≥ viewport, I2): tmux reports the cursor hidden, never positioned', () => {
+      const probe = runInTmux(run, 5, undefined);
+      expect(probe.pane.some((line) => line.includes(`> ${COMPOSITION}`))).toBe(true);
+      expect(probe.cursorVisible).toBe(false);
+    }, 90_000);
+
+    it('PRODUCT_IME_CURSOR=0 kill switch: tmux reports the cursor hidden even at 24 rows', () => {
+      const probe = runInTmux(run, 24, '0');
+      const inputRow = probe.pane.findIndex((line) => line.includes(`> ${COMPOSITION}`));
+      expect(inputRow).toBeGreaterThanOrEqual(0);
+      expect(probe.cursorVisible).toBe(false);
+      expect(probe.cursorY).not.toBe(inputRow);
+    }, 90_000);
+  },
+);