@aria-cli/tools 1.0.0

package/src/executors/pty.ts

@@ -0,0 +1,342 @@
+/**
+ * @aria/tools - PTY executor for interactive terminal programs
+ *
+ * Provides PTY (pseudo-terminal) support for running interactive programs
+ * that require a terminal environment (like vim, less, etc.)
+ */
+
+import * as nodePty from "node-pty";
+import { sanitizeEnv } from "./shell.js";
+
+/**
+ * Options for creating a PTY session.
+ */
+export interface PTYOptions {
+  /** Command to execute */
+  command: string;
+  /** Arguments to pass to the command */
+  args?: string[];
+  /** Working directory */
+  cwd?: string;
+  /** Environment variables */
+  env?: Record<string, string>;
+  /** Terminal columns (default: 80) */
+  cols?: number;
+  /** Terminal rows (default: 24) */
+  rows?: number;
+}
+
+/**
+ * Result of running a command in a PTY.
+ */
+export interface PTYResult {
+  /** All output from the command */
+  output: string;
+  /** Exit code of the process */
+  exitCode: number;
+}
+
+/**
+ * Error thrown when a PTY operation times out.
+ */
+export class PTYTimeoutError extends Error {
+  constructor(
+    message: string,
+    public readonly output: string,
+  ) {
+    super(message);
+    this.name = "PTYTimeoutError";
+  }
+}
+
+/**
+ * Error thrown when a PTY operation fails.
+ */
+export class PTYError extends Error {
+  constructor(
+    message: string,
+    public readonly output?: string,
+  ) {
+    super(message);
+    this.name = "PTYError";
+  }
+}
+
+/**
+ * A session wrapping a PTY process.
+ * Provides methods for interacting with the process and collecting output.
+ */
+export class PTYSession {
+  private static MAX_OUTPUT = 10 * 1024 * 1024; // 10MB
+  private _output: string = "";
+  private _isRunning: boolean = true;
+  private _exitCode: number | undefined;
+  private _exitPromise: Promise<number>;
+  private _exitResolve!: (code: number) => void;
+  private _pty: nodePty.IPty;
+  private _dataDisposable: nodePty.IDisposable;
+  private _exitDisposable: nodePty.IDisposable;
+
+  constructor(pty: nodePty.IPty) {
+    this._pty = pty;
+
+    // Set up exit promise
+    this._exitPromise = new Promise<number>((resolve) => {
+      this._exitResolve = resolve;
+    });
+
+    // Collect output with buffer cap
+    this._dataDisposable = pty.onData((data: string) => {
+      this._output += data;
+      if (this._output.length > PTYSession.MAX_OUTPUT) {
+        this._output = this._output.slice(-PTYSession.MAX_OUTPUT);
+      }
+    });
+
+    // Handle exit
+    this._exitDisposable = pty.onExit(({ exitCode }) => {
+      this._isRunning = false;
+      this._exitCode = exitCode;
+      this._exitResolve(exitCode);
+    });
+  }
+
+  /**
+   * Write data to the terminal input.
+   */
+  write(data: string): void {
+    if (!this._isRunning) {
+      throw new PTYError("Cannot write to a closed PTY session");
+    }
+    this._pty.write(data);
+  }
+
+  /**
+   * Resize the terminal.
+   */
+  resize(cols: number, rows: number): void {
+    if (!this._isRunning) {
+      throw new PTYError("Cannot resize a closed PTY session");
+    }
+    this._pty.resize(cols, rows);
+  }
+
+  /**
+   * Wait for a pattern to appear in the output.
+   * @param pattern String or RegExp to match
+   * @param timeoutMs Timeout in milliseconds (default: 5000)
+   * @returns The output accumulated up to and including the match
+   */
+  async waitFor(pattern: string | RegExp, timeoutMs: number = 5000): Promise<string> {
+    const startTime = Date.now();
+    const regex = typeof pattern === "string" ? new RegExp(escapeRegExp(pattern)) : pattern;
+
+    // Check if pattern already matches
+    if (regex.test(this._output)) {
+      return this._output;
+    }
+
+    return new Promise<string>((resolve, reject) => {
+      let checkInterval: NodeJS.Timeout | undefined;
+      let timeoutHandle: NodeJS.Timeout | undefined;
+
+      const cleanup = () => {
+        if (checkInterval) clearInterval(checkInterval);
+        if (timeoutHandle) clearTimeout(timeoutHandle);
+      };
+
+      const check = () => {
+        if (regex.test(this._output)) {
+          cleanup();
+          resolve(this._output);
+          return true;
+        }
+
+        if (!this._isRunning) {
+          cleanup();
+          reject(new PTYError(`Process exited before pattern was found: ${pattern}`, this._output));
+          return true;
+        }
+
+        return false;
+      };
+
+      // Initial check
+      if (check()) return;
+
+      // Set up polling
+      checkInterval = setInterval(() => {
+        check();
+      }, 10);
+
+      // Set up timeout
+      timeoutHandle = setTimeout(() => {
+        cleanup();
+        const elapsed = Date.now() - startTime;
+        reject(
+          new PTYTimeoutError(
+            `Timeout (${elapsed}ms) waiting for pattern: ${pattern}`,
+            this._output,
+          ),
+        );
+      }, timeoutMs);
+    });
+  }
+
+  /**
+   * Wait for the process to exit.
+   * @param timeoutMs Timeout in milliseconds (default: 30000)
+   * @returns The complete output
+   */
+  async waitForExit(timeoutMs: number = 30000): Promise<string> {
+    if (!this._isRunning) {
+      return this._output;
+    }
+
+    return new Promise<string>((resolve, reject) => {
+      let timeoutHandle: NodeJS.Timeout | undefined;
+
+      timeoutHandle = setTimeout(() => {
+        reject(
+          new PTYTimeoutError(`Timeout (${timeoutMs}ms) waiting for process to exit`, this._output),
+        );
+      }, timeoutMs);
+
+      this._exitPromise
+        .then(() => {
+          if (timeoutHandle) clearTimeout(timeoutHandle);
+          resolve(this._output);
+        })
+        .catch(reject);
+    });
+  }
+
+  /**
+   * Kill the process.
+   * @param signal Signal to send (default: SIGHUP on Unix)
+   */
+  kill(signal?: string): void {
+    if (!this._isRunning) {
+      return;
+    }
+
+    try {
+      this._pty.kill(signal);
+    } catch {
+      // Process may already be dead
+    }
+  }
+
+  /**
+   * Close the session and clean up resources.
+   */
+  close(): void {
+    // Kill the process first before disposing handlers
+    if (this._isRunning) {
+      this.kill("SIGKILL");
+      // Mark as not running since we won't receive the exit event
+      // after disposing the handlers
+      this._isRunning = false;
+      // Resolve the exit promise to unblock any waiters
+      // Use -1 to indicate forced termination
+      this._exitResolve(-1);
+    }
+
+    this._dataDisposable.dispose();
+    this._exitDisposable.dispose();
+  }
+
+  /**
+   * Get the current output buffer.
+   */
+  get output(): string {
+    return this._output;
+  }
+
+  /**
+   * Check if the process is still running.
+   */
+  get isRunning(): boolean {
+    return this._isRunning;
+  }
+
+  /**
+   * Get the process ID.
+   */
+  get pid(): number {
+    return this._pty.pid;
+  }
+
+  /**
+   * Get the exit code (undefined if still running).
+   */
+  get exitCode(): number | undefined {
+    return this._exitCode;
+  }
+
+  /**
+   * Get the current terminal columns.
+   */
+  get cols(): number {
+    return this._pty.cols;
+  }
+
+  /**
+   * Get the current terminal rows.
+   */
+  get rows(): number {
+    return this._pty.rows;
+  }
+}
+
+/**
+ * Create a new PTY session.
+ * @param options Options for the PTY
+ * @returns A PTYSession wrapping the process
+ */
+export async function createPTYSession(options: PTYOptions): Promise<PTYSession> {
+  const defaultCols = 80;
+  const defaultRows = 24;
+
+  const pty = nodePty.spawn(options.command, options.args ?? [], {
+    name: "xterm-256color",
+    cols: options.cols ?? defaultCols,
+    rows: options.rows ?? defaultRows,
+    cwd: options.cwd ?? process.cwd(),
+    env: {
+      ...sanitizeEnv(options.env),
+      TERM: "xterm-256color",
+    },
+  });
+
+  return new PTYSession(pty);
+}
+
+/**
+ * Run a command in a PTY and wait for it to complete.
+ * This is a convenience function for commands that don't require interaction.
+ *
+ * @param options Options for the PTY, with optional timeout
+ * @returns The output and exit code
+ */
+export async function runInPTY(options: PTYOptions & { timeoutMs?: number }): Promise<PTYResult> {
+  const { timeoutMs = 30000, ...ptyOptions } = options;
+  const session = await createPTYSession(ptyOptions);
+
+  try {
+    const output = await session.waitForExit(timeoutMs);
+    return {
+      output,
+      exitCode: session.exitCode ?? 0,
+    };
+  } finally {
+    session.close();
+  }
+}
+
+/**
+ * Escape special regex characters in a string.
+ */
+function escapeRegExp(string: string): string {
+  return string.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}

