@zswarm/core 0.1.4 → 0.1.6

package/dist/ops/status.js

@@ -1,5 +1,6 @@
+import { ZellijError } from "../errors.js";
 import { resolveHarness } from "../harness.js";
-import { isTrue, normalizeScreen, numberArg, optionalString } from "./util.js";
+import { isTrue, normalizeScreen, numberArg, optionalString, throwIfAborted, } from "./util.js";
 /**
  * Legacy last-line prompt shapes for callers without a profile. A term counts
  * only when it is a question, not chrome: a y/n form, a trailing `?`, or the
@@ -18,6 +19,10 @@ const QUESTION = /(\(y\/n\)|\[y\/n\]|\(yes\/no\)|\[y\/n\/a\]|password:|passphras
  * where it is or it would fire on chrome.
  */
 const PROMPT_WINDOW = 24;
+/** Default overall budget for a sampled status pass (covers IPC + dumps). */
+export const DEFAULT_STATUS_TIMEOUT_MS = 30_000;
+/** How many dump-screen calls to run at once on the direct (non-bus) path. */
+export const STATUS_DUMP_CONCURRENCY = 3;
 export function lastLine(screen) {
     const lines = screen.split("\n").filter((l) => l.trim());
     return lines.length > 0 ? lines[lines.length - 1].trim() : "";
@@ -30,25 +35,39 @@ function trailingLines(screen, n) {
         .filter((line) => line.length > 0)
         .slice(-n);
 }
-/**
- * True when the trailing window holds a named approval prompt. The profile's
- * waiting patterns run across the window; the legacy last-line QUESTION check
- * stays as the conservative fallback for callers without a profile. Bias is
- * toward false negatives: a hit must be prompt UI we can name, never a bare
- * question mark or "confirm".
- */
-function promptHolds(screen, profile) {
+export function waitingPrompt(screen, profile) {
     const lines = trailingLines(screen, PROMPT_WINDOW);
-    const patterns = profile?.waiting;
-    if (patterns && patterns.length > 0) {
-        for (const line of lines) {
-            for (const re of patterns) {
-                if (re.test(line))
-                    return true;
-            }
+    // A menu requires a choice structure AND navigation chrome. A lone "Allow
+    // once" in logs/help must not turn a worker into an approval request.
+    const choices = lines.filter((line) => /^(?:[›❯>●]\s*)?\d+[.)]\s+(?:Yes\b|No\b|Allow\b|Deny\b|Cancel\b)/i.test(line));
+    const navigation = lines.some((line) => /(?:enter|return)\s+(?:to\s+)?(?:select|confirm)|(?:esc|escape)\s+(?:to\s+)?cancel/i.test(line));
+    const approval = lines.find((line) => /^(?:[›❯>]\s*)?(?:Approve (?:this|the) (?:operation|command|action)|Approval required|Would you like to run the following command\?|Run this command\?)[?:]?$/i.test(line));
+    if (approval && choices.length >= 2 && navigation) {
+        return { reason: "approval_menu", evidence: choices.slice(0, 3).join("\n").slice(0, 320), source: "screen" };
+    }
+    for (const line of lines) {
+        if (profile?.waiting.some((re) => re.test(line))) {
+            return { reason: "prompt", evidence: line.slice(0, 320), source: "screen" };
         }
     }
-    return QUESTION.test(lines[lines.length - 1] ?? "");
+    const last = lines[lines.length - 1] ?? "";
+    return QUESTION.test(last) ? { reason: "prompt", evidence: last.slice(0, 320), source: "screen" } : null;
+}
+function promptHolds(screen, profile) {
+    return waitingPrompt(screen, profile) !== null;
+}
+/** Compact summary of the selected terminal peers, including inactive tabs. */
+export function statusTabs(peers) {
+    const tabs = new Map();
+    for (const peer of peers) {
+        const key = JSON.stringify([peer.tabId, peer.tab]);
+        const tab = tabs.get(key) ?? { id: peer.tabId, name: peer.tab, panes: 0, states: {} };
+        tab.panes++;
+        const state = String(peer.state);
+        tab.states[state] = (tab.states[state] ?? 0) + 1;
+        tabs.set(key, tab);
+    }
+    return [...tabs.values()];
 }
 export function classify(input) {
     if (input.exited)
@@ -57,72 +76,114 @@ export function classify(input) {
         return "busy";
     return promptHolds(input.after, input.profile) ? "waiting" : "idle";
 }
+/** Run `fn` over items with at most `limit` in flight. */
+export async function mapPool(items, limit, fn) {
+    if (items.length === 0)
+        return [];
+    const concurrency = Math.max(1, Math.min(limit, items.length));
+    const results = new Array(items.length);
+    let next = 0;
+    async function worker() {
+        while (next < items.length) {
+            const i = next++;
+            results[i] = await fn(items[i], i);
+        }
+    }
+    await Promise.all(Array.from({ length: concurrency }, () => worker()));
+    return results;
+}
+function isCancelledError(err) {
+    return ((err instanceof ZellijError && err.code === "cancelled") ||
+        (err instanceof Error && /cancelled/i.test(err.message)));
+}
+function peerEntry(pane, state, screen, verbose, extra) {
+    const entry = {
+        id: pane.id,
+        title: pane.title,
+        tab: pane.tabName ?? null,
+        tabId: pane.tabId ?? null,
+        state,
+        lastLine: lastLine(screen).slice(0, 160),
+        ...extra,
+    };
+    if (state === "waiting")
+        entry.waiting = waitingPrompt(screen, resolveHarness(pane));
+    if (verbose) {
+        entry.command = pane.command ?? null;
+        entry.cwd = pane.cwd ?? null;
+    }
+    return entry;
+}
 /**
  * Sample every pane twice and say who is working, who is stuck on a prompt,
  * and who is free — the routing question `list` cannot answer.
+ *
+ * `deadlineAt` is the absolute clock deadline for the whole status op (setup
+ * included). When omitted, one is derived from `timeoutMs` at entry.
  */
-export async function peerStatus(client, args, clock, supplied) {
+export async function peerStatus(client, args, clock, supplied, opts = {}) {
+    const signal = opts.signal;
+    throwIfAborted(signal);
+    const budget = numberArg(args, "timeoutMs", DEFAULT_STATUS_TIMEOUT_MS, {
+        min: 1_000,
+        max: 900_000,
+    });
+    const deadline = opts.deadlineAt ?? clock.now() + budget;
+    const remaining = () => Math.max(0, deadline - clock.now());
+    const setupBudget = () => {
+        throwIfAborted(signal);
+        const left = remaining();
+        if (left <= 0) {
+            throw new ZellijError("zellij_failed", "status timed out during setup");
+        }
+        return left;
+    };
+    // Prefer the caller's already-resolved session/panes so dispatch's setup
+    // budget is not spent twice.
     const session = supplied?.session ??
-        (await client.resolveSession(typeof args.session === "string" ? args.session : undefined)).session;
-    const panes = supplied?.panes ?? (await client.listPanes(session));
+        (await client.resolveSession(typeof args.session === "string" ? args.session : undefined, setupBudget())).session;
+    throwIfAborted(signal);
+    const panes = supplied?.panes ?? (await client.listPanes(session, setupBudget()));
+    throwIfAborted(signal);
     const source = supplied?.source ?? "zellij";
     const only = optionalString(args.to);
+    const verbose = isTrue(args.verbose);
     const targets = only
         ? [client.resolvePane(panes, only)]
         : panes.filter((p) => !p.isPlugin);
-    // sampleMs=0 asks for the cheap answer: who is alive, from state the plugin
-    // already holds. Below that, two samples too close together read as idle.
     const requested = numberArg(args, "sampleMs", 400, { min: 0, max: 10_000 });
     if (requested === 0) {
         const peers = targets
-            .map((pane) => {
-            const entry = {
-                id: pane.id,
-                title: pane.title,
-                state: pane.exited ? "exited" : "running",
-            };
-            if (isTrue(args.verbose)) {
-                entry.command = pane.command ?? null;
-                entry.cwd = pane.cwd ?? null;
-                entry.tab = pane.tabName ?? null;
-            }
-            return entry;
-        })
+            .map((pane) => peerEntry(pane, pane.exited ? "exited" : "running", "", verbose))
             .sort((a, b) => String(a.id).localeCompare(String(b.id)));
-        // No `free`: without sampling there is no way to tell busy from idle.
         return {
             ok: true,
-            data: { session, source, sampled: false, sampleMs: 0, peers },
+            data: { session, source, sampled: false, sampleMs: 0, peers, tabs: statusTabs(peers) },
         };
     }
     const sampleMs = Math.max(50, requested);
-    const live = targets.filter((pane) => !pane.exited).map((pane) => pane.id);
-    // sinceLast trades the fixed 400ms window for "moved since your last call".
-    // The plugin remembers the previous screen, so there is no gap to wait out —
-    // but ask twice in quick succession and everything reads idle.
+    const live = targets.filter((pane) => !pane.exited);
     if (isTrue(args.sinceLast) && supplied?.readChanged) {
-        const changed = await supplied.readChanged(live);
+        const left = remaining();
+        const changed = left > 0 ? await supplied.readChanged(live.map((p) => p.id), left) : null;
+        throwIfAborted(signal);
         if (changed) {
             const peers = targets
                 .map((pane) => {
+                if (pane.exited) {
+                    return peerEntry(pane, "exited", "", verbose);
+                }
                 const row = changed.get(pane.id);
-                const state = pane.exited
-                    ? "exited"
-                    : row?.changed
+                const state = !row
+                    ? "unknown"
+                    : row.changed
                         ? "busy"
                         : promptHolds(row?.screen ?? "", resolveHarness(pane))
                             ? "waiting"
                             : "idle";
-                const entry = {
-                    id: pane.id,
-                    title: pane.title,
-                    state,
-                    lastLine: lastLine(row?.screen ?? "").slice(0, 160),
-                };
-                // First sight has nothing to compare against, so idle is a guess.
-                if (row?.first)
-                    entry.first = true;
-                return entry;
+                return peerEntry(pane, state, row?.screen ?? "", verbose, {
+                    ...(row?.first ? { first: true } : {}),
+                });
             })
                 .sort((a, b) => String(a.id).localeCompare(String(b.id)));
             return {
@@ -133,60 +194,139 @@ export async function peerStatus(client, args, clock, supplied) {
                     sampled: false,
                     sinceLast: true,
                     peers,
+                    tabs: statusTabs(peers),
                     free: peers.filter((p) => p.state === "idle").map((p) => p.id),
                 },
             };
         }
     }
     /**
-     * One batched read when the bus can serve it, otherwise a process per pane.
-     * Both paths normalize, which is what makes them comparable: the plugin pads
-     * lines to the terminal width and `dump-screen` does not.
+     * Bus path: one batched read per round, each bounded by the remaining budget.
+     * Direct path: each pane completes its own before→sleep→after pair under a
+     * shared concurrency limit so one stall does not block healthy peers.
      */
-    const sample = async () => {
-        const batched = supplied?.readScreens
-            ? await supplied.readScreens(live)
-            : null;
-        if (batched) {
-            return new Map([...batched].map(([id, text]) => [id, normalizeScreen(text)]));
+    const samples = new Map();
+    if (supplied?.readScreens) {
+        const sampleRound = async () => {
+            throwIfAborted(signal);
+            const left = remaining();
+            if (left <= 0) {
+                return new Map(live.map((p) => [p.id, null]));
+            }
+            try {
+                const batched = await supplied.readScreens(live.map((p) => p.id), left);
+                throwIfAborted(signal);
+                if (!batched)
+                    return new Map(); // signal fallback to dumps below
+                return new Map(live.map((p) => {
+                    const text = batched.get(p.id);
+                    return [
+                        p.id,
+                        text === undefined ? null : normalizeScreen(text),
+                    ];
+                }));
+            }
+            catch (err) {
+                if (isCancelledError(err) || signal?.aborted) {
+                    throw new ZellijError("cancelled", "operation cancelled");
+                }
+                return new Map(live.map((p) => [p.id, null]));
+            }
+        };
+        let before = await sampleRound();
+        if (before.size === 0) {
+            // Bus declined — fall through to per-pane dumps.
+            before = new Map();
         }
-        const screens = new Map();
-        for (const id of live) {
-            const dumped = await client.dumpPane({ session, paneId: id });
-            screens.set(id, normalizeScreen(dumped.text));
+        else {
+            let after = new Map();
+            if (remaining() > sampleMs) {
+                await clock.sleep(sampleMs);
+                throwIfAborted(signal);
+                after = await sampleRound();
+            }
+            for (const pane of live) {
+                samples.set(pane.id, {
+                    before: before.get(pane.id) ?? null,
+                    after: after.get(pane.id) ?? null,
+                });
+            }
         }
-        return screens;
-    };
-    const before = await sample();
-    await clock.sleep(sampleMs);
-    const afterScreens = await sample();
+    }
+    if (samples.size === 0) {
+        // Per-pane sample pairs under bounded concurrency.
+        await mapPool(live, STATUS_DUMP_CONCURRENCY, async (pane) => {
+            throwIfAborted(signal);
+            const dumpOne = async () => {
+                const left = remaining();
+                if (left <= 0)
+                    return null;
+                try {
+                    const dumped = await client.dumpPane({
+                        session,
+                        paneId: pane.id,
+                        timeoutMs: left,
+                    });
+                    throwIfAborted(signal);
+                    return normalizeScreen(dumped.text);
+                }
+                catch (err) {
+                    if (isCancelledError(err) || signal?.aborted) {
+                        throw new ZellijError("cancelled", "operation cancelled");
+                    }
+                    return null;
+                }
+            };
+            const before = await dumpOne();
+            throwIfAborted(signal);
+            let after = null;
+            // This pane's interval starts when its first screen is available. Queue
+            // time and a slow first read cannot replace time between observations.
+            // Without room for the whole interval, keep it unknown rather than idle.
+            if (before !== null && remaining() > sampleMs) {
+                await clock.sleep(sampleMs);
+                throwIfAborted(signal);
+                after = await dumpOne();
+            }
+            samples.set(pane.id, { before, after });
+        });
+    }
+    throwIfAborted(signal);
     const peers = [];
+    let partial = false;
     for (const pane of targets) {
-        const first = before.get(pane.id) ?? "";
-        const after = pane.exited ? first : (afterScreens.get(pane.id) ?? "");
+        if (pane.exited) {
+            peers.push(peerEntry(pane, "exited", "", verbose));
+            continue;
+        }
+        const pair = samples.get(pane.id);
+        const first = pair?.before ?? null;
+        const after = pair?.after ?? null;
+        if (first == null || after == null) {
+            partial = true;
+            peers.push(peerEntry(pane, "unknown", after ?? first ?? "", verbose));
+            continue;
+        }
         const state = classify({
-            exited: pane.exited,
+            exited: false,
             before: first,
             after,
             profile: resolveHarness(pane),
         });
-        const entry = {
-            id: pane.id,
-            title: pane.title,
-            state,
-            lastLine: lastLine(after).slice(0, 160),
-        };
-        if (isTrue(args.verbose)) {
-            entry.command = pane.command ?? null;
-            entry.cwd = pane.cwd ?? null;
-            entry.tab = pane.tabName ?? null;
-        }
-        peers.push(entry);
+        peers.push(peerEntry(pane, state, after, verbose));
     }
     peers.sort((a, b) => String(a.id).localeCompare(String(b.id)));
     const free = peers.filter((p) => p.state === "idle").map((p) => p.id);
-    return {
-        ok: true,
-        data: { session, source, sampled: true, sampleMs, peers, free },
+    const data = {
+        session,
+        source,
+        sampled: true,
+        sampleMs,
+        peers,
+        tabs: statusTabs(peers),
+        free,
     };
+    if (partial || remaining() <= 0)
+        data.partial = true;
+    return { ok: true, data };
 }

package/dist/ops/types.d.ts

@@ -1,4 +1,5 @@
-export type OpsResult = {
+import type { RoutingContext } from "./routing.js";
+export type OpsResult = ({
     ok: true;
     data: unknown;
 } | {
@@ -6,7 +7,10 @@ export type OpsResult = {
     error: {
         code: string;
         message: string;
+        details?: Record<string, unknown>;
     };
+}) & {
+    context?: RoutingContext;
 };
 import type { GitClient } from "../git.js";
 import type { Policy } from "../policy.js";
@@ -19,6 +23,8 @@ export type DispatchDeps = {
     state?: StateStore;
     policy?: Policy;
     env?: NodeJS.ProcessEnv;
+    /** MCP cancellation; aborted waits stop instead of running to timeout. */
+    signal?: AbortSignal;
 };
 export type Clock = {
     now: () => number;

package/dist/ops/util.d.ts

@@ -13,6 +13,7 @@ export declare function paneViewSlim(p: ZellijPane): {
     title: string;
     command: string | null;
     tab: string | null;
+    tabId: number | null;
 };
 /**
  * The event-bus view. Zellij's pane manifest carries no command, so the key is
@@ -22,6 +23,7 @@ export declare function paneViewBus(p: ZellijPane): {
     id: string;
     title: string;
     tab: string | null;
+    tabId: number | null;
 };
 export declare function paneViewFull(p: ZellijPane): {
     cwd: string | null;
@@ -32,6 +34,7 @@ export declare function paneViewFull(p: ZellijPane): {
     title: string;
     command: string | null;
     tab: string | null;
+    tabId: number | null;
 };
 /** Truncate dump text; default keeps the tail (recent output). */
 export declare function truncateDumpText(text: string, maxChars: number, keep?: "tail" | "head"): {
@@ -45,4 +48,5 @@ export declare function numberArg(args: Record<string, unknown>, key: string, fa
     min: number;
     max: number;
 }): number;
+export declare function throwIfAborted(signal?: AbortSignal): void;
 export declare function dumpMaxChars(args: Record<string, unknown>, fallback?: number): number;

package/dist/ops/util.js

@@ -25,6 +25,7 @@ export function paneViewSlim(p) {
         title: p.title,
         command: p.command ?? null,
         tab: p.tabName ?? null,
+        tabId: p.tabId ?? null,
     };
 }
 /**
@@ -32,7 +33,7 @@ export function paneViewSlim(p) {
  * left out rather than reported as null — absent means unknown, not none.
  */
 export function paneViewBus(p) {
-    return { id: p.id, title: p.title, tab: p.tabName ?? null };
+    return { id: p.id, title: p.title, tab: p.tabName ?? null, tabId: p.tabId ?? null };
 }
 export function paneViewFull(p) {
     return {
@@ -73,6 +74,11 @@ export function numberArg(args, key, fallback, limits) {
     }
     return Math.min(limits.max, Math.max(limits.min, Math.floor(n)));
 }
+export function throwIfAborted(signal) {
+    if (signal?.aborted) {
+        throw new ZellijError("cancelled", "operation cancelled");
+    }
+}
 export function dumpMaxChars(args, fallback = DEFAULT_DUMP_MAX_CHARS) {
     if (args.max === undefined || args.max === null || args.max === "") {
         return fallback;

package/dist/ops/wait.d.ts

@@ -5,6 +5,13 @@ import type { Clock, OpsResult } from "./types.js";
 export declare function buildMatcher(args: Record<string, unknown>): ((text: string) => boolean) | null;
 /** Held-pipe wait answer, shaped by `parseWaitReply` in `zellij/bus.ts`. */
 export type { BusWait };
+/** Clamped timing the bus path must use — never the raw request numbers. */
+export type WaitBusTiming = {
+    idleMs: number;
+    timeoutMs: number;
+    pollMs: number;
+    full: boolean;
+};
 /**
  * Poll a pane's screen until it goes quiet, prints a match, or the deadline
  * passes — so callers stop re-dumping in a loop of their own.
@@ -16,4 +23,4 @@ export type { BusWait };
 export declare function waitForPane(client: ZellijClient, target: {
     session: string;
     pane: ZellijPane;
-}, args: Record<string, unknown>, clock: Clock, waitViaBus?: () => Promise<BusWait | null>): Promise<OpsResult>;
+}, args: Record<string, unknown>, clock: Clock, waitViaBus?: (timing: WaitBusTiming) => Promise<BusWait | null>, signal?: AbortSignal): Promise<OpsResult>;

package/dist/ops/wait.js

@@ -1,5 +1,5 @@
 import { ZellijError } from "../errors.js";
-import { DEFAULT_WAIT_MAX_CHARS, dumpMaxChars, isTrue, normalizeScreen, numberArg, optionalString, truncateDumpText, } from "./util.js";
+import { DEFAULT_WAIT_MAX_CHARS, dumpMaxChars, isTrue, normalizeScreen, numberArg, optionalString, throwIfAborted, truncateDumpText, } from "./util.js";
 const WAIT_DEFAULTS = {
     idleMs: 2_000,
     pollMs: 150,
@@ -56,7 +56,7 @@ function waitResult(reason, ctx) {
  * Null (plugin missing or silent) falls back to dump-screen polling. The
  * pipe's own timeout belongs to the transport; this op does not cap it.
  */
-export async function waitForPane(client, target, args, clock, waitViaBus) {
+export async function waitForPane(client, target, args, clock, waitViaBus, signal) {
     const { session, pane } = target;
     const matcher = buildMatcher(args);
     const requested = optionalString(args.for) ?? (matcher ? "match" : "idle");
@@ -72,8 +72,11 @@ export async function waitForPane(client, target, args, clock, waitViaBus) {
     const pollMs = numberArg(args, "pollMs", WAIT_DEFAULTS.pollMs, WAIT_LIMITS.pollMs);
     const timeoutMs = numberArg(args, "timeoutMs", WAIT_DEFAULTS.timeoutMs, WAIT_LIMITS.timeoutMs);
     const started = clock.now();
+    const full = isTrue(args.full);
     if (waitViaBus) {
-        const reply = await waitViaBus();
+        throwIfAborted(signal);
+        const reply = await waitViaBus({ idleMs, timeoutMs, pollMs, full });
+        throwIfAborted(signal);
         // `gone` is filtered upstream: a pane that vanished mid-wait is reported by
         // the polling path, which has the error message for it.
         if (reply && reply.reason !== "gone") {
@@ -96,6 +99,7 @@ export async function waitForPane(client, target, args, clock, waitViaBus) {
     let polls = 0;
     let changes = 0;
     for (;;) {
+        throwIfAborted(signal);
         const dumped = await client.dumpPane({
             session,
             paneId: pane.id,

package/dist/schema.d.ts

@@ -14,6 +14,8 @@ export type ParamSpec = {
     flags: string[];
     /** Repeatable flags collect into an array (`--key a --key b`). */
     repeat?: boolean;
+    /** Local CLI preprocessing, excluded from the MCP protocol. */
+    cliOnly?: boolean;
     values?: readonly string[];
     description: string;
 };