@docyrus/docyrus 0.0.21 → 0.0.22

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docyrus/docyrus",
-  "version": "0.0.21",
+  "version": "0.0.22",
   "private": false,
   "description": "Docyrus API CLI",
   "main": "./main.js",
@@ -13,18 +13,21 @@
     "@modelcontextprotocol/ext-apps": "^1.2.2",
     "@modelcontextprotocol/sdk": "^1.25.1",
     "@mariozechner/pi-ai": "0.61.0",
-    "@mariozechner/pi-coding-agent": "0.61.0",
+    "@mariozechner/pi-coding-agent": "0.61.1",
     "@opentui/core": "^0.1.85",
     "@opentui/react": "^0.1.85",
+    "@xterm/headless": "^5.5.0",
     "cheerio": "^1.1.2",
     "diff": "^8.0.2",
     "incur": "^0.1.6",
     "jsdom": "^27.0.1",
     "marked": "^15.0.12",
     "marked-terminal": "^7.3.0",
+    "node-pty": "^1.0.0",
     "picocolors": "^1.1.1",
     "puppeteer-core": "^24.31.0",
     "react": "^19.1.1",
+    "strip-ansi": "^7.1.0",
     "turndown": "^7.2.2",
     "turndown-plugin-gfm": "^1.0.2",
     "undici": "^7.16.0",

package/resources/pi-agent/extensions/pi-bash-live-view/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lucas Meijer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/resources/pi-agent/extensions/pi-bash-live-view/README.md

@@ -0,0 +1,19 @@
+# pi-bash-live-view
+
+When agents emit tool calls calls for build systems, those calls can take a long time.
+Often they have really nice visualizations of progress.
+I cannot see those in pi, making me blind to what is happening.
+
+This extension upgrades model-initiated `bash` calls with an optional PTY-backed live terminal view.
+
+[![Demo](assets/demo.gif)](https://github.com/lucasmeijer/pi-bash-live-view/releases/download/readme-assets/Screen.Recording.2026-03-20.at.22.27.36.web.mp4)
+
+_Open the full demo video:_
+https://github.com/lucasmeijer/pi-bash-live-view/releases/download/readme-assets/Screen.Recording.2026-03-20.at.22.27.36.web.mp4
+
+## Install
+
+```bash
+pi install npm:pi-bash-live-view
+```
+

package/resources/pi-agent/extensions/pi-bash-live-view/index.ts

@@ -0,0 +1,52 @@
+import { createBashTool, type ExtensionAPI, type ExtensionCommandContext, type ExtensionContext } from '@mariozechner/pi-coding-agent';
+import { Type } from '@sinclair/typebox';
+import { executePtyCommand } from './pty-execute.ts';
+import { ensureSpawnHelperExecutable } from './spawn-helper.ts';
+
+const bashLiveViewParams = Type.Object({
+  command: Type.String({ description: 'Command to execute' }),
+  timeout: Type.Optional(Type.Number({ description: 'Timeout in seconds' })),
+  usePTY: Type.Optional(Type.Boolean({ description: 'Run inside a PTY with a live terminal widget the user can see while its running. Use this when you suspect the program being ran has interesting ansi progress output, like buildsystems.' })),
+});
+
+ensureSpawnHelperExecutable();
+
+async function runSlashCommand(args: string, ctx: ExtensionCommandContext) {
+  const command = args.trim();
+  if (!command) {
+    ctx.ui.notify('Usage: /bash-pty <command>', 'error');
+    return;
+  }
+  const result = await executePtyCommand(
+    `slash-${Date.now()}`,
+    { command },
+    new AbortController().signal,
+    ctx as unknown as ExtensionContext,
+  );
+  const text = result.content[0]?.type === 'text' ? result.content[0].text : '(no output)';
+  ctx.ui.notify(text.slice(0, 4000), 'info');
+}
+
+export default function bashLiveView(pi: ExtensionAPI) {
+  const originalBash = createBashTool(process.cwd());
+
+  pi.registerTool({
+    name: 'bash',
+    label: 'bash',
+    description: `${originalBash.description} Supports optional usePTY=true live terminal rendering for terminal-style programs and richer progress UIs.`,
+    parameters: bashLiveViewParams,
+    async execute(toolCallId, params, signal, onUpdate, ctx) {
+      if (params.usePTY !== true) {
+        return originalBash.execute(toolCallId, params, signal, onUpdate);
+      }
+      return executePtyCommand(toolCallId, params, signal, ctx);
+    },
+  });
+
+  pi.registerCommand('bash-pty', {
+    description: 'Run a command through the PTY-backed bash path',
+    handler: async (args, ctx) => {
+      await runSlashCommand(args, ctx);
+    },
+  });
+}

package/resources/pi-agent/extensions/pi-bash-live-view/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "pi-bash-live-view",
+  "version": "0.1.1",
+  "description": "A pi extension that adds optional PTY-backed live terminal rendering to the bash tool via usePTY=true.",
+  "type": "module",
+  "author": "Lucas Meijer",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lucasmeijer/pi-bash-live-view.git"
+  },
+  "bugs": {
+    "url": "https://github.com/lucasmeijer/pi-bash-live-view/issues"
+  },
+  "homepage": "https://github.com/lucasmeijer/pi-bash-live-view#readme",
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-coding-agent",
+    "extension",
+    "bash",
+    "pty",
+    "terminal",
+    "tui"
+  ],
+  "files": [
+    "index.ts",
+    "pty-execute.ts",
+    "pty-kill.ts",
+    "pty-session.ts",
+    "spawn-helper.ts",
+    "truncate.ts",
+    "widget.ts",
+    "terminal-emulator.ts",
+    "examples/",
+    "README.md",
+    "LICENSE"
+  ],
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "test": "node --test tests/*.test.mjs"
+  },
+  "dependencies": {
+    "@mariozechner/pi-coding-agent": "^0.58.4",
+    "@sinclair/typebox": "^0.34.38",
+    "node-pty": "^1.0.0",
+    "strip-ansi": "^7.1.0",
+    "@xterm/headless": "^5.5.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.3.0",
+    "typescript": "^5.7.3"
+  }
+}

