@zq-silk/yui 0.0.0

package/dist/scheduler/activeRoleRunDelivery.js

@@ -0,0 +1,94 @@
+/**
+ * Delivers durable Work AgentRuns before liveness reconciliation. Task command
+ * handlers only record intent; this Controller path is the sole automated
+ * route into the Agent terminal, through tmux receipt-backed delivery.
+ */
+export async function processActiveRoleRunDeliveries(store, delivery, now) {
+    const results = [];
+    for (const task of store.listTasks()) {
+        if (task.status !== "active")
+            continue;
+        for (const role of store.listRoles(task.id)) {
+            const run = store.getActiveAgentRun(task.id, role.name);
+            // A crash after a Leader wake is durably claimed but before tmux input
+            // is recoverable through the same receipt-backed delivery path.
+            if (run === null || run.deliveredAt !== undefined)
+                continue;
+            if (task.repositoryId !== undefined && task.cwd === undefined) {
+                results.push({
+                    taskId: task.id,
+                    roleName: role.name,
+                    runId: run.id,
+                    status: "skipped",
+                    reason: "workspace-not-ready"
+                });
+                continue;
+            }
+            const existingSession = store.getRoleSession(task.id, role.name);
+            const receiptId = `agent-run:${run.id}`;
+            try {
+                const nativeSessionId = run.mode === "resume"
+                    ? requireResumeSession(role, existingSession)
+                    : undefined;
+                const prepared = await delivery.prepareRoleSession({
+                    taskId: task.id,
+                    roleName: role.name,
+                    agentId: role.activeAgentId,
+                    adapterId: role.adapterId,
+                    mode: run.mode,
+                    ...(nativeSessionId === undefined ? {} : { nativeSessionId })
+                });
+                const existingReceipt = await delivery.findExistingReceipt?.({
+                    delivery: prepared,
+                    receiptId
+                }) ?? null;
+                const ready = existingReceipt ?? await delivery.waitUntilReady(prepared);
+                const session = validateReadySession(role, existingSession, run.mode, ready);
+                let status = "already-delivered";
+                if (existingReceipt === null) {
+                    status = await delivery.sendOnce({
+                        delivery: ready,
+                        receiptId,
+                        text: run.input
+                    }) === "sent" ? "delivered" : "already-delivered";
+                }
+                store.saveRoleRunDelivery({ task, role, run, session, now });
+                results.push({ taskId: task.id, roleName: role.name, runId: run.id, status });
+            }
+            catch (error) {
+                results.push({
+                    taskId: task.id,
+                    roleName: role.name,
+                    runId: run.id,
+                    status: "failed",
+                    error: error instanceof Error ? error.message : String(error)
+                });
+            }
+        }
+    }
+    return results;
+}
+function requireResumeSession(role, session) {
+    if (session === null || !hasText(session.nativeSessionId)) {
+        throw new Error(`Role resume has no fixed native session: ${role.taskId}/${role.name}.`);
+    }
+    return session.nativeSessionId;
+}
+function validateReadySession(role, existing, mode, ready) {
+    const session = ready.session;
+    if (mode === "new" && session === null)
+        return null;
+    if (session === null || !hasText(session.nativeSessionId)) {
+        throw new Error(`Ready Role session has no native session id: ${role.taskId}/${role.name}.`);
+    }
+    if (session.agentId !== role.activeAgentId || session.adapterId !== role.adapterId) {
+        throw new Error(`Ready Role session identity changed: ${role.taskId}/${role.name}.`);
+    }
+    if (mode === "resume" && session.nativeSessionId !== existing?.nativeSessionId) {
+        throw new Error(`Role resume changed the fixed native session id: ${role.taskId}/${role.name}.`);
+    }
+    return { ...session, status: "running" };
+}
+function hasText(value) {
+    return typeof value === "string" && value.trim().length > 0;
+}

package/dist/scheduler/archivedTaskRuntime.js

