@zswarm/core 0.1.0

package/dist/keys.js

@@ -0,0 +1,168 @@
+import { ZellijError } from "./errors.js";
+/** Named keys Zellij accepts verbatim, keyed by their lowercase spelling. */
+const NAMED_KEYS = {
+    enter: "Enter",
+    return: "Enter",
+    esc: "Esc",
+    escape: "Esc",
+    tab: "Tab",
+    backspace: "Backspace",
+    bs: "Backspace",
+    delete: "Delete",
+    del: "Delete",
+    insert: "Insert",
+    ins: "Insert",
+    space: "Space",
+    up: "Up",
+    down: "Down",
+    left: "Left",
+    right: "Right",
+    home: "Home",
+    end: "End",
+    pageup: "PageUp",
+    pgup: "PageUp",
+    pagedown: "PageDown",
+    pgdn: "PageDown",
+};
+const MODIFIERS = {
+    ctrl: "Ctrl",
+    control: "Ctrl",
+    c: "Ctrl",
+    alt: "Alt",
+    meta: "Alt",
+    opt: "Alt",
+    option: "Alt",
+    shift: "Shift",
+    super: "Super",
+    cmd: "Super",
+    win: "Super",
+};
+/** Emission order; Zellij prints modifiers this way in its own docs. */
+const MODIFIER_ORDER = ["Ctrl", "Alt", "Shift", "Super"];
+function canonicalKey(raw) {
+    const key = raw.trim();
+    if (!key)
+        throw new ZellijError("bad_key", "empty key");
+    if (key.length === 1)
+        return key;
+    const named = NAMED_KEYS[key.toLowerCase()];
+    if (named)
+        return named;
+    if (/^f([1-9]|1[0-2])$/i.test(key))
+        return `F${key.slice(1)}`;
+    throw new ZellijError("bad_key", `unknown key "${raw}"; use a single character, F1-F12, or one of ${Object.values(NAMED_KEYS)
+        .filter((v, i, a) => a.indexOf(v) === i)
+        .join("/")}`);
+}
+/**
+ * Normalize one key spec into Zellij's `send-keys` spelling.
+ * Accepts `ctrl+c`, `Ctrl-C`, `^C`, `esc`, `Alt Shift b`, `f1`.
+ */
+export function normalizeKey(raw) {
+    const spec = raw.trim();
+    if (!spec)
+        throw new ZellijError("bad_key", "empty key");
+    if (/^\^[A-Za-z]$/.test(spec)) {
+        return `Ctrl ${spec.slice(1).toLowerCase()}`;
+    }
+    // Split on `+`, whitespace, or a `-` that separates a known modifier.
+    const parts = spec
+        .replace(/\b(ctrl|control|alt|meta|opt|option|shift|super|cmd|win)-/gi, "$1 ")
+        .split(/[+\s]+/)
+        .filter(Boolean);
+    if (parts.length === 0)
+        throw new ZellijError("bad_key", "empty key");
+    const mods = [];
+    for (let i = 0; i < parts.length - 1; i++) {
+        const mod = MODIFIERS[parts[i].toLowerCase()];
+        if (!mod) {
+            throw new ZellijError("bad_key", `unknown modifier "${parts[i]}" in "${raw}"`);
+        }
+        if (!mods.includes(mod))
+            mods.push(mod);
+    }
+    const key = canonicalKey(parts[parts.length - 1]);
+    if (mods.length === 0)
+        return key;
+    const ordered = MODIFIER_ORDER.filter((m) => mods.includes(m));
+    // A lone letter with a modifier is lowercase in Zellij's key syntax.
+    const base = key.length === 1 ? key.toLowerCase() : key;
+    return `${ordered.join(" ")} ${base}`;
+}
+/**
+ * Normalize a key list. Arrays hold one spec per entry; a string is a single
+ * spec unless it is comma separated (`"Esc,Enter"`), since `"Ctrl c"` is one key.
+ */
+export function normalizeKeys(input) {
+    const specs = [];
+    if (Array.isArray(input)) {
+        for (const entry of input) {
+            if (typeof entry !== "string") {
+                throw new ZellijError("bad_key", "keys entries must be strings");
+            }
+            specs.push(entry);
+        }
+    }
+    else if (typeof input === "string") {
+        specs.push(...(input.includes(",") ? input.split(",") : [input]));
+    }
+    else {
+        throw new ZellijError("bad_key", "keys must be a string or string array");
+    }
+    const keys = specs.map((s) => s.trim()).filter(Boolean).map(normalizeKey);
+    if (keys.length === 0)
+        throw new ZellijError("bad_key", "no keys given");
+    return keys;
+}
+/**
+ * Split a command line into argv. Arrays pass through; strings honour single
+ * and double quotes. Zellij runs the command directly — there is no shell.
+ */
+export function tokenizeCommand(input) {
+    if (input === undefined || input === null || input === "")
+        return [];
+    if (Array.isArray(input)) {
+        return input.map((part) => {
+            if (typeof part !== "string") {
+                throw new ZellijError("bad_command", "command entries must be strings");
+            }
+            return part;
+        });
+    }
+    if (typeof input !== "string") {
+        throw new ZellijError("bad_command", "command must be a string or array");
+    }
+    const argv = [];
+    let current = "";
+    let quote = null;
+    let started = false;
+    for (const ch of input) {
+        if (quote) {
+            if (ch === quote)
+                quote = null;
+            else
+                current += ch;
+            continue;
+        }
+        if (ch === '"' || ch === "'") {
+            quote = ch;
+            started = true;
+            continue;
+        }
+        if (/\s/.test(ch)) {
+            if (started)
+                argv.push(current);
+            current = "";
+            started = false;
+            continue;
+        }
+        current += ch;
+        started = true;
+    }
+    if (quote) {
+        throw new ZellijError("bad_command", `unbalanced ${quote} in command`);
+    }
+    if (started)
+        argv.push(current);
+    return argv;
+}