package/resources/pi-agent/extensions/pi-bash-live-view/pty-execute.ts

@@ -0,0 +1,97 @@
+import { getShellConfig, type ExtensionContext } from '@mariozechner/pi-coding-agent';
+import { buildAbortError, buildExitCodeError, buildSuccessfulBashResult, buildTimeoutError } from './truncate.ts';
+import { hideWidget, showWidget, type LiveSession } from './widget.ts';
+import { PtyTerminalSession } from './pty-session.ts';
+
+export const WIDGET_DELAY_MS = 100;
+export const WIDGET_HEIGHT = 15;
+export const DEFAULT_PTY_COLS = 100;
+export const XTERM_SCROLLBACK_LINES = 100_000;
+
+export async function executePtyCommand(
+  toolCallId: string,
+  params: { command: string; timeout?: number },
+  signal: AbortSignal,
+  ctx: ExtensionContext,
+) {
+  const shellConfig = getShellConfig();
+  const cols = DEFAULT_PTY_COLS;
+  const rows = WIDGET_HEIGHT;
+  const ptySession = new PtyTerminalSession({
+    command: params.command,
+    cwd: ctx.cwd,
+    cols,
+    rows,
+    scrollback: XTERM_SCROLLBACK_LINES,
+    shell: shellConfig.shell,
+    shellArgs: shellConfig.args,
+  });
+
+  const session: LiveSession = {
+    id: toolCallId,
+    startedAt: Date.now(),
+    rows,
+    visible: false,
+    disposed: false,
+    session: ptySession,
+  };
+
+  const unsubscribe = ptySession.subscribe(() => {
+    session.requestRender?.();
+  });
+
+  if (ctx.hasUI) {
+    session.timer = setTimeout(() => showWidget(ctx, session), WIDGET_DELAY_MS);
+  }
+
+  let timeoutHandle: NodeJS.Timeout | undefined;
+  let timedOut = false;
+  let aborted = false;
+
+  const kill = () => {
+    ptySession.kill();
+  };
+  const onAbort = () => {
+    aborted = true;
+    kill();
+  };
+
+  if (params.timeout && params.timeout > 0) {
+    timeoutHandle = setTimeout(() => {
+      timedOut = true;
+      kill();
+    }, params.timeout * 1000);
+  }
+  if (signal.aborted) {
+    onAbort();
+  } else {
+    signal.addEventListener('abort', onAbort, { once: true });
+  }
+
+  const exit = await new Promise<{ exitCode: number | null }>((resolve) => {
+    ptySession.addExitListener((exitCode) => resolve({ exitCode }));
+  });
+
+  await ptySession.whenIdle();
+  if (timeoutHandle) clearTimeout(timeoutHandle);
+  signal.removeEventListener('abort', onAbort);
+  if (session.timer) clearTimeout(session.timer);
+  session.disposed = true;
+  hideWidget(ctx, session);
+  unsubscribe();
+
+  const fullText = ptySession.getStrippedTextIncludingEntireScrollback();
+  ptySession.dispose();
+
+  if (aborted) {
+    throw buildAbortError(fullText);
+  }
+  if (timedOut && params.timeout && params.timeout > 0) {
+    throw buildTimeoutError(fullText, params.timeout);
+  }
+  if (exit.exitCode !== 0 && exit.exitCode !== null) {
+    throw buildExitCodeError(fullText, exit.exitCode);
+  }
+
+  return buildSuccessfulBashResult(fullText);
+}