@@ -0,0 +1,12 @@
+/** Stops archived Task processes at the tmux boundary and closes their sessions. */
+export async function stopArchivedTaskRuntimes(store, delivery, now) {
+    const stopped = [];
+    for (const task of store.listTasks()) {
+        if (task.status !== "archived")
+            continue;
+        if (await delivery.stopTask(task.id))
+            stopped.push(task.id);
+        store.saveArchivedTaskStopped(task.id, now);
+    }
+    return stopped;
+}

package/dist/scheduler/leaderFailure.js

@@ -0,0 +1,18 @@
+export function recordLeaderFailure(taskId, nativeSessionId, message, now, existing) {
+    const timestamp = now.toISOString();
+    return {
+        schemaVersion: 1,
+        taskId: requiredText(taskId, "Task id"),
+        nativeSessionId: requiredText(nativeSessionId, "Native session id"),
+        message: requiredText(message, "Leader failure message"),
+        attemptCount: (existing?.attemptCount ?? 0) + 1,
+        firstFailedAt: existing?.firstFailedAt ?? timestamp,
+        lastFailedAt: timestamp
+    };
+}
+function requiredText(value, label) {
+    const normalized = value.trim();
+    if (normalized.length === 0)
+        throw new Error(`${label} is required.`);
+    return normalized;
+}

package/dist/scheduler/leaderWakeupProcessor.js

