@zswarm/core 0.1.0

package/dist/ops/delivery.js

@@ -0,0 +1,191 @@
+import { resolveHarness } from "../harness.js";
+import { isTrue, numberArg } from "./util.js";
+/** Cursor / Claude leave this in scrollback after a successful submit. */
+const PASTE_MARKER = "[Pasted text";
+export function senderLabel(args) {
+    return (typeof args.from === "string" && args.from.trim()) || "swarm";
+}
+export function bodyText(client, args, body) {
+    return isTrue(args.raw) ? body : client.formatPeerMessage(senderLabel(args), body);
+}
+/**
+ * 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 function resolveSubmitMode(args, pane) {
+    const raw = args.submit;
+    if (raw === "none" || raw === "double-enter" || raw === "auto")
+        return raw;
+    if (raw !== undefined && raw !== null && raw !== "")
+        return "auto";
+    return resolveHarness(pane).submit;
+}
+function nonEmptyLines(screen) {
+    return screen
+        .replace(/\r/g, "")
+        .split("\n")
+        .map((line) => line.replace(/\s+$/, ""))
+        .filter((line) => line.length > 0);
+}
+function isPasteLine(line, needle) {
+    if (line.includes(PASTE_MARKER))
+        return true;
+    return needle.length > 0 && line.includes(needle);
+}
+/** True when the paste still sits in the composer (bottom of the screen). */
+export function composerHolds(screen, body) {
+    const needle = body.slice(0, 40);
+    const lines = nonEmptyLines(screen);
+    const last3 = lines.slice(-3);
+    const last = lines[lines.length - 1] ?? "";
+    if (last.includes(PASTE_MARKER))
+        return true;
+    return needle.length > 0 && last3.some((line) => line.includes(needle));
+}
+/**
+ * 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 function classifySubmit(before, after, body) {
+    const needle = body.slice(0, 40);
+    const beforeLines = nonEmptyLines(before);
+    const afterLines = nonEmptyLines(after);
+    const beforeNorm = beforeLines.join("\n");
+    const afterNorm = afterLines.join("\n");
+    const last3 = afterLines.slice(-3);
+    const last = afterLines[afterLines.length - 1] ?? "";
+    const markerInLastLine = last.includes(PASTE_MARKER);
+    const bodyInLastRegion = needle.length > 0 && last3.some((line) => line.includes(needle));
+    const holds = bodyInLastRegion || markerInLastLine;
+    if (afterNorm === beforeNorm) {
+        // Marker may only count when it sits in the last-line region *and*
+        // nothing else moved — leftover scrollback must not flip the answer.
+        if (markerInLastLine)
+            return false;
+        return "unverified";
+    }
+    if (holds) {
+        const withoutPaste = afterLines.filter((line) => !isPasteLine(line, needle));
+        if (withoutPaste.join("\n") === beforeNorm)
+            return false;
+        const lastPasteIdx = afterLines.reduce((found, line, i) => (isPasteLine(line, needle) ? i : found), -1);
+        const belowNovel = afterLines
+            .slice(lastPasteIdx + 1)
+            .filter((line) => !isPasteLine(line, needle))
+            .filter((line) => !beforeLines.includes(line));
+        return belowNovel.length > 0 ? true : false;
+    }
+    // Paste left the input region: still on screen, just not at the bottom.
+    if (needle.length > 0 && afterLines.some((line) => line.includes(needle))) {
+        return true;
+    }
+    return "unverified";
+}
+async function dumpOrNull(client, session, paneId) {
+    try {
+        return (await client.dumpPane({ session, paneId })).text;
+    }
+    catch {
+        return null;
+    }
+}
+async function verifySubmit(client, input) {
+    const { session, paneId, body, mode, settleMs, clock, before } = input;
+    if (mode === "none")
+        return "unverified";
+    if (mode === "double-enter") {
+        await clock.sleep(settleMs);
+        await client.sendKeys({ session, paneId, keys: ["Enter"] });
+        return "unverified";
+    }
+    if (before === null)
+        return "unverified";
+    await clock.sleep(settleMs);
+    const after = await dumpOrNull(client, session, paneId);
+    if (after === null)
+        return "unverified";
+    let verdict = classifySubmit(before, after, body);
+    if (verdict === true)
+        return true;
+    if (verdict === false) {
+        await client.sendKeys({ session, paneId, keys: ["Enter"] });
+        await clock.sleep(settleMs);
+        const rescued = await dumpOrNull(client, session, paneId);
+        if (rescued === null)
+            return "unverified";
+        verdict = classifySubmit(before, rescued, body);
+        if (verdict === true)
+            return true;
+        if (verdict === false)
+            return false;
+    }
+    // First look was inconclusive; TUIs often redraw after the first settle.
+    await clock.sleep(Math.min(Math.max(settleMs * 2, 800), 5000));
+    const later = await dumpOrNull(client, session, paneId);
+    if (later === null)
+        return "unverified";
+    if (composerHolds(after, body) && !composerHolds(later, body))
+        return true;
+    return classifySubmit(before, later, body);
+}
+/** Paste a body into one pane and record the attempt. */
+export async function deliverTo(client, state, args, input) {
+    const { session, pane, body, op, at, clock } = input;
+    const from = senderLabel(args);
+    const mode = resolveSubmitMode(args, pane);
+    const settleMs = numberArg(args, "settleMs", 300, { min: 50, max: 5000 });
+    try {
+        let before = null;
+        if (mode === "auto") {
+            before = await dumpOrNull(client, session, pane.id);
+        }
+        const delivered = await client.injectPane({
+            session,
+            paneId: pane.id,
+            text: bodyText(client, args, body),
+        });
+        const submitted = await verifySubmit(client, {
+            session,
+            paneId: delivered.paneId,
+            body,
+            mode,
+            settleMs,
+            clock,
+            before,
+        });
+        state.appendLog({
+            at,
+            op,
+            session,
+            to: delivered.paneId,
+            from,
+            bytes: body.length,
+            ok: true,
+            detail: `submitted=${submitted}`,
+        });
+        return {
+            to: delivered.paneId,
+            ok: true,
+            delivery: "zellij_paste",
+            submitted,
+        };
+    }
+    catch (err) {
+        const code = err && typeof err === "object" && "code" in err
+            ? String(err.code)
+            : "failed";
+        const message = err instanceof Error ? err.message : String(err);
+        state.appendLog({
+            at,
+            op,
+            session,
+            to: pane.id,
+            from,
+            bytes: body.length,
+            ok: false,
+            detail: `${code}: ${message}`,
+        });
+        return { to: pane.id, ok: false, error: { code, message } };
+    }
+}

