@hienlh/ppm 0.23.13 → 0.23.15

package/src/services/session-file-baselines/session-file-history.ts

@@ -27,6 +27,7 @@ import { isCredentialPath } from "../fs-credential-path-guard.ts";
 import { realPathOrSelf } from "../fs-ops/fs-real-path.ts";
 import { splitLines } from "../../shared/review-blocks.ts";
 import { BASELINE_MAX_BYTES, sessionDir, type BaselineSource } from "./session-file-baselines.service.ts";
+import { sessionFileWritten } from "./session-file-writes.ts";
 
 /** A log past this keeps only hashes: a file rewritten whole hundreds of times is not worth more. */
 export const HISTORY_MAX_FILE_BYTES = 16 * 1024 * 1024;
@@ -270,7 +271,7 @@ export function observeFile(sessionId: string, filePath: string, call: string, p
   if (isCredentialPath(path)) return Promise.resolve();
   const file = join(dir, logName(path));
   const at = Date.now();
-  return serialized(file, async () => {
+  const done = serialized(file, async () => {
     if (isCredentialPath(await realPathOrSelf(path))) return;
     const state = source === undefined ? await readState(path) : stateOf(source);
     if (!state) return;
@@ -300,6 +301,9 @@ export function observeFile(sessionId: string, filePath: string, call: string, p
       utimesSync(dirname(dir), now, now);
     } catch { /* pruned meanwhile: the next capture makes it again */ }
   });
+  // The call is done with the file: whoever keeps the session's list works this one out again.
+  if (phase === "after") void done.then(() => sessionFileWritten(sessionId, path));
+  return done;
 }
 
 /** Every path the session has a history for. */

package/src/services/session-file-baselines/session-file-writes.ts

@@ -0,0 +1,28 @@
+/**
+ * The moment a session's tool has finished changing a file — a file tool's PostToolUse, a shell
+ * command's `git status` bracket, a codex patch — announced by `observeFile`'s "after", which
+ * every one of those goes through. Its own module so the history can announce it without
+ * reaching the list that listens (`session-file-changes.service.ts`), which reads the history.
+ */
+type FileWrittenListener = (sessionId: string, path: string) => void;
+
+const listeners = new Set<FileWrittenListener>();
+
+/** Subscribe; returns the unsubscribe function. */
+export function onSessionFileWritten(cb: FileWrittenListener): () => void {
+  listeners.add(cb);
+  return () => {
+    listeners.delete(cb);
+  };
+}
+
+export function sessionFileWritten(sessionId: string, path: string): void {
+  for (const cb of listeners) {
+    // A failing listener must not turn a write the agent made into an error.
+    try {
+      cb(sessionId, path);
+    } catch (e) {
+      console.warn(`[session-baselines] file-written listener failed: ${(e as Error).message}`);
+    }
+  }
+}

package/src/services/sliding-window-limiter.ts

@@ -0,0 +1,106 @@
+/**
+ * A keyed sliding-window rate limiter with a bounded number of keys.
+ *
+ * Each key keeps the times of its recent hits (at most `max` of them), so a refusal says
+ * exactly how long until the oldest one ages out. `granularityMs` folds hits that land
+ * within that span of each other into one entry, which keeps a large budget (hundreds a
+ * minute) at a few dozen entries per key; 0 keeps every hit exact.
+ *
+ * Keys are kept in least-recently-used order and the oldest is dropped past `maxKeys`, so a
+ * caller that can mint keys at will (a forged client address) cannot grow the map without
+ * bound. Nothing sweeps the whole map: each key is pruned when it is touched.
+ */
+
+export interface WindowRule {
+  windowMs: number;
+  /** Hits allowed per window. */
+  max: number;
+  /** Least time between two hits of one key; 0 or absent for none. */
+  minIntervalMs?: number;
+  /** Hits this close to the previous entry share it; 0 or absent keeps each hit exact. */
+  granularityMs?: number;
+}
+
+export type LimitReason = "interval" | "window";
+
+export interface LimitRefusal {
+  reason: LimitReason;
+  /** How long until the same request would be allowed. */
+  retryMs: number;
+}
+
+interface Slot { t: number; n: number }
+interface KeyState { slots: Slot[]; count: number; last: number }
+
+export interface SlidingWindowLimiter {
+  /** Why `key` may not hit now, or null when it may. Counts nothing. */
+  check(key: string, now: number): LimitRefusal | null;
+  /** Count one hit for `key`, unconditionally. */
+  record(key: string, now: number): void;
+  /** {@link check}, then {@link record} when allowed. */
+  take(key: string, now: number): LimitRefusal | null;
+  reset(): void;
+  readonly size: number;
+}
+
+export function createSlidingWindowLimiter(rule: WindowRule, opts: { maxKeys: number }): SlidingWindowLimiter {
+  const minInterval = rule.minIntervalMs ?? 0;
+  const granularity = rule.granularityMs ?? 0;
+  const keys = new Map<string, KeyState>();
+
+  /** The key's live state with aged-out hits removed, or undefined when nothing is left. */
+  function live(key: string, now: number): KeyState | undefined {
+    const state = keys.get(key);
+    if (!state) return undefined;
+    let drop = 0;
+    while (drop < state.slots.length && now - state.slots[drop]!.t >= rule.windowMs) {
+      state.count -= state.slots[drop]!.n;
+      drop++;
+    }
+    if (drop) state.slots.splice(0, drop);
+    if (state.slots.length === 0 && now - state.last >= minInterval) {
+      keys.delete(key);
+      return undefined;
+    }
+    return state;
+  }
+
+  function check(key: string, now: number): LimitRefusal | null {
+    const state = live(key, now);
+    if (!state) return null;
+    if (minInterval && now - state.last < minInterval) return { reason: "interval", retryMs: minInterval - (now - state.last) };
+    if (state.count >= rule.max) return { reason: "window", retryMs: rule.windowMs - (now - state.slots[0]!.t) };
+    return null;
+  }
+
+  function record(key: string, now: number): void {
+    const state = live(key, now) ?? { slots: [], count: 0, last: now };
+    const tail = state.slots[state.slots.length - 1];
+    if (tail && granularity && now - tail.t < granularity) tail.n++;
+    else state.slots.push({ t: now, n: 1 });
+    state.count++;
+    state.last = now;
+    // Re-inserting moves the key to the most recent end.
+    keys.delete(key);
+    keys.set(key, state);
+    while (keys.size > opts.maxKeys) {
+      const oldest = keys.keys().next();
+      if (oldest.done) break;
+      keys.delete(oldest.value);
+    }
+  }
+
+  return {
+    check,
+    record,
+    take(key, now) {
+      const refusal = check(key, now);
+      if (!refusal) record(key, now);
+      return refusal;
+    },
+    reset: () => keys.clear(),
+    get size() {
+      return keys.size;
+    },
+  };
+}

package/src/services/tab-tools-mcp/open-url-tool.ts

@@ -0,0 +1,149 @@
+import { OPEN_URL_TOOL, type TabOpenAsk, type TabOpenUrlRequest } from "../../shared/tab-open-protocol.ts";
+import { textResult, type Json } from "../mcp-http-endpoint.ts";
+import { deviceError, type TabOpenOutcome } from "./tab-open-broker.ts";
+import type { TabToolsBinding } from "./tab-target.ts";
+
+/**
+ * `open_url`: a web server running on the host — a dev server, typically — in a web-preview tab
+ * on the user's device, the tab Port Forwarding opens.
+ *
+ * Only the host's own servers: the tool exists because a device cannot reach `localhost` on the
+ * host, not to put arbitrary sites inside PPM. A device reaches the server through a forward the
+ * user already runs for that port, else through a private Tailscale forward PPM starts (the
+ * tailnet's own devices only), else directly, which works only from a browser on the host. PPM
+ * never opens a public Cloudflare link for the AI: that is the user's call, in Port Forwarding.
+ * A chat may have PPM start forwards for a few ports only; the user forwards any more.
+ */
+
+/** How long a device has to say the tab is open. */
+export const OPEN_URL_WAIT_MS = 8_000;
+/** Ports one chat may have PPM forward privately; an agent cannot expose every port it finds. */
+export const MAX_FORWARDS_PER_CHAT = 4;
+
+type Via = TabOpenUrlRequest["via"];
+
+export interface LocalUrl {
+  protocol: "http:" | "https:";
+  port: number;
+  /** Path, query and fragment, as asked for: never joined as a string, which `//host` would escape. */
+  pathname: string;
+  search: string;
+  hash: string;
+}
+
+export interface OpenUrlDeps {
+  request: (sessionId: string, req: TabOpenAsk, waitMs: number) => Promise<TabOpenOutcome>;
+  /** Whether a server answers on this port on loopback. */
+  listening: (port: number) => Promise<boolean>;
+  /** The ports PPM itself answers on: a tab on PPM's own origin could read its token. */
+  ownPorts: () => number[];
+  /** A forward already running for this port. */
+  existingForward: (port: number) => { url: string; via: "tailscale" | "cloudflare" } | null;
+  /** Starts a private forward and answers its URL; throws why it could not. */
+  startPrivateForward: (port: number) => Promise<string>;
+  /** The chat a session id names now: Codex renames a new chat during its first turn. */
+  canonical?: (sessionId: string) => string;
+}
+
+const LOOPBACK_HOSTS = new Set(["localhost", "127.0.0.1", "[::1]", "0.0.0.0", "[::]"]);
+
+/** The page asked for, when it is one on this machine. */
+export function parseLocalUrl(input: unknown): { ok: true; url: LocalUrl } | { ok: false; error: string } {
+  if (typeof input !== "string" || !input.trim()) {
+    return { ok: false, error: "`url` is required: the page on this machine, such as http://localhost:5173/." };
+  }
+  if (input.length > 4096) return { ok: false, error: "`url` is too long." };
+  const given = input.trim();
+  const raw = /^\d{1,5}$/.test(given) ? `http://localhost:${given}/` : /^[a-z][a-z\d+.-]*:\/\//i.test(given) ? given : `http://${given}`;
+  let url: URL;
+  try {
+    url = new URL(raw);
+  } catch {
+    return { ok: false, error: `${given} is not a URL.` };
+  }
+  if (url.protocol !== "http:" && url.protocol !== "https:") return { ok: false, error: "Only an http or https page opens in a tab." };
+  if (!LOOPBACK_HOSTS.has(url.hostname) && !/^127(?:\.\d{1,3}){3}$/.test(url.hostname)) {
+    return {
+      ok: false,
+      error: `open_url shows servers running on this machine (localhost) only, and ${url.host} is not one. Give the user that link in your reply instead.`,
+    };
+  }
+  if (url.username || url.password) return { ok: false, error: "`url` must not carry a user name or password." };
+  const port = url.port ? Number(url.port) : url.protocol === "https:" ? 443 : 80;
+  return { ok: true, url: { protocol: url.protocol, port, pathname: url.pathname, search: url.search, hash: url.hash } };
+}
+
+/**
+ * The page at `origin`. The parts are set one by one: as a string, a path such as `//evil.com/`
+ * (from `http://localhost:5173//evil.com/`) is a URL of its own and would leave the forward.
+ */
+export function pageOn(origin: string, url: LocalUrl): string {
+  const page = new URL(origin);
+  page.pathname = url.pathname;
+  page.search = url.search;
+  page.hash = url.hash;
+  return page.href;
+}
+
+export function createOpenUrlTool(deps: OpenUrlDeps) {
+  const canonical = deps.canonical ?? ((sessionId: string) => sessionId);
+  /** Chat session id → the ports PPM has forwarded for it, a forward still starting included. */
+  const forwarded = new Map<string, Set<number>>();
+
+  /** The ports PPM forwarded for this chat, under the id it had then or has now. */
+  function forwardsOf(sessionId: string): Set<number> {
+    const chat = canonical(sessionId);
+    return new Set([...forwarded].filter(([key]) => canonical(key) === chat).flatMap(([, ports]) => [...ports]));
+  }
+
+  return async function openUrl(binding: TabToolsBinding, args: Record<string, unknown>): Promise<Json> {
+    const parsed = parseLocalUrl(args.url);
+    if (!parsed.ok) return textResult(parsed.error, true);
+    const { protocol, port } = parsed.url;
+    const asked = pageOn(`${protocol}//localhost:${port}/`, parsed.url);
+    if (deps.ownPorts().includes(port)) return textResult(`Port ${port} is PPM itself, which the user already has open.`, true);
+    if (!(await deps.listening(port))) {
+      return textResult(`Nothing is listening on port ${port} on this machine. Start the server first, wait until it says it is ready, then call open_url again.`, true);
+    }
+
+    let base = `${protocol}//localhost:${port}/`;
+    let via: Via = "local";
+    let how = "directly, which works because that device is this machine";
+    let forwardFailed: string | null = null;
+    const existing = deps.existingForward(port);
+    if (existing) {
+      ({ url: base, via } = existing);
+      how = `through the ${via === "tailscale" ? "private Tailscale" : "public Cloudflare"} forward the user already has for port ${port} (${existing.url})`;
+    } else {
+      const taken = forwardsOf(binding.sessionId);
+      if (!taken.has(port) && taken.size >= MAX_FORWARDS_PER_CHAT) {
+        forwardFailed = `this chat already had ${MAX_FORWARDS_PER_CHAT} ports forwarded, the most PPM starts for one chat`;
+      } else {
+        const ports = forwarded.get(binding.sessionId) ?? new Set<number>();
+        // Taken before the forward starts, so calls made together cannot pass the limit.
+        forwarded.set(binding.sessionId, ports.add(port));
+        try {
+          base = await deps.startPrivateForward(port);
+          via = "tailscale";
+          how = `through a private Tailscale forward PPM started for port ${port} (${base}), which only the user's own devices can open; it runs until stopped in Port Forwarding`;
+        } catch (e) {
+          ports.delete(port);
+          forwardFailed = (e as Error).message;
+        }
+      }
+    }
+    const url = via === "local" ? asked : pageOn(base, parsed.url);
+
+    const outcome = await deps.request(binding.sessionId, { tool: OPEN_URL_TOOL, url, port, via }, OPEN_URL_WAIT_MS);
+    if (!outcome.ok) return textResult(`${outcome.message} The page is ${asked}.`, true);
+    if (!outcome.result.opened) {
+      const fix = forwardFailed
+        ? ` PPM could not forward the port privately (${forwardFailed}); the user can forward it in Port Forwarding, or open ${asked} on this machine.`
+        : "";
+      return textResult(`The user's device could not open ${asked}: ${deviceError(outcome.result.error)}.${fix}`, true);
+    }
+    return textResult(`Opened ${asked} in a PPM tab on the user's device, ${how}. Nothing about the page comes back: check it with your own tools if you need to.`);
+  };
+}
+
+export type OpenUrlTool = ReturnType<typeof createOpenUrlTool>;

package/src/services/tab-tools-mcp/tab-open-broker.ts

@@ -1,5 +1,6 @@
 import { randomBytes } from "node:crypto";
-import type { TabOpenRequest, TabOpenResult } from "../../shared/tab-open-protocol.ts";
+import type { TabOpenAsk, TabOpenRequest, TabOpenResult } from "../../shared/tab-open-protocol.ts";
+import { neutralizeFences } from "../../shared/untrusted-text.ts";
 
 /**
  * The server half of the tab tools. Only a browser can open a tab, so a call is a round trip:
@@ -21,6 +22,10 @@ export type TabOpenOutcome =
   | { ok: true; result: TabOpenResult }
   | { ok: false; reason: "no-device" | "timeout" | "busy" | "rate-limited"; message: string };
 
+/** What a device said went wrong; it may quote a page, which the page's scripts wrote. */
+export const deviceError = (error: string | undefined): string =>
+  error ? neutralizeFences(error.replace(/[\u0000-\u001f\u007f]/g, " ")) : "it gave no reason";
+
 export const MAX_PENDING_TAB_OPENS = 64;
 export const MAX_TAB_OPENS_IN_FLIGHT_PER_SESSION = 4;
 export const MAX_TAB_OPENS_PER_MINUTE = 20;
@@ -66,7 +71,7 @@ export function createTabOpenBroker(opts: {
     return true;
   }
 
-  function request(asked: string, req: Omit<TabOpenRequest, "type" | "requestId">, waitMs: number): Promise<TabOpenOutcome> {
+  function request(asked: string, req: TabOpenAsk, waitMs: number): Promise<TabOpenOutcome> {
     const sessionId = canonical(asked);
     if (pending.size >= maxPending || inFlight(sessionId) >= maxInFlight) {
       return Promise.resolve({ ok: false, reason: "busy", message: "Too many tabs are already being opened for this chat; wait for them, then call again." });
@@ -85,7 +90,7 @@ export function createTabOpenBroker(opts: {
       pending.set(requestId, { sessionId, settle });
       let reached = 0;
       try {
-        reached = opts.deliver(sessionId, { type: "tab_open", requestId, ...req });
+        reached = opts.deliver(sessionId, { type: "tab_open", requestId, ...req } as TabOpenRequest);
       } catch (e) {
         console.warn(`[tab-tools] delivery failed for session=${sessionId}: ${(e as Error).message}`);
       }
@@ -129,7 +134,10 @@ export function setTabOpenDelivery(fn: TabOpenDelivery | null, canonical?: (sess
   resolveSession = canonical ?? ((sessionId) => sessionId);
 }
 
+/** The chat a session id names now, after any rename its provider made. */
+export const canonicalTabSession = (sessionId: string): string => resolveSession(sessionId);
+
 export const tabOpenBroker = createTabOpenBroker({
   deliver: (sessionId, req) => delivery?.(sessionId, req) ?? 0,
-  canonical: (sessionId) => resolveSession(sessionId),
+  canonical: canonicalTabSession,
 });

package/src/services/tab-tools-mcp/tab-tools-mcp-endpoint.ts

@@ -1,31 +1,37 @@
 import { resolve } from "node:path";
 import { configService } from "../config.service.ts";
 import { formatPreviewCheck } from "../../shared/design-canvas-check-format.ts";
-import { MAX_TAB_LINE, type TabOpenRequest } from "../../shared/tab-open-protocol.ts";
-import { neutralizeFences } from "../../shared/untrusted-text.ts";
+import { MAX_TAB_LINE, type TabOpenAsk } from "../../shared/tab-open-protocol.ts";
+import { isPpmTool, ppmToolOffMessage, ppmToolOn } from "../../shared/ppm-tools.ts";
+import { activeTunnels } from "../../server/routes/tunnel-spawn.ts";
 import { createMcpHttpHandler, imageBlock, textResult, type Json } from "../mcp-http-endpoint.ts";
-import { tabOpenBroker, type TabOpenOutcome } from "./tab-open-broker.ts";
+import { listeningLoopback } from "../port-forward/forward-hop.ts";
+import { listTailscaleForwards, startTailscaleForward } from "../port-forward/tailscale-forward.ts";
+import { localServerBaseUrl } from "../server-listen-address.ts";
+import { terminalService } from "../terminal.service.ts";
+import { createOpenUrlTool, type OpenUrlTool } from "./open-url-tool.ts";
+import { canonicalTabSession, deviceError, tabOpenBroker, type TabOpenOutcome } from "./tab-open-broker.ts";
 import { resolveTabTarget, type TabTarget, type TabTargetOutcome, type TabToolsBinding } from "./tab-target.ts";
 import { tabToolsMcpTokens, type TabToolsTokenBinding } from "./tab-tools-mcp-tokens.ts";
 import {
-  OPEN_FILE_TOOL, OPEN_FILE_TOOL_DEFINITION, OPEN_FILE_WAIT_MS, OPEN_PREVIEW_TOOL_DEFINITION, OPEN_PREVIEW_WAIT_MS,
+  OPEN_FILE_TOOL, OPEN_FILE_TOOL_DEFINITION, OPEN_FILE_WAIT_MS, OPEN_PREVIEW_TOOL, OPEN_PREVIEW_TOOL_DEFINITION,
+  OPEN_PREVIEW_WAIT_MS, OPEN_URL_TOOL, OPEN_URL_TOOL_DEFINITION, READ_TERMINAL_TOOL, READ_TERMINAL_TOOL_DEFINITION,
+  RUN_IN_TERMINAL_TOOL, RUN_IN_TERMINAL_TOOL_DEFINITION,
 } from "./tab-tools-mcp-tool.ts";
+import { createTerminalTools, type TerminalTools } from "./terminal-tools.ts";
 
 /**
- * `/api/tab-tools-mcp` — serves `open_file` and `open_preview` to one chat session's own
- * agent (the MCP plumbing is `mcp-http-endpoint.ts`). Its token can do exactly one thing:
- * open a tab on that session's devices, for a file the agent could already read. Nothing the
- * tab shows comes back except, for an HTML page, the check of how it rendered.
+ * `/api/tab-tools-mcp` — serves the tab tools to one chat session's own agent (the MCP plumbing
+ * is `mcp-http-endpoint.ts`): `open_file` and `open_preview` open a file the agent could already
+ * read, `open_url` a web server on the host, and `run_in_terminal` a terminal with a command
+ * typed in, all on that session's devices; `read_terminal` reads the terminals of the session's
+ * project. Nothing a tab shows comes back except, for an HTML page, the check of how it rendered.
  */
 
-type Request = (sessionId: string, req: Omit<TabOpenRequest, "type" | "requestId">, waitMs: number) => Promise<TabOpenOutcome>;
+type Request = (sessionId: string, req: TabOpenAsk, waitMs: number) => Promise<TabOpenOutcome>;
 
 const isObj = (v: unknown): v is Json => !!v && typeof v === "object" && !Array.isArray(v);
 
-/** What the device said went wrong; it may quote the page, which the page's scripts wrote. */
-const deviceError = (error: string | undefined): string =>
-  error ? neutralizeFences(error.replace(/[\u0000-\u001f\u007f]/g, " ")) : "it gave no reason";
-
 function failure(outcome: Extract<TabOpenOutcome, { ok: false }>, target: TabTarget): Json {
   if (outcome.reason === "no-device") {
     return textResult(`${outcome.message} The file is at ${target.displayPath}; tell the user where to find it.`, true);
@@ -38,7 +44,10 @@ export function createTabToolsMcpHandler(deps: {
   /** The session's project as it is now; relative paths resolve against it. */
   sessionProject: (sessionId: string) => Promise<Omit<TabToolsBinding, "sessionId">>;
   request: Request;
-  enabled: () => boolean;
+  /** Whether the user has this tool on (Settings → Tools). */
+  enabled: (tool: string) => boolean;
+  terminal: TerminalTools;
+  openUrl: OpenUrlTool;
   resolveTarget?: (input: unknown, binding: TabToolsBinding) => Promise<TabTargetOutcome>;
 }) {
   const resolveTarget = deps.resolveTarget ?? resolveTabTarget;
@@ -81,17 +90,22 @@ export function createTabToolsMcpHandler(deps: {
     serverName: "ppm-tabs",
     tokenRequired: "A chat session token is required",
     resolveToken: deps.resolveToken,
-    tools: [OPEN_FILE_TOOL_DEFINITION, OPEN_PREVIEW_TOOL_DEFINITION],
+    tools: [
+      OPEN_FILE_TOOL_DEFINITION, OPEN_PREVIEW_TOOL_DEFINITION, OPEN_URL_TOOL_DEFINITION,
+      READ_TERMINAL_TOOL_DEFINITION, RUN_IN_TERMINAL_TOOL_DEFINITION,
+    ],
+    unavailable: (name) => (deps.enabled(name) ? null : ppmToolOffMessage(name)),
     callTool: async ({ sessionId }, name, rawArgs) => {
-      // A chat keeps the tools it started with, so turning the setting off is enforced here.
-      if (!deps.enabled()) {
-        return textResult("The user turned off \"Let the AI open tabs in PPM\" in PPM's settings, so nothing was shown.", true);
-      }
       const binding: TabToolsBinding = { sessionId, ...(await deps.sessionProject(sessionId)) };
       const args = isObj(rawArgs) ? rawArgs : {};
+      if (name === OPEN_URL_TOOL) return deps.openUrl(binding, args);
+      if (name === READ_TERMINAL_TOOL) return deps.terminal.read(binding, args);
+      if (name === RUN_IN_TERMINAL_TOOL) return deps.terminal.run(binding, args);
       const resolved = await resolveTarget(args.path, binding);
       if (!resolved.ok) return textResult(resolved.error, true);
-      return name === OPEN_FILE_TOOL ? openFile(binding, resolved.target, args) : openPreview(binding, resolved.target, args);
+      if (name === OPEN_FILE_TOOL) return openFile(binding, resolved.target, args);
+      if (name === OPEN_PREVIEW_TOOL) return openPreview(binding, resolved.target, args);
+      return textResult(`Unknown tool: ${name}`, true);
     },
   });
 }
@@ -108,9 +122,39 @@ async function sessionProject(sessionId: string): Promise<Omit<TabToolsBinding,
   return { projectPath, projectName };
 }
 
+/** The ports PPM itself answers on: the configured one, and the server's own behind the supervisor. */
+function ppmPorts(): number[] {
+  const base = localServerBaseUrl();
+  return [configService.get("port"), base ? Number(new URL(base).port) : 0].filter((port) => Number.isInteger(port) && port > 0);
+}
+
+/** The forward the user already runs for a port: a private Tailscale one before a public quick tunnel. */
+export function existingForwardFor(
+  port: number,
+  tailscale: ReadonlyArray<{ port: number; url: string }> = listTailscaleForwards(),
+  quick: ReadonlyMap<number, { url: string }> = activeTunnels,
+): { url: string; via: "tailscale" | "cloudflare" } | null {
+  const forward = tailscale.find((f) => f.port === port);
+  if (forward) return { url: forward.url, via: "tailscale" };
+  const tunnel = quick.get(port);
+  return tunnel ? { url: tunnel.url, via: "cloudflare" } : null;
+}
+
+const request: Request = (sessionId, req, waitMs) => tabOpenBroker.request(sessionId, req, waitMs);
+const enabled = (tool: string): boolean => isPpmTool(tool) && ppmToolOn(configService.get("ai"), tool);
+
 export const tabToolsMcpHandler = createTabToolsMcpHandler({
   resolveToken: (token) => tabToolsMcpTokens.resolve(token),
   sessionProject,
-  request: (sessionId, req, waitMs) => tabOpenBroker.request(sessionId, req, waitMs),
-  enabled: () => configService.get("ai").tab_tools === true,
+  request,
+  enabled,
+  terminal: createTerminalTools({ terminals: terminalService, request, enabled, canonical: canonicalTabSession }),
+  openUrl: createOpenUrlTool({
+    request,
+    canonical: canonicalTabSession,
+    listening: async (port) => (await listeningLoopback(port)) !== null,
+    ownPorts: ppmPorts,
+    existingForward: (port) => existingForwardFor(port),
+    startPrivateForward: async (port) => (await startTailscaleForward(port)).url,
+  }),
 });

package/src/services/tab-tools-mcp/tab-tools-mcp-tokens.ts

@@ -4,7 +4,9 @@ import type { TabToolsMcpAccess } from "./tab-tools-mcp-tool.ts";
 
 /**
  * Capability tokens for the tab-tools MCP endpoint, one per chat session (see
- * `mcp-session-tokens.ts`). A token can only open tabs on that one session's devices.
+ * `mcp-session-tokens.ts`). A token acts for that one session only: it opens tabs on the
+ * session's devices, reads the terminals its chat may read, and types — never runs — a command
+ * into a terminal it opened.
  *
  * It names the session and nothing else — the project is looked up when a tool is called —
  * so the token a warm CLI is started with, before its session has a project, is the one the

package/src/services/tab-tools-mcp/tab-tools-mcp-tool.ts

@@ -1,14 +1,16 @@
 import { DESIGN_CDN_HOSTS } from "../../shared/design-cdn-hosts.ts";
-import { OPEN_FILE_TOOL, OPEN_PREVIEW_TOOL } from "../../shared/tab-open-protocol.ts";
+import {
+  OPEN_FILE_TOOL, OPEN_PREVIEW_TOOL, OPEN_URL_TOOL, READ_TERMINAL_TOOL, RUN_IN_TERMINAL_TOOL,
+} from "../../shared/tab-open-protocol.ts";
 
 /**
- * The two tools the tab-tools MCP endpoint serves. The names each provider knows them by are
- * in `tab-open-protocol.ts`, because the chat's tool cards need them too.
+ * The tools the tab-tools MCP endpoint serves. The names each provider knows them by are in
+ * `tab-open-protocol.ts`, because the chat's tool cards need them too.
  */
 
 export {
-  OPEN_FILE_TOOL, OPEN_PREVIEW_TOOL, CLAUDE_TAB_TOOLS_MCP_SERVER, CLAUDE_OPEN_FILE_TOOL, CLAUDE_OPEN_PREVIEW_TOOL,
-  CODEX_TAB_TOOLS_MCP_SERVER,
+  OPEN_FILE_TOOL, OPEN_PREVIEW_TOOL, OPEN_URL_TOOL, READ_TERMINAL_TOOL, RUN_IN_TERMINAL_TOOL,
+  CLAUDE_TAB_TOOLS_MCP_SERVER, CLAUDE_OPEN_FILE_TOOL, CLAUDE_OPEN_PREVIEW_TOOL, CODEX_TAB_TOOLS_MCP_SERVER,
 } from "../../shared/tab-open-protocol.ts";
 /** Environment variable the Codex app-server reads the bearer token from. */
 export const CODEX_TAB_TOOLS_MCP_TOKEN_ENV = "PPM_TAB_TOOLS_MCP_TOKEN";
@@ -20,7 +22,13 @@ export const OPEN_FILE_WAIT_MS = 8_000;
  * 15 s for the load, 1.5 s for the page's scripts and up to 15 s for the check itself.
  */
 export const OPEN_PREVIEW_WAIT_MS = 40_000;
-/** The providers' own timeout for a call; it must exceed the longest wait above. */
+/** Lines `read_terminal` reads from the end unless the call asks otherwise, and at most. */
+export const READ_TERMINAL_DEFAULT_LINES = 100;
+export const READ_TERMINAL_MAX_LINES = 1_000;
+/**
+ * The providers' own timeout for a call; it must exceed the longest wait above, and
+ * `open_url`'s Tailscale forward (up to 10 s) followed by its device's 8 s.
+ */
 export const TAB_TOOLS_TIMEOUT_MS = 60_000;
 
 /** How a provider reaches the endpoint for one session; built by `chatService` per turn. */
@@ -76,3 +84,67 @@ export const OPEN_PREVIEW_TOOL_DEFINITION = {
   },
   annotations: { readOnlyHint: true, openWorldHint: false },
 };
+
+export const OPEN_URL_TOOL_DEFINITION = {
+  name: OPEN_URL_TOOL,
+  title: "Show a running web app in PPM",
+  description:
+    "Show a web server running on this machine, such as a dev server at http://localhost:5173, in a PPM tab on the "
+    + "device the user is chatting from. On a phone or another computer PPM reaches it through a private Tailscale "
+    + "forward when the host has Tailscale. Call it once the server is up, so the user watches the app while you "
+    + "work on it. Only this machine's own servers: give the user any other link in your reply. Nothing about the "
+    + "page comes back; check it with your own tools if you need to.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      url: { type: "string", description: "The page on this machine, such as http://localhost:5173/admin, or just its port." },
+    },
+    required: ["url"],
+    additionalProperties: false,
+  },
+  annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false },
+};
+
+export const READ_TERMINAL_TOOL_DEFINITION = {
+  name: READ_TERMINAL_TOOL,
+  title: "Read a PPM terminal",
+  description:
+    "Read what a terminal open in PPM printed, as its screen shows it: a dev server's log, a test run, the error "
+    + "the user is looking at. Use it when the user mentions their terminal, instead of asking them to paste from "
+    + "it. It reads the terminals started in this chat's project folder and the ones run_in_terminal opened. "
+    + "Without `terminal`, a single terminal comes back whole and several come back as a list, each with its id "
+    + "and last lines. PPM keeps the last 1 MB of each terminal's output.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      terminal: { type: "string", description: "A terminal's id, as read_terminal or run_in_terminal gave it." },
+      lines: {
+        type: "integer", minimum: 1, maximum: READ_TERMINAL_MAX_LINES,
+        description: `Lines to read, from the end (default ${READ_TERMINAL_DEFAULT_LINES}).`,
+      },
+    },
+    additionalProperties: false,
+  },
+  annotations: { readOnlyHint: true, openWorldHint: false },
+};
+
+export const RUN_IN_TERMINAL_TOOL_DEFINITION = {
+  name: RUN_IN_TERMINAL_TOOL,
+  title: "Type a command into a PPM terminal",
+  description:
+    "Open a new terminal in PPM on the device the user is chatting from, with a shell command typed at its prompt. "
+    + "Nothing runs until the user presses Enter, so use it for what you should not or cannot run yourself: a "
+    + "command that needs sudo or a password, signs in interactively, or that the user wants to run themselves. "
+    + "Run everything else with your own shell tool. One line only: join steps with && or ;. The result names the "
+    + "terminal, so read_terminal can read what the command printed once the user has run it.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      command: { type: "string", description: "The command, on one line." },
+      cwd: { type: "string", description: "Folder the shell starts in: absolute, or relative to the project folder (default: the project folder)." },
+    },
+    required: ["command"],
+    additionalProperties: false,
+  },
+  annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false },
+};

package/src/services/tab-tools-mcp/terminal-text.ts

@@ -0,0 +1,45 @@
+import { Terminal } from "@xterm/headless";
+
+/**
+ * A terminal's output as text, the way its screen shows it. The server keeps what a shell
+ * printed as raw bytes (`terminalService`'s buffer); replaying them through xterm's own parser
+ * — headless, the one the browser runs — applies every carriage return, cursor move and erase.
+ * A progress bar is then its last state, and a line editor's redraws are the line the user
+ * typed: stripping escapes instead keeps every suggestion zsh drew and erased on the way, and
+ * those quote the shell's history (measured with zsh-autosuggestions: a stripped
+ * `echo hello world` read back with pieces of two unrelated history entries spliced into it).
+ */
+
+export interface TerminalScreen {
+  /** Oldest first. A row the terminal wrapped is joined back to the line it continues. */
+  lines: string[];
+  /** A full-screen program (an editor, `top`) has the screen: `lines` is that screen alone. */
+  fullScreen: boolean;
+}
+
+/** More rows than the 1 MB buffer can fill at any usable width. */
+const SCROLLBACK = 100_000;
+
+const clamp = (n: number, min: number, max: number): number => Math.min(max, Math.max(min, Math.floor(n) || min));
+
+/** Replays `raw` on a terminal of the PTY's size. Measured: 1 MB of colored log lines in ~35 ms. */
+export async function renderTerminal(raw: string, cols: number, rows: number): Promise<TerminalScreen> {
+  const term = new Terminal({ cols: clamp(cols, 20, 1000), rows: clamp(rows, 2, 500), scrollback: SCROLLBACK });
+  try {
+    await new Promise<void>((done) => term.write(raw, done));
+    const buffer = term.buffer.active;
+    const lines: string[] = [];
+    for (let i = 0; i < buffer.length; i++) {
+      const line = buffer.getLine(i);
+      if (!line) continue;
+      // A row the next one continues runs to the edge: its trailing spaces are the line's own.
+      const text = line.translateToString(!buffer.getLine(i + 1)?.isWrapped);
+      if (line.isWrapped && lines.length > 0) lines[lines.length - 1] += text;
+      else lines.push(text);
+    }
+    while (lines.length > 0 && !lines[lines.length - 1]!.trim()) lines.pop();
+    return { lines, fullScreen: buffer.type === "alternate" };
+  } finally {
+    term.dispose();
+  }
+}