@priyanshumit/macos-terminal-mcp 0.5.1 → 0.6.1

package/README.md

@@ -14,7 +14,7 @@ A local MCP server that lets AI agents inspect and drive your macOS Terminal.app
 
 ## What it does
 
-Twelve MCP tools across three categories:
+Fifteen MCP tools across four categories:
 
 ### Terminal interaction
 
@@ -25,6 +25,8 @@ Twelve MCP tools across three categories:
 | `terminal_execute` | **write** | Type a command into a specific tab and press Enter. Refuses if the target tab is busy unless `force=true`. `dry_run=true` returns the safety verdict without any side effects. |
 | `terminal_clear` | **write** | Wipe scrollback of a specific tab via Cmd+K. Briefly steals focus. |
 | `terminal_new_tab` | **write** | Open a new empty tab in Terminal.app and return its tty for follow-up calls. No dialog — low blast radius (user can close the tab). |
+| `terminal_close_tab` | **write** | Close a specific tab by tty. Refuses busy tabs unless `force=true`. No dialog. |
+| `terminal_wait_for_idle` | read | Block until the target tab is no longer busy, or until `timeout_seconds` (default 60, max 600). Polls every 250ms inside a single JXA call. |
 
 ### Safety policy management
 
@@ -43,6 +45,12 @@ Twelve MCP tools across three categories:
 | `pending_approve` | **write** | Approve a queued command by id. Triggers its own confirmation dialog. |
 | `pending_deny` | **write** | Deny a queued command. |
 
+### Observability
+
+| Tool | Read/Write | Description |
+|---|---|---|
+| `audit_log_tail` | read | Read the last N entries from the audit log. Default count 20, max 1000. Returns parsed JSON array of `{timestamp, tool, outcome, ...}` entries. |
+
 Write tools are **off by default**. Set `WRITE_TOOLS_ENABLED=1` in the server's environment to enable them. Even when enabled, every non-`safe` operation triggers a native macOS confirmation dialog.
 
 ## Prerequisites
@@ -193,6 +201,25 @@ Whichever path resolves first wins. For solo desktop use, the dialog is the cano
 
 Pending entries auto-expire after 10 minutes. The queue is in-memory only — a server restart drops all pending entries.
 
+## Privacy & data
+
+**No network, no telemetry.** The server speaks MCP over stdio to your local Claude client. It makes zero outbound network calls — no analytics, no crash reporting, no auto-update pings.
+
+**What is stored on disk:**
+
+| File | Path | Contents | Permissions |
+|---|---|---|---|
+| Audit log | `~/.local/state/macos-terminal-mcp/audit.log` | One JSON line per write-tool call: tool name, tty, **full command text**, safety level, matched pattern, outcome, timestamp | `0o600` (owner read/write only); parent dir `0o700` |
+| Safety config | `~/.config/macos-terminal-mcp/safety.json` | User-added regex patterns with their levels and descriptions | default umask |
+
+**Important caveat for secrets handling**: `terminal_execute` writes the **full command text** to the audit log. If a command contains a password, API key, or other secret, that secret ends up on disk in plaintext (owner-readable only). Mitigations:
+
+- Delete the log at any time: `rm ~/.local/state/macos-terminal-mcp/audit.log`
+- Default forbidden patterns already block common secret-leak vectors (`>\s*/etc/`, `\bcurl\b[^|;]*\|`, `\|\s*(bash|sh|zsh)\b`, `~/.ssh`, `/etc/passwd`, `/etc/shadow`)
+- Add your own forbidden patterns for company-specific secret formats via `safety_add`
+
+**Where the audit log helps**: post-hoc review of what an AI agent ran on your machine, debugging unexpected command refusals, and satisfying audit requirements in regulated environments.
+
 ## Usage examples
 
 Once registered, from Claude Code:

package/dist/index.js