package/dist/ops/broadcast.d.ts

@@ -0,0 +1,19 @@
+import type { Policy } from "../policy.js";
+import type { StateStore } from "../state.js";
+import type { ZellijClient } from "../zellij/client.js";
+import type { ZellijPane } from "../zellij/panes.js";
+import type { Clock, OpsResult } from "./types.js";
+export type Skipped = {
+    id: string;
+    reason: string;
+};
+/**
+ * Pick the panes a broadcast should reach: an explicit comma list, a tab, or
+ * every terminal pane — then drop the ones it must not write to.
+ */
+export declare function selectTargets(client: ZellijClient, panes: ZellijPane[], args: Record<string, unknown>): {
+    targets: ZellijPane[];
+    skipped: Skipped[];
+};
+/** Send one body to many panes, reporting per-pane outcomes. */
+export declare function broadcast(client: ZellijClient, state: StateStore, args: Record<string, unknown>, clock: Clock, policy?: Policy): Promise<OpsResult>;

package/dist/ops/broadcast.js

@@ -0,0 +1,113 @@
+import { ZellijError } from "../errors.js";
+import { assertPaneAllowed } from "../policy.js";
+import { deliverTo } from "./delivery.js";
+import { isTrue, optionalString } from "./util.js";
+/**
+ * Pick the panes a broadcast should reach: an explicit comma list, a tab, or
+ * every terminal pane — then drop the ones it must not write to.
+ */
+export function selectTargets(client, panes, args) {
+    const skipped = [];
+    const list = optionalString(args.to);
+    const tab = optionalString(args.tab);
+    const group = optionalString(args.group);
+    let candidates;
+    if (list) {
+        candidates = [];
+        for (const key of list.split(",").map((k) => k.trim()).filter(Boolean)) {
+            try {
+                candidates.push(client.resolvePane(panes, key));
+            }
+            catch (err) {
+                skipped.push({
+                    id: key,
+                    reason: err instanceof ZellijError ? err.code : "peer_not_found",
+                });
+            }
+        }
+    }
+    else if (tab) {
+        const wanted = tab.toLowerCase();
+        candidates = panes.filter((p) => (p.tabName ?? "").toLowerCase() === wanted);
+    }
+    else if (isTrue(args.all)) {
+        candidates = panes.slice();
+    }
+    else {
+        throw new ZellijError("missing_target", "broadcast needs to, tab, or all");
+    }
+    // `group` narrows whatever the selector produced, by title or command.
+    if (group) {
+        const needle = group.toLowerCase();
+        candidates = candidates.filter((p) => p.title.toLowerCase().includes(needle) ||
+            (p.command ?? "").toLowerCase().includes(needle));
+    }
+    const seen = new Set();
+    const targets = [];
+    for (const pane of candidates) {
+        if (seen.has(pane.id))
+            continue;
+        seen.add(pane.id);
+        if (pane.isPlugin) {
+            skipped.push({ id: pane.id, reason: "pane_is_plugin" });
+            continue;
+        }
+        if (pane.id === client.selfPaneId && !isTrue(args.allowSelf)) {
+            skipped.push({ id: pane.id, reason: "self_target" });
+            continue;
+        }
+        if (pane.exited && !isTrue(args.force)) {
+            skipped.push({ id: pane.id, reason: "pane_exited" });
+            continue;
+        }
+        targets.push(pane);
+    }
+    return { targets, skipped };
+}
+/** Send one body to many panes, reporting per-pane outcomes. */
+export async function broadcast(client, state, args, clock, policy) {
+    const body = String(args.body ?? args.text ?? "");
+    if (!body.trim())
+        throw new ZellijError("missing_body", "body required");
+    const { session } = await client.resolveSession(typeof args.session === "string" ? args.session : undefined);
+    const panes = await client.listPanes(session);
+    const { targets: selected, skipped } = selectTargets(client, panes, args);
+    // Policy narrows the selection rather than failing the whole broadcast.
+    const targets = selected.filter((pane) => {
+        if (!policy)
+            return true;
+        try {
+            assertPaneAllowed(policy, pane, "broadcast");
+            return true;
+        }
+        catch {
+            skipped.push({ id: pane.id, reason: "policy_denied" });
+            return false;
+        }
+    });
+    if (targets.length === 0) {
+        throw new ZellijError("no_targets", `nothing to broadcast to${skipped.length > 0 ? ` (skipped ${skipped.map((s) => `${s.id}:${s.reason}`).join(", ")})` : ""}`);
+    }
+    const results = [];
+    for (const pane of targets) {
+        results.push(await deliverTo(client, state, args, {
+            session,
+            pane,
+            body,
+            op: "broadcast",
+            at: clock.now(),
+            clock,
+        }));
+    }
+    const delivered = results.filter((r) => r.ok);
+    return {
+        ok: true,
+        data: {
+            session,
+            from: (typeof args.from === "string" && args.from.trim()) || "swarm",
+            delivered: delivered.map((r) => r.to),
+            failed: results.filter((r) => !r.ok),
+            skipped,
+        },
+    };
+}