package/resources/pi-agent/extensions/pi-bash-live-view/pty-kill.ts

@@ -0,0 +1,25 @@
+import type pty from 'node-pty';
+
+export type PtyLikeProcess = {
+  pid: number;
+  kill: (signal?: string) => void;
+};
+
+export function killPtyProcess(ptyProcess: PtyLikeProcess, signal: string = 'SIGTERM'): void {
+  const pid = ptyProcess.pid;
+
+  if (process.platform !== 'win32' && pid) {
+    try {
+      process.kill(-pid, signal as NodeJS.Signals);
+      return;
+    } catch {
+      // Fall through to direct PTY kill.
+    }
+  }
+
+  try {
+    ptyProcess.kill(signal);
+  } catch {
+    // Process may already be dead.
+  }
+}

package/resources/pi-agent/extensions/pi-bash-live-view/pty-session.ts

@@ -0,0 +1,143 @@
+import { createRequire } from 'node:module';
+import { createTerminalEmulator } from './terminal-emulator.ts';
+import { killPtyProcess } from './pty-kill.ts';
+
+const require = createRequire(import.meta.url);
+const pty = require('node-pty') as typeof import('node-pty');
+
+export type PtyTerminalSessionOptions = {
+  command: string;
+  cwd: string;
+  cols: number;
+  rows: number;
+  scrollback: number;
+  shell: string;
+  shellArgs?: string[];
+  env?: Record<string, string | undefined>;
+};
+
+type TerminalEmulator = ReturnType<typeof createTerminalEmulator>;
+
+type ExitListener = (exitCode: number | null, signal?: number) => void;
+
+export class PtyTerminalSession {
+  private readonly ptyProcess: pty.IPty;
+  private readonly terminalEmulator: TerminalEmulator;
+  private readonly startedAt = Date.now();
+  private readonly exitListeners = new Set<ExitListener>();
+  private _exited = false;
+  private _exitCode: number | null = null;
+  private _signal: number | undefined;
+  private disposed = false;
+
+  constructor(options: PtyTerminalSessionOptions) {
+    const {
+      command,
+      cwd,
+      cols,
+      rows,
+      scrollback,
+      shell,
+      shellArgs = [],
+      env,
+    } = options;
+
+    this.terminalEmulator = createTerminalEmulator({ cols, rows, scrollback });
+    this.ptyProcess = pty.spawn(shell, [...shellArgs, command], {
+      name: 'xterm-256color',
+      cols,
+      rows,
+      cwd,
+      env: {
+        ...process.env,
+        ...env,
+        TERM: 'xterm-256color',
+        COLORTERM: 'truecolor',
+      },
+    });
+
+    this.ptyProcess.onData((chunk) => {
+      void this.terminalEmulator.consumeProcessStdout(chunk, {
+        elapsedMs: Date.now() - this.startedAt,
+      });
+    });
+
+    this.ptyProcess.onExit(({ exitCode, signal }) => {
+      this._exited = true;
+      this._exitCode = exitCode;
+      this._signal = signal;
+      void this.whenIdle().then(() => {
+        for (const listener of [...this.exitListeners]) {
+          listener(exitCode, signal);
+        }
+      });
+    });
+  }
+
+  get exited() {
+    return this._exited;
+  }
+
+  get exitCode() {
+    return this._exitCode;
+  }
+
+  get signal() {
+    return this._signal;
+  }
+
+  get pid() {
+    return this.ptyProcess.pid;
+  }
+
+  get cols() {
+    return this.terminalEmulator.cols;
+  }
+
+  get rows() {
+    return this.terminalEmulator.rows;
+  }
+
+  addExitListener(listener: ExitListener): () => void {
+    this.exitListeners.add(listener);
+    if (this._exited) {
+      void this.whenIdle().then(() => {
+        if (this.exitListeners.has(listener)) {
+          listener(this._exitCode, this._signal);
+        }
+      });
+    }
+    return () => {
+      this.exitListeners.delete(listener);
+    };
+  }
+
+  whenIdle(): Promise<void> {
+    return this.terminalEmulator.whenIdle();
+  }
+
+  getViewportSnapshot() {
+    return this.terminalEmulator.getViewportSnapshot();
+  }
+
+  getStrippedTextIncludingEntireScrollback() {
+    return this.terminalEmulator.getStrippedTextIncludingEntireScrollback();
+  }
+
+  subscribe(listener: (payload: { elapsedMs: number; snapshot: ReturnType<TerminalEmulator['getViewportSnapshot']>; inAltScreen: boolean; inSyncRender: boolean }) => void): () => void {
+    return this.terminalEmulator.subscribe(listener);
+  }
+
+  kill(signal = 'SIGTERM') {
+    if (this._exited) return;
+    killPtyProcess(this.ptyProcess, signal);
+  }
+
+  dispose() {
+    if (this.disposed) return;
+    this.disposed = true;
+    this.kill();
+    this.terminalEmulator.dispose();
+    this.exitListeners.clear();
+  }
+}

package/resources/pi-agent/extensions/pi-bash-live-view/spawn-helper.ts

@@ -0,0 +1,31 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+
+export function getBundledSpawnHelperPaths() {
+  const base = path.dirname(require.resolve('node-pty/package.json'));
+  return [
+    path.join(base, 'prebuilds', 'darwin-arm64', 'spawn-helper'),
+    path.join(base, 'prebuilds', 'darwin-x64', 'spawn-helper'),
+  ];
+}
+
+export function ensureExecutablePaths(paths: string[], log?: (...args: unknown[]) => void) {
+  for (const helper of paths) {
+    if (!fs.existsSync(helper)) continue;
+    const mode = fs.statSync(helper).mode & 0o777;
+    if (mode === 0o755) continue;
+    fs.chmodSync(helper, 0o755);
+    log?.('chmod', helper);
+  }
+}
+
+export function ensureSpawnHelperExecutable(log?: (...args: unknown[]) => void) {
+  try {
+    ensureExecutablePaths(getBundledSpawnHelperPaths(), log);
+  } catch (error) {
+    log?.('spawn-helper chmod failed', error);
+  }
+}