@@ -1,8 +1,16 @@
 #!/usr/bin/env node
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { registerAll } from "./tools/register.js";
-const server = new McpServer({ name: "macos-terminal-mcp", version: "0.1.0" }, { capabilities: { tools: {} } });
+// Read package.json at runtime so serverInfo.version stays in sync with the
+// shipped package. Works in dev (tsx src/index.ts → ../package.json) and from
+// the installed npm package (dist/index.js → ../package.json).
+const pkgPath = join(dirname(fileURLToPath(import.meta.url)), "..", "package.json");
+const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+const server = new McpServer({ name: "macos-terminal-mcp", version: pkg.version }, { capabilities: { tools: {} } });
 registerAll(server);
 async function main() {
     const transport = new StdioServerTransport();

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAElD,MAAM,MAAM,GAAG,IAAI,SAAS,CAC1B,EAAE,IAAI,EAAE,oBAAoB,EAAE,OAAO,EAAE,OAAO,EAAE,EAChD,EAAE,YAAY,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,EAAE,CAChC,CAAC;AAEF,WAAW,CAAC,MAAM,CAAC,CAAC;AAEpB,KAAK,UAAU,IAAI;IACjB,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAChC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,8CAA8C,CAAC,CAAC;AACvE,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,GAAY,EAAE,EAAE;IAC5B,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,+BAA+B,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CACpF,CAAC;IACF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAElD,4EAA4E;AAC5E,8EAA8E;AAC9E,+DAA+D;AAC/D,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,cAAc,CAAC,CAAC;AACpF,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,OAAO,EAAE,MAAM,CAAC,CAAwB,CAAC;AAE7E,MAAM,MAAM,GAAG,IAAI,SAAS,CAC1B,EAAE,IAAI,EAAE,oBAAoB,EAAE,OAAO,EAAE,GAAG,CAAC,OAAO,EAAE,EACpD,EAAE,YAAY,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,EAAE,CAChC,CAAC;AAEF,WAAW,CAAC,MAAM,CAAC,CAAC;AAEpB,KAAK,UAAU,IAAI;IACjB,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAChC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,8CAA8C,CAAC,CAAC;AACvE,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,GAAY,EAAE,EAAE;IAC5B,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,+BAA+B,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CACpF,CAAC;IACF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/safety/audit.js

@@ -1,4 +1,4 @@
-import { appendFile, chmod, mkdir } from "node:fs/promises";
+import { appendFile, chmod, mkdir, readFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 function resolveDefaultPath() {
@@ -41,4 +41,34 @@ export async function appendAudit(entry, path = AUDIT_LOG_PATH) {
         process.stderr.write(`[macos-terminal-mcp] audit log write failed: ${err.message}\n`);
     }
 }
+/**
+ * Read the last N JSONL entries from the audit log. Returns [] if the file
+ * does not exist (no write tool calls have happened yet).
+ *
+ * Malformed lines are silently skipped — the audit log is best-effort writes
+ * and a corrupt entry shouldn't break the read path.
+ */
+export async function readAuditTail(count, path = AUDIT_LOG_PATH) {
+    let content;
+    try {
+        content = await readFile(path, "utf8");
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return [];
+        throw err;
+    }
+    const lines = content.split("\n").filter((l) => l.length > 0);
+    const tail = lines.slice(-count);
+    const entries = [];
+    for (const line of tail) {
+        try {
+            entries.push(JSON.parse(line));
+        }
+        catch {
+            // Defensive: skip malformed lines.
+        }
+    }
+    return entries;
+}
 //# sourceMappingURL=audit.js.map

package/dist/safety/audit.js.map

@@ -1 +1 @@
-{"version":3,"file":"audit.js","sourceRoot":"","sources":["../../src/safety/audit.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAC5D,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAmB1C,SAAS,kBAAkB;IACzB,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC;IACvC,MAAM,IAAI,GAAG,GAAG,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,EAAE,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC;IAC9E,OAAO,IAAI,CAAC,IAAI,EAAE,oBAAoB,EAAE,WAAW,CAAC,CAAC;AACvD,CAAC;AAED,MAAM,CAAC,MAAM,cAAc,GAAG,kBAAkB,EAAE,CAAC;AAEnD,MAAM,gBAAgB,GAAG,IAAI,CAAC;AAE9B,SAAS,QAAQ,CAAC,CAAS,EAAE,GAAW;IACtC,OAAO,CAAC,CAAC,MAAM,GAAG,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,MAAM,GAAG,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;AACxE,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,KAAoC,EACpC,OAAe,cAAc;IAE7B,4EAA4E;IAC5E,uEAAuE;IACvE,0BAA0B;IAC1B,MAAM,MAAM,GAAe;QACzB,GAAG,KAAK;QACR,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;KACpC,CAAC;IACF,IAAI,MAAM,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;QACjC,MAAM,CAAC,OAAO,GAAG,QAAQ,CAAC,MAAM,CAAC,OAAO,EAAE,gBAAgB,CAAC,CAAC;IAC9D,CAAC;IACD,IAAI,CAAC;QACH,MAAM,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;QAC7D,4EAA4E;QAC5E,wEAAwE;QACxE,MAAM,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;QAChD,MAAM,UAAU,CAAC,IAAI,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IAC3F,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,gDAAiD,GAAa,CAAC,OAAO,IAAI,CAC3E,CAAC;IACJ,CAAC;AACH,CAAC"}
+{"version":3,"file":"audit.js","sourceRoot":"","sources":["../../src/safety/audit.ts"],"names":[],"mappings":"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"}

package/dist/tools/audit.js

@@ -0,0 +1,33 @@
+import { z } from "zod";
+import { readAuditTail } from "../safety/audit.js";
+export async function auditTailHandler({ count = 20 }) {
+    try {
+        const entries = await readAuditTail(count);
+        return {
+            content: [{ type: "text", text: JSON.stringify(entries, null, 2) }],
+        };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            content: [{ type: "text", text: `audit_log_tail failed: ${message}` }],
+            isError: true,
+        };
+    }
+}
+export function register(server) {
+    server.registerTool("audit_log_tail", {
+        description: "Read the last N entries from the audit log (~/.local/state/macos-terminal-mcp/audit.log, or $XDG_STATE_HOME equivalent). Each entry is a JSON object with {timestamp, tool, outcome, tty?, command?, level?, matchedPattern?, source?, errorMessage?, details?}. Read-only — does not require WRITE_TOOLS_ENABLED and is not itself logged. Returns [] if the log file does not exist yet.",
+        inputSchema: {
+            count: z
+                .number()
+                .int()
+                .min(1)
+                .max(1000)
+                .optional()
+                .describe("Number of entries to return from the tail of the log. Default 20, max 1000."),
+        },
+        annotations: { readOnlyHint: true, idempotentHint: true },
+    }, auditTailHandler);
+}
+//# sourceMappingURL=audit.js.map

package/dist/tools/audit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit.js","sourceRoot":"","sources":["../../src/tools/audit.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAMnD,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,EAAE,KAAK,GAAG,EAAE,EAAkB;IACnE,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,MAAM,aAAa,CAAC,KAAK,CAAC,CAAC;QAC3C,OAAO;YACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC;SACpE,CAAC;IACJ,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACjE,OAAO;YACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,0BAA0B,OAAO,EAAE,EAAE,CAAC;YACtE,OAAO,EAAE,IAAI;SACd,CAAC;IACJ,CAAC;AACH,CAAC;AAED,MAAM,UAAU,QAAQ,CAAC,MAAiB;IACxC,MAAM,CAAC,YAAY,CACjB,gBAAgB,EAChB;QACE,WAAW,EACT,4XAA4X;QAC9X,WAAW,EAAE;YACX,KAAK,EAAE,CAAC;iBACL,MAAM,EAAE;iBACR,GAAG,EAAE;iBACL,GAAG,CAAC,CAAC,CAAC;iBACN,GAAG,CAAC,IAAI,CAAC;iBACT,QAAQ,EAAE;iBACV,QAAQ,CAAC,6EAA6E,CAAC;SAC3F;QACD,WAAW,EAAE,EAAE,YAAY,EAAE,IAAI,EAAE,cAAc,EAAE,IAAI,EAAE;KAC1D,EACD,gBAAgB,CACjB,CAAC;AACJ,CAAC"}

package/dist/tools/close_tab.js

@@ -0,0 +1,134 @@
+import { z } from "zod";
+import { OsascriptError, runJxa } from "../applescript.js";
+import { appendAudit } from "../safety/audit.js";
+import { isWriteToolsEnabled, writeToolsDisabledMessage } from "../safety/confirm.js";
+export function buildCloseTabScript(tty, force) {
+    return `
+function safe(fn) { try { return fn(); } catch (e) { return null; } }
+(function closeTab(targetTty, force) {
+  const terminal = Application("Terminal");
+  const wins = terminal.windows();
+  for (let wi = 0; wi < wins.length; wi++) {
+    const w = wins[wi];
+    const tabs = w.tabs();
+    for (let ti = 0; ti < tabs.length; ti++) {
+      const t = tabs[ti];
+      if (safe(function () { return t.tty(); }) === targetTty) {
+        const busy = safe(function () { return t.busy(); }) === true;
+        if (busy && !force) {
+          return JSON.stringify({ status: "busy", tty: targetTty });
+        }
+        // Terminal.app's AppleScript dictionary does NOT expose "close" on tab
+        // objects — only on window objects. Each tab is enumerated as its own
+        // "window" entry though (a quirk of the dictionary), so closing the
+        // enclosing "w" reference closes just this tab in the physical window.
+        w.close();
+        return JSON.stringify({ status: "closed", tty: targetTty, killedRunningCommand: busy });
+      }
+    }
+  }
+  return JSON.stringify({ status: "missing", tty: targetTty });
+})(${JSON.stringify(tty)}, ${JSON.stringify(force)});
+`;
+}
+export async function closeTabHandler({ tty, force = false, }) {
+    if (!isWriteToolsEnabled()) {
+        return {
+            content: [{ type: "text", text: writeToolsDisabledMessage("terminal_close_tab") }],
+            isError: true,
+        };
+    }
+    let raw;
+    try {
+        raw = await runJxa(buildCloseTabScript(tty, force));
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        const hint = err instanceof OsascriptError && /not authorized/i.test(err.stderr)
+            ? "\nAutomation permission missing — System Settings → Privacy & Security → Automation."
+            : "";
+        await appendAudit({
+            tool: "terminal_close_tab",
+            outcome: "error",
+            tty,
+            errorMessage: message,
+        });
+        return {
+            content: [{ type: "text", text: `terminal_close_tab failed: ${message}${hint}` }],
+            isError: true,
+        };
+    }
+    let result;
+    try {
+        result = JSON.parse(raw);
+    }
+    catch (err) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `terminal_close_tab: unexpected JXA response: ${err.message}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+    if (result.status === "missing") {
+        return {
+            content: [{ type: "text", text: `No Terminal.app tab found with tty ${tty}.` }],
+            isError: true,
+        };
+    }
+    if (result.status === "busy") {
+        await appendAudit({
+            tool: "terminal_close_tab",
+            outcome: "refused",
+            tty,
+            details: { reason: "target tab is busy" },
+        });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Refused: target tab ${tty} is busy with a running command. Closing it would kill the process. ` +
+                        `Pass force=true to close anyway, or wait for the command to finish (see terminal_wait_for_idle).`,
+                },
+            ],
+            isError: true,
+        };
+    }
+    await appendAudit({
+        tool: "terminal_close_tab",
+        outcome: "success",
+        tty,
+        ...(result.killedRunningCommand
+            ? { details: { killedRunningCommand: true, force: true } }
+            : {}),
+    });
+    return {
+        content: [
+            {
+                type: "text",
+                text: result.killedRunningCommand
+                    ? `Closed ${tty} [force=true, killed running command].`
+                    : `Closed ${tty}.`,
+            },
+        ],
+    };
+}
+export function register(server) {
+    server.registerTool("terminal_close_tab", {
+        description: "Close a specific Terminal.app tab by tty. Useful for cleaning up scratch tabs spawned via terminal_new_tab. If the tab has a running foreground command, the call refuses by default — pass force=true to close anyway (the running command is killed). Requires WRITE_TOOLS_ENABLED=1 but no confirmation dialog (low blast radius for idle tabs; force=true scenarios are deliberate).",
+        inputSchema: {
+            tty: z
+                .string()
+                .regex(/^\/dev\/ttys[0-9]+$/)
+                .describe('Target tab tty, e.g. "/dev/ttys003"'),
+            force: z
+                .boolean()
+                .optional()
+                .describe("If true, close even when a foreground command is running (killing it). Default: false."),
+        },
+    }, closeTabHandler);
+}
+//# sourceMappingURL=close_tab.js.map