package/dist/ops/dispatch.d.ts

@@ -0,0 +1,4 @@
+import { type ZellijClient } from "../zellij/client.js";
+import type { DispatchDeps, OpsResult } from "./types.js";
+/** Shared MCP/CLI dispatch for zswarm ops. */
+export declare function dispatchZswarm(args: Record<string, unknown>, client?: ZellijClient, deps?: DispatchDeps): Promise<OpsResult>;

package/dist/ops/dispatch.js

@@ -0,0 +1,331 @@
+import { ZellijError } from "../errors.js";
+import { createGitClient } from "../git.js";
+import { normalizeKeys } from "../keys.js";
+import { createZellijClient } from "../zellij/client.js";
+import { assertOpAllowed, assertPaneAllowed, loadPolicy, } from "../policy.js";
+import { createStateStore } from "../state.js";
+import { busToPanes } from "../zellij/bus.js";
+import { broadcast } from "./broadcast.js";
+import { busChanged, busOp, busScreens, busSnapshot, busWait } from "./bus.js";
+import { dumpLayoutOp, focusTarget, listTabsOp, renameTarget, stackTargets, } from "./panes.js";
+import { peerCheckpoint, peerDiff } from "./review.js";
+import { deliverTo } from "./delivery.js";
+import { assertNotPlugin, assertNotSelf, assertPaneExpects, assertWritable, } from "./guards.js";
+import { readDeliveryLog } from "./log.js";
+import { awaitSignal, listSignals, postSignal } from "./signals.js";
+import { spawnPane } from "./spawn.js";
+import { peerStatus } from "./status.js";
+import { tailPane } from "./tail.js";
+import { OP_NAMES } from "../schema.js";
+import { dumpMaxChars, fail, isTrue, isVerbose, paneViewBus, paneViewFull, paneViewSlim, truncateDumpText, } from "./util.js";
+import { waitForPane } from "./wait.js";
+import { listPeerWorktrees, removePeerWorktree } from "./worktree.js";
+/** Same default `wait` applies: match when a needle is given, else idle. */
+function waitMode(args) {
+    const requested = typeof args.for === "string" ? args.for.trim() : "";
+    if (requested === "match" || requested === "either" || requested === "idle") {
+        return requested;
+    }
+    return typeof args.match === "string" && args.match ? "match" : "idle";
+}
+async function resolveTarget(client, args, state, clock, env, policy, op) {
+    const to = String(args.to ?? "").trim();
+    if (!to)
+        throw new ZellijError("missing_peer", "to required");
+    const { session } = await client.resolveSession(typeof args.session === "string" ? args.session : undefined);
+    // The plugin manifest carries no cwd/command/floating, so verbose
+    // responses have to go the polling route.
+    const bus = isVerbose(args)
+        ? null
+        : await busSnapshot(client, state, session, clock, env);
+    let panes = null;
+    if (bus) {
+        const busPanes = busToPanes(bus.snapshot);
+        try {
+            client.resolvePane(busPanes, to);
+            panes = busPanes;
+        }
+        catch {
+            // A command-shaped `to` only matches the polled list.
+        }
+    }
+    if (!panes)
+        panes = await client.listPanes(session);
+    const pane = client.resolvePane(panes, to);
+    if (policy && op)
+        assertPaneAllowed(policy, pane, op);
+    return { session, panes, pane };
+}
+/** Shared MCP/CLI dispatch for zswarm ops. */
+export async function dispatchZswarm(args, client = createZellijClient(), deps = {}) {
+    const op = String(args.op ?? "");
+    const verbose = isVerbose(args);
+    const clock = {
+        now: deps.now ?? (() => Date.now()),
+        sleep: deps.sleep ??
+            ((ms) => new Promise((r) => setTimeout(r, ms))),
+    };
+    // Only the worktree ops need git, so the client is built on demand.
+    let gitClient = deps.git ?? null;
+    const git = () => (gitClient ??= createGitClient());
+    let stateStore = deps.state ?? null;
+    const state = () => (stateStore ??= createStateStore());
+    const policy = deps.policy ?? loadPolicy(deps.env);
+    try {
+        // Policy gates the op before anything touches the session.
+        assertOpAllowed(policy, op);
+        switch (op) {
+            case "sessions": {
+                const sessions = await client.listSessions();
+                return { ok: true, data: { sessions, zellij: client.zellijPath } };
+            }
+            case "list": {
+                const { session } = await client.resolveSession(typeof args.session === "string" ? args.session : undefined);
+                // The plugin's manifest carries no cwd or floating flag, so anything
+                // verbose has to go the polling route.
+                const bus = verbose
+                    ? null
+                    : await busSnapshot(client, state(), session, clock, deps.env);
+                const view = bus ? paneViewBus : verbose ? paneViewFull : paneViewSlim;
+                const panes = (bus ? busToPanes(bus.snapshot) : await client.listPanes(session))
+                    .filter((p) => !p.isPlugin)
+                    .map(view)
+                    .sort((a, b) => a.id.localeCompare(b.id));
+                const data = {
+                    session,
+                    source: bus ? "plugin" : "zellij",
+                    panes,
+                };
+                if (verbose && client.selfPaneId)
+                    data.self = client.selfPaneId;
+                return { ok: true, data };
+            }
+            case "send": {
+                const body = String(args.body ?? args.text ?? "");
+                if (!body.trim())
+                    throw new ZellijError("missing_body", "body required");
+                const { session, pane } = await resolveTarget(client, args, state(), clock, deps.env, policy, op);
+                assertWritable(client, pane, args, "send");
+                // A pane that dropped back to a shell will *run* the message. There is
+                // no reliable way to tell an agent from a prompt, so the caller names
+                // something the screen must show first.
+                const expect = typeof args.expect === "string" ? args.expect.trim() : "";
+                if (expect) {
+                    const screen = await client.dumpPane({ session, paneId: pane.id });
+                    assertPaneExpects(screen.text, expect, pane.id);
+                }
+                const result = await deliverTo(client, state(), args, {
+                    session,
+                    pane,
+                    body,
+                    op: "send",
+                    at: clock.now(),
+                    clock,
+                });
+                if (!result.ok && result.error) {
+                    throw new ZellijError(result.error.code, result.error.message);
+                }
+                const data = {
+                    delivery: result.delivery,
+                    session,
+                    to: result.to,
+                    from: (typeof args.from === "string" && args.from.trim()) || "swarm",
+                    submitted: result.submitted,
+                };
+                if (verbose)
+                    data.pane = paneViewFull(pane);
+                return { ok: true, data };
+            }
+            case "broadcast":
+                return await broadcast(client, state(), args, clock, policy);
+            case "keys":
+            case "interrupt": {
+                const { session, pane } = await resolveTarget(client, args, state(), clock, deps.env, policy, op);
+                assertWritable(client, pane, args, op);
+                const chars = typeof args.chars === "string" ? args.chars : "";
+                if (op === "keys" && chars) {
+                    await client.writeChars({ session, paneId: pane.id, chars });
+                    if (isTrue(args.enter)) {
+                        await client.sendKeys({ session, paneId: pane.id, keys: ["Enter"] });
+                    }
+                    state().appendLog({
+                        at: clock.now(),
+                        op,
+                        session,
+                        to: pane.id,
+                        bytes: chars.length,
+                        ok: true,
+                        detail: "write-chars",
+                    });
+                    return {
+                        ok: true,
+                        data: {
+                            session,
+                            to: pane.id,
+                            delivery: "zellij_write_chars",
+                            chars: chars.length,
+                            enter: isTrue(args.enter),
+                        },
+                    };
+                }
+                const keys = op === "interrupt"
+                    ? normalizeKeys(args.keys ?? (isTrue(args.hard) ? "Ctrl c" : "Esc"))
+                    : normalizeKeys(args.keys);
+                const sent = await client.sendKeys({ session, paneId: pane.id, keys });
+                if (op === "keys" && isTrue(args.enter)) {
+                    await client.sendKeys({ session, paneId: pane.id, keys: ["Enter"] });
+                }
+                state().appendLog({
+                    at: clock.now(),
+                    op,
+                    session,
+                    to: sent.paneId,
+                    ok: true,
+                    detail: sent.keys.join(" "),
+                });
+                return {
+                    ok: true,
+                    data: {
+                        session,
+                        to: sent.paneId,
+                        delivery: "zellij_send_keys",
+                        keys: sent.keys,
+                    },
+                };
+            }
+            case "dump": {
+                const { session, pane } = await resolveTarget(client, args, state(), clock, deps.env);
+                const dumped = await client.dumpPane({
+                    session,
+                    paneId: pane.id,
+                    full: isTrue(args.full),
+                });
+                const max = dumpMaxChars(args);
+                const keep = isTrue(args.head) ? "head" : "tail";
+                const clipped = truncateDumpText(dumped.text, max, keep);
+                return {
+                    ok: true,
+                    data: {
+                        session: dumped.session,
+                        to: dumped.paneId,
+                        text: clipped.text,
+                        truncated: clipped.truncated,
+                        chars: clipped.chars,
+                        max,
+                    },
+                };
+            }
+            case "tail": {
+                const target = await resolveTarget(client, args, state(), clock, deps.env);
+                return await tailPane(client, state(), args, target);
+            }
+            case "wait": {
+                const target = await resolveTarget(client, args, state(), clock, deps.env);
+                // The plugin holds one pipe for the whole wait and polls far tighter
+                // than spawning a process allows. It declines a regex needle — it has
+                // no engine — and then this is the loop that runs.
+                const viaBus = isTrue(args.regex)
+                    ? undefined
+                    : () => busWait(client, state(), target.session, {
+                        pane: target.pane.id,
+                        for: waitMode(args),
+                        match: typeof args.match === "string" ? args.match : null,
+                        ignoreCase: isTrue(args.ignoreCase),
+                        idleMs: Number(args.idleMs ?? 2000),
+                        timeoutMs: Number(args.timeoutMs ?? 60_000),
+                    }, deps.env);
+                return await waitForPane(client, target, args, clock, viaBus);
+            }
+            case "status": {
+                const { session } = await client.resolveSession(typeof args.session === "string" ? args.session : undefined);
+                // Verbose reports cwd and command, which the plugin manifest lacks.
+                const bus = verbose
+                    ? null
+                    : await busSnapshot(client, state(), session, clock, deps.env);
+                let supplied = bus
+                    ? {
+                        session,
+                        panes: busToPanes(bus.snapshot),
+                        source: "plugin",
+                        // Sampling is 2N dumps; the plugin reads them all in one pipe.
+                        readScreens: (paneIds) => busScreens(client, state(), session, paneIds, clock, deps.env),
+                        readChanged: async (paneIds) => {
+                            const reply = await busChanged(client, state(), session, paneIds, deps.env);
+                            if (!reply)
+                                return null;
+                            return new Map(reply.panes.map((p) => [
+                                p.id,
+                                { changed: p.changed, first: p.first, screen: p.screen },
+                            ]));
+                        },
+                    }
+                    : null;
+                const only = typeof args.to === "string" ? args.to.trim() : "";
+                if (supplied && only) {
+                    try {
+                        client.resolvePane(supplied.panes, only);
+                    }
+                    catch {
+                        // The manifest has no commands, so a command-shaped `to` only
+                        // resolves against the polled list.
+                        supplied = null;
+                    }
+                }
+                return await peerStatus(client, args, clock, supplied);
+            }
+            case "bus":
+                return await busOp(client, state(), args, clock, deps.env, policy);
+            case "signal":
+                return postSignal(state(), args, clock);
+            case "signals":
+                return listSignals(state());
+            case "await":
+                return await awaitSignal(state(), args, clock);
+            case "log":
+                return readDeliveryLog(state(), args);
+            case "rename":
+                return await renameTarget(client, args);
+            case "focus":
+                return await focusTarget(client, args);
+            case "tabs":
+                return await listTabsOp(client, args);
+            case "layout":
+                return await dumpLayoutOp(client, args);
+            case "stack":
+                return await stackTargets(client, args);
+            case "diff":
+                return await peerDiff(git(), args);
+            case "checkpoint":
+                return await peerCheckpoint(git(), args, clock);
+            case "spawn":
+                return await spawnPane(client, args, deps.git);
+            case "worktrees":
+                return await listPeerWorktrees(git(), client, args);
+            case "unworktree":
+                return await removePeerWorktree(git(), client, args);
+            case "close": {
+                const { session, pane } = await resolveTarget(client, args, state(), clock, deps.env, policy, op);
+                // Not assertWritable: closing an exited pane is the point of close.
+                assertNotPlugin(pane, "close");
+                assertNotSelf(client, pane, args, "close");
+                const closed = await client.closePane({ session, paneId: pane.id });
+                state().appendLog({
+                    at: clock.now(),
+                    op: "close",
+                    session,
+                    to: closed.paneId,
+                    ok: true,
+                });
+                return {
+                    ok: true,
+                    data: { session: closed.session, closed: closed.paneId },
+                };
+            }
+            default:
+                throw new ZellijError("usage", `zswarm requires op=${OP_NAMES.join("|")}`);
+        }
+    }
+    catch (err) {
+        return fail(err);
+    }
+}