@@ -0,0 +1,143 @@
+import { createAgentRun } from "../run/agentRun.js";
+import { recordLeaderFailure } from "./leaderFailure.js";
+import { createLeaderRecoveryNotification } from "./operatorNotification.js";
+export async function processLeaderWakeups(store, delivery, now) {
+    const results = [];
+    for (const wakeup of store.listPendingWakeups()) {
+        const task = store.getTask(wakeup.taskId);
+        const role = store.getRole(wakeup.taskId, "leader");
+        if (task === null || task.status !== "active" || role === null) {
+            results.push({ taskId: wakeup.taskId, status: "skipped", reason: "unavailable" });
+            continue;
+        }
+        if (task.repositoryId !== undefined && task.cwd === undefined) {
+            results.push({ taskId: task.id, status: "skipped", reason: "workspace-not-ready" });
+            continue;
+        }
+        if (store.getLeaderFailure(task.id) !== null) {
+            results.push({ taskId: task.id, status: "skipped", reason: "recovery-blocked" });
+            continue;
+        }
+        if (store.hasOpenInputRequest(task.id)) {
+            results.push({ taskId: task.id, status: "skipped", reason: "waiting-input" });
+            continue;
+        }
+        // This check deliberately precedes every tmux operation. A pending wake is
+        // durable state, not text that may be injected into a busy Agent composer.
+        if (store.getActiveAgentRun(task.id, role.name) !== null) {
+            results.push({ taskId: task.id, status: "skipped", reason: "busy" });
+            continue;
+        }
+        const existingSession = store.getRoleSession(task.id, role.name);
+        let effectiveSession = existingSession;
+        let claimed = false;
+        let run = null;
+        try {
+            const mode = hasNativeSession(existingSession) ? "resume" : "new";
+            const input = leaderWakeupInput(task.id, wakeup.reasons, store.getTaskBrief(task.id), store.listDecisions(task.id), store.listMilestones(task.id));
+            run = createAgentRun(store.nextAgentRunId(task.id), task.id, role.name, mode, input, now);
+            const prepared = await delivery.prepareRoleSession({
+                taskId: task.id,
+                roleName: role.name,
+                agentId: role.activeAgentId,
+                adapterId: role.adapterId,
+                mode,
+                ...(mode === "resume" ? { nativeSessionId: existingSession.nativeSessionId } : {})
+            });
+            const ready = await delivery.waitUntilReady(prepared);
+            const latestTask = store.getTask(task.id);
+            if (latestTask === null || latestTask.status !== "active") {
+                results.push({ taskId: task.id, status: "skipped", reason: "unavailable" });
+                continue;
+            }
+            effectiveSession = validateReadySession(role.activeAgentId, existingSession, mode, ready.session);
+            const claim = store.saveLeaderDispatch({ task, role, run, session: effectiveSession, wakeup, now });
+            if (claim !== "claimed") {
+                results.push({ taskId: task.id, status: "skipped", reason: claim });
+                continue;
+            }
+            claimed = true;
+            await delivery.sendOnce({
+                delivery: ready,
+                receiptId: `agent-run:${run.id}`,
+                text: input
+            });
+            store.saveRoleRunDelivery({ task, role, run, session: effectiveSession, now });
+            results.push({ taskId: task.id, status: "dispatched" });
+        }
+        catch (error) {
+            const detail = error instanceof Error ? error.message : String(error);
+            const message = `Leader dispatch failed: ${detail}`;
+            store.saveLeaderDispatchFailure({
+                task,
+                role,
+                session: effectiveSession,
+                failure: recordLeaderFailure(task.id, effectiveSession?.nativeSessionId ?? "(unregistered)", message, now, store.getLeaderFailure(task.id)),
+                notification: createLeaderRecoveryNotification(task.id, message, now, store.getOperatorNotification(task.id)),
+                ...(claimed && run !== null ? { claimed: { run, wakeup } } : {}),
+                now
+            });
+            results.push({ taskId: task.id, status: "failed", error: message });
+        }
+    }
+    return results;
+}
+function validateReadySession(activeAgentId, existing, mode, session) {
+    if (mode === "new" && session === null)
+        return null;
+    if (session === null)
+        throw new Error("Leader resume returned no fixed native session.");
+    if (session.agentId !== activeAgentId) {
+        throw new Error(`Ready session belongs to another Agent: ${session.agentId}.`);
+    }
+    if (!hasNativeSession(session)) {
+        throw new Error("Ready Leader session has no native session id.");
+    }
+    if (mode === "resume" && session.nativeSessionId !== existing?.nativeSessionId) {
+        throw new Error("Leader resume changed the fixed native session id.");
+    }
+    return { ...session, status: "running" };
+}
+function hasNativeSession(session) {
+    return session !== null &&
+        typeof session.nativeSessionId === "string" &&
+        session.nativeSessionId.trim().length > 0;
+}
+function leaderWakeupInput(taskId, reasons, brief, decisions, milestones) {
+    const lines = [
+        `Yui wakeup reasons: ${reasons.join(", ")}.`
+    ];
+    if (brief !== null) {
+        lines.push(`Objective: ${brief.objective}`);
+        if (brief.boundaries.length > 0) {
+            lines.push("Boundaries:");
+            for (const boundary of brief.boundaries) {
+                lines.push(`  - ${boundary}`);
+            }
+        }
+        if (brief.currentFocus.trim().length > 0) {
+            lines.push(`Current focus: ${brief.currentFocus}`);
+        }
+        if (brief.leaderSummary.trim().length > 0) {
+            lines.push(`Leader summary: ${brief.leaderSummary}`);
+        }
+    }
+    const activeDecisions = decisions.filter((d) => d.status === "active").slice(-3);
+    if (activeDecisions.length > 0) {
+        lines.push("Active decisions:");
+        for (const decision of activeDecisions) {
+            lines.push(`  - ${decision.title}: ${decision.rationale}`);
+        }
+    }
+    const recentMilestones = [...milestones]
+        .sort((a, b) => b.createdAt.localeCompare(a.createdAt))
+        .slice(0, 3);
+    if (recentMilestones.length > 0) {
+        lines.push("Recent milestones:");
+        for (const milestone of recentMilestones) {
+            lines.push(`  - ${milestone.title}`);
+        }
+    }
+    lines.push(`Inspect yui task context ${taskId}, which includes open and recently resolved input requests; then continue Leader stewardship. Use narrower show/list commands only when one record needs closer inspection.`);
+    return lines.join("\n");
+}

package/dist/scheduler/operatorInputNotificationProcessor.js

