@zswarm/core 0.2.6 → 0.2.7

package/dist/ops/restart.js

@@ -0,0 +1,416 @@
+import { readFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { ZellijError } from "../errors.js";
+import { readyPrompt, resolveHarness } from "../harness.js";
+import { findLease } from "../host/lease.js";
+import { tokenizeCommand } from "../keys.js";
+import { deliverTo } from "./delivery.js";
+import { assertNotPlugin, assertNotSelf } from "./guards.js";
+import { isTrue, numberArg, optionalString, throwIfAborted } from "./util.js";
+/**
+ * Restart the agent in one pane, in place: same pane id, title and position.
+ *
+ * A Zellij command pane (a `command=` layout entry or `zellij run`) stays open
+ * when its command exits and offers ENTER to re-run the same command — that is
+ * the in-place relaunch. A shell pane has no such prompt, so the profile's
+ * launch command (or `--command`) is typed instead.
+ */
+/** The agent prints this once its handoff file is written. */
+export const HANDOFF_MARKER = "ZSWARM-HANDOFF-DONE";
+/** A handoff at or under this many chars is pasted; longer ones get a pointer. */
+export const HANDOFF_INLINE_MAX = 2_000;
+/** Bound on waiting for a self-written handoff marker. */
+export const HANDOFF_SELF_WAIT_MS = 60_000;
+/** Bound on waiting for the pane's command to exit before the Ctrl+C fallback. */
+export const EXIT_WAIT_MS = 10_000;
+/** Bound on waiting for readiness after relaunch (marker or settled screen). */
+export const READY_WAIT_MS = 45_000;
+/** Extra settle after a ready marker before the handoff is pasted. */
+export const READY_SETTLE_MS = 500;
+/** A screen that has not changed for this long counts as settled. */
+export const READY_STABLE_GAP_MS = 1_000;
+/** Screen poll interval while a step waits. */
+export const RESTART_POLL_MS = 250;
+/**
+ * Zellij keeps an exited command pane on screen with a re-run prompt. The exact
+ * wording has changed between releases, so match the stable phrases.
+ */
+const RERUN_PROMPT = /press\s+enter[^\n]*re-?run|re-?run[^\n]*press\s+enter|command exited|exit\s+code/i;
+/** A shell prompt at the end of a line (the agent quit back to the shell). */
+const SHELL_PROMPT = /(?:^|\n)[^\n]*[$#%] ?$|❯ ?$/;
+/** Basenames that mean "this pane is a shell, not an agent command". */
+const SHELL_COMMANDS = new Set([
+    "bash", "zsh", "fish", "sh", "dash", "ksh", "csh", "tcsh", "nu", "nushell",
+    "pwsh", "powershell", "cmd", "wsl", "login",
+]);
+/**
+ * A command pane ran the agent itself, so ENTER re-runs it. A shell pane had the
+ * agent started inside a shell, so the launch command has to be typed again.
+ * A pane with no command information is treated as a shell: typing a launch
+ * command is recoverable, pressing ENTER into a live agent is not.
+ */
+export function restartPaneKind(pane) {
+    const command = pane.command?.trim();
+    if (!command)
+        return "shell";
+    const base = command
+        .replace(/\\/g, "/")
+        .split("/")
+        .pop()
+        .replace(/\.(exe|cmd|bat)$/i, "")
+        .toLowerCase();
+    return SHELL_COMMANDS.has(base) ? "shell" : "command";
+}
+/** The command line a shell pane gets to relaunch the agent. */
+export function restartLaunchCommand(args, profile) {
+    const raw = args.command;
+    if (typeof raw === "string" && raw.trim())
+        return raw.trim();
+    if (Array.isArray(raw)) {
+        const tokens = tokenizeCommand(raw);
+        if (tokens.length > 0)
+            return tokens.join(" ");
+    }
+    return profile.launch;
+}
+function readTextFile(path) {
+    try {
+        return readFileSync(path, "utf8");
+    }
+    catch {
+        return null;
+    }
+}
+async function waitForScreen(client, session, paneId, predicate, budgetMs, clock, signal) {
+    const started = clock.now();
+    const end = started + budgetMs;
+    let screen = "";
+    for (;;) {
+        throwIfAborted(signal);
+        try {
+            screen = (await client.dumpPane({ session, paneId })).text;
+        }
+        catch {
+            screen = "";
+        }
+        if (predicate(screen)) {
+            return { ok: true, elapsedMs: clock.now() - started, screen };
+        }
+        if (clock.now() >= end) {
+            return { ok: false, elapsedMs: clock.now() - started, screen };
+        }
+        await clock.sleep(Math.min(RESTART_POLL_MS, Math.max(1, end - clock.now())));
+    }
+}
+/**
+ * Wait until the screen stops changing: two identical non-empty dumps at least
+ * READY_STABLE_GAP_MS apart. This is the readiness evidence for a profile with
+ * no declared marker (OpenCode has one, but an unknown or unmarked harness has
+ * nothing better than "the UI stopped repainting").
+ */
+async function waitForStableScreen(client, session, paneId, budgetMs, clock, signal) {
+    const started = clock.now();
+    const end = started + budgetMs;
+    let previous = null;
+    let lastChangeAt = started;
+    let screen = "";
+    for (;;) {
+        throwIfAborted(signal);
+        try {
+            screen = (await client.dumpPane({ session, paneId })).text;
+        }
+        catch {
+            screen = "";
+        }
+        const now = clock.now();
+        if (previous !== null &&
+            screen === previous &&
+            screen.trim().length > 0 &&
+            now - lastChangeAt >= READY_STABLE_GAP_MS) {
+            return { ok: true, elapsedMs: now - started, screen };
+        }
+        if (previous === null || screen !== previous)
+            lastChangeAt = now;
+        previous = screen;
+        if (now >= end)
+            return { ok: false, elapsedMs: now - started, screen };
+        await clock.sleep(Math.min(RESTART_POLL_MS, Math.max(1, end - clock.now())));
+    }
+}
+/**
+ * Readiness after the relaunch. A declared marker is waited for, then a short
+ * settle so the composer accepts input. Without one, the screen has to stop
+ * changing; skipping the wait is what pasted a handoff into OpenCode before its
+ * UI took input.
+ */
+async function awaitReady(client, session, paneId, profile, budgetMs, clock, signal) {
+    const waitMs = Math.max(1, budgetMs());
+    if (profile.ready.length > 0) {
+        const seen = await waitForScreen(client, session, paneId, (screen) => readyPrompt(screen, profile), waitMs, clock, signal);
+        if (!seen.ok) {
+            return { ok: false, detail: `${profile.name} ready marker not seen within ${waitMs}ms` };
+        }
+        await clock.sleep(READY_SETTLE_MS);
+        return { ok: true, detail: `ready after ${seen.elapsedMs}ms` };
+    }
+    const stable = await waitForStableScreen(client, session, paneId, waitMs, clock, signal);
+    if (!stable.ok) {
+        return { ok: false, detail: `${profile.name} screen did not settle within ${waitMs}ms` };
+    }
+    return {
+        ok: true,
+        detail: `screen stable after ${stable.elapsedMs}ms (no ready marker for ${profile.name})`,
+    };
+}
+async function waitForExit(client, session, pane, kind, profile, budgetMs, clock, signal) {
+    const end = clock.now() + budgetMs;
+    for (;;) {
+        throwIfAborted(signal);
+        try {
+            const panes = await client.listPanes(session, Math.max(1, end - clock.now()), { fresh: true });
+            const live = panes.find((p) => p.id === pane.id);
+            if (live?.exited)
+                return { exited: true, reason: "pane_exited" };
+        }
+        catch {
+            // A transient listing failure is not evidence the pane is gone.
+        }
+        try {
+            const screen = (await client.dumpPane({ session, paneId: pane.id })).text;
+            if (kind === "command" && RERUN_PROMPT.test(screen)) {
+                return { exited: true, reason: "rerun_prompt" };
+            }
+            if (kind === "shell" &&
+                SHELL_PROMPT.test(screen) &&
+                !readyPrompt(screen, profile) &&
+                !/\besc to interrupt\b/i.test(screen)) {
+                return { exited: true, reason: "shell_prompt" };
+            }
+        }
+        catch {
+            // Keep polling; a failed read is not proof of exit.
+        }
+        if (clock.now() >= end)
+            return { exited: false, reason: "timeout" };
+        await clock.sleep(Math.min(RESTART_POLL_MS, Math.max(1, end - clock.now())));
+    }
+}
+function failStep(step, message, steps) {
+    throw new ZellijError("restart_failed", `restart failed at step "${step}": ${message}`, {
+        step,
+        steps,
+    });
+}
+function handoffBodyFor(content, pointer) {
+    if (content && content.length > 0) {
+        if (content.length <= HANDOFF_INLINE_MAX || !pointer) {
+            return { body: content, pointer: false };
+        }
+    }
+    if (pointer) {
+        return { body: `Read your handoff from ${pointer} and continue the task.`, pointer: true };
+    }
+    return null;
+}
+/**
+ * Restart one already-resolved pane. `target` comes from dispatch's
+ * `resolveTarget`, so policy and pane lookup are shared with the other ops.
+ */
+export async function restartPane(client, state, args, target, clock, opts = {}) {
+    const { session, pane } = target;
+    const signal = opts.signal;
+    const started = clock.now();
+    const timeoutMs = numberArg(args, "timeoutMs", 30_000, { min: 1, max: 900_000 });
+    const deadline = started + timeoutMs;
+    const remaining = () => Math.max(0, deadline - clock.now());
+    // A bus-resolved pane carries no command, but restart must know whether it
+    // is a command pane (ENTER re-run) or a shell pane (type the launch command).
+    // Re-list directly so the pane's command is present.
+    let observed = pane;
+    if (!observed.command) {
+        try {
+            const fresh = await client.listPanes(session, Math.max(1, remaining()), { fresh: true });
+            observed = fresh.find((p) => p.id === pane.id) ?? pane;
+        }
+        catch {
+            // Keep the bus pane; an unknown command falls back to the shell branch.
+        }
+    }
+    assertNotPlugin(observed, "restart");
+    assertNotSelf(client, observed, args, "restart");
+    // A relay working the pane owns it; restarting under it would kill the task.
+    const to = String(args.to ?? "").trim();
+    const held = findLease(state, {
+        serve: typeof args.serve === "string" && args.serve.trim() ? args.serve.trim() : opts.env?.ZSWARM_SERVE,
+        session,
+        pane: to,
+    });
+    if (held && !isTrue(args.force)) {
+        throw new ZellijError("pane_leased", `pane ${to} is leased by relay ${held.relayId} (from ${held.from}, since ${new Date(held.at).toISOString()}); pass force=true to restart it anyway`, { relayId: held.relayId, from: held.from, at: held.at, dir: held.dir });
+    }
+    const profile = resolveHarness(observed);
+    const kind = restartPaneKind(observed);
+    const handoffSelf = isTrue(args.handoffSelf);
+    const supplied = typeof args.handoff === "string" && args.handoff.length > 0 ? args.handoff : null;
+    const suppliedPath = optionalString(args.handoffPath) ?? optionalString(args.handoffFile);
+    const steps = [];
+    const record = (step, ok, detail) => {
+        steps.push({ step, ok, detail, elapsedMs: clock.now() - started });
+    };
+    // (1) Handoff: the running agent writes one, or the caller supplies it.
+    let handoffContent = supplied;
+    let handoffPath = suppliedPath;
+    if (handoffSelf) {
+        const path = handoffPath
+            ?? join(tmpdir(), `zswarm-handoff-${session}-${pane.numericId}.md`);
+        handoffPath = path;
+        const instruction = `Write your handoff for the next agent to ${path}. ` +
+            `Then print ${HANDOFF_MARKER} on its own line.`;
+        const asked = await deliverTo(client, state, args, {
+            session,
+            pane: observed,
+            body: instruction,
+            op: "restart",
+            at: clock.now(),
+            clock,
+            timeoutMs: Math.max(1, remaining()),
+        });
+        if (!asked.ok) {
+            record("handoff-self", false, `could not ask the agent: ${asked.error?.message ?? "unknown"}`);
+            failStep("handoff-self", `could not ask the agent for its handoff (${asked.error?.message ?? "unknown"})`, steps);
+        }
+        const waitMs = Math.min(HANDOFF_SELF_WAIT_MS, Math.max(1, remaining()));
+        // The instruction embeds the marker inline, so only a line that is exactly
+        // the marker counts as the agent's completion signal.
+        const seen = await waitForScreen(client, session, pane.id, (screen) => screen.split(/\r?\n/).some((line) => line.trim() === HANDOFF_MARKER), waitMs, clock, signal);
+        if (!seen.ok) {
+            record("handoff-self", false, `marker ${HANDOFF_MARKER} not seen within ${waitMs}ms`);
+            failStep("handoff-self", `marker ${HANDOFF_MARKER} not seen within ${waitMs}ms`, steps);
+        }
+        record("handoff-self", true, `marker seen after ${seen.elapsedMs}ms; handoff at ${path}`);
+        handoffContent = readTextFile(path);
+    }
+    else if (supplied || suppliedPath) {
+        if (!handoffContent && handoffPath)
+            handoffContent = readTextFile(handoffPath);
+        const chars = handoffContent?.length ?? 0;
+        record("handoff", true, handoffPath ? `${chars} chars from ${handoffPath}` : `${chars} chars`);
+    }
+    else {
+        record("handoff", true, "none");
+    }
+    // (2) Ask the harness to exit; (3) wait for the command to actually stop.
+    const exit = profile.exit;
+    if (exit?.command) {
+        await client.injectPane({ session, paneId: pane.id, text: exit.command });
+        record("exit", true, `typed ${exit.command}`);
+    }
+    else if (exit?.keys && exit.keys.length > 0) {
+        await client.sendKeys({ session, paneId: pane.id, keys: [...exit.keys] });
+        record("exit", true, `sent ${exit.keys.join(" ")}`);
+    }
+    else {
+        record("exit", true, `no exit recipe for ${profile.name}; Ctrl+C fallback`);
+    }
+    let outcome;
+    try {
+        outcome = await waitForExit(client, session, pane, kind, profile, Math.min(EXIT_WAIT_MS, Math.max(1, remaining())), clock, signal);
+    }
+    catch (err) {
+        record("wait-exit", false, err instanceof Error ? err.message : String(err));
+        throw err;
+    }
+    if (!outcome.exited) {
+        // Bounded wait elapsed: fall back to two Ctrl+C presses, then wait again.
+        await client.sendKeys({ session, paneId: pane.id, keys: ["Ctrl c"] });
+        await clock.sleep(RESTART_POLL_MS);
+        await client.sendKeys({ session, paneId: pane.id, keys: ["Ctrl c"] });
+        const fallback = await waitForExit(client, session, pane, kind, profile, Math.min(EXIT_WAIT_MS, Math.max(1, remaining())), clock, signal);
+        if (!fallback.exited) {
+            record("wait-exit", false, `pane ${pane.id} did not exit after Ctrl+C x2`);
+            failStep("wait-exit", `pane ${pane.id} did not exit after the exit recipe and Ctrl+C x2`, steps);
+        }
+        record("wait-exit", true, `exited after Ctrl+C x2 (${fallback.reason})`);
+    }
+    else {
+        record("wait-exit", true, `${outcome.reason}`);
+    }
+    // (4) Relaunch in the same pane.
+    if (kind === "command") {
+        await client.sendKeys({ session, paneId: pane.id, keys: ["Enter"] });
+        record("relaunch", true, "pressed Enter at the re-run prompt");
+    }
+    else {
+        const launch = restartLaunchCommand(args, profile);
+        if (!launch) {
+            record("relaunch", false, "no launch command");
+            failStep("relaunch", `no launch command for ${profile.name}; pass --command`, steps);
+        }
+        await client.writeChars({ session, paneId: pane.id, chars: launch });
+        await client.sendKeys({ session, paneId: pane.id, keys: ["Enter"] });
+        record("relaunch", true, `typed ${launch}`);
+    }
+    // (5) Wait for readiness: a declared marker, or a screen that stopped
+    // changing when the profile has none. Never skip this before a handoff.
+    const readyBudget = () => Math.min(READY_WAIT_MS, Math.max(1, remaining()));
+    const ready = await awaitReady(client, session, pane.id, profile, readyBudget, clock, signal);
+    if (!ready.ok) {
+        record("ready", false, ready.detail);
+        failStep("ready", ready.detail, steps);
+    }
+    record("ready", true, ready.detail);
+    // (6) Deliver the handoff, inline or as a pointer to the file.
+    const handoff = handoffBodyFor(handoffContent, handoffPath);
+    if (!handoff) {
+        record("deliver", true, "skipped: no handoff");
+    }
+    else {
+        const deliverOnce = () => deliverTo(client, state, args, {
+            session,
+            pane: observed,
+            body: handoff.body,
+            op: "restart",
+            at: clock.now(),
+            clock,
+            timeoutMs: Math.max(1, remaining()),
+        });
+        let delivered = await deliverOnce();
+        let resent = false;
+        // `not-delivered` is positive evidence the paste never landed: wait for the
+        // pane to be ready again and resend exactly once. Every other non-true
+        // result (false / unverified / queued) is reported, never resent.
+        if (!delivered.ok && delivered.error?.code === "not_delivered") {
+            const readyAgain = await awaitReady(client, session, pane.id, profile, readyBudget, clock, signal);
+            if (!readyAgain.ok) {
+                record("deliver", false, `not delivered; ${readyAgain.detail}`);
+                failStep("deliver", `handoff not delivered and the pane did not become ready again (${readyAgain.detail})`, steps);
+            }
+            delivered = await deliverOnce();
+            resent = true;
+        }
+        if (!delivered.ok) {
+            record("deliver", false, delivered.error?.message ?? "handoff not delivered");
+            failStep("deliver", `handoff not delivered (${delivered.error?.message ?? "unknown"})`, steps);
+        }
+        const source = handoff.pointer ? `pointer to ${handoffPath}` : `${handoff.body.length} chars`;
+        const submitted = delivered.submitted === undefined ? "unknown" : String(delivered.submitted);
+        record("deliver", true, `${source} ${resent ? "resent" : "sent"}; submitted=${submitted}`);
+    }
+    return {
+        ok: true,
+        data: {
+            session,
+            to: pane.id,
+            paneId: pane.id,
+            harness: profile.name,
+            paneKind: kind,
+            restarted: true,
+            handoff: handoffPath
+                ? { path: handoffPath, delivered: handoff?.pointer ? "pointer" : "inline" }
+                : null,
+            steps,
+            elapsedMs: clock.now() - started,
+        },
+    };
+}

package/dist/ops/serve-install.d.ts

@@ -1,5 +1,5 @@
 import { type DoctorCheck } from "./doctor.js";
-import { type ServeHelloData } from "./serve.js";
+import { type ServeHelloData, type ServeTaskTarget } from "./serve.js";
 import { type NetworkInterfacesFn, type TailscaleStatusRunner } from "./serve-bind.js";
 import type { ServeInstallDeps, ServePowerShellResult } from "./types.js";
 /** Overall install/readiness deadline when `timeoutMs` is omitted. */
@@ -34,6 +34,10 @@ export type ServeInstallSuccess = {
     ready: true;
     running: true;
     task: string;
+    /** `\zswarm\` for a per-session task, the resolved folder (or `''`) otherwise. */
+    taskPath: string;
+    /** True only when the legacy root-folder task was adopted for its session. */
+    legacy: boolean;
     listen: string;
     command: string;
     principal: {
@@ -72,6 +76,7 @@ export declare function sameWindowsSid(a: string, b: string): boolean;
 export declare function sameWindowsAccount(a: string, b: string): boolean;
 export declare function buildServeTaskScript(action: ServeTaskAction, params?: {
     command?: string;
+    target?: ServeTaskTarget;
 }): string;
 export declare function serveCommandFingerprint(command: string): string;
 /**
@@ -81,6 +86,8 @@ export declare function serveCommandFingerprint(command: string): string;
 export declare function installServeLogon(input?: ServeInstallInput): Promise<ServeInstallSuccess>;
 export declare function uninstallServeLogon(input?: ServeInstallInput): Promise<{
     task: string;
+    taskPath: string;
+    legacy: boolean;
     cleared: true;
     stopped?: boolean;
     missing?: boolean;