package/dist/ops/guards.d.ts

@@ -0,0 +1,15 @@
+import type { ZellijClient } from "../zellij/client.js";
+import type { ZellijPane } from "../zellij/panes.js";
+export declare function assertNotPlugin(pane: ZellijPane, action: string): void;
+export declare function assertNotSelf(client: ZellijClient, pane: ZellijPane, args: Record<string, unknown>, action: string): void;
+/**
+ * Refuse writes that would loop back into the caller's own pane, land in a
+ * dead pane, or hit a plugin pane. `allowSelf` / `force` opt out.
+ */
+export declare function assertWritable(client: ZellijClient, pane: ZellijPane, args: Record<string, unknown>, action: string): void;
+/**
+ * Opt-in check that the pane still looks like the intended agent, not a
+ * shell that would execute the body as a command. Substring only — a regex
+ * in a safety check is a foot-gun.
+ */
+export declare function assertPaneExpects(screen: string, expect: string, paneId: string): void;

package/dist/ops/guards.js

@@ -0,0 +1,36 @@
+import { ZellijError } from "../errors.js";
+import { isTrue } from "./util.js";
+export function assertNotPlugin(pane, action) {
+    if (pane.isPlugin) {
+        throw new ZellijError("pane_is_plugin", `${pane.id} is a plugin pane; ${action} targets terminal panes`);
+    }
+}
+export function assertNotSelf(client, pane, args, action) {
+    const self = client.selfPaneId;
+    if (self && pane.id === self && !isTrue(args.allowSelf)) {
+        throw new ZellijError("self_target", `refusing to ${action} into zswarm's own pane (${self}); pass allowSelf=true to override`);
+    }
+}
+/**
+ * Refuse writes that would loop back into the caller's own pane, land in a
+ * dead pane, or hit a plugin pane. `allowSelf` / `force` opt out.
+ */
+export function assertWritable(client, pane, args, action) {
+    assertNotPlugin(pane, action);
+    assertNotSelf(client, pane, args, action);
+    if (pane.exited && !isTrue(args.force)) {
+        throw new ZellijError("pane_exited", `${pane.id} has exited; pass force=true to write to it anyway`);
+    }
+}
+/**
+ * Opt-in check that the pane still looks like the intended agent, not a
+ * shell that would execute the body as a command. Substring only — a regex
+ * in a safety check is a foot-gun.
+ */
+export function assertPaneExpects(screen, expect, paneId) {
+    if (!expect)
+        return;
+    if (screen.toLowerCase().includes(expect.toLowerCase()))
+        return;
+    throw new ZellijError("expect_missing", `${paneId} screen does not contain ${JSON.stringify(expect)}`);
+}

