feat(kernel-tui): add TUI with sessions view

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: grypez

packages/kernel-cli/package.json

@@ -66,6 +66,7 @@
     "@metamask/eslint-config": "^15.0.0",
     "@metamask/eslint-config-nodejs": "^15.0.0",
     "@metamask/eslint-config-typescript": "^15.0.0",
+    "@ocap/kernel-tui": "workspace:^",
     "@ocap/repo-tools": "workspace:^",
     "@ts-bridge/cli": "^0.6.3",
     "@ts-bridge/shims": "^0.1.1",

packages/kernel-cli/src/app.ts

@@ -1,6 +1,9 @@
 import '@metamask/kernel-shims/endoify-node';
 import { Logger } from '@metamask/logger';
 import type { LogEntry } from '@metamask/logger';
+import { spawn } from 'node:child_process';
+import { access } from 'node:fs/promises';
+import { createRequire } from 'node:module';
 import path from 'node:path';
 import yargs from 'yargs';
 import { hideBin } from 'yargs/helpers';
@@ -22,7 +25,7 @@ import {
   stopRelay,
 } from './commands/relay.ts';
 import { getServer } from './commands/serve.ts';
-import { buildSessionCommands } from './commands/session.ts';
+import { buildSessionCommands, resolveSessionUrl } from './commands/session.ts';
 import { watchDir } from './commands/watch.ts';
 import { defaultConfig } from './config.ts';
 import type { Config } from './config.ts';
@@ -44,6 +47,25 @@ function consoleTransport(entry: LogEntry): void {
 
 const logger = new Logger({ tags: ['cli'], transports: [consoleTransport] });
 
+/**
+ * Resolve the built ocap-tui binary from the @ocap/kernel-tui workspace package.
+ * Returns undefined if the package cannot be resolved or its dist output hasn't
+ * been built yet (run `yarn build` from the repo root to fix the latter).
+ *
+ * @returns The absolute path to dist/app.mjs, or undefined if not found.
+ */
+async function findTuiBinPath(): Promise<string | undefined> {
+  try {
+    const resolve = createRequire(import.meta.url);
+    const pkgPath = resolve.resolve('@ocap/kernel-tui/package.json');
+    const binPath = path.join(path.dirname(pkgPath), 'dist', 'app.mjs');
+    await access(binPath);
+    return binPath;
+  } catch {
+    return undefined;
+  }
+}
+
 const yargsInstance = yargs(hideBin(process.argv))
   .scriptName('ocap')
   .usage('$0 <command> [options]')
@@ -435,5 +457,70 @@ const yargsInstance = yargs(hideBin(process.argv))
     () => {
       // Handled by subcommands.
     },
+  )
+  .command(
+    'modal <sid>',
+    'Open an interactive TUI for a session',
+    (_yargs) =>
+      _yargs.positional('sid', {
+        type: 'string',
+        demandOption: true,
+        describe: 'Session ID (from ocap session create)',
+      }),
+    async (args) => {
+      const socketPath = getSocketPath();
+      const binPath = await findTuiBinPath();
+      if (binPath === undefined) {
+        process.stderr.write(
+          'Error: kernel-tui binary not found.\n' +
+            'Run `yarn build` from the repository root to build it first.\n',
+        );
+        process.exitCode = 1;
+        return;
+      }
+      await ensureDaemon(socketPath);
+      const ocapUrl = await resolveSessionUrl(socketPath, String(args.sid));
+      if (ocapUrl === undefined) {
+        return;
+      }
+      await new Promise<void>((resolve, reject) => {
+        const child = spawn(process.execPath, [binPath, 'modal', ocapUrl], {
+          stdio: 'inherit',
+        });
+        child.on('close', (code) => {
+          process.exitCode = code ?? 0;
+          resolve();
+        });
+        child.on('error', reject);
+      });
+    },
+  )
+  .command(
+    'tui',
+    'Open the full interactive kernel TUI',
+    (_yargs) => _yargs,
+    async () => {
+      const socketPath = getSocketPath();
+      const binPath = await findTuiBinPath();
+      if (binPath === undefined) {
+        process.stderr.write(
+          'Error: kernel-tui binary not found.\n' +
+            'Run `yarn build` from the repository root to build it first.\n',
+        );
+        process.exitCode = 1;
+        return;
+      }
+      await ensureDaemon(socketPath);
+      await new Promise<void>((resolve, reject) => {
+        const child = spawn(process.execPath, [binPath, 'tui'], {
+          stdio: 'inherit',
+        });
+        child.on('close', (code) => {
+          process.exitCode = code ?? 0;
+          resolve();
+        });
+        child.on('error', reject);
+      });
+    },
   );
 await yargsInstance.help('help').parse();

packages/kernel-tui/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+[Unreleased]: https://github.com/MetaMask/ocap-kernel/

packages/kernel-tui/README.md

