@zq-silk/yui 0.0.0

package/dist/tmux/tmuxManager.js

@@ -0,0 +1,408 @@
+import { createHash } from "node:crypto";
+import { resolve } from "node:path";
+import { runtimeError } from "../errors/cliError.js";
+import { handoffTerminal } from "./terminalHandoff.js";
+import { CommandExecutionError } from "./commandExecutor.js";
+const DEFAULT_READINESS_TIMEOUT_MS = 15_000;
+const DEFAULT_READINESS_POLL_MS = 50;
+export class TmuxReadinessTimeoutError extends Error {
+    taskId;
+    roleName;
+    timeoutMs;
+    constructor(taskId, roleName, timeoutMs) {
+        super(`Role ${roleName} did not become ready within ${timeoutMs} ms.`);
+        this.taskId = taskId;
+        this.roleName = roleName;
+        this.timeoutMs = timeoutMs;
+        this.name = "TmuxReadinessTimeoutError";
+    }
+}
+export class TmuxReadinessProbeRequiredError extends Error {
+    constructor() {
+        super("Automated tmux delivery requires an Agent-specific readiness probe.");
+        this.name = "TmuxReadinessProbeRequiredError";
+    }
+}
+/**
+ * Owns tmux lifecycle and input delivery. Interactive attach first releases
+ * every Yui reader from the terminal. Automated delivery is accepted only
+ * after a bounded readiness probe and is recorded by a pane-local receipt.
+ */
+export class TmuxManager {
+    tmuxBin;
+    executor;
+    #yuiHome;
+    #terminalInput;
+    #closeInteractiveInput;
+    #readinessTimeoutMs;
+    #readinessPollMs;
+    #initialColumns;
+    #initialRows;
+    #now;
+    #sleep;
+    constructor(tmuxBin, executor, yuiHomeOrOptions = {}) {
+        this.tmuxBin = tmuxBin;
+        this.executor = executor;
+        const options = typeof yuiHomeOrOptions === "string"
+            ? { yuiHome: yuiHomeOrOptions }
+            : yuiHomeOrOptions;
+        this.#yuiHome = options.yuiHome ?? process.env.YUI_HOME ?? process.cwd();
+        this.#terminalInput = options.terminalInput ?? process.stdin;
+        this.#closeInteractiveInput = options.closeInteractiveInput ?? (() => { });
+        this.#readinessTimeoutMs = positiveInteger(options.readinessTimeoutMs, DEFAULT_READINESS_TIMEOUT_MS, "readiness timeout");
+        this.#readinessPollMs = positiveInteger(options.readinessPollMs, DEFAULT_READINESS_POLL_MS, "readiness poll interval");
+        this.#initialColumns = positiveInteger(options.initialColumns, 120, "initial tmux columns");
+        this.#initialRows = positiveInteger(options.initialRows, 40, "initial tmux rows");
+        this.#now = options.now ?? Date.now;
+        this.#sleep = options.sleep ?? blockingSleep;
+    }
+    enterRole(taskId, role, launch) {
+        this.ensureRoleWindow(taskId, role, launch);
+        this.attachRole(taskId, role.name);
+    }
+    ensureRoleWindow(taskId, role, launch) {
+        if (this.windowNames(taskId).includes(role.name))
+            return false;
+        if (launch === undefined) {
+            throw runtimeError(`Agent launch plan is required to create Role window: ${role.name}.`);
+        }
+        if (!this.hasSession(taskId)) {
+            this.executor.run(this.tmuxBin, [
+                "new-session", "-d",
+                "-x", String(this.#initialColumns),
+                "-y", String(this.#initialRows),
+                "-s", this.sessionName(taskId),
+                "-n", role.name,
+                "-c", safeValue(role.workspace, "Role workspace"),
+                "--",
+                ...launchCommand(launch)
+            ]);
+        }
+        else {
+            this.executor.run(this.tmuxBin, [
+                "new-window",
+                "-t", this.sessionName(taskId),
+                "-n", role.name,
+                "-c", safeValue(role.workspace, "Role workspace"),
+                "--",
+                ...launchCommand(launch)
+            ]);
+        }
+        return true;
+    }
+    attachRole(taskId, roleName) {
+        handoffTerminal(this.#terminalInput, this.#closeInteractiveInput);
+        this.executor.run(this.tmuxBin, [
+            "attach-session", "-t", this.target(taskId, roleName)
+        ], { inheritStdio: true });
+    }
+    captureRole(taskId, roleName, lines = 80) {
+        return this.executor.run(this.tmuxBin, [
+            "capture-pane", "-p", "-t", this.target(taskId, roleName), "-S", `-${lines}`
+        ]);
+    }
+    dispatchRole(taskId, role, launch, input, options) {
+        if (options.replaceExisting === true) {
+            try {
+                this.killRole(taskId, role.name);
+            }
+            catch (error) {
+                if (!isExplicitlyAbsentTmuxSession(error))
+                    throw error;
+            }
+        }
+        this.ensureRoleWindow(taskId, role, launch);
+        return this.sendRoleInputOnce(taskId, role.name, options.receiptId, input, options.readinessProbe);
+    }
+    waitUntilReady(taskId, roleName, readinessProbe) {
+        if (readinessProbe === undefined) {
+            throw new TmuxReadinessProbeRequiredError();
+        }
+        const start = this.#now();
+        for (;;) {
+            const pane = this.inspectPane(taskId, roleName);
+            if (readinessProbe(pane))
+                return pane;
+            if (this.#now() - start >= this.#readinessTimeoutMs) {
+                throw new TmuxReadinessTimeoutError(taskId, roleName, this.#readinessTimeoutMs);
+            }
+            this.#sleep(this.#readinessPollMs);
+        }
+    }
+    inspectPane(taskId, roleName) {
+        const target = this.target(taskId, roleName);
+        const output = this.executor.run(this.tmuxBin, [
+            "display-message", "-p", "-t", target,
+            "#{pane_dead}|#{pane_pid}|#{pane_current_command}"
+        ]).trim();
+        const separator = output.indexOf("|");
+        const secondSeparator = separator < 0 ? -1 : output.indexOf("|", separator + 1);
+        if (separator < 0 || secondSeparator < 0) {
+            throw runtimeError(`Tmux returned an invalid pane state for ${roleName}.`);
+        }
+        const dead = output.slice(0, separator);
+        const pidText = output.slice(separator + 1, secondSeparator);
+        const currentCommand = output.slice(secondSeparator + 1);
+        const pid = Number(pidText);
+        const content = this.executor.run(this.tmuxBin, [
+            "capture-pane", "-p", "-t", target, "-S", "-40"
+        ]);
+        return {
+            taskId,
+            roleName,
+            target,
+            dead: dead === "1",
+            ...(Number.isSafeInteger(pid) && pid > 0 ? { pid } : {}),
+            currentCommand,
+            content
+        };
+    }
+    /** Reads every Role pane in one tmux call without capturing terminal output. */
+    inspectTaskRolePanes(taskId) {
+        const separator = "\u001f";
+        let output;
+        try {
+            output = this.executor.run(this.tmuxBin, [
+                "list-panes", "-s", "-t", this.sessionName(taskId), "-F",
+                `#{window_name}${separator}#{pane_dead}${separator}#{pane_pid}${separator}#{pane_current_command}`
+            ]);
+        }
+        catch (error) {
+            if (isExplicitlyAbsentTmuxSession(error))
+                return [];
+            throw error;
+        }
+        return output.split("\n").flatMap((line) => {
+            if (line.length === 0)
+                return [];
+            const [roleName, deadText, pidText, currentCommand, ...extra] = line.split(separator);
+            if (roleName === undefined
+                || deadText === undefined
+                || pidText === undefined
+                || currentCommand === undefined
+                || extra.length > 0
+                || (deadText !== "0" && deadText !== "1")) {
+                throw runtimeError(`Tmux returned an invalid Task Role pane state for ${taskId}.`);
+            }
+            const pid = Number(pidText);
+            return [{
+                    taskId,
+                    roleName,
+                    target: this.target(taskId, roleName),
+                    dead: deadText === "1",
+                    ...(Number.isSafeInteger(pid) && pid > 0 ? { pid } : {}),
+                    currentCommand
+                }];
+        });
+    }
+    /**
+     * The receipt test, receipt write, literal input and Enter all run through a
+     * single tmux server command queue. Retrying the same receipt cannot type the
+     * input twice into the same pane.
+     */
+    sendRoleInputOnce(taskId, roleName, receiptId, input, readinessProbe) {
+        if (readinessProbe === undefined) {
+            throw new TmuxReadinessProbeRequiredError();
+        }
+        safeValue(receiptId, "tmux delivery receipt id");
+        safeValue(input, "tmux input");
+        // A delivered run is normally still busy on the next Controller scan. The
+        // pane receipt is authoritative for that retry, so do not wait for the
+        // composer merely to discover that the input was already sent.
+        if (this.hasDeliveryReceipt(taskId, roleName, receiptId)) {
+            return "already-sent";
+        }
+        this.waitUntilReady(taskId, roleName, readinessProbe);
+        return this.sendReadyRoleInputOnce(taskId, roleName, receiptId, input);
+    }
+    sendReadyRoleInputOnce(taskId, roleName, receiptId, input) {
+        safeValue(receiptId, "tmux delivery receipt id");
+        safeValue(input, "tmux input");
+        if (this.hasDeliveryReceipt(taskId, roleName, receiptId)) {
+            return "already-sent";
+        }
+        const target = this.target(taskId, roleName);
+        const digest = createHash("sha256").update(receiptId).digest("hex");
+        const option = `@yui_delivery_${digest}`;
+        const sentMarker = `__YUI_DELIVERY_SENT_${digest}__`;
+        const presentMarker = `__YUI_DELIVERY_PRESENT_${digest}__`;
+        const apply = [
+            `set-option -w -t ${tmuxWord(target)} ${option} 1`,
+            `send-keys -l -t ${tmuxWord(target)} -- ${tmuxWord(input)}`,
+            `send-keys -t ${tmuxWord(target)} Enter`,
+            `display-message -p ${sentMarker}`
+        ].join(" ; ");
+        const output = this.executor.run(this.tmuxBin, [
+            "if-shell", "-t", target, "-F", `#{==:#{${option}},1}`,
+            `display-message -p ${presentMarker}`,
+            apply
+        ]).trim();
+        if (output === sentMarker)
+            return "sent";
+        if (output === presentMarker)
+            return "already-sent";
+        throw runtimeError(`Tmux did not confirm delivery receipt ${receiptId}.`);
+    }
+    sendRoleInputOnceIfReady(taskId, roleName, receiptId, input, readinessProbe) {
+        if (readinessProbe === undefined) {
+            throw new TmuxReadinessProbeRequiredError();
+        }
+        if (this.hasDeliveryReceipt(taskId, roleName, receiptId)) {
+            return "already-sent";
+        }
+        if (!readinessProbe(this.inspectPane(taskId, roleName)))
+            return "not-ready";
+        return this.sendReadyRoleInputOnce(taskId, roleName, receiptId, input);
+    }
+    hasDeliveryReceipt(taskId, roleName, receiptId) {
+        safeValue(receiptId, "tmux delivery receipt id");
+        const digest = createHash("sha256").update(receiptId).digest("hex");
+        const option = `@yui_delivery_${digest}`;
+        return this.executor.run(this.tmuxBin, [
+            "show-options", "-wqv", "-t", this.target(taskId, roleName), option
+        ]).trim() === "1";
+    }
+    detachRole(taskId) {
+        this.executor.run(this.tmuxBin, ["detach-client", "-s", this.sessionName(taskId)]);
+    }
+    restartRole(taskId, role, launch) {
+        try {
+            this.killRole(taskId, role.name);
+        }
+        catch (error) {
+            if (!isExplicitlyAbsentTmuxSession(error))
+                throw error;
+        }
+        this.enterRole(taskId, role, launch);
+    }
+    detectRoleStatus(taskId, roleName, fallback = "exited") {
+        try {
+            return this.probeRoleStatus(taskId, roleName);
+        }
+        catch {
+            return fallback;
+        }
+    }
+    probeRoleStatus(taskId, roleName) {
+        if (!this.hasSession(taskId))
+            return "exited";
+        return this.windowNames(taskId).includes(roleName) ? "running" : "exited";
+    }
+    stopTask(taskId) {
+        if (!this.hasSession(taskId))
+            return false;
+        this.executor.run(this.tmuxBin, ["kill-session", "-t", this.sessionName(taskId)]);
+        return true;
+    }
+    stopRole(taskId, roleName) {
+        this.executor.run(this.tmuxBin, ["send-keys", "-t", this.target(taskId, roleName), "C-c"]);
+    }
+    killRole(taskId, roleName) {
+        this.executor.run(this.tmuxBin, ["kill-window", "-t", this.target(taskId, roleName)]);
+    }
+    renameRole(taskId, oldRoleName, newRoleName) {
+        this.executor.run(this.tmuxBin, [
+            "rename-window", "-t", this.target(taskId, oldRoleName), safeValue(newRoleName, "Role name")
+        ]);
+    }
+    hasSession(taskId) {
+        try {
+            this.executor.run(this.tmuxBin, ["has-session", "-t", this.sessionName(taskId)]);
+            return true;
+        }
+        catch (error) {
+            if (isExplicitlyAbsentTmuxSession(error))
+                return false;
+            // Older/fake executors do not expose stderr. A failed has-session is the
+            // tmux absence contract; other operations remain strict.
+            if (!(error instanceof CommandExecutionError))
+                return false;
+            throw error;
+        }
+    }
+    windowNames(taskId) {
+        if (!this.hasSession(taskId))
+            return [];
+        return this.executor.run(this.tmuxBin, [
+            "list-windows", "-t", this.sessionName(taskId), "-F", "#{window_name}"
+        ]).split("\n").map((name) => name.trim()).filter(Boolean);
+    }
+    sessionName(taskId) {
+        return yuiTmuxSessionName(this.#yuiHome, taskId);
+    }
+    target(taskId, roleName) {
+        return yuiTmuxTarget(this.#yuiHome, taskId, roleName);
+    }
+}
+/** A small FIFO boundary for Controller scheduler passes. */
+export class TmuxDeliveryPump {
+    tmux;
+    #queue = [];
+    constructor(tmux) {
+        this.tmux = tmux;
+    }
+    get pending() {
+        return this.#queue.length;
+    }
+    enqueue(delivery) {
+        this.#queue.push(delivery);
+    }
+    pump(limit = Number.POSITIVE_INFINITY) {
+        if (!(limit === Number.POSITIVE_INFINITY || Number.isSafeInteger(limit) && limit > 0)) {
+            throw new TypeError("tmux delivery pump limit must be a positive integer");
+        }
+        const completed = [];
+        while (this.#queue.length > 0 && completed.length < limit) {
+            const delivery = this.#queue[0];
+            const outcome = this.tmux.sendRoleInputOnce(delivery.taskId, delivery.roleName, delivery.receiptId, delivery.input, delivery.readinessProbe);
+            this.#queue.shift();
+            completed.push({ receiptId: delivery.receiptId, outcome });
+        }
+        return completed;
+    }
+}
+export function yuiTmuxSessionName(yuiHome, taskId) {
+    const safeTaskId = safeValue(taskId, "Task id");
+    const namespace = createHash("sha256").update(resolve(yuiHome)).digest("hex").slice(0, 12);
+    return `yui-${namespace}-${safeTaskId}`;
+}
+export function yuiTmuxTarget(yuiHome, taskId, roleName) {
+    return `${yuiTmuxSessionName(yuiHome, taskId)}:${safeValue(roleName, "Role name")}`;
+}
+function launchCommand(launch) {
+    const command = safeValue(launch.command, "Agent command");
+    const args = launch.args.map((arg) => safeValue(arg, "Agent argument"));
+    const environment = Object.entries(launch.env).map(([key, value]) => {
+        if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) {
+            throw new TypeError(`Invalid Agent environment variable: ${key}`);
+        }
+        return `${key}=${safeValue(value, `Agent environment ${key}`)}`;
+    });
+    return environment.length === 0
+        ? [command, ...args]
+        : ["env", ...environment, command, ...args];
+}
+function isExplicitlyAbsentTmuxSession(error) {
+    if (!(error instanceof CommandExecutionError))
+        return false;
+    return /can't find (?:session|window|pane)|no server running/i.test(error.stderr);
+}
+function tmuxWord(value) {
+    return JSON.stringify(value);
+}
+function safeValue(value, label) {
+    if (value.length === 0 || value.includes("\0")) {
+        throw new TypeError(`${label} must be non-empty and contain no NUL bytes`);
+    }
+    return value;
+}
+function positiveInteger(value, fallback, label) {
+    const resolved = value ?? fallback;
+    if (!Number.isSafeInteger(resolved) || resolved <= 0) {
+        throw new TypeError(`${label} must be a positive integer`);
+    }
+    return resolved;
+}
+function blockingSleep(milliseconds) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, milliseconds);
+}

package/dist/workItem/workItem.js

@@ -0,0 +1,45 @@
+export function createWorkItem(id, taskId, input, now) {
+    const timestamp = now.toISOString();
+    return {
+        schemaVersion: 1,
+        id: requireSafeIdentity(id, "Work item id"),
+        taskId: requireSafeIdentity(taskId, "Task id"),
+        title: requireText(input.title, "Work item title"),
+        assignee: requireSafeIdentity(input.assignee, "Work item assignee"),
+        status: "pending",
+        createdAt: timestamp,
+        updatedAt: timestamp
+    };
+}
+export function updateWorkItemStatus(workItem, status, outcome, now) {
+    const terminal = ["completed", "failed", "cancelled", "superseded"].includes(status);
+    const normalizedOutcome = outcome === undefined ? undefined : requireText(outcome, "Work item outcome");
+    if (terminal && normalizedOutcome === undefined) {
+        throw new Error(`Work item outcome is required for ${status}.`);
+    }
+    const timestamp = now.toISOString();
+    const { outcome: _outcome, endedAt: _endedAt, ...base } = workItem;
+    return {
+        ...base,
+        status,
+        ...(normalizedOutcome === undefined ? {} : { outcome: normalizedOutcome }),
+        updatedAt: timestamp,
+        ...(terminal ? { endedAt: timestamp } : {})
+    };
+}
+function requireSafeIdentity(value, label) {
+    const normalized = requireText(value, label);
+    if (["__proto__", "prototype", "constructor", ".", ".."].includes(normalized)
+        || /[\/\\\0]/.test(normalized)) {
+        throw new Error(`${label} is invalid.`);
+    }
+    return normalized;
+}
+function requireText(value, label) {
+    if (typeof value !== "string" || value.includes("\0"))
+        throw new Error(`${label} is invalid.`);
+    const normalized = value.trim();
+    if (normalized.length === 0)
+        throw new Error(`${label} is required.`);
+    return normalized;
+}

package/dist/worktree/roleWorkspace.js

@@ -0,0 +1,62 @@
+import { resolve } from "node:path";
+export function createRoleWorkspace(input, now) {
+    const timestamp = now.toISOString();
+    return validateRoleWorkspace({
+        schemaVersion: 1,
+        taskId: requireIdentity(input.taskId, "Task id"),
+        roleName: requireIdentity(input.roleName, "Role name"),
+        repositoryId: requireIdentity(input.repositoryId, "Repository id"),
+        path: resolve(requireText(input.path, "Role workspace path")),
+        branch: requireText(input.branch, "Role workspace branch"),
+        baseRef: requireText(input.baseRef, "Role workspace base ref"),
+        baseCommit: requireCommit(input.baseCommit),
+        createdAt: timestamp,
+        updatedAt: timestamp
+    });
+}
+export function validateRoleWorkspace(workspace) {
+    if (workspace.schemaVersion !== 1) {
+        throw new Error("RoleWorkspace must use schemaVersion 1.");
+    }
+    requireIdentity(workspace.taskId, "Task id");
+    requireIdentity(workspace.roleName, "Role name");
+    requireIdentity(workspace.repositoryId, "Repository id");
+    if (resolve(requireText(workspace.path, "Role workspace path")) !== workspace.path) {
+        throw new Error("Role workspace path must be absolute and normalized.");
+    }
+    requireText(workspace.branch, "Role workspace branch");
+    requireText(workspace.baseRef, "Role workspace base ref");
+    requireCommit(workspace.baseCommit);
+    requireTimestamp(workspace.createdAt, "RoleWorkspace createdAt");
+    requireTimestamp(workspace.updatedAt, "RoleWorkspace updatedAt");
+    return workspace;
+}
+function requireIdentity(value, label) {
+    const identity = requireText(value, label);
+    if ([".", "..", "__proto__", "prototype", "constructor"].includes(identity)
+        || /[\/\\\0]/.test(identity)) {
+        throw new Error(`${label} is invalid.`);
+    }
+    return identity;
+}
+function requireCommit(value) {
+    const commit = requireText(value, "Role workspace base commit").toLowerCase();
+    if (!/^[a-f0-9]{40}(?:[a-f0-9]{24})?$/.test(commit)) {
+        throw new Error("Role workspace base commit is invalid.");
+    }
+    return commit;
+}
+function requireText(value, label) {
+    if (typeof value !== "string" || value.includes("\0")) {
+        throw new Error(`${label} is invalid.`);
+    }
+    const normalized = value.trim();
+    if (normalized.length === 0)
+        throw new Error(`${label} is required.`);
+    return normalized;
+}
+function requireTimestamp(value, label) {
+    if (typeof value !== "string" || !Number.isFinite(Date.parse(value))) {
+        throw new Error(`${label} is invalid.`);
+    }
+}