package/src/executors/restart.ts

@@ -0,0 +1,168 @@
+/**
+ * @aria/tools - Restart executor
+ *
+ * Two restart paths:
+ *
+ * 1. Supervised (TUI via relaunch.ts): ARIA_NO_RELAUNCH=true is set by the
+ *    parent supervisor. Child exits with RELAUNCH_EXIT_CODE (199), parent
+ *    respawns automatically.
+ *
+ * 2. Daemon (daemon-launcher): No supervisor loop. The executor spawns a
+ *    replacement daemon on the process 'exit' event (after the singleton lock
+ *    is released), then sends SIGINT to trigger graceful shutdown.
+ */
+
+import type { ToolContext, ToolResult } from "../types.js";
+import { success, fail } from "./utils.js";
+import { spawn } from "node:child_process";
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import * as os from "node:os";
+import {
+  NO_RELAUNCH_ENV,
+  RELAUNCH_EXIT_CODE,
+  RESUME_ARION_ENV,
+  RESUME_SESSION_ENV,
+  writeRelaunchMarker,
+} from "@aria/types";
+
+export interface RestartInput {
+  reason?: string;
+}
+
+function findPnpmWorkspaceRoot(startDir: string): string | null {
+  let dir = resolve(startDir);
+  while (true) {
+    if (existsSync(join(dir, "pnpm-workspace.yaml"))) return dir;
+    const parent = dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+function getPnpmCommand(): string {
+  return process.platform === "win32" ? "pnpm.cmd" : "pnpm";
+}
+
+async function rebuildWorkspaceIfPresent(startDir: string): Promise<{ attempted: boolean }> {
+  const root = findPnpmWorkspaceRoot(startDir);
+  if (!root) return { attempted: false };
+
+  const pnpm = getPnpmCommand();
+  await new Promise<void>((resolvePromise, rejectPromise) => {
+    const child = spawn(pnpm, ["build"], {
+      cwd: root,
+      env: process.env,
+      stdio: "inherit",
+    });
+    child.on("error", rejectPromise);
+    child.on("close", (code) => {
+      if (code === 0) resolvePromise();
+      else rejectPromise(new Error(`pnpm build failed with exit code ${code ?? "unknown"}`));
+    });
+  });
+  return { attempted: true };
+}
+
+/**
+ * Find the daemon PID for the current ARIA_HOME by scanning owner records.
+ * Owner records live at $RUNTIME_ROOT/owners/*.json where RUNTIME_ROOT is
+ * XDG_RUNTIME_DIR/aria or ~/.aria/run.
+ */
+function findDaemonPid(): number | null {
+  const ariaHome = process.env.ARIA_HOME?.trim() || join(os.homedir(), ".aria");
+  const runtimeDir = process.env.XDG_RUNTIME_DIR?.trim();
+  const runtimeRoot = runtimeDir ? join(runtimeDir, "aria") : join(ariaHome, "run");
+  const ownersDir = join(runtimeRoot, "owners");
+
+  if (!existsSync(ownersDir)) return null;
+
+  const canonicalHome = resolve(ariaHome);
+  for (const file of readdirSync(ownersDir).filter((f) => f.endsWith(".json"))) {
+    try {
+      const record = JSON.parse(readFileSync(join(ownersDir, file), "utf8"));
+      if (record.ariaHome && resolve(record.ariaHome) === canonicalHome) {
+        return typeof record.runtimePid === "number" ? record.runtimePid : null;
+      }
+    } catch {
+      // Skip malformed records
+    }
+  }
+  return null;
+}
+
+export async function executeRestart(input: RestartInput, ctx: ToolContext): Promise<ToolResult> {
+  if (ctx.abortSignal?.aborted) return fail("Operation cancelled");
+
+  const supervised = process.env[NO_RELAUNCH_ENV] === "true";
+  const reason = (input.reason ?? "").trim() || "Restart requested";
+
+  // Note: tool definition has requiresConfirmation: true, so the framework
+  // already prompts the user before execute() is called. No need to confirm again.
+
+  process.stderr.write(`[aria] Rebuilding workspace before restart...\n`);
+  try {
+    const rebuilt = await rebuildWorkspaceIfPresent(ctx.workingDir || process.cwd());
+    if (!rebuilt.attempted) {
+      process.stderr.write(`[aria] No pnpm workspace detected; skipping build\n`);
+    }
+  } catch (error) {
+    process.stderr.write(`[aria] Build failed; continuing restart: ${(error as Error).message}\n`);
+  }
+
+  process.stderr.write(`[aria] Restarting: ${reason}\n`);
+
+  const sessionId = process.env[RESUME_SESSION_ENV] ?? null;
+  const arionName = process.env[RESUME_ARION_ENV] || "ARIA";
+
+  // Write disk-backed marker as durable fallback in case IPC is lost.
+  writeRelaunchMarker({
+    sessionId,
+    arionName,
+    pid: process.ppid || process.pid,
+    timestamp: new Date().toISOString(),
+  });
+
+  if (supervised) {
+    // Path 1: Supervised by parent-child relaunch loop (TUI mode).
+    // Pass session forward via IPC, then exit with magic code for parent to respawn.
+    try {
+      const send = (process as NodeJS.Process & { send?: (msg: unknown) => void }).send;
+      if (typeof send === "function") {
+        send({
+          type: "aria-relaunch",
+          resumeSessionId: sessionId,
+          arionName,
+        });
+      }
+    } catch {
+      // non-fatal — disk marker is the fallback
+    }
+    process.exit(RELAUNCH_EXIT_CODE);
+  } else {
+    // Path 2: Daemon mode — no supervisor loop.
+    // Register an 'exit' handler to spawn the replacement AFTER the singleton
+    // lock is released (beforeExit releases it). Then SIGINT ourselves to
+    // trigger graceful daemon shutdown. The SIGINT handler fires synchronously
+    // (just sets controller.abort()), so the tool can still return success.
+    const daemonPid = findDaemonPid() ?? process.pid;
+
+    process.once("exit", () => {
+      spawn(process.execPath, [...process.execArgv, ...process.argv.slice(1)], {
+        detached: true,
+        stdio: "ignore",
+      }).unref();
+    });
+
+    process.stderr.write(`[aria] Sending SIGINT to daemon pid ${daemonPid} for graceful restart\n`);
+    try {
+      process.kill(daemonPid, "SIGINT");
+    } catch {
+      // PID already dead or not our process — fall back to self
+      process.kill(process.pid, "SIGINT");
+    }
+  }
+
+  // Unreachable in supervised path (process.exit above), but returned in daemon path
+  return success("Restarting...");
+}

package/src/executors/search-types.ts

@@ -0,0 +1,98 @@
+/**
+ * Shared types and utilities for the unified search tool.
+ *
+ * Used by:
+ * - Base executor in @aria/tools (learning-meta.ts)
+ * - Runner wrapper in @aria/aria (search-wrapper.ts)
+ * - Tests
+ */
+
+/** Tagged search result — every result carries runnability info. */
+export interface SearchResult {
+  kind: "tool" | "skill" | "memory";
+  name: string;
+  description: string;
+  source:
+    | "memoria"
+    | "local"
+    | "local_cli"
+    | "builtin"
+    | "skills.sh"
+    | "clawhub"
+    | "npm"
+    | "brew"
+    | "web";
+  runnable: boolean;
+  action: "call" | "bash" | "read_skill" | "install" | "recall";
+  id?: string;
+  path?: string;
+  url?: string;
+  installCmd?: string;
+  installs?: number;
+  version?: string;
+  usageHint?: string;
+  /** Schema for injection (builtin source only, consumed by runner wrapper). */
+  _schema?: { name: string; description: string; parameters?: unknown };
+}
+
+/** OS context for platform-aware search and result metadata. */
+export interface OSContext {
+  os: "macos" | "linux" | "windows";
+  arch: string;
+  distro?: string;
+}
+
+/** Input for the unified search tool. */
+export interface SearchInput {
+  query: string;
+  sources?: Array<"memoria" | "local" | "local_cli" | "builtin" | "registry" | "web">;
+  limit?: number;
+  learn?: boolean;
+  adopt?: boolean;
+  rebuild_index?: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Shared dedup logic — single source of truth for both base executor and wrapper
+// ---------------------------------------------------------------------------
+
+/** Source priority for dedup (lower = higher priority). */
+export const SOURCE_PRIORITY: Record<SearchResult["source"], number> = {
+  builtin: 0,
+  local_cli: 1,
+  memoria: 2,
+  local: 3,
+  "skills.sh": 4,
+  clawhub: 5,
+  npm: 6,
+  brew: 7,
+  web: 8,
+};
+
+/**
+ * Dedup search results by name with source priority.
+ * When the same name appears from multiple sources, keep the higher-priority one.
+ */
+export function dedupSearchResults(results: SearchResult[], limit: number): SearchResult[] {
+  const deduped = new Map<string, SearchResult>();
+  for (const item of results) {
+    const normalizedName = item.name.trim().toLowerCase();
+    const existing = deduped.get(normalizedName);
+    if (!existing) {
+      deduped.set(normalizedName, item);
+    } else {
+      const existingPriority = SOURCE_PRIORITY[existing.source] ?? 99;
+      const newPriority = SOURCE_PRIORITY[item.source] ?? 99;
+      if (newPriority < existingPriority) {
+        deduped.set(normalizedName, item);
+      }
+    }
+  }
+  const sorted = [...deduped.values()].sort((a, b) => {
+    const aPriority = SOURCE_PRIORITY[a.source] ?? 99;
+    const bPriority = SOURCE_PRIORITY[b.source] ?? 99;
+    if (aPriority !== bPriority) return aPriority - bPriority;
+    return a.name.localeCompare(b.name);
+  });
+  return sorted.slice(0, limit);
+}