@@ -0,0 +1,85 @@
+export async function processOperatorInputNotifications(store, delivery) {
+    const requests = store.listOpenInputRequests();
+    if (requests.length === 0)
+        return [];
+    const target = store.getOperatorDeliveryTarget();
+    if (target === null || delivery.notifyOperatorInputOnce === undefined) {
+        const reason = target === null ? "operator-unavailable" : "delivery-unsupported";
+        return requests.map((request) => skipped(request, reason));
+    }
+    const results = [];
+    for (const [index, request] of requests.entries()) {
+        try {
+            const outcome = await delivery.notifyOperatorInputOnce({
+                ...target,
+                receiptId: `input-request:${request.id}`,
+                text: renderOperatorInputNotification(request)
+            });
+            if (outcome === "unavailable") {
+                results.push(skipped(request, "operator-unavailable"));
+                results.push(...requests.slice(index + 1).map((pending) => (skipped(pending, "operator-unavailable"))));
+                break;
+            }
+            else if (outcome === "not-ready") {
+                results.push(skipped(request, "operator-not-ready"));
+                results.push(...requests.slice(index + 1).map((pending) => (skipped(pending, "operator-not-ready"))));
+                break;
+            }
+            else {
+                results.push({
+                    inputRequestId: request.id,
+                    taskId: request.taskId,
+                    status: outcome
+                });
+                if (outcome === "sent") {
+                    results.push(...requests.slice(index + 1).map((pending) => (skipped(pending, "operator-not-ready"))));
+                    break;
+                }
+            }
+        }
+        catch (error) {
+            results.push({
+                inputRequestId: request.id,
+                taskId: request.taskId,
+                status: "failed",
+                error: error instanceof Error ? error.message : String(error)
+            });
+        }
+    }
+    return results;
+}
+function renderOperatorInputNotification(request) {
+    const recommendedChoiceKey = request.policy.kind === "recommended"
+        ? request.policy.recommendedChoiceKey
+        : undefined;
+    const recommendedChoice = recommendedChoiceKey === undefined
+        ? undefined
+        : request.choices.find((choice) => choice.key === recommendedChoiceKey);
+    return [
+        "A Task Leader is waiting for user input. Present this question to the user; do not answer it yourself.",
+        `Task: ${request.taskId}`,
+        `Input: ${request.id}`,
+        `Question: ${request.question}`,
+        ...(request.choices.length === 0
+            ? ["Answer type: free text"]
+            : ["Choices:", ...request.choices.map((choice) => `  ${choice.key}: ${choice.label}`)]),
+        ...(request.policy.kind === "required"
+            ? ["Decision policy: user response required; there is no automatic fallback."]
+            : [
+                `Agent recommendation: ${recommendedChoice.key}: ${recommendedChoice.label}`,
+                `Automatic fallback after: ${request.policy.timeoutAt}`
+            ]),
+        `Inspect: yui task input show ${request.id}`,
+        request.choices.length === 0
+            ? `After the user replies: yui task input answer ${request.id} --text "<answer>"`
+            : `After the user chooses: yui task input answer ${request.id} --choice <key>`
+    ].join("\n");
+}
+function skipped(request, reason) {
+    return {
+        inputRequestId: request.id,
+        taskId: request.taskId,
+        status: "skipped",
+        reason
+    };
+}

package/dist/scheduler/operatorNotification.js

@@ -0,0 +1,17 @@
+export function createLeaderRecoveryNotification(taskId, message, now, existing) {
+    const timestamp = now.toISOString();
+    return {
+        schemaVersion: 1,
+        taskId: requiredText(taskId, "Task id"),
+        type: "leader-recovery-failed",
+        message: requiredText(message, "Operator notification message"),
+        createdAt: existing?.createdAt ?? timestamp,
+        updatedAt: timestamp
+    };
+}
+function requiredText(value, label) {
+    const normalized = value.trim();
+    if (normalized.length === 0)
+        throw new Error(`${label} is required.`);
+    return normalized;
+}