package/dist/ops/bus.d.ts

@@ -0,0 +1,59 @@
+import type { Policy } from "../policy.js";
+import type { StateStore } from "../state.js";
+import { type BusChanged, type BusSnapshot, type BusWait } from "../zellij/bus.js";
+import type { WaitRequest } from "../zellij/args.js";
+import type { ZellijClient } from "../zellij/client.js";
+import type { Clock, OpsResult } from "./types.js";
+export type BusPlan = {
+    enabled: boolean;
+    /** Why the bus is off, or how it was turned on. */
+    reason: string;
+    plugin: string | null;
+    url: string | null;
+    configKey: string;
+    installed: boolean;
+};
+/** Tests share a module instance; this drops what a previous case cached. */
+export declare function resetBusCache(): void;
+export declare function planBus(client: ZellijClient, state: StateStore, env?: NodeJS.ProcessEnv): BusPlan;
+/**
+ * One pipe, one answer — or null, and the caller polls instead.
+ *
+ * Two things go wrong in practice. A stale instance under the same key eats the
+ * message and replies with nothing, so each attempt rotates to a new key. And a
+ * freshly launched instance replies before Zellij has pushed it a manifest, so
+ * a not-ready answer is retried once rather than reported as an empty session.
+ */
+export declare function busSnapshot(client: ZellijClient, state: StateStore, session: string, clock: Clock, env?: NodeJS.ProcessEnv, payload?: string): Promise<{
+    snapshot: BusSnapshot;
+    configKey: string;
+} | null>;
+/**
+ * Read several pane screens in one pipe, or null to make the caller poll.
+ *
+ * Measured on this tree: the pipe costs ~0.055s fixed plus ~0.014s per pane,
+ * `dump-screen` ~0.050s per pane. So this is a loss for one pane and a win from
+ * two upward — callers must not route single-pane reads here.
+ *
+ * The text comes back as viewport lines padded to the terminal width, where
+ * `dump-screen` returns them ragged. `normalizeScreen` erases exactly that
+ * difference, and every caller here already normalizes before comparing.
+ */
+export declare function busScreens(client: ZellijClient, state: StateStore, session: string, paneIds: string[], clock: Clock, env?: NodeJS.ProcessEnv): Promise<Map<string, string> | null>;
+/**
+ * Hand the whole wait to the plugin, which holds the pipe until it resolves.
+ * One process covers a minute-long wait instead of one per poll, and the plugin
+ * can poll far tighter than a process spawn allows.
+ *
+ * Returns null for anything it will not serve — a regex needle, a cold
+ * instance, no reply — and the caller runs its own loop.
+ */
+export declare function busWait(client: ZellijClient, state: StateStore, session: string, request: WaitRequest, env?: NodeJS.ProcessEnv): Promise<BusWait | null>;
+/**
+ * Screens plus "did this move since you last asked". Answers the same question
+ * `status` answers by sampling twice, without the gap between samples — but
+ * relative to the previous call rather than a fixed window.
+ */
+export declare function busChanged(client: ZellijClient, state: StateStore, session: string, paneIds: string[], env?: NodeJS.ProcessEnv): Promise<BusChanged | null>;
+/** Report on the bus, install it, or forget it. */
+export declare function busOp(client: ZellijClient, state: StateStore, args: Record<string, unknown>, clock: Clock, env?: NodeJS.ProcessEnv, policy?: Policy): Promise<OpsResult>;