@@ -0,0 +1,15 @@
+# `@ocap/kernel-tui`
+
+Interactive terminal UI for the OCAP kernel
+
+## Installation
+
+`yarn add @ocap/kernel-tui`
+
+or
+
+`npm install @ocap/kernel-tui`
+
+## Contributing
+
+This package is part of a monorepo. Instructions for contributing can be found in the [monorepo README](https://github.com/MetaMask/ocap-kernel#readme).

packages/kernel-tui/package.json

@@ -0,0 +1,92 @@
+{
+  "name": "@ocap/kernel-tui",
+  "version": "0.0.0",
+  "private": true,
+  "description": "Interactive terminal UI for the OCAP kernel",
+  "homepage": "https://github.com/MetaMask/ocap-kernel/tree/main/packages/kernel-tui#readme",
+  "bugs": {
+    "url": "https://github.com/MetaMask/ocap-kernel/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/MetaMask/ocap-kernel.git"
+  },
+  "type": "module",
+  "bin": {
+    "ocap-tui": "./dist/app.mjs"
+  },
+  "exports": {
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist/"
+  ],
+  "scripts": {
+    "build": "ts-bridge --project tsconfig.build.json --no-references --clean && chmod +x dist/app.mjs",
+    "build:docs": "typedoc",
+    "changelog:validate": "../../scripts/validate-changelog.sh @ocap/kernel-tui",
+    "clean": "rimraf --glob './*.tsbuildinfo' ./.eslintcache ./coverage ./dist ./.turbo ./logs",
+    "lint": "yarn lint:eslint && yarn lint:misc --check && yarn constraints && yarn lint:dependencies",
+    "lint:dependencies": "depcheck --quiet",
+    "lint:eslint": "eslint . --cache",
+    "lint:fix": "yarn lint:eslint --fix && yarn lint:misc --write && yarn constraints --fix && yarn lint:dependencies",
+    "lint:misc": "prettier --no-error-on-unmatched-pattern '**/*.json' '**/*.md' '**/*.html' '!**/CHANGELOG.old.md' '**/*.yml' '!.yarnrc.yml' '!merged-packages/**' --ignore-path ../../.gitignore --log-level error",
+    "publish:preview": "yarn npm publish --tag preview",
+    "test": "vitest run --config vitest.config.ts",
+    "test:clean": "yarn test --no-cache --coverage.clean",
+    "test:dev": "yarn test --mode development",
+    "test:verbose": "yarn test --reporter verbose",
+    "test:watch": "vitest --config vitest.config.ts",
+    "test:dev:quiet": "yarn test:dev --reporter @ocap/repo-tools/vitest-reporters/silent"
+  },
+  "devDependencies": {
+    "@arethetypeswrong/cli": "^0.17.4",
+    "@metamask/auto-changelog": "^5.3.0",
+    "@metamask/eslint-config": "^15.0.0",
+    "@metamask/eslint-config-nodejs": "^15.0.0",
+    "@metamask/eslint-config-typescript": "^15.0.0",
+    "@ocap/repo-tools": "workspace:^",
+    "@ts-bridge/cli": "^0.6.3",
+    "@ts-bridge/shims": "^0.1.1",
+    "@types/node": "^22.13.1",
+    "@types/react": "^18.3.18",
+    "@types/yargs": "^17.0.33",
+    "@typescript-eslint/eslint-plugin": "^8.29.0",
+    "@typescript-eslint/parser": "^8.29.0",
+    "@typescript-eslint/utils": "^8.29.0",
+    "@vitest/eslint-plugin": "^1.6.14",
+    "depcheck": "^1.4.7",
+    "eslint": "^9.23.0",
+    "eslint-config-prettier": "^10.1.1",
+    "eslint-import-resolver-typescript": "^4.3.1",
+    "eslint-plugin-import-x": "^4.10.0",
+    "eslint-plugin-jsdoc": "^50.6.9",
+    "eslint-plugin-n": "^17.17.0",
+    "eslint-plugin-prettier": "^5.2.6",
+    "eslint-plugin-promise": "^7.2.1",
+    "prettier": "^3.5.3",
+    "rimraf": "^6.0.1",
+    "turbo": "^2.9.1",
+    "typedoc": "^0.28.1",
+    "typescript": "~5.8.2",
+    "typescript-eslint": "^8.29.0",
+    "vite": "^8.0.6",
+    "vitest": "^4.1.3"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "dependencies": {
+    "@metamask/kernel-node-runtime": "workspace:^",
+    "@metamask/kernel-shims": "workspace:^",
+    "@metamask/kernel-utils": "workspace:^",
+    "@metamask/streams": "workspace:^",
+    "glob": "^11.0.0",
+    "ink": "^5.2.1",
+    "ink-select-input": "^6.0.0",
+    "ink-spinner": "^5.0.0",
+    "ink-text-input": "^6.0.0",
+    "react": "^18.3.1",
+    "yargs": "^17.7.2"
+  }
+}

packages/kernel-tui/src/app.ts

@@ -0,0 +1,43 @@
+import '@metamask/kernel-shims/endoify-node';
+import { getSocketPath } from '@metamask/kernel-node-runtime/daemon';
+import yargs from 'yargs';
+import { hideBin } from 'yargs/helpers';
+
+import { makeDaemonKernelApi } from './hooks/use-kernel.ts';
+import { runModal } from './modal.tsx';
+import { startTui } from './start-tui.ts';
+
+const yargsInstance = yargs(hideBin(process.argv))
+  .scriptName('ocap-tui')
+  .usage('$0 <command> [options]')
+  .demandCommand(1)
+  .strict()
+  .command(
+    'tui',
+    'Open the full interactive kernel TUI (connected to the daemon)',
+    (_yargs) =>
+      _yargs.option('socket-path', {
+        type: 'string',
+        describe: 'Daemon socket path (defaults to standard path)',
+        default: getSocketPath(),
+      }),
+    async (args) => {
+      const kernelApi = makeDaemonKernelApi(args['socket-path']);
+      await startTui({ cwd: process.cwd(), kernelApi });
+    },
+  )
+  .command(
+    'modal <ocap-url>',
+    'Open an interactive TUI for a modal channel',
+    (_yargs) =>
+      _yargs.positional('ocap-url', {
+        type: 'string',
+        demandOption: true,
+        describe: 'OCAP URL of the channel (from `ocap session create`)',
+      }),
+    async (args) => {
+      await runModal(args['ocap-url']);
+    },
+  );
+
+await yargsInstance.help('help').parse();

packages/kernel-tui/src/components/file-browser.tsx

@@ -0,0 +1,106 @@
+import { glob } from 'glob';
+import { Box, Text } from 'ink';
+import SelectInput from 'ink-select-input';
+import Spinner from 'ink-spinner';
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import React, { useEffect, useState } from 'react';
+
+import type { KernelApi } from '../types.ts';
+
+type FileBrowserProps = {
+  cwd: string;
+  kernelApi: KernelApi;
+  onLog: (message: string) => void;
+};
+
+type FileItem = {
+  label: string;
+  value: string;
+};
+
+/**
+ * File browser for discovering and launching .bundle and subcluster.json files.
+ *
+ * @param props - Component props.
+ * @param props.cwd - Current working directory to scan.
+ * @param props.kernelApi - Kernel API for launching subclusters.
+ * @param props.onLog - Callback to add a log message.
+ * @returns The FileBrowser component.
+ */
+export function FileBrowser({
+  cwd,
+  kernelApi,
+  onLog,
+}: FileBrowserProps): React.ReactElement {
+  const [files, setFiles] = useState<FileItem[]>([]);
+  const [loading, setLoading] = useState(false);
+  const [result, setResult] = useState<string | null>(null);
+
+  useEffect(() => {
+    Promise.all([
+      glob('**/*.bundle', { cwd, maxDepth: 3 }),
+      glob('**/subcluster.json', { cwd, maxDepth: 3 }),
+    ])
+      .then(([bundleFiles, jsonFiles]) => {
+        const items = [...bundleFiles, ...jsonFiles].map((file) => ({
+          label: file,
+          value: path.resolve(cwd, file),
+        }));
+        setFiles(items);
+        return undefined;
+      })
+      .catch(() => undefined);
+  }, [cwd]);
+
+  const handleSelect = (item: FileItem): void => {
+    setLoading(true);
+    setResult(null);
+    const filePath = item.value;
+
+    (async () => {
+      const content = await readFile(filePath, 'utf-8');
+      let config: Record<string, unknown>;
+
+      if (filePath.endsWith('.json')) {
+        config = JSON.parse(content) as Record<string, unknown>;
+      } else {
+        config = {
+          bootstrap: 'main',
+          vats: { main: { bundleSpec: `file://${filePath}` } },
+        };
+      }
+
+      const launchResult = await kernelApi.launchSubcluster(config);
+      const logMessage = `Launched ${item.label} → kref: ${launchResult.bootstrapRootKref}`;
+      setResult(logMessage);
+      onLog(logMessage);
+    })()
+      .catch((error: Error) => {
+        const logMessage = `Error launching ${item.label}: ${error.message}`;
+        setResult(logMessage);
+        onLog(logMessage);
+      })
+      .finally(() => setLoading(false));
+  };
+
+  return (
+    <Box flexDirection="column" paddingX={1}>
+      <Text bold>File Browser</Text>
+      <Text dimColor>Select a .bundle or subcluster.json to launch</Text>
+      {files.length === 0 ? (
+        <Text color="yellow">
+          No .bundle or subcluster.json files found in {cwd}
+        </Text>
+      ) : (
+        <SelectInput items={files} onSelect={handleSelect} />
+      )}
+      {loading && (
+        <Text>
+          <Spinner type="dots" /> Launching...
+        </Text>
+      )}
+      {result && <Text color="green">{result}</Text>}
+    </Box>
+  );
+}