package/dist/scheduler/pendingWakeup.js

@@ -0,0 +1,33 @@
+export function mergePendingWakeup(taskId, reason, now, existing) {
+    const normalizedTaskId = requiredText(taskId, "Task id");
+    const normalizedReason = requiredText(reason, "Wakeup reason");
+    if (existing !== null && existing.taskId !== normalizedTaskId) {
+        throw new Error(`Pending wakeup belongs to another Task: ${existing.taskId}.`);
+    }
+    const timestamp = now.toISOString();
+    return {
+        schemaVersion: 1,
+        taskId: normalizedTaskId,
+        reasons: existing === null
+            ? [normalizedReason]
+            : [...new Set([...existing.reasons, normalizedReason])],
+        requestCount: (existing?.requestCount ?? 0) + 1,
+        firstRequestedAt: existing?.firstRequestedAt ?? timestamp,
+        lastRequestedAt: timestamp
+    };
+}
+export function pendingWakeupsMatch(left, right) {
+    return left.schemaVersion === right.schemaVersion &&
+        left.taskId === right.taskId &&
+        left.requestCount === right.requestCount &&
+        left.firstRequestedAt === right.firstRequestedAt &&
+        left.lastRequestedAt === right.lastRequestedAt &&
+        left.reasons.length === right.reasons.length &&
+        left.reasons.every((reason, index) => reason === right.reasons[index]);
+}
+function requiredText(value, label) {
+    const normalized = value.trim();
+    if (normalized.length === 0)
+        throw new Error(`${label} is required.`);
+    return normalized;
+}

package/dist/scheduler/ports.js

@@ -0,0 +1 @@
+export {};

package/dist/scheduler/roleRunLiveness.js

@@ -0,0 +1,41 @@
+import { queueLeaderWakeup } from "./wakeupQueue.js";
+export const EXITED_ROLE_RUN_SUMMARY = "The role's tmux session exited before the run yielded.";
+/**
+ * Lightweight liveness only: an active AgentRun whose tmux role is absent is
+ * failed, then the Leader is durably queued. No TTL, cooldown, or schedules.
+ */
+export async function reconcileExitedRoleRuns(store, delivery, now) {
+    const failed = [];
+    for (const task of store.listTasks()) {
+        for (const role of store.listRoles(task.id)) {
+            const run = store.getActiveAgentRun(task.id, role.name);
+            if (run === null)
+                continue;
+            const session = store.getRoleSession(task.id, role.name);
+            const status = await delivery.inspectRole({
+                taskId: task.id,
+                roleName: role.name,
+                agentId: role.activeAgentId,
+                adapterId: role.adapterId,
+                ...(session?.nativeSessionId === undefined
+                    ? {}
+                    : { nativeSessionId: session.nativeSessionId })
+            });
+            if (status === "present")
+                continue;
+            store.saveExitedRoleRun({
+                task,
+                role,
+                run,
+                session,
+                summary: EXITED_ROLE_RUN_SUMMARY,
+                now
+            });
+            failed.push(run.id);
+            if (task.status === "active") {
+                queueLeaderWakeup(store, task.id, role.name === "leader" ? "leader-run-failed" : "role-run-failed", now);
+            }
+        }
+    }
+    return failed;
+}

package/dist/scheduler/wakeupQueue.js

@@ -0,0 +1,13 @@
+import { mergePendingWakeup } from "./pendingWakeup.js";
+export function queueLeaderWakeup(store, taskId, reason, now) {
+    const pending = mergePendingWakeup(taskId, reason, now, store.getPendingWakeup(taskId));
+    store.savePendingWakeup(pending);
+    return pending;
+}
+export function queueLeaderWakeupAfterYield(store, task, run, now) {
+    if (run.taskId !== task.id)
+        throw new Error(`AgentRun belongs to another Task: ${run.taskId}.`);
+    if (task.status !== "active" || run.roleName === "leader")
+        return null;
+    return queueLeaderWakeup(store, task.id, "role-result", now);
+}