package/dist/ops/bus.js

@@ -0,0 +1,284 @@
+import { existsSync } from "node:fs";
+import { ZellijError } from "../errors.js";
+import { DEFAULT_BUS_KEY, busPluginUrl, nextConfigKey, parseBusReply, parseChangedReply, parseScrollbackReply, parseWaitReply, resolveBusPlugin, scrollbackToScreen, } from "../zellij/bus.js";
+import { isTrue } from "./util.js";
+/**
+ * Whether to ask the event-bus plugin, and what to do when it does not answer.
+ *
+ * The bus is off until `bus --install` has walked the plugin's permission
+ * prompt, because a pipe to a plugin that was never approved costs a process
+ * and a timeout on every call and then falls back anyway.
+ */
+/** Config keys to try before giving up; each one is a fresh pipe destination. */
+const MAX_KEY_ATTEMPTS = 3;
+/** A just-launched instance answers before Zellij has pushed it anything. */
+const COLD_RETRY_MS = 200;
+/** Set once a pipe has failed, so one dead plugin costs one timeout, not many. */
+let processDisabled = null;
+/** The key that actually answered, per session, for the life of this process. */
+const answeredWith = new Map();
+/** Tests share a module instance; this drops what a previous case cached. */
+export function resetBusCache() {
+    processDisabled = null;
+    answeredWith.clear();
+}
+function affirmative(raw) {
+    const v = (raw ?? "").trim().toLowerCase();
+    return v === "1" || v === "true" || v === "yes" || v === "on";
+}
+function negative(raw) {
+    const v = (raw ?? "").trim().toLowerCase();
+    return v === "0" || v === "false" || v === "no" || v === "off";
+}
+export function planBus(client, state, env = process.env) {
+    const marker = state.readBus();
+    // A marker can outlive the wasm it names — an upgrade renames the artifact,
+    // so a remembered path that no longer exists must not shadow the current one.
+    const remembered = marker && existsSync(marker.plugin) ? marker : null;
+    const plugin = remembered?.plugin ?? resolveBusPlugin(env);
+    const configKey = remembered?.configKey ?? DEFAULT_BUS_KEY;
+    const base = {
+        enabled: false,
+        reason: "",
+        plugin,
+        url: plugin ? busPluginUrl(plugin) : null,
+        configKey,
+        installed: marker !== null,
+    };
+    if (negative(env.ZSWARM_BUS))
+        return { ...base, reason: "ZSWARM_BUS=0" };
+    if (client.remote) {
+        return { ...base, reason: "remote session: a file: plugin url is local-only" };
+    }
+    if (!plugin) {
+        return {
+            ...base,
+            reason: "no plugin wasm found; build plugin/zswarm-events or set ZSWARM_BUS_PLUGIN",
+        };
+    }
+    if (processDisabled)
+        return { ...base, reason: processDisabled };
+    if (affirmative(env.ZSWARM_BUS)) {
+        return { ...base, enabled: true, reason: "ZSWARM_BUS=1" };
+    }
+    if (marker)
+        return { ...base, enabled: true, reason: "installed" };
+    return { ...base, reason: 'not installed; run zswarm({op:"bus", install:true})' };
+}
+async function askOnce(client, session, url, configKey, payload) {
+    const result = await client.pipePlugin({ session, url, configKey, payload });
+    return parseBusReply(result.stdout);
+}
+/**
+ * One pipe, one answer — or null, and the caller polls instead.
+ *
+ * Two things go wrong in practice. A stale instance under the same key eats the
+ * message and replies with nothing, so each attempt rotates to a new key. And a
+ * freshly launched instance replies before Zellij has pushed it a manifest, so
+ * a not-ready answer is retried once rather than reported as an empty session.
+ */
+export async function busSnapshot(client, state, session, clock, env = process.env, payload = "status") {
+    const plan = planBus(client, state, env);
+    const pluginPath = plan.plugin;
+    if (!plan.enabled || !plan.url || !pluginPath)
+        return null;
+    let configKey = answeredWith.get(session) ?? plan.configKey;
+    for (let attempt = 0; attempt < MAX_KEY_ATTEMPTS; attempt++) {
+        let snapshot = await askOnce(client, session, plan.url, configKey, payload);
+        if (snapshot && !snapshot.ready) {
+            await clock.sleep(COLD_RETRY_MS);
+            snapshot =
+                (await askOnce(client, session, plan.url, configKey, payload)) ??
+                    snapshot;
+        }
+        if (snapshot) {
+            answeredWith.set(session, configKey);
+            if (plan.installed && configKey !== plan.configKey) {
+                // Remember the rotation, so the next process starts on a live key.
+                state.writeBus({
+                    plugin: pluginPath,
+                    configKey,
+                    installedAt: clock.now(),
+                });
+            }
+            return { snapshot, configKey };
+        }
+        configKey = nextConfigKey(configKey);
+    }
+    processDisabled = "plugin did not answer; using zellij polling for this run";
+    return null;
+}
+/**
+ * Read several pane screens in one pipe, or null to make the caller poll.
+ *
+ * Measured on this tree: the pipe costs ~0.055s fixed plus ~0.014s per pane,
+ * `dump-screen` ~0.050s per pane. So this is a loss for one pane and a win from
+ * two upward — callers must not route single-pane reads here.
+ *
+ * The text comes back as viewport lines padded to the terminal width, where
+ * `dump-screen` returns them ragged. `normalizeScreen` erases exactly that
+ * difference, and every caller here already normalizes before comparing.
+ */
+export async function busScreens(client, state, session, paneIds, clock, env = process.env) {
+    if (paneIds.length < 2)
+        return null;
+    const plan = planBus(client, state, env);
+    if (!plan.enabled || !plan.url)
+        return null;
+    const configKey = answeredWith.get(session) ?? plan.configKey;
+    const reply = await client.scrollbackPlugin({
+        session,
+        url: plan.url,
+        configKey,
+        panes: paneIds,
+    });
+    const parsed = parseScrollbackReply(reply.stdout);
+    if (!parsed || !parsed.ready)
+        return null;
+    const screens = new Map();
+    for (const pane of parsed.panes) {
+        screens.set(pane.id, scrollbackToScreen(pane));
+    }
+    // A pane that vanished mid-read is normal; a wholesale miss is not, and
+    // silently returning fewer screens would read as "those panes are quiet".
+    return screens.size === paneIds.length ? screens : null;
+}
+/**
+ * Hand the whole wait to the plugin, which holds the pipe until it resolves.
+ * One process covers a minute-long wait instead of one per poll, and the plugin
+ * can poll far tighter than a process spawn allows.
+ *
+ * Returns null for anything it will not serve — a regex needle, a cold
+ * instance, no reply — and the caller runs its own loop.
+ */
+export async function busWait(client, state, session, request, env = process.env) {
+    const plan = planBus(client, state, env);
+    if (!plan.enabled || !plan.url)
+        return null;
+    const configKey = answeredWith.get(session) ?? plan.configKey;
+    const reply = await client.waitPlugin({
+        session,
+        url: plan.url,
+        configKey,
+        ...request,
+    });
+    const parsed = parseWaitReply(reply.stdout);
+    // `gone` means the pane vanished mid-wait; the polling path reports that
+    // with its own error, so let it.
+    return parsed && parsed.reason !== "gone" ? parsed : null;
+}
+/**
+ * Screens plus "did this move since you last asked". Answers the same question
+ * `status` answers by sampling twice, without the gap between samples — but
+ * relative to the previous call rather than a fixed window.
+ */
+export async function busChanged(client, state, session, paneIds, env = process.env) {
+    if (paneIds.length === 0)
+        return null;
+    const plan = planBus(client, state, env);
+    if (!plan.enabled || !plan.url)
+        return null;
+    const configKey = answeredWith.get(session) ?? plan.configKey;
+    const reply = await client.changedPlugin({
+        session,
+        url: plan.url,
+        configKey,
+        panes: paneIds,
+    });
+    const parsed = parseChangedReply(reply.stdout);
+    if (!parsed || !parsed.ready)
+        return null;
+    return parsed.panes.length === paneIds.length ? parsed : null;
+}
+/** Report on the bus, install it, or forget it. */
+export async function busOp(client, state, args, clock, env = process.env, policy) {
+    if (isTrue(args.clear)) {
+        state.clearBus();
+        resetBusCache();
+        return { ok: true, data: { installed: false, cleared: true } };
+    }
+    const { session } = await client.resolveSession(typeof args.session === "string" ? args.session : undefined);
+    if (isTrue(args.install)) {
+        // Installing opens a pane, which a read-only crew is not allowed to do.
+        if (policy?.readOnly) {
+            throw new ZellijError("policy_denied", 'op "bus" with install opens a pane; denied by ZSWARM_READONLY');
+        }
+        const plugin = resolveBusPlugin(env);
+        if (!plugin) {
+            throw new ZellijError("bus_missing", "no plugin wasm found; build plugin/zswarm-events or set ZSWARM_BUS_PLUGIN");
+        }
+        const previous = state.readBus();
+        const force = isTrue(args.force);
+        // Launching again would add a second instance, so an install that is
+        // already answering is a no-op unless the caller asked for a fresh one.
+        if (previous && !force) {
+            const live = await busSnapshot(client, state, session, clock, env);
+            if (live?.snapshot.ready) {
+                return {
+                    ok: true,
+                    data: {
+                        session,
+                        installed: true,
+                        plugin: previous.plugin,
+                        url: busPluginUrl(previous.plugin),
+                        configKey: live.configKey,
+                        ready: true,
+                        panes: live.snapshot.panes.length,
+                        note: "already installed; --force reloads under a fresh key",
+                    },
+                };
+            }
+        }
+        // A reload needs a key Zellij has not already bound an instance to.
+        const configKey = force && previous
+            ? nextConfigKey(previous.configKey)
+            : (previous?.configKey ?? DEFAULT_BUS_KEY);
+        const url = busPluginUrl(plugin);
+        const launched = await client.launchPlugin({
+            session,
+            url,
+            configKey,
+            floating: true,
+            skipCache: force,
+        });
+        state.writeBus({ plugin, configKey, installedAt: clock.now() });
+        resetBusCache();
+        const probe = await busSnapshot(client, state, session, clock, env);
+        return {
+            ok: true,
+            data: {
+                session,
+                installed: true,
+                plugin,
+                url,
+                configKey,
+                pane: launched.paneId,
+                ready: probe?.snapshot.ready ?? false,
+                panes: probe?.snapshot.panes.length ?? null,
+                note: probe
+                    ? "bus answering; list and status use it now, and this pane can be closed"
+                    : "approve the plugin's permission prompt in the new pane, then re-run",
+            },
+        };
+    }
+    const plan = planBus(client, state, env);
+    const probe = plan.enabled
+        ? await busSnapshot(client, state, session, clock, env)
+        : null;
+    return {
+        ok: true,
+        data: {
+            session,
+            enabled: plan.enabled,
+            reason: plan.reason,
+            installed: plan.installed,
+            plugin: plan.plugin,
+            url: plan.url,
+            configKey: probe?.configKey ?? plan.configKey,
+            ready: probe?.snapshot.ready ?? false,
+            paneUpdates: probe?.snapshot.paneUpdates ?? null,
+            tabUpdates: probe?.snapshot.tabUpdates ?? null,
+            panes: probe?.snapshot.panes.length ?? null,
+        },
+    };
+}