package/dist/tools/close_tab.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"close_tab.js","sourceRoot":"","sources":["../../src/tools/close_tab.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,cAAc,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAC3D,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,mBAAmB,EAAE,yBAAyB,EAAE,MAAM,sBAAsB,CAAC;AAEtF,MAAM,UAAU,mBAAmB,CAAC,GAAW,EAAE,KAAc;IAC7D,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;KAyBJ,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,KAAK,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC;CACjD,CAAC;AACF,CAAC;AAcD,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,EACpC,GAAG,EACH,KAAK,GAAG,KAAK,GACC;IACd,IAAI,CAAC,mBAAmB,EAAE,EAAE,CAAC;QAC3B,OAAO;YACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,yBAAyB,CAAC,oBAAoB,CAAC,EAAE,CAAC;YAClF,OAAO,EAAE,IAAI;SACd,CAAC;IACJ,CAAC;IAED,IAAI,GAAW,CAAC;IAChB,IAAI,CAAC;QACH,GAAG,GAAG,MAAM,MAAM,CAAC,mBAAmB,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC,CAAC;IACtD,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACjE,MAAM,IAAI,GACR,GAAG,YAAY,cAAc,IAAI,iBAAiB,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC;YACjE,CAAC,CAAC,sFAAsF;YACxF,CAAC,CAAC,EAAE,CAAC;QACT,MAAM,WAAW,CAAC;YAChB,IAAI,EAAE,oBAAoB;YAC1B,OAAO,EAAE,OAAO;YAChB,GAAG;YACH,YAAY,EAAE,OAAO;SACtB,CAAC,CAAC;QACH,OAAO;YACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,8BAA8B,OAAO,GAAG,IAAI,EAAE,EAAE,CAAC;YACjF,OAAO,EAAE,IAAI;SACd,CAAC;IACJ,CAAC;IAED,IAAI,MAAmB,CAAC;IACxB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAgB,CAAC;IAC1C,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO;YACL,OAAO,EAAE;gBACP;oBACE,IAAI,EAAE,MAAM;oBACZ,IAAI,EAAE,gDAAiD,GAAa,CAAC,OAAO,EAAE;iBAC/E;aACF;YACD,OAAO,EAAE,IAAI;SACd,CAAC;IACJ,CAAC;IAED,IAAI,MAAM,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;QAChC,OAAO;YACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,sCAAsC,GAAG,GAAG,EAAE,CAAC;YAC/E,OAAO,EAAE,IAAI;SACd,CAAC;IACJ,CAAC;IAED,IAAI,MAAM,CAAC,MAAM,KAAK,MAAM,EAAE,CAAC;QAC7B,MAAM,WAAW,CAAC;YAChB,IAAI,EAAE,oBAAoB;YAC1B,OAAO,EAAE,SAAS;YAClB,GAAG;YACH,OAAO,EAAE,EAAE,MAAM,EAAE,oBAAoB,EAAE;SAC1C,CAAC,CAAC;QACH,OAAO;YACL,OAAO,EAAE;gBACP;oBACE,IAAI,EAAE,MAAM;oBACZ,IAAI,EACF,uBAAuB,GAAG,sEAAsE;wBAChG,kGAAkG;iBACrG;aACF;YACD,OAAO,EAAE,IAAI;SACd,CAAC;IACJ,CAAC;IAED,MAAM,WAAW,CAAC;QAChB,IAAI,EAAE,oBAAoB;QAC1B,OAAO,EAAE,SAAS;QAClB,GAAG;QACH,GAAG,CAAC,MAAM,CAAC,oBAAoB;YAC7B,CAAC,CAAC,EAAE,OAAO,EAAE,EAAE,oBAAoB,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE;YAC1D,CAAC,CAAC,EAAE,CAAC;KACR,CAAC,CAAC;IACH,OAAO;QACL,OAAO,EAAE;YACP;gBACE,IAAI,EAAE,MAAM;gBACZ,IAAI,EAAE,MAAM,CAAC,oBAAoB;oBAC/B,CAAC,CAAC,UAAU,GAAG,wCAAwC;oBACvD,CAAC,CAAC,UAAU,GAAG,GAAG;aACrB;SACF;KACF,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,QAAQ,CAAC,MAAiB;IACxC,MAAM,CAAC,YAAY,CACjB,oBAAoB,EACpB;QACE,WAAW,EACT,0XAA0X;QAC5X,WAAW,EAAE;YACX,GAAG,EAAE,CAAC;iBACH,MAAM,EAAE;iBACR,KAAK,CAAC,qBAAqB,CAAC;iBAC5B,QAAQ,CAAC,qCAAqC,CAAC;YAClD,KAAK,EAAE,CAAC;iBACL,OAAO,EAAE;iBACT,QAAQ,EAAE;iBACV,QAAQ,CACP,wFAAwF,CACzF;SACJ;KACF,EACD,eAAe,CAChB,CAAC;AACJ,CAAC"}

