@zq-silk/yui 0.2.0 → 0.4.2

package/dist/runtime/tmuxAdapters.js

@@ -0,0 +1,315 @@
+import { randomUUID } from "node:crypto";
+import { createRuntimeBinding } from "./runtimeBinding.js";
+import { normalizeRuntimeOwner } from "./runtimeOwner.js";
+import { requireSafeIdentity } from "./validation.js";
+/**
+ * Runtime lifecycle adapter for the current tmux host. The returned hostRef is
+ * opaque to the domain and self-contained for a later inspect/stop operation.
+ */
+export class TmuxSessionHost {
+    planner;
+    tmux;
+    #globalHostId;
+    #createBindingId;
+    #launchTails = new Map();
+    constructor(planner, tmux, options = {}) {
+        this.planner = planner;
+        this.tmux = tmux;
+        this.#globalHostId = requireSafeIdentity(options.globalHostId ?? "operator", "Global tmux host id");
+        this.#createBindingId = options.createBindingId ?? randomUUID;
+    }
+    async start(request, beforeHostStart) {
+        return this.#launch(request, beforeHostStart);
+    }
+    async resume(request, beforeHostStart) {
+        return this.#launch(request, beforeHostStart);
+    }
+    async stop(binding) {
+        const ref = requireMatchingHostRef(binding);
+        await stopExactRole(this.tmux, ref.hostId, ref.roleName);
+    }
+    async inspect(binding) {
+        const ref = requireMatchingHostRef(binding);
+        try {
+            const state = await probeRoleStatus(this.tmux, ref.hostId, ref.roleName) === "running"
+                ? "running"
+                : "stopped";
+            return {
+                state,
+                ...(binding.nativeSessionId === undefined
+                    ? {}
+                    : { nativeSessionId: binding.nativeSessionId })
+            };
+        }
+        catch {
+            return {
+                state: "unavailable",
+                ...(binding.nativeSessionId === undefined
+                    ? {}
+                    : { nativeSessionId: binding.nativeSessionId })
+            };
+        }
+    }
+    async inspectOwner(owner) {
+        const normalized = normalizeRuntimeOwner(owner);
+        const hostId = normalized.scope === "task"
+            ? normalized.taskId
+            : this.#globalHostId;
+        try {
+            return {
+                state: await probeRoleStatus(this.tmux, hostId, normalized.roleName) === "running"
+                    ? "running"
+                    : "stopped"
+            };
+        }
+        catch {
+            return { state: "unavailable" };
+        }
+    }
+    async inspectOwners(owners) {
+        const normalized = owners.map(normalizeRuntimeOwner);
+        if (this.tmux.inspectRolePaneInventory === undefined
+            && this.tmux.inspectRolePaneInventoryAsync === undefined) {
+            return Promise.all(normalized.map(async (owner) => ({
+                owner,
+                inspection: await this.inspectOwner(owner)
+            })));
+        }
+        try {
+            const inventory = this.tmux.inspectRolePaneInventoryAsync === undefined
+                ? this.tmux.inspectRolePaneInventory()
+                : await this.tmux.inspectRolePaneInventoryAsync();
+            const running = new Set(inventory
+                .filter((pane) => !pane.dead)
+                .map((pane) => `${pane.taskId}\0${pane.roleName}`));
+            return normalized.map((owner) => {
+                const hostId = owner.scope === "task"
+                    ? owner.taskId
+                    : this.#globalHostId;
+                return {
+                    owner,
+                    inspection: {
+                        state: running.has(`${hostId}\0${owner.roleName}`)
+                            ? "running"
+                            : "stopped"
+                    }
+                };
+            });
+        }
+        catch {
+            return normalized.map((owner) => ({
+                owner,
+                inspection: { state: "unavailable" }
+            }));
+        }
+    }
+    async stopOwner(owner) {
+        const normalized = normalizeRuntimeOwner(owner);
+        const hostId = normalized.scope === "task"
+            ? normalized.taskId
+            : this.#globalHostId;
+        try {
+            await stopExactRole(this.tmux, hostId, normalized.roleName);
+            return await probeRoleStatus(this.tmux, hostId, normalized.roleName)
+                === "exited";
+        }
+        catch {
+            return false;
+        }
+    }
+    async #launch(request, beforeHostStart) {
+        const hostId = request.owner.scope === "task"
+            ? request.owner.taskId
+            : this.#globalHostId;
+        // All Role windows for one Task share the same tmux session. Serialize the
+        // short create/ensure boundary per host so two first Roles cannot race
+        // `new-session`; different Tasks and the global Operator remain parallel.
+        const key = hostId;
+        const previous = this.#launchTails.get(key) ?? Promise.resolve();
+        let release;
+        const turn = new Promise((resolve) => { release = resolve; });
+        const tail = previous.then(() => turn);
+        this.#launchTails.set(key, tail);
+        await previous;
+        try {
+            return await this.#launchUnlocked(request, hostId, beforeHostStart);
+        }
+        finally {
+            release();
+            if (this.#launchTails.get(key) === tail)
+                this.#launchTails.delete(key);
+        }
+    }
+    async #launchUnlocked(request, hostId, beforeHostStart) {
+        // Validate generated identity before starting an external process.
+        const bindingId = requireSafeIdentity(this.#createBindingId(), "Runtime binding id");
+        const input = {
+            roleName: request.owner.roleName,
+            agentId: request.agentId,
+            adapterId: request.adapterId,
+            effective: request.effective,
+            launchId: request.launchId,
+            mode: request.mode,
+            ...(request.runId === undefined ? {} : { runId: request.runId }),
+            ...(request.runtimeIsolation === undefined
+                ? {}
+                : { runtimeIsolation: request.runtimeIsolation }),
+            ...(request.environment === undefined
+                ? {}
+                : { environment: request.environment }),
+            ...(request.mode === "resume" ? { nativeSessionId: request.nativeSessionId } : {})
+        };
+        const planned = request.owner.scope === "task"
+            ? this.planner.plan({ taskId: request.owner.taskId, ...input })
+            : this.planner.planGlobalRole(input);
+        if (planned.role.name !== request.owner.roleName) {
+            throw new Error("Planned Role does not match the runtime owner.");
+        }
+        if (planned.role.workspace !== request.workspace) {
+            throw new Error("Planned Role workspace does not match the runtime request.");
+        }
+        const plannedNativeSessionId = planned.session?.nativeSessionId;
+        if (request.mode === "resume"
+            && plannedNativeSessionId !== undefined
+            && plannedNativeSessionId !== request.nativeSessionId) {
+            throw new Error("Planned native session does not match the resume request.");
+        }
+        const nativeSessionId = plannedNativeSessionId
+            ?? (request.mode === "resume" ? request.nativeSessionId : undefined);
+        beforeHostStart?.({
+            owner: request.owner,
+            launchId: request.launchId,
+            ...(request.runId === undefined ? {} : { runId: request.runId }),
+            agentId: request.agentId,
+            adapterId: request.adapterId,
+            effective: request.effective,
+            ...(nativeSessionId === undefined ? {} : { nativeSessionId }),
+            ...(planned.initialPromptRunId === undefined
+                ? {}
+                : { initialPromptRunId: planned.initialPromptRunId })
+        });
+        // Process creation is last: every local invariant has already passed.
+        const hostCreated = await ensureRoleWindow(this.tmux, hostId, planned.role, planned.launch);
+        return createRuntimeBinding({
+            id: bindingId,
+            launchId: request.launchId,
+            owner: request.owner,
+            agentId: request.agentId,
+            adapterId: request.adapterId,
+            hostRef: encodeHostRef({
+                scope: request.owner.scope,
+                hostId,
+                roleName: request.owner.roleName
+            }),
+            hostCreated,
+            ...(hostCreated && planned.initialPromptRunId !== undefined
+                ? { initialPromptRunId: planned.initialPromptRunId }
+                : {}),
+            ...(nativeSessionId === undefined ? {} : { nativeSessionId })
+        });
+    }
+}
+/** Non-blocking receipt-backed tmux push; it never interprets provider output. */
+export class TmuxPromptPushAdapter {
+    tmux;
+    readiness;
+    constructor(tmux, readiness) {
+        this.tmux = tmux;
+        this.readiness = readiness;
+    }
+    async tryPush(request) {
+        const ref = requireMatchingHostRef(request.binding);
+        const readinessProbe = this.readiness(request.binding.adapterId);
+        const outcome = this.tmux.sendRoleInputOnceIfReadyAsync === undefined
+            ? this.tmux.sendRoleInputOnceIfReady(ref.hostId, ref.roleName, request.envelope.id, request.envelope.text, readinessProbe)
+            : await this.tmux.sendRoleInputOnceIfReadyAsync(ref.hostId, ref.roleName, request.envelope.id, request.envelope.text, readinessProbe);
+        if (outcome === "unavailable")
+            return "unavailable";
+        return outcome === "not-ready" ? "busy" : "delivered";
+    }
+}
+async function ensureRoleWindow(tmux, hostId, role, launch) {
+    return tmux.ensureRoleWindowAsync === undefined
+        ? tmux.ensureRoleWindow(hostId, role, launch)
+        : tmux.ensureRoleWindowAsync(hostId, role, launch);
+}
+async function probeRoleStatus(tmux, hostId, roleName) {
+    return tmux.probeRoleStatusAsync === undefined
+        ? tmux.probeRoleStatus(hostId, roleName)
+        : tmux.probeRoleStatusAsync(hostId, roleName);
+}
+async function killRole(tmux, hostId, roleName) {
+    if (tmux.killRoleAsync === undefined) {
+        tmux.killRole(hostId, roleName);
+        return;
+    }
+    await tmux.killRoleAsync(hostId, roleName);
+}
+async function stopExactRole(tmux, hostId, roleName) {
+    if (await probeRoleStatus(tmux, hostId, roleName) !== "running")
+        return;
+    try {
+        await killRole(tmux, hostId, roleName);
+    }
+    catch (error) {
+        // Killing the final window may make the tmux server exit before the
+        // client observes a clean command status. The authoritative outcome is
+        // the exact Role's postcondition. Preserve the original error unless the
+        // Role is positively proven stopped.
+        try {
+            if (await probeRoleStatus(tmux, hostId, roleName) === "exited")
+                return;
+        }
+        catch {
+            // Fall through to the original kill error; an unavailable postcondition
+            // is not evidence that cleanup succeeded.
+        }
+        throw error;
+    }
+}
+const HOST_REF_PREFIX = "yui-tmux:v1:";
+function encodeHostRef(ref) {
+    return `${HOST_REF_PREFIX}${Buffer.from(JSON.stringify(ref), "utf8").toString("base64url")}`;
+}
+function requireMatchingHostRef(binding) {
+    const ref = decodeHostRef(binding.hostRef);
+    const matches = binding.owner.scope === ref.scope
+        && binding.owner.roleName === ref.roleName
+        && (binding.owner.scope === "global" || binding.owner.taskId === ref.hostId);
+    if (!matches)
+        throw new Error("Tmux host reference does not match runtime owner.");
+    return ref;
+}
+function decodeHostRef(value) {
+    if (!value.startsWith(HOST_REF_PREFIX)) {
+        throw new Error("Tmux host reference is invalid.");
+    }
+    let input;
+    try {
+        const encoded = value.slice(HOST_REF_PREFIX.length);
+        input = JSON.parse(Buffer.from(encoded, "base64url").toString("utf8"));
+    }
+    catch {
+        throw new Error("Tmux host reference is invalid.");
+    }
+    if (typeof input !== "object" || input === null || Array.isArray(input)) {
+        throw new Error("Tmux host reference is invalid.");
+    }
+    const record = input;
+    const expectedKeys = ["hostId", "roleName", "scope"];
+    if (Object.keys(record).sort().join("\0") !== expectedKeys.sort().join("\0")) {
+        throw new Error("Tmux host reference is invalid.");
+    }
+    if (record.scope !== "global" && record.scope !== "task") {
+        throw new Error("Tmux host reference is invalid.");
+    }
+    const hostId = requireSafeIdentity(record.hostId, "Tmux host id");
+    const roleName = requireSafeIdentity(record.roleName, "Tmux Role name");
+    if (record.scope === "global")
+        return { scope: "global", hostId, roleName };
+    return {
+        scope: "task",
+        hostId,
+        roleName
+    };
+}

package/dist/runtime/turnCompletion.js

@@ -0,0 +1,3 @@
+// Compatibility facade. The authoritative Turn-completion model belongs to
+// the Execution domain; runtime adapters only translate external Hook facts.
+export * from "../executor/turnCompletion.js";

package/dist/runtime/validation.js

@@ -0,0 +1,23 @@
+export 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;
+}
+export 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;
+}
+export function requireTimestamp(value, label) {
+    if (!(value instanceof Date) || !Number.isFinite(value.getTime())) {
+        throw new Error(`${label} must be a valid date.`);
+    }
+    return value.toISOString();
+}