package/dist/ops/delivery.d.ts

@@ -0,0 +1,43 @@
+import type { StateStore } from "../state.js";
+import type { ZellijClient } from "../zellij/client.js";
+import type { ZellijPane } from "../zellij/panes.js";
+import type { Clock } from "./types.js";
+export type Submitted = boolean | "unverified";
+export type DeliveryResult = {
+    to: string;
+    ok: boolean;
+    delivery?: string;
+    submitted?: Submitted;
+    error?: {
+        code: string;
+        message: string;
+    };
+};
+export type SubmitMode = "auto" | "double-enter" | "none";
+export declare function senderLabel(args: Record<string, unknown>): string;
+export declare function bodyText(client: ZellijClient, args: Record<string, unknown>, body: string): string;
+/**
+ * Caller `submit=` always wins. With none given, the pane's harness picks
+ * auto vs double-enter (codex needs two Enters; the rest submit on one).
+ */
+export declare function resolveSubmitMode(args: Record<string, unknown>, pane: {
+    command?: string | null;
+    title?: string | null;
+}): SubmitMode;
+/** True when the paste still sits in the composer (bottom of the screen). */
+export declare function composerHolds(screen: string, body: string): boolean;
+/**
+ * Compare the pane before vs after the paste.
+ * Composer clearing (pasted text left the bottom input region) is submission.
+ * `[Pasted text` in scrollback is not evidence.
+ */
+export declare function classifySubmit(before: string, after: string, body: string): Submitted;
+/** Paste a body into one pane and record the attempt. */
+export declare function deliverTo(client: ZellijClient, state: StateStore, args: Record<string, unknown>, input: {
+    session: string;
+    pane: ZellijPane;
+    body: string;
+    op: string;
+    at: number;
+    clock: Clock;
+}): Promise<DeliveryResult>;