arona-agent 1.0.0

package/src/slash_menu.ts

@@ -0,0 +1,371 @@
+/**
+ * 斜杠命令候选菜单。
+ *
+ * 参考 opencode-source/packages/tui/src/component/prompt/autocomplete.tsx 的
+ * 状态机思路（visible/selected/scrollTop + 循环选择 + 视口滚动），但用原生
+ * ANSI 实现，不依赖 SolidJS/OpenTUI 框架。
+ *
+ * 关键设计：
+ * - 菜单画在 readline 提示符下方，带完整边框浮层。
+ * - 用「相对光标移动」管理位置（\r\n 下移、\x1b[NA 上移），不依赖 DECSC/DECRC
+ *   的绝对位置——后者在菜单导致终端滚动时会失效（保存的坐标被滚动打乱），
+ *   从而造成菜单堆积。相对移动天然抗滚动。
+ * - 每行用 \r\n 分隔，确保每行回到第 1 列；画完后上移 lineCount 行回到提示行，
+ *   再调 rl.prompt(true) 让 readline 重新渲染提示行并校正光标列。
+ * - Enter 补全时整体替换 rl.line（旧实现用 rl.write 追加，导致 /re/resume 重复）；
+ *   若已敲完命令名、正在补参数（首 token = 完整名/别名），则保留原行只关菜单。
+ */
+
+import chalk from "chalk";
+import type { Interface } from "readline";
+import { SLASH_COMMANDS, resolveSlashCommand, type SlashCommandSpec } from "./slash_registry.ts";
+import { t } from "./locale.ts";
+
+const MAX_VISIBLE = 8;
+
+// ── 显示宽度工具（CJK/全角算 2，控制符算 0）──────────────────────
+function charWidth(code: number): number {
+  if (code < 0x20) return 0;
+  if (
+    code >= 0x1100 &&
+    (code <= 0x115f ||
+      (code >= 0x2e80 && code <= 0x303e) ||
+      (code >= 0x3040 && code <= 0x33bf) ||
+      (code >= 0x3400 && code <= 0x4dbf) ||
+      (code >= 0x4e00 && code <= 0xa4cf) ||
+      (code >= 0xac00 && code <= 0xd7af) ||
+      (code >= 0xf900 && code <= 0xfaff) ||
+      (code >= 0xfe30 && code <= 0xfe6f) ||
+      (code >= 0xff01 && code <= 0xff60) ||
+      (code >= 0xffe0 && code <= 0xffe6) ||
+      (code >= 0x1f300 && code <= 0x1f9ff))
+  ) {
+    return 2;
+  }
+  return 1;
+}
+
+function strWidth(s: string): number {
+  let w = 0;
+  for (const ch of s) w += charWidth(ch.codePointAt(0)!);
+  return w;
+}
+
+/** 去除 ANSI 颜色/光标转义序列，返回纯可见文本。 */
+function stripAnsi(s: string): string {
+  return s.replace(/\x1b(?:\[[0-9;?]*[A-Za-z]|[0-9])/g, "");
+}
+
+function padRight(s: string, width: number): string {
+  const w = strWidth(s);
+  return w >= width ? s : s + " ".repeat(width - w);
+}
+
+function truncateToWidth(s: string, width: number): string {
+  if (width <= 0) return "";
+  if (strWidth(s) <= width) return s;
+  let res = "";
+  let w = 0;
+  for (const ch of s) {
+    const cw = charWidth(ch.codePointAt(0)!);
+    if (w + cw > width - 1) break;
+    res += ch;
+    w += cw;
+  }
+  return res + "…";
+}
+
+// ── 模糊评分（子序列匹配 + 连续命中加分 + 前缀加权）──────────────
+function fuzzyScore(query: string, target: string): number {
+  if (!query) return 0;
+  const q = query.toLowerCase();
+  const t = target.toLowerCase();
+  let qi = 0;
+  let score = 0;
+  let prevMatch = false;
+  for (let ti = 0; ti < t.length && qi < q.length; ti++) {
+    if (t[ti] === q[qi]) {
+      score += prevMatch ? 5 : 1;
+      if (ti === 0) score += 8; // 前缀加权
+      qi++;
+      prevMatch = true;
+    } else {
+      prevMatch = false;
+    }
+  }
+  return qi === q.length ? score : -1;
+}
+
+function bestScore(query: string, spec: SlashCommandSpec): number {
+  const names = [spec.name, ...(spec.aliases ?? [])];
+  let best = -1;
+  for (const n of names) {
+    const s = fuzzyScore(query, n);
+    if (s > best) best = s;
+  }
+  return best;
+}
+
+// ── 菜单类 ───────────────────────────────────────────────────────
+export class SlashMenu {
+  private matches: SlashCommandSpec[] = [];
+  private selected = 0;
+  private scrollTop = 0;
+  private visible = false;
+  // 当前已画出的菜单行数（含边框与页脚）。用于 close 时定位要清除的区域。
+  private drawnLineCount = 0;
+  // 「本次填入不执行」信号：confirm() 在选中 needsParams 指令且实际替换了输入行时
+  // 置位，由 repl 的 line handler 消费（同一按键的 "line" 事件同步跟随，无泄漏）。
+  private pendingNoExec = false;
+
+  isOpen(): boolean {
+    return this.visible;
+  }
+
+  /** 供 repl 的 line handler 读取并清除「本次填入不执行」信号。 */
+  consumeNoExecSignal(): boolean {
+    const v = this.pendingNoExec;
+    this.pendingNoExec = false;
+    return v;
+  }
+
+  /**
+   * 根据当前 readline 缓冲区决定打开/关闭/更新菜单。用于普通按键后调用
+   *（readline 已先更新缓冲区）。
+   */
+  refresh(rl: Interface): void {
+    const line = (rl as any).line ?? "";
+    if (!line.startsWith("/")) {
+      if (this.visible) this.close(rl);
+      return;
+    }
+    const query = line.slice(1).split(/\s/)[0]; // 仅对第一个 token 做模糊
+    // 守卫：首 token 已是完整指令名/别名（已选定或正在输参数）→ 不弹菜单，
+    // 让输入框干净地留着指令。仅输入 "/" 时 query 为空，跳过守卫照常弹全部。
+    if (query && resolveSlashCommand(query)) {
+      if (this.visible) this.close(rl);
+      return;
+    }
+    if (query === "") {
+      this.setMatches(SLASH_COMMANDS.slice(), rl);
+      return;
+    }
+    const scored = SLASH_COMMANDS.map((spec) => ({ spec, s: bestScore(query, spec) }))
+      .filter((x) => x.s >= 0)
+      .sort((a, b) => b.s - a.s)
+      .map((x) => x.spec);
+    if (scored.length === 0) {
+      if (this.visible) this.close(rl);
+      return;
+    }
+    this.setMatches(scored, rl);
+  }
+
+  private setMatches(matches: SlashCommandSpec[], rl: Interface): void {
+    this.matches = matches;
+    this.selected = 0;
+    this.scrollTop = 0;
+    if (!this.visible) {
+      this.visible = true;
+    }
+    this.redraw(rl);
+  }
+
+  /** ↑/↓ 导航（循环）。 */
+  move(direction: -1 | 1, rl: Interface): void {
+    if (!this.visible || this.matches.length === 0) return;
+    let next = this.selected + direction;
+    if (next < 0) next = this.matches.length - 1;
+    if (next >= this.matches.length) next = 0;
+    this.selected = next;
+    this.clampScroll();
+    this.redraw(rl);
+  }
+
+  /**
+   * Enter：把选中命令写入输入框（整体替换 rl.line），然后让 readline 的
+   * return 处理自然 emit "line" 事件以执行命令。
+   *
+   * 时序（配合 repl.ts 里的 prependListener，本监听器先于 readline 执行）：
+   * 1. 本方法：eraseMenu 擦画面 + 重置状态 + 设置 rl.line = "/<name> "
+   * 2. readline 的 _onKeypress 处理 return → _onLine → emit "line" 带新值
+   * 3. repl 的 line handler 收到补全后的命令名并执行
+   *
+   * 注意：不能调 rl.prompt(true)——它的 clearScreenDown 会干扰，且会让
+   * readline 认为 return 前已重绘，可能跳过 emit "line"。
+   *
+   * needsParams 指令：填完不执行——置 pendingNoExec
+   * 信号，repl 的 line handler 消费后只重绘提示行，用户补参数再 Enter。
+   */
+  confirm(rl: Interface): void {
+    if (!this.visible) {
+      this.pendingNoExec = false;
+      return;
+    }
+    const spec = this.matches[this.selected];
+    const filled = this.fillSelected(rl);
+    this.pendingNoExec = !!(filled && spec?.needsParams);
+  }
+
+  /**
+   * → 键：把选中命令填入输入框，但不触发执行（无后续 return 事件，readline
+   * 不会 emit "line"）。与 confirm 的区别仅在「是否让执行发生」，填入逻辑共享
+   * fillSelected。填完手动 prompt(true) 重绘提示行——此流程没有后续按键来触发
+   * 重绘。参数保护同样生效：已在输参数时只关菜单保留原行。
+   */
+  complete(rl: Interface): void {
+    if (!this.visible) return;
+    this.fillSelected(rl);
+    (rl as any).prompt(true);
+  }
+
+  /**
+   * 擦菜单 + 重置状态 + 按选中项整体替换 rl.line（含参数保护）。返回是否真正
+   * 替换了行（false = 首 token 已是完整命令名/别名，参数输入中，保留原行）。
+   * 注意先读 spec 再重置 this.matches。
+   */
+  private fillSelected(rl: Interface): boolean {
+    const spec = this.matches[this.selected];
+    // 擦除菜单画面并重置状态
+    this.eraseMenu();
+    this.visible = false;
+    this.matches = [];
+    this.selected = 0;
+    this.scrollTop = 0;
+    this.drawnLineCount = 0;
+    if (!spec) return false;
+    const currentLine: string = (rl as any).line ?? "";
+    const currentToken = currentLine.startsWith("/") ? currentLine.slice(1).split(/\s/)[0] : "";
+    const names = [spec.name, ...(spec.aliases ?? [])];
+    if (names.includes(currentToken)) return false; // 参数输入中，保留原行
+    const replacement = spec.interactive ? `/${spec.name}` : `/${spec.name} `;
+    (rl as any).line = replacement;
+    (rl as any).cursor = replacement.length;
+    return true;
+  }
+
+  /** Esc / 外部关闭。保留已输入内容。 */
+  close(rl: Interface): void {
+    if (!this.visible) return;
+    this.eraseMenu();
+    this.visible = false;
+    this.matches = [];
+    this.selected = 0;
+    this.scrollTop = 0;
+    this.drawnLineCount = 0;
+    (rl as any).prompt(true);
+  }
+
+  // ── 渲染 ──────────────────────────────────────────────────────
+
+  private clampScroll(): void {
+    const maxVisible = this.maxVisible();
+    if (this.selected < this.scrollTop) this.scrollTop = this.selected;
+    else if (this.selected >= this.scrollTop + maxVisible) {
+      this.scrollTop = this.selected - maxVisible + 1;
+    }
+    // 防止 scrollTop 超出末尾窗口
+    const lastTop = Math.max(0, this.matches.length - maxVisible);
+    if (this.scrollTop > lastTop) this.scrollTop = lastTop;
+  }
+
+  private maxVisible(): number {
+    const rows = process.stdout.rows ?? 24;
+    return Math.max(3, Math.min(MAX_VISIBLE, rows - 6));
+  }
+
+  /**
+   * 擦除已绘制的菜单并回到提示行。调用时光标应在提示行（由上次 redraw 或
+   * readline 的按键处理留在那里）。用相对移动：下移 1 行到菜单顶 → 清到屏幕
+   * 末尾 → 上移 1 行回提示行。相对移动天然抗终端滚动。
+   */
+  private eraseMenu(): void {
+    if (this.drawnLineCount === 0) return;
+    process.stdout.write("\r\n"); // 回到第 1 列并下移 1 行（到菜单顶）
+    process.stdout.write("\x1b[0J"); // 清除从菜单顶到屏幕末尾
+    process.stdout.write("\x1b[1A"); // 上移 1 行回提示行
+    this.drawnLineCount = 0;
+  }
+
+  private redraw(rl: Interface): void {
+    if (!this.visible) return;
+    const cols = process.stdout.columns ?? 80;
+    const maxVisible = this.maxVisible();
+    const start = this.scrollTop;
+    const end = Math.min(this.matches.length, start + maxVisible);
+    const items = this.matches.slice(start, end);
+
+    // 计算列宽
+    const nameCols = items.map((s) => {
+      const alias = s.aliases?.length ? ` (${s.aliases.join(", ")})` : "";
+      return `/${s.name}${alias}`;
+    });
+    const maxNameW = Math.max(...nameCols.map(strWidth));
+    const descStart = 2 + maxNameW + 2; // marker(2) + name + gap(2)
+    let maxDescW = Math.max(...items.map((s) => strWidth(s.description)));
+
+    const maxInnerW = Math.max(20, cols - 6);
+    let innerW = descStart + maxDescW;
+    if (innerW > maxInnerW) {
+      innerW = maxInnerW;
+      maxDescW = Math.max(0, innerW - descStart);
+    }
+
+    const lines: string[] = [];
+    const border = chalk.cyan;
+    // 顶边
+    lines.push(border("┌" + "─".repeat(innerW + 2) + "┐"));
+    // 各项
+    for (let i = 0; i < items.length; i++) {
+      const spec = items[i];
+      const idx = start + i;
+      const nameCol = nameCols[i];
+      const marker = idx === this.selected ? "▶ " : "  ";
+      const gap = " ".repeat(descStart - 2 - strWidth(nameCol));
+      let desc = spec.description;
+      if (strWidth(desc) > maxDescW) desc = truncateToWidth(desc, maxDescW);
+      const content = marker + nameCol + gap + desc;
+      const padded = padRight(content, innerW);
+      // 选中行整行高亮（含边框），否则边框青色、内容默认色
+      const full =
+        idx === this.selected
+          ? chalk.bgCyan.black("┃ " + padded + " ┃")
+          : border("┃ ") + padded + border(" ┃");
+      lines.push(full);
+    }
+    // 底边
+    lines.push(border("└" + "─".repeat(innerW + 2) + "┘"));
+    // 页脚提示
+    const moreUp = this.scrollTop > 0;
+    const moreDown = this.scrollTop + maxVisible < this.matches.length;
+    let footer = t("  ↑/↓ 选择 · Enter 补全 · → 填入 · Esc 取消", "  ↑/↓ select · Enter complete · → fill · Esc cancel");
+    if (moreUp || moreDown) {
+      const ind = `${moreUp ? "↑" : ""}${moreDown ? "↓" : ""}`;
+      footer += t(`  · ${ind} 可滚动`, `  · ${ind} scrollable`);
+    }
+    lines.push(chalk.cyan(footer));
+
+    // ── 绘制（相对移动，抗滚动）──────────────────────────────────
+    // 光标当前在提示行。下移 1 行到菜单顶 → 清到屏幕末尾（擦旧菜单）→
+    // 画新菜单 → 回到提示行并定位光标到输入位置。
+    //
+    // 关键：不能调 rl.prompt(true)！readline 的 _refreshLine 会执行
+    // clearScreenDown（\x1b[J 清到屏幕末尾），把刚画的菜单整个擦掉。
+    // 改为手动把光标定位到「prompt 宽度 + cursor」列，让光标停在输入
+    // 末尾，readline 下次按键时会自行重绘提示行。
+    process.stdout.write("\r\n"); // 回到第 1 列并下移 1 行（末行会滚动）
+    process.stdout.write("\x1b[0J"); // 清除从菜单顶到屏幕末尾（擦旧菜单）
+    // 画各行，用 \r\n 分隔确保每行回到第 1 列
+    process.stdout.write(lines.join("\r\n"));
+    // 光标现在在最后一行末尾；回到提示行第 1 列
+    const lineCount = lines.length;
+    process.stdout.write("\r\x1b[" + lineCount + "A");
+    this.drawnLineCount = lineCount;
+    // 光标右移到输入位置：prompt 可见宽度 + cursor。
+    // 注意 prompt 可能带 ANSI 颜色转义（如 chalk.cyan("❯ ")），必须先 strip
+    // 否则转义里的 [36m 等可见字符会被算进宽度，导致光标右移过多。
+    const promptStr = stripAnsi(String((rl as any)._prompt ?? ""));
+    const targetCol = strWidth(promptStr) + ((rl as any).cursor ?? 0);
+    if (targetCol > 0) process.stdout.write("\x1b[" + targetCol + "C");
+  }
+}

package/src/slash_registry.ts

@@ -0,0 +1,53 @@
+/**
+ * Slash command registry shared by the completion menu and the dispatcher.
+ *
+ * Each command has a primary name, optional aliases, and a Chinese description
+ * shown in the menu. Add new commands here and they'll automatically appear
+ * in the / menu AND be dispatchable by /name or /alias.
+ */
+
+import { t } from "./locale.ts";
+
+export interface SlashCommandSpec {
+  name: string;
+  aliases?: string[];
+  description: string;
+  // When true, the command takes over the line (e.g. /resume opens an
+  // interactive picker that uses raw-mode keypresses). The menu should
+  // not auto-append a space after these commands.
+  interactive?: boolean;
+  // When true, Enter in the menu fills the command into the input line
+  // WITHOUT executing it, so the user can type the required argument
+  // and press Enter again. Set for every argument-taking command.
+  needsParams?: boolean;
+}
+
+export const SLASH_COMMANDS: SlashCommandSpec[] = [
+  { name: "help", aliases: ["?"], description: t("显示命令列表", "Show command list") },
+  { name: "exit", aliases: ["quit", "q"], description: t("退出（仅在有实际对话时保存会话）", "Exit (saves session only after a real conversation)") },
+  { name: "new", aliases: ["clear"], description: t("开始新会话（清空上下文）", "Start a new session (clear context)") },
+  { name: "resume", aliases: ["r"], description: t("上下键选择并恢复一个已保存的会话", "Pick and resume a saved session with arrow keys"), interactive: true },
+  { name: "export", description: t("导出当前会话为 Markdown", "Export current session as Markdown") },
+  { name: "thinking", description: t("开关思考/推理块显示", "Toggle thinking/reasoning block display") },
+  { name: "details", description: t("开关工具执行详情显示", "Toggle tool execution detail display") },
+  { name: "compact", description: t("压缩当前上下文以节省 token", "Compact current context to save tokens") },
+  { name: "tts", description: t("开关文字转语音", "Toggle text-to-speech") },
+  { name: "stt", description: t("开关语音转文字（长按右 Cmd ≥2秒录音）", "Toggle speech-to-text (hold right Cmd ≥2s to record)") },
+  { name: "skill", description: t("调用技能（/skill <名称>）", "Invoke a skill (/skill <name>)") },
+  { name: "mcp", description: t("管理 MCP 服务器和工具", "Manage MCP servers and tools") },
+  { name: "change-agent", description: t("切换主 Agent + 多选子 Agent", "Switch main agent + multi-select sub agents"), interactive: true },
+  { name: "undo", description: t("撤销上一个回合的全部文件改动（本地快照）", "Undo the previous turn's file changes (local snapshot)") },
+  { name: "redo", description: t("重做已撤销的改动", "Redo undone changes") },
+];
+
+/**
+ * Resolve a typed command (without leading `/`) to its spec. Matches against
+ * the primary name and any alias. Returns null if not found.
+ */
+export function resolveSlashCommand(typed: string): SlashCommandSpec | null {
+  for (const spec of SLASH_COMMANDS) {
+    if (spec.name === typed) return spec;
+    if (spec.aliases?.includes(typed)) return spec;
+  }
+  return null;
+}

package/src/speaker_context.ts

@@ -0,0 +1,41 @@
+// 群聊发言者标注扩展：每次 LLM 调用前（context 事件）触发，给带 speaker 标记的
+// assistant 历史消息文本加上「角色名：」前缀，让模型能区分"哪句话是谁说的"。
+//
+// 为什么需要它：SDK 序列化请求时只取 role + content（pi-ai convertMessages），
+// 项目自定义的 speaker 字段不会发给模型 —— 必须把发言者编码进文本才能让模型区分。
+//
+// 关键性质：只作用于发送边界。扩展返回新数组（不改 state.messages），
+// 因此存储 / 渲染 / TTS / 会话存档全部保持纯文本，前缀零污染。
+// 当前正在生成的 assistant 回复没有 speaker，不会被加前缀（模型知道自己说什么）。
+
+import type { ContextEvent, ExtensionAPI, InlineExtension } from "@earendil-works/pi-coding-agent";
+import { getAgentLabel, type AgentId } from "./agent_registry.ts";
+
+/** speaker 是项目自定义字段（repl.ts 回填时标记），不在 SDK 的 AgentMessage 类型上。 */
+interface SpeakerMessage {
+  role: "assistant";
+  speaker?: string;
+  content?: Array<{ type: string; text?: string; [k: string]: unknown }>;
+}
+
+export const speakerContextExtension: InlineExtension = {
+  name: "arona-speaker-context",
+  hidden: true, // 不显示在启动扩展列表
+  factory: (pi: ExtensionAPI) => {
+    pi.on("context", (event: ContextEvent) => {
+      const messages = event.messages.map((m) => {
+        const speaker = (m as unknown as SpeakerMessage).speaker;
+        if (m.role !== "assistant" || !speaker || !Array.isArray(m.content)) return m;
+        const label = getAgentLabel(speaker as AgentId);
+        if (!label) return m;
+        return {
+          ...m,
+          content: m.content.map((b) =>
+            b.type === "text" && b.text?.trim() ? { ...b, text: `${label}：${b.text}` } : b,
+          ),
+        };
+      });
+      return { messages };
+    });
+  },
+};

package/src/text_split.ts

@@ -0,0 +1,79 @@
+/**
+ * 流式文本切句工具：renderer 气泡与 TTS 共用同一套算法。
+ *
+ * 规则：
+ * - 只在句子终止标点（中文。！？… / 英文 . ! ? / 换行）处切句，连续终止标点归入同一条。
+ * - 英文句点 "." 仅当后跟空白/换行/中文/中文标点/串尾时才视为句末，
+ *   避免把小数点/版本号（"3.12"、"qwen-audio-3.0"）误切。
+ * - 逗号族（，、；：,;:）不做句边界，保留在句内交给 TTS 引擎自行处理停顿，
+ *   避免把"好好吃饭哦，Sensei"拆成碎句破坏语气。
+ * - 连续无标点超过 forceLen 字时，按 forceLen 强切，避免长文本滞留。
+ * - 返回本次可输出的完整句子和剩余残段（等待后续 delta 或 isEnd 收尾）。
+ */
+const SENTENCE_END = /[。！？!?\n…]/;
+
+/** 判断 buffer[i]（英文句点）是否为句末：后跟空白/换行/中文/中文标点/串尾才算，否则视为小数点或缩写。 */
+function isPeriodEnd(buffer: string, i: number): boolean {
+  if (buffer[i] !== ".") return false;
+  const next = buffer[i + 1];
+  if (next === undefined) return true;
+  if (/\s/.test(next)) return true;
+  if (/[。！？!?…，、；：]/.test(next)) return true;
+  if (/[\u4e00-\u9fff]/.test(next)) return true;
+  return false;
+}
+
+/** CJK 表意文字（含扩展 A 区与兼容区）：字数统计中每个字符算 1 字。 */
+const CJK_RE = /[\u4e00-\u9fff\u3400-\u4dbf\uf900-\ufaff]/g;
+
+export interface SplitStreamedTextResult {
+  sentences: string[];
+  rest: string;
+}
+
+/**
+ * 统计"朗读/气泡字数"：中文字符每个算 1，英文/数字按空白切分的连续串每个算 1
+ * （一个英文单词算一个字），中英文标点与符号不计入。
+ */
+export function countTextUnits(text: string): number {
+  // 去掉所有标点符号（仅保留字母、数字、空白与 CJK）
+  const noPunct = text.replace(/[^\p{L}\p{N}\s]/gu, "");
+  const cjkCount = (noPunct.match(CJK_RE) || []).length;
+  const latinPart = noPunct.replace(CJK_RE, " ");
+  const words = latinPart.trim().split(/\s+/).filter(Boolean).length;
+  return cjkCount + words;
+}
+
+export function splitStreamedText(buffer: string, forceLen: number): SplitStreamedTextResult {
+  const sentences: string[] = [];
+  let current = "";
+
+  for (let i = 0; i < buffer.length; i++) {
+    const ch = buffer[i];
+    current += ch;
+
+    const isEnd = SENTENCE_END.test(ch) || isPeriodEnd(buffer, i);
+
+    if (isEnd) {
+      // 连续终止标点（如“！！”、“…”、句点+空格）与当前句一起输出，避免产生只有标点的碎句
+      while (i + 1 < buffer.length) {
+        const nx = buffer[i + 1];
+        if (SENTENCE_END.test(nx) || nx === "." || nx === " ") {
+          current += nx;
+          i++;
+        } else {
+          break;
+        }
+      }
+      const sent = current.trim();
+      if (sent) sentences.push(sent);
+      current = "";
+    } else if (current.length >= forceLen) {
+      const sent = current.trim();
+      if (sent) sentences.push(sent);
+      current = "";
+    }
+  }
+
+  return { sentences, rest: current };
+}

package/src/tools/computer_use.ts

@@ -0,0 +1,142 @@
+import { Type } from "typebox";
+import { defineTool } from "@earendil-works/pi-coding-agent";
+import { PythonBridge } from "../utils/python.ts";
+import { config } from "../config.ts";
+
+let bridge: PythonBridge | null = null;
+
+async function getBridge(): Promise<PythonBridge> {
+  if (!bridge || !bridge.isRunning) {
+    bridge = new PythonBridge("computer_use.py", [], {
+      CUA_API_KEY: config.cuaApiKey,
+    });
+    await bridge.start();
+  }
+  return bridge;
+}
+
+function imageResult(screenshot: string) {
+  return {
+    content: [
+      { type: "text" as const, text: `Screenshot captured (${Math.round(screenshot.length / 1024)} KB).` },
+      { type: "image" as const, data: screenshot, mimeType: "image/png" },
+    ],
+    details: {},
+  };
+}
+
+export const computerScreenshot = defineTool({
+  name: "computer_screenshot",
+  label: "Screenshot",
+  description: "Take a screenshot of the current screen. Returns the screenshot as an image.",
+  parameters: Type.Object({}),
+  execute: async () => {
+    const b = await getBridge();
+    const result = await b.send({ action: "screenshot" });
+    if (result.error) throw new Error(result.error);
+    return imageResult(result.screenshot);
+  },
+});
+
+export const computerClick = defineTool({
+  name: "computer_click",
+  label: "Click",
+  description: "Click at the specified coordinates on the screen. Returns a new screenshot after clicking.",
+  parameters: Type.Object({
+    x: Type.Number({ description: "X coordinate" }),
+    y: Type.Number({ description: "Y coordinate" }),
+    button: Type.Optional(Type.Union([Type.Literal("left"), Type.Literal("right"), Type.Literal("double")], { description: "Mouse button (default: left)" })),
+  }),
+  execute: async (_id, params) => {
+    const b = await getBridge();
+    const result = await b.send({ action: "click", x: params.x, y: params.y, button: params.button || "left" });
+    if (result.error) throw new Error(result.error);
+    return imageResult(result.screenshot);
+  },
+});
+
+export const computerType = defineTool({
+  name: "computer_type",
+  label: "Type Text",
+  description: "Type text at the current cursor position. Returns a new screenshot after typing.",
+  parameters: Type.Object({
+    text: Type.String({ description: "Text to type" }),
+  }),
+  execute: async (_id, params) => {
+    const b = await getBridge();
+    const result = await b.send({ action: "type", text: params.text });
+    if (result.error) throw new Error(result.error);
+    return imageResult(result.screenshot);
+  },
+});
+
+export const computerKey = defineTool({
+  name: "computer_key",
+  label: "Press Keys",
+  description: "Press a key combination (e.g. ['ctrl', 'c']). Returns a new screenshot after pressing.",
+  parameters: Type.Object({
+    keys: Type.Array(Type.String(), { description: "Keys to press, e.g. ['ctrl', 'c'] or ['enter']" }),
+  }),
+  execute: async (_id, params) => {
+    const b = await getBridge();
+    const result = await b.send({ action: "key", keys: params.keys });
+    if (result.error) throw new Error(result.error);
+    return imageResult(result.screenshot);
+  },
+});
+
+export const computerScroll = defineTool({
+  name: "computer_scroll",
+  label: "Scroll",
+  description: "Scroll at the specified coordinates. Returns a new screenshot after scrolling.",
+  parameters: Type.Object({
+    x: Type.Number({ description: "X coordinate" }),
+    y: Type.Number({ description: "Y coordinate" }),
+    direction: Type.Optional(Type.Union([Type.Literal("up"), Type.Literal("down")], { description: "Scroll direction (default: down)" })),
+    amount: Type.Optional(Type.Number({ description: "Scroll amount in clicks (default: 3)" })),
+  }),
+  execute: async (_id, params) => {
+    const b = await getBridge();
+    const result = await b.send({
+      action: "scroll",
+      x: params.x,
+      y: params.y,
+      direction: params.direction || "down",
+      amount: params.amount || 3,
+    });
+    if (result.error) throw new Error(result.error);
+    return imageResult(result.screenshot);
+  },
+});
+
+export const computerMove = defineTool({
+  name: "computer_move",
+  label: "Move Mouse",
+  description: "Move the mouse to the specified coordinates. Returns a new screenshot after moving.",
+  parameters: Type.Object({
+    x: Type.Number({ description: "X coordinate" }),
+    y: Type.Number({ description: "Y coordinate" }),
+  }),
+  execute: async (_id, params) => {
+    const b = await getBridge();
+    const result = await b.send({ action: "move", x: params.x, y: params.y });
+    if (result.error) throw new Error(result.error);
+    return imageResult(result.screenshot);
+  },
+});
+
+export function stopComputerUse(): void {
+  if (bridge) {
+    bridge.stop();
+    bridge = null;
+  }
+}
+
+export const computerUseTools = [
+  computerScreenshot,
+  computerClick,
+  computerType,
+  computerKey,
+  computerScroll,
+  computerMove,
+];