package/dist/ops/log.d.ts

@@ -0,0 +1,4 @@
+import type { StateStore } from "../state.js";
+import type { OpsResult } from "./types.js";
+/** Read back the delivery log: what zswarm sent where, and whether it landed. */
+export declare function readDeliveryLog(state: StateStore, args: Record<string, unknown>): OpsResult;

package/dist/ops/log.js

@@ -0,0 +1,26 @@
+import { isTrue, numberArg, optionalString } from "./util.js";
+/** Read back the delivery log: what zswarm sent where, and whether it landed. */
+export function readDeliveryLog(state, args) {
+    const limit = numberArg(args, "limit", 20, { min: 1, max: 1_000 });
+    const to = optionalString(args.to);
+    const since = optionalString(args.since);
+    const sinceAt = since ? Number(since) : null;
+    const failures = isTrue(args.failed);
+    let entries = state.readLog();
+    if (to)
+        entries = entries.filter((e) => e.to === to);
+    if (sinceAt !== null && Number.isFinite(sinceAt)) {
+        entries = entries.filter((e) => e.at >= sinceAt);
+    }
+    if (failures)
+        entries = entries.filter((e) => !e.ok);
+    return {
+        ok: true,
+        data: {
+            dir: state.dir,
+            logging: state.logging,
+            total: entries.length,
+            entries: entries.slice(-limit),
+        },
+    };
+}

package/dist/ops/panes.d.ts

@@ -0,0 +1,13 @@
+import type { ZellijClient } from "../zellij/client.js";
+import type { OpsResult } from "./types.js";
+/**
+ * Give a pane (or its tab) a stable name, so peers can be addressed as
+ * `reviewer` instead of whatever id Zellij handed out.
+ */
+export declare function renameTarget(client: ZellijClient, args: Record<string, unknown>): Promise<OpsResult>;
+export declare function focusTarget(client: ZellijClient, args: Record<string, unknown>): Promise<OpsResult>;
+export declare function listTabsOp(client: ZellijClient, args: Record<string, unknown>): Promise<OpsResult>;
+/** The session's current layout as KDL — a spawnable description of the crew. */
+export declare function dumpLayoutOp(client: ZellijClient, args: Record<string, unknown>): Promise<OpsResult>;
+/** Collapse several peers into one stack so a big crew stays readable. */
+export declare function stackTargets(client: ZellijClient, args: Record<string, unknown>): Promise<OpsResult>;