package/dist/tools/new_tab.js

@@ -22,7 +22,38 @@ function snapshotTabs(terminal) {
 (function newTab() {
   const terminal = Application("Terminal");
   const systemEvents = Application("System Events");
+  // Detect cold start: if Terminal isn't running yet, activate() has to LAUNCH
+  // it, which takes much longer than the warm-path 150ms delay. We then wait
+  // for the new process to be ready before sending the keystroke.
+  const wasRunning = (function () { try { return terminal.running(); } catch (e) { return true; } })();
   terminal.activate();
+  // activate() returns before the window server actually makes Terminal frontmost,
+  // and macOS sometimes refuses to honor activate() when another app is in use
+  // by the user. System Events accessibility-layer "frontmost = true" is a more
+  // forceful way to make Terminal the key app — required for Cmd+T to land on it.
+  try { Application("System Events").applicationProcesses["Terminal"].frontmost = true; } catch (e) { /* best-effort */ }
+  // Cold start: poll up to 3s for Terminal to come up. Warm start: short settle.
+  if (!wasRunning) {
+    for (let i = 0; i < 30; i++) {
+      delay(0.1);
+      try { if (terminal.running()) break; } catch (e) { /* keep waiting */ }
+    }
+    delay(0.5);
+    // Cold-start: Terminal almost always auto-opens a default window per the
+    // user's "When Terminal Starts" preference. Since Terminal wasn't running
+    // before, ANY tab that exists now is the new one we owe the caller — return
+    // it directly. Don't ALSO send Cmd+T (which would create a second tab the
+    // caller didn't ask for; reported by user during v0.6.1 verification).
+    const afterLaunch = snapshotTabs(terminal);
+    const launchedKeys = Object.keys(afterLaunch);
+    if (launchedKeys.length > 0) {
+      return JSON.stringify({ tty: launchedKeys[0], windowId: afterLaunch[launchedKeys[0]] });
+    }
+    // Cold launch produced no default window (user disabled it in prefs) — fall
+    // through to the keystroke path so Cmd+N creates one.
+  } else {
+    delay(0.3);
+  }
   const before = snapshotTabs(terminal);
   const wasEmpty = Object.keys(before).length === 0;
   // Cmd+T opens a new tab in the front window; Cmd+N opens a new window when

package/dist/tools/new_tab.js.map

@@ -1 +1 @@
-{"version":3,"file":"new_tab.js","sourceRoot":"","sources":["../../src/tools/new_tab.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,cAAc,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAC3D,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,mBAAmB,EAAE,yBAAyB,EAAE,MAAM,sBAAsB,CAAC;AAEtF,MAAM,CAAC,MAAM,cAAc,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAgD7B,CAAC;AAEF,MAAM,CAAC,KAAK,UAAU,aAAa;IACjC,IAAI,CAAC,mBAAmB,EAAE,EAAE,CAAC;QAC3B,OAAO;YACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,yBAAyB,CAAC,kBAAkB,CAAC,EAAE,CAAC;YAChF,OAAO,EAAE,IAAI;SACd,CAAC;IACJ,CAAC;IACD,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,cAAc,CAAC,CAAC;QAC1C,MAAM,WAAW,CAAC,EAAE,IAAI,EAAE,kBAAkB,EAAE,OAAO,EAAE,SAAS,EAAE,CAAC,CAAC;QACpE,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC;IACrD,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACjE,MAAM,IAAI,GACR,GAAG,YAAY,cAAc,IAAI,iBAAiB,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC;YACjE,CAAC,CAAC,sFAAsF;YACxF,CAAC,CAAC,EAAE,CAAC;QACT,MAAM,WAAW,CAAC;YAChB,IAAI,EAAE,kBAAkB;YACxB,OAAO,EAAE,OAAO;YAChB,YAAY,EAAE,OAAO;SACtB,CAAC,CAAC;QACH,OAAO;YACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,4BAA4B,OAAO,GAAG,IAAI,EAAE,EAAE,CAAC;YAC/E,OAAO,EAAE,IAAI;SACd,CAAC;IACJ,CAAC;AACH,CAAC;AAED,MAAM,UAAU,QAAQ,CAAC,MAAiB;IACxC,MAAM,CAAC,YAAY,CACjB,kBAAkB,EAClB;QACE,WAAW,EACT,2nBAA2nB;KAC9nB,EACD,aAAa,CACd,CAAC;AACJ,CAAC"}
+{"version":3,"file":"new_tab.js","sourceRoot":"","sources":["../../src/tools/new_tab.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,cAAc,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAC3D,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,mBAAmB,EAAE,yBAAyB,EAAE,MAAM,sBAAsB,CAAC;AAEtF,MAAM,CAAC,MAAM,cAAc,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA+E7B,CAAC;AAEF,MAAM,CAAC,KAAK,UAAU,aAAa;IACjC,IAAI,CAAC,mBAAmB,EAAE,EAAE,CAAC;QAC3B,OAAO;YACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,yBAAyB,CAAC,kBAAkB,CAAC,EAAE,CAAC;YAChF,OAAO,EAAE,IAAI;SACd,CAAC;IACJ,CAAC;IACD,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,cAAc,CAAC,CAAC;QAC1C,MAAM,WAAW,CAAC,EAAE,IAAI,EAAE,kBAAkB,EAAE,OAAO,EAAE,SAAS,EAAE,CAAC,CAAC;QACpE,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC;IACrD,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACjE,MAAM,IAAI,GACR,GAAG,YAAY,cAAc,IAAI,iBAAiB,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC;YACjE,CAAC,CAAC,sFAAsF;YACxF,CAAC,CAAC,EAAE,CAAC;QACT,MAAM,WAAW,CAAC;YAChB,IAAI,EAAE,kBAAkB;YACxB,OAAO,EAAE,OAAO;YAChB,YAAY,EAAE,OAAO;SACtB,CAAC,CAAC;QACH,OAAO;YACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,4BAA4B,OAAO,GAAG,IAAI,EAAE,EAAE,CAAC;YAC/E,OAAO,EAAE,IAAI;SACd,CAAC;IACJ,CAAC;AACH,CAAC;AAED,MAAM,UAAU,QAAQ,CAAC,MAAiB;IACxC,MAAM,CAAC,YAAY,CACjB,kBAAkB,EAClB;QACE,WAAW,EACT,2nBAA2nB;KAC9nB,EACD,aAAa,CACd,CAAC;AACJ,CAAC"}

package/dist/tools/register.js

@@ -1,17 +1,27 @@
+import * as audit from "./audit.js";
 import * as clear from "./clear.js";
+import * as closeTab from "./close_tab.js";
 import * as execute from "./execute.js";
 import * as list from "./list.js";
 import * as newTab from "./new_tab.js";
 import * as pending from "./pending.js";
 import * as read from "./read.js";
 import * as safety from "./safety.js";
+import * as waitForIdle from "./wait_for_idle.js";
 export function registerAll(server) {
+    // Terminal interaction
     list.register(server);
     read.register(server);
     execute.register(server);
     clear.register(server);
     newTab.register(server);
+    closeTab.register(server);
+    waitForIdle.register(server);
+    // Safety policy
     safety.register(server);
+    // Async approval queue
     pending.register(server);
+    // Observability
+    audit.register(server);
 }
 //# sourceMappingURL=register.js.map

package/dist/tools/register.js.map

@@ -1 +1 @@
-{"version":3,"file":"register.js","sourceRoot":"","sources":["../../src/tools/register.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,KAAK,MAAM,YAAY,CAAC;AACpC,OAAO,KAAK,OAAO,MAAM,cAAc,CAAC;AACxC,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAClC,OAAO,KAAK,MAAM,MAAM,cAAc,CAAC;AACvC,OAAO,KAAK,OAAO,MAAM,cAAc,CAAC;AACxC,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAClC,OAAO,KAAK,MAAM,MAAM,aAAa,CAAC;AAEtC,MAAM,UAAU,WAAW,CAAC,MAAiB;IAC3C,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;IACtB,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;IACtB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;IACzB,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;IACvB,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;IACxB,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;IACxB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;AAC3B,CAAC"}
+{"version":3,"file":"register.js","sourceRoot":"","sources":["../../src/tools/register.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,KAAK,MAAM,YAAY,CAAC;AACpC,OAAO,KAAK,KAAK,MAAM,YAAY,CAAC;AACpC,OAAO,KAAK,QAAQ,MAAM,gBAAgB,CAAC;AAC3C,OAAO,KAAK,OAAO,MAAM,cAAc,CAAC;AACxC,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAClC,OAAO,KAAK,MAAM,MAAM,cAAc,CAAC;AACvC,OAAO,KAAK,OAAO,MAAM,cAAc,CAAC;AACxC,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAClC,OAAO,KAAK,MAAM,MAAM,aAAa,CAAC;AACtC,OAAO,KAAK,WAAW,MAAM,oBAAoB,CAAC;AAElD,MAAM,UAAU,WAAW,CAAC,MAAiB;IAC3C,uBAAuB;IACvB,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;IACtB,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;IACtB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;IACzB,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;IACvB,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;IACxB,QAAQ,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC1B,WAAW,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC7B,gBAAgB;IAChB,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;IACxB,uBAAuB;IACvB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;IACzB,gBAAgB;IAChB,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;AACzB,CAAC"}

package/dist/tools/wait_for_idle.js

@@ -0,0 +1,91 @@
+import { z } from "zod";
+import { runJxa } from "../applescript.js";
+const DEFAULT_TIMEOUT_SEC = 60;
+const MAX_TIMEOUT_SEC = 600;
+const POLL_INTERVAL_SEC = 0.25;
+export function buildWaitForIdleScript(tty, timeoutSec) {
+    return `
+function safe(fn) { try { return fn(); } catch (e) { return null; } }
+var app = Application.currentApplication();
+app.includeStandardAdditions = true;
+(function waitForIdle(targetTty, timeoutSec) {
+  const terminal = Application("Terminal");
+  const startMs = Date.now();
+  const deadlineMs = startMs + timeoutSec * 1000;
+
+  function probe() {
+    const wins = terminal.windows();
+    for (let wi = 0; wi < wins.length; wi++) {
+      const w = wins[wi];
+      const tabs = w.tabs();
+      for (let ti = 0; ti < tabs.length; ti++) {
+        const t = tabs[ti];
+        if (safe(function () { return t.tty(); }) === targetTty) {
+          return { found: true, busy: safe(function () { return t.busy(); }) === true };
+        }
+      }
+    }
+    return { found: false, busy: false };
+  }
+
+  let state = probe();
+  if (!state.found) {
+    return JSON.stringify({ tty: targetTty, missing: true, waited_ms: 0 });
+  }
+  if (!state.busy) {
+    return JSON.stringify({ tty: targetTty, idle: true, waited_ms: 0 });
+  }
+
+  while (Date.now() < deadlineMs) {
+    delay(${POLL_INTERVAL_SEC});
+    state = probe();
+    if (!state.found) {
+      return JSON.stringify({ tty: targetTty, missing: true, waited_ms: Date.now() - startMs });
+    }
+    if (!state.busy) {
+      return JSON.stringify({ tty: targetTty, idle: true, waited_ms: Date.now() - startMs });
+    }
+  }
+
+  return JSON.stringify({ tty: targetTty, timed_out: true, waited_ms: Date.now() - startMs });
+})(${JSON.stringify(tty)}, ${timeoutSec});
+`;
+}
+export async function waitForIdleHandler({ tty, timeout_seconds = DEFAULT_TIMEOUT_SEC, }) {
+    const timeoutSec = Math.min(Math.max(timeout_seconds, 1), MAX_TIMEOUT_SEC);
+    try {
+        // Outer runJxa timeout is the inner poll deadline + 5s buffer to let the
+        // JXA finish writing its "timed_out" result before SIGKILL engages.
+        const raw = await runJxa(buildWaitForIdleScript(tty, timeoutSec), {
+            timeoutMs: (timeoutSec + 5) * 1000,
+        });
+        return { content: [{ type: "text", text: raw }] };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            content: [{ type: "text", text: `terminal_wait_for_idle failed: ${message}` }],
+            isError: true,
+        };
+    }
+}
+export function register(server) {
+    server.registerTool("terminal_wait_for_idle", {
+        description: "Block until the target Terminal.app tab is no longer busy (no foreground command running), or until timeout. Polls every 250ms inside a single osascript invocation. Useful for sequential workflows like 'run npm install, then run npm test'. Returns one of {idle: true, waited_ms}, {timed_out: true, waited_ms}, or {missing: true, waited_ms}. Read-only — no WRITE_TOOLS_ENABLED gate.",
+        inputSchema: {
+            tty: z
+                .string()
+                .regex(/^\/dev\/ttys[0-9]+$/)
+                .describe('Target tab tty, e.g. "/dev/ttys003"'),
+            timeout_seconds: z
+                .number()
+                .int()
+                .min(1)
+                .max(MAX_TIMEOUT_SEC)
+                .optional()
+                .describe(`Maximum seconds to wait before giving up. Default ${DEFAULT_TIMEOUT_SEC}, max ${MAX_TIMEOUT_SEC}.`),
+        },
+        annotations: { readOnlyHint: true, idempotentHint: true },
+    }, waitForIdleHandler);
+}
+//# sourceMappingURL=wait_for_idle.js.map

package/dist/tools/wait_for_idle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wait_for_idle.js","sourceRoot":"","sources":["../../src/tools/wait_for_idle.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAE3C,MAAM,mBAAmB,GAAG,EAAE,CAAC;AAC/B,MAAM,eAAe,GAAG,GAAG,CAAC;AAC5B,MAAM,iBAAiB,GAAG,IAAI,CAAC;AAE/B,MAAM,UAAU,sBAAsB,CAAC,GAAW,EAAE,UAAkB;IACpE,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;YAiCG,iBAAiB;;;;;;;;;;;KAWxB,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,KAAK,UAAU;CACtC,CAAC;AACF,CAAC;AAOD,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,EACvC,GAAG,EACH,eAAe,GAAG,mBAAmB,GACpB;IACjB,MAAM,UAAU,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,eAAe,EAAE,CAAC,CAAC,EAAE,eAAe,CAAC,CAAC;IAC3E,IAAI,CAAC;QACH,yEAAyE;QACzE,oEAAoE;QACpE,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC,sBAAsB,CAAC,GAAG,EAAE,UAAU,CAAC,EAAE;YAChE,SAAS,EAAE,CAAC,UAAU,GAAG,CAAC,CAAC,GAAG,IAAI;SACnC,CAAC,CAAC;QACH,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC;IACpD,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACjE,OAAO;YACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,kCAAkC,OAAO,EAAE,EAAE,CAAC;YAC9E,OAAO,EAAE,IAAI;SACd,CAAC;IACJ,CAAC;AACH,CAAC;AAED,MAAM,UAAU,QAAQ,CAAC,MAAiB;IACxC,MAAM,CAAC,YAAY,CACjB,wBAAwB,EACxB;QACE,WAAW,EACT,+XAA+X;QACjY,WAAW,EAAE;YACX,GAAG,EAAE,CAAC;iBACH,MAAM,EAAE;iBACR,KAAK,CAAC,qBAAqB,CAAC;iBAC5B,QAAQ,CAAC,qCAAqC,CAAC;YAClD,eAAe,EAAE,CAAC;iBACf,MAAM,EAAE;iBACR,GAAG,EAAE;iBACL,GAAG,CAAC,CAAC,CAAC;iBACN,GAAG,CAAC,eAAe,CAAC;iBACpB,QAAQ,EAAE;iBACV,QAAQ,CACP,qDAAqD,mBAAmB,SAAS,eAAe,GAAG,CACpG;SACJ;QACD,WAAW,EAAE,EAAE,YAAY,EAAE,IAAI,EAAE,cAAc,EAAE,IAAI,EAAE;KAC1D,EACD,kBAAkB,CACnB,CAAC;AACJ,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@priyanshumit/macos-terminal-mcp",
-  "version": "0.5.1",
+  "version": "0.6.1",
   "description": "MCP server exposing macOS Terminal.app to AI agents via AppleScript / JXA. List windows, read scrollback, execute commands, clear buffers — with three-tier safety patterns and confirmation dialogs.",
   "type": "module",
   "bin": {