@zq-silk/yui 0.2.0 → 0.4.2

package/dist/scheduler/taskExecutionProjection.js

@@ -0,0 +1,544 @@
+import { currentWorkItemExecutionGroup } from "../workItem/workItem.js";
+import { summarizeExecutionGroup } from "../execution/executionGroup.js";
+import { isRoleRunStalled, latestStallProgressAt } from "./roleRunStall.js";
+/**
+ * Build one consistent Task-first projection from the existing durable
+ * aggregate. This function only reads; it never starts a Controller, queues a
+ * wake, writes a Message, or mutates any record.
+ */
+export function buildTaskExecutionProjection(store, taskId, taskOverride) {
+    const task = store.getTask?.(taskId) ?? taskOverride ?? null;
+    if (task === null)
+        return null;
+    const roles = store.listRoles?.(taskId) ?? [];
+    const runs = store.listAgentRuns?.(taskId) ?? [];
+    const leaderMailbox = store.getWorkMailbox?.({
+        kind: "role",
+        taskId,
+        roleName: "leader"
+    }) ?? null;
+    const roleSessions = roles.flatMap((role) => {
+        const session = store.getRoleSession?.(taskId, role.name, role.activeAgentId);
+        return session === null || session === undefined
+            ? []
+            : [{ roleName: role.name, ...session }];
+    });
+    return projectTaskExecution({
+        task,
+        roles,
+        runs,
+        executionGroups: store.listWorkItems === undefined && store.listReviewRounds === undefined
+            ? []
+            : collectExecutionGroups(store.listWorkItems?.(taskId) ?? [], store.listReviewRounds?.(taskId) ?? []),
+        workItems: store.listWorkItems?.(taskId) ?? [],
+        inputRequests: store.listInputRequests?.(taskId) ?? [],
+        ...(store.listReviewRounds === undefined
+            ? {}
+            : { reviewRounds: store.listReviewRounds(taskId) }),
+        ...(store.listChangeSets === undefined
+            ? {}
+            : { changeSets: store.listChangeSets(taskId) }),
+        ...(store.listIntegrationAttempts === undefined
+            ? {}
+            : { integrations: store.listIntegrationAttempts(taskId) }),
+        ...(store.listEvents === undefined ? {} : { events: store.listEvents(taskId) }),
+        ...(store.getTaskBrief === undefined ? {} : { brief: store.getTaskBrief(taskId) }),
+        pendingWakeup: store.getPendingWakeup?.(taskId) ?? null,
+        leaderMailbox,
+        leaderFailure: store.getLeaderFailure?.(taskId) ?? null,
+        operatorNotification: store.getOperatorNotification?.(taskId) ?? null,
+        roleSessions
+    });
+}
+/** Alias kept intentionally small for scheduler callers and external read models. */
+export const deriveTaskExecutionProjection = projectTaskExecution;
+export function projectTaskExecution(facts) {
+    const { task, roles, runs, workItems = [], inputRequests = [], reviewRounds = [], integrations = [], events = [], pendingWakeup = null, leaderMailbox = null, leaderFailure = null, operatorNotification = null, roleSessions = [], executionGroups = [] } = facts;
+    const groupSummaries = executionGroups.map((group) => summarizeExecutionGroup(group));
+    const render = (input) => projection({
+        ...input,
+        executionGroups: groupSummaries
+    });
+    const activeRuns = runs.filter((run) => run.status === "active");
+    const activeRunViews = activeRuns.map((run) => ({
+        id: run.id,
+        roleName: run.roleName,
+        purpose: run.purpose,
+        delivered: run.deliveredAt !== undefined,
+        status: run.status,
+        ...(run.executionGroupId === undefined ? {} : { executionGroupId: run.executionGroupId }),
+        ...(run.executionLaneId === undefined ? {} : { executionLaneId: run.executionLaneId })
+    }));
+    const monitoring = task.status === "completed"
+        || task.status === "retired"
+        || task.status === "archived"
+        ? "stopped"
+        : "active";
+    if (monitoring === "stopped") {
+        const stoppedStatus = task.status;
+        return render({
+            task,
+            status: stoppedStatus,
+            owner: "none",
+            action: "none",
+            summary: `Task ${task.id} is ${task.status}; execution monitoring is stopped.`,
+            reason: "task-terminal",
+            monitoring,
+            failClosed: false,
+            activeRuns: activeRunViews,
+            activeExecutorCount: 0,
+            attention: [],
+            blockers: [],
+            pendingWakeup
+        });
+    }
+    const attention = collectAttention({
+        task,
+        roles,
+        activeRuns,
+        events,
+        leaderFailure,
+        operatorNotification,
+        roleSessions,
+        inputRequests
+    });
+    const openInputs = inputRequests.filter((request) => request.status === "open");
+    const blockers = collectBlockers(workItems, reviewRounds, integrations, openInputs, task);
+    const activeExecutors = activeRuns.filter((run) => isExecutionCarrier(run));
+    const activeWorkers = activeExecutors.filter((run) => run.roleName !== "leader");
+    const healthyExecutionCarriers = activeWorkers.filter((run) => (run.deliveredAt !== undefined
+        && !attention.some((item) => item.runId === run.id)));
+    const activeLeader = activeRuns.find((run) => run.roleName === "leader");
+    const pendingDelivery = activeRuns.some((run) => run.deliveredAt === undefined);
+    const hasPendingLeaderWork = pendingWakeup !== null
+        || leaderMailbox?.pending !== null && leaderMailbox?.pending !== undefined;
+    const recoveryPending = isRecoveryPending(pendingWakeup, leaderMailbox, leaderFailure, operatorNotification);
+    const failedWork = workItems.some((item) => item.status === "failed");
+    const candidateReady = workItems.some((item) => item.status === "awaiting_acceptance");
+    const blockedIntegration = integrations.some((attempt) => attempt.status === "blocked");
+    const unresolvedIntegration = integrations.some((attempt) => (attempt.status === "running"
+        || attempt.status === "validating"
+        || attempt.status === "blocked"));
+    const hasLeaderMismatch = attention.some((item) => item.kind === "identity-mismatch");
+    if (attention.length > 0) {
+        const first = attention[0];
+        const progressingWithAttention = first.kind === "checkpoint-overdue"
+            && healthyExecutionCarriers.length > 0;
+        return render({
+            task,
+            status: progressingWithAttention ? "progressing-with-attention" : "attention",
+            owner: first.owner,
+            action: "inspect-attention",
+            summary: progressingWithAttention
+                ? `${healthyExecutionCarriers.length} healthy execution carrier(s) remain while ${first.summary}`
+                : first.summary,
+            reason: progressingWithAttention ? "progressing-with-attention" : first.kind,
+            monitoring,
+            failClosed: hasLeaderMismatch || attention.some((item) => item.failClosed === true),
+            activeRuns: activeRunViews,
+            activeExecutorCount: activeExecutors.length,
+            attention,
+            blockers,
+            pendingWakeup
+        });
+    }
+    if (openInputs.length > 0) {
+        return render({
+            task,
+            status: "waiting-user",
+            owner: "user",
+            action: "answer-input",
+            summary: openInputs[0].question,
+            reason: "open-input-request",
+            monitoring,
+            failClosed: false,
+            activeRuns: activeRunViews,
+            activeExecutorCount: activeExecutors.length,
+            attention,
+            blockers,
+            pendingWakeup
+        });
+    }
+    if (blockedIntegration || failedWork || hasLeaderMismatch) {
+        return render({
+            task,
+            status: "blocked",
+            owner: "leader",
+            action: "resolve-blocker",
+            summary: blockers[0]?.summary ?? `Task ${task.id} has a blocked durable record.`,
+            reason: blockedIntegration ? "integration-blocked" : failedWork ? "work-failed" : "identity-mismatch",
+            monitoring,
+            failClosed: hasLeaderMismatch,
+            activeRuns: activeRunViews,
+            activeExecutorCount: activeExecutors.length,
+            attention,
+            blockers,
+            pendingWakeup
+        });
+    }
+    if (recoveryPending) {
+        return render({
+            task,
+            status: "recovering",
+            owner: leaderFailure !== null ? "operator" : "leader",
+            action: leaderFailure !== null ? "inspect-attention" : "recover-leader",
+            summary: leaderFailure?.message
+                ?? `Task ${task.id} has a durable recovery wake pending.`,
+            reason: leaderFailure === null ? "recovery-pending" : "leader-recovery-failed",
+            monitoring,
+            failClosed: leaderFailure !== null,
+            activeRuns: activeRunViews,
+            activeExecutorCount: activeExecutors.length,
+            attention,
+            blockers,
+            pendingWakeup
+        });
+    }
+    if (pendingDelivery) {
+        return render({
+            task,
+            status: "recovering",
+            owner: "leader",
+            action: "recover-leader",
+            summary: "An active Run is awaiting provider acceptance; delivery remains fail-closed.",
+            reason: "delivery-pending",
+            monitoring,
+            failClosed: false,
+            activeRuns: activeRunViews,
+            activeExecutorCount: activeExecutors.length,
+            attention,
+            blockers,
+            pendingWakeup
+        });
+    }
+    if (activeWorkers.length > 0 && activeLeader === undefined) {
+        return render({
+            task,
+            status: "waiting-on-agents",
+            owner: roleOwner(activeWorkers[0].roleName),
+            action: "wait-for-agents",
+            summary: `${activeWorkers.length} delegated execution Run(s) are active; Leader is waiting for their result.`,
+            reason: "delegated-work-active",
+            monitoring,
+            failClosed: false,
+            activeRuns: activeRunViews,
+            activeExecutorCount: activeExecutors.length,
+            attention,
+            blockers,
+            pendingWakeup
+        });
+    }
+    if (activeLeader !== undefined) {
+        return render({
+            task,
+            status: activeWorkers.length > 0 ? "waiting-on-agents" : "working",
+            owner: "leader",
+            action: activeWorkers.length > 0 ? "wait-for-agents" : "advance-task",
+            summary: activeWorkers.length > 0
+                ? `Leader Run is active while ${activeWorkers.length} delegated Run(s) continue.`
+                : "Leader Run is actively advancing the Task.",
+            reason: activeWorkers.length > 0 ? "leader-and-delegates-active" : "leader-run-active",
+            monitoring,
+            failClosed: false,
+            activeRuns: activeRunViews,
+            activeExecutorCount: activeExecutors.length,
+            attention,
+            blockers,
+            pendingWakeup
+        });
+    }
+    if (activeExecutors.length > 0) {
+        return render({
+            task,
+            status: "waiting-on-agents",
+            owner: roleOwner(activeExecutors[0].roleName),
+            action: "wait-for-agents",
+            summary: `${activeExecutors.length} delegated execution Run(s) are active.`,
+            reason: "delegated-work-active",
+            monitoring,
+            failClosed: false,
+            activeRuns: activeRunViews,
+            activeExecutorCount: activeExecutors.length,
+            attention,
+            blockers,
+            pendingWakeup
+        });
+    }
+    if (candidateReady || unresolvedIntegration || hasPendingLeaderWork) {
+        return render({
+            task,
+            status: "needs-leader-action",
+            owner: "leader",
+            action: "advance-task",
+            summary: candidateReady
+                ? "A WorkItem Candidate is awaiting Leader action."
+                : unresolvedIntegration
+                    ? "An Integration or validation record needs Leader action."
+                    : "A durable Leader wake is pending.",
+            reason: candidateReady
+                ? "candidate-ready"
+                : unresolvedIntegration ? "integration-pending" : "leader-wake-pending",
+            monitoring,
+            failClosed: false,
+            activeRuns: activeRunViews,
+            activeExecutorCount: activeExecutors.length,
+            attention,
+            blockers,
+            pendingWakeup
+        });
+    }
+    return render({
+        task,
+        status: "needs-leader-action",
+        owner: "leader",
+        action: "advance-task",
+        summary: `Active Task ${task.id} has no current executor or open input.`,
+        reason: "no-executor",
+        monitoring,
+        failClosed: false,
+        activeRuns: activeRunViews,
+        activeExecutorCount: activeExecutors.length,
+        attention,
+        blockers,
+        pendingWakeup
+    });
+}
+function projection(input) {
+    return {
+        taskId: input.task.id,
+        taskStatus: input.task.status,
+        status: input.status,
+        owner: input.owner,
+        action: input.action,
+        summary: input.summary,
+        reason: input.reason,
+        monitoring: input.monitoring,
+        failClosed: input.failClosed,
+        activeExecutorCount: input.activeExecutorCount,
+        activeRuns: input.activeRuns,
+        executionGroups: input.executionGroups ?? [],
+        attention: input.attention,
+        blockers: input.blockers,
+        pendingWakeup: input.pendingWakeup,
+        next: { owner: input.owner, action: input.action }
+    };
+}
+function collectExecutionGroups(workItems, reviewRounds) {
+    const groups = [
+        ...workItems.flatMap((item) => {
+            const group = currentWorkItemExecutionGroup(item);
+            return group === undefined ? [] : [group];
+        }),
+        ...reviewRounds.flatMap((round) => round.executionGroup === undefined ? [] : [round.executionGroup])
+    ];
+    const seen = new Set();
+    return groups.filter((group) => {
+        if (seen.has(group.id))
+            return false;
+        seen.add(group.id);
+        return true;
+    });
+}
+function collectAttention(input) {
+    const result = [];
+    const { task, activeRuns, events, leaderFailure, operatorNotification } = input;
+    if (leaderFailure !== null || operatorNotification?.type === "leader-recovery-failed") {
+        result.push({
+            kind: "leader-recovery",
+            id: `leader-recovery:${task.id}`,
+            owner: "operator",
+            summary: leaderFailure?.message
+                ?? (operatorNotification?.type === "leader-recovery-failed"
+                    ? operatorNotification.message
+                    : "Leader recovery failed."),
+            ...(leaderFailure === null ? {} : { failClosed: true })
+        });
+    }
+    if (operatorNotification?.type === "leader-stalled") {
+        result.push({
+            kind: "leader-stalled",
+            id: `leader-stall:${operatorNotification.runId}:${operatorNotification.progressAt}`,
+            owner: "operator",
+            summary: operatorNotification.message,
+            runId: operatorNotification.runId,
+            roleName: "leader"
+        });
+    }
+    for (const run of activeRuns) {
+        const role = input.roles.find((candidate) => candidate.name === run.roleName);
+        const session = input.roleSessions.find((candidate) => candidate.roleName === run.roleName);
+        if (role !== undefined
+            && ((role.activeAgentId !== undefined && role.activeAgentId !== run.effective?.agentId)
+                || (role.adapterId !== undefined && role.adapterId !== run.effective?.adapterId))) {
+            result.push({
+                kind: "identity-mismatch",
+                id: `identity:${run.id}`,
+                owner: "leader",
+                summary: `Run ${run.id} does not match the current ${run.roleName} Agent/adapter fence.`,
+                runId: run.id,
+                roleName: run.roleName,
+                failClosed: true
+            });
+        }
+        if (session !== undefined
+            && (session.agentId !== run.effective?.agentId || session.adapterId !== run.effective?.adapterId)) {
+            result.push({
+                kind: "identity-mismatch",
+                id: `session:${run.id}`,
+                owner: "leader",
+                summary: `Run ${run.id} has a provider/session identity mismatch; monitoring fails closed.`,
+                runId: run.id,
+                roleName: run.roleName,
+                failClosed: true
+            });
+        }
+        if (isRoleRunStalled(events, run.id)) {
+            if (run.roleName === "leader") {
+                const progressAt = latestStallProgressAt(events, run.id) ?? "unknown";
+                result.push({
+                    kind: "leader-stalled",
+                    id: `leader-stall:${run.id}:${progressAt}`,
+                    owner: "operator",
+                    summary: `Leader Run ${run.id} has an unresolved no-progress attention.`,
+                    runId: run.id,
+                    roleName: run.roleName
+                });
+            }
+            else {
+                result.push({
+                    kind: "checkpoint-overdue",
+                    id: `checkpoint-overdue:${run.id}`,
+                    owner: "leader",
+                    summary: `Delegated Run ${run.id} has an unresolved checkpoint-overdue signal.`,
+                    runId: run.id,
+                    roleName: run.roleName
+                });
+            }
+        }
+    }
+    for (const request of input.inputRequests.filter(({ status }) => status === "open")) {
+        const requester = request.requester;
+        const run = requester === undefined
+            ? undefined
+            : activeRuns.find(({ id }) => id === requester.runId);
+        const role = requester === undefined
+            ? undefined
+            : input.roles.find(({ name }) => name === requester.roleName);
+        const session = requester === undefined
+            ? undefined
+            : input.roleSessions.find(({ roleName }) => roleName === requester.roleName);
+        if (run === undefined
+            || run.roleName !== "leader"
+            || requester === undefined
+            || run.effective?.agentId !== requester.agentId
+            || (role?.adapterId !== undefined && role.adapterId !== run.effective?.adapterId)
+            || (requester.nativeSessionId !== undefined
+                && session?.nativeSessionId !== requester.nativeSessionId)) {
+            result.push({
+                kind: "identity-mismatch",
+                id: `input:${request.id}`,
+                owner: "leader",
+                summary: `InputRequest ${request.id} does not match the active Leader Run/session; it is held fail-closed.`,
+                ...(requester?.runId === undefined ? {} : { runId: requester.runId }),
+                roleName: "leader",
+                failClosed: true
+            });
+        }
+    }
+    return uniqueAttention(result);
+}
+function collectBlockers(workItems, reviewRounds, integrations, openInputs, task) {
+    const blockers = [];
+    const byId = new Map(workItems.map((item) => [item.id, item]));
+    for (const item of workItems) {
+        if (item.status === "failed" || item.status === "awaiting_acceptance") {
+            blockers.push({
+                kind: "work",
+                id: item.id,
+                owner: "leader",
+                summary: item.outcome ?? `WorkItem ${item.id} is ${item.status}.`
+            });
+        }
+        if (item.status === "pending" && (item.dependsOn ?? []).some((id) => byId.get(id)?.status !== "completed")) {
+            blockers.push({
+                kind: "work",
+                id: item.id,
+                owner: "leader",
+                summary: `WorkItem ${item.id} is waiting on a dependency.`
+            });
+        }
+    }
+    for (const round of reviewRounds.filter(({ status }) => status === "failed")) {
+        blockers.push({
+            kind: "review",
+            id: round.id,
+            owner: "leader",
+            summary: round.summary ?? `ReviewRound ${round.id} failed.`
+        });
+    }
+    for (const attempt of integrations.filter(({ status }) => status === "blocked" || status === "failed")) {
+        blockers.push({
+            kind: "integration",
+            id: attempt.id,
+            owner: "leader",
+            summary: attempt.conflict?.summary ?? `Integration ${attempt.id} is ${attempt.status}.`
+        });
+    }
+    for (const request of openInputs) {
+        blockers.push({
+            kind: "input",
+            id: request.id,
+            owner: "user",
+            summary: request.question
+        });
+    }
+    if (task.status === "active" && task.cwd === undefined) {
+        blockers.push({
+            kind: "identity",
+            id: `workspace:${task.id}`,
+            owner: "leader",
+            summary: "Project-backed Task workspace is not ready."
+        });
+    }
+    return blockers;
+}
+function isExecutionCarrier(run) {
+    return run.purpose === "review"
+        || run.roleName === "leader"
+        // A scheduler-only projection may not have the WorkItem fold available
+        // (for example during a recovery read). An active non-Leader Role is still
+        // an execution carrier; omitting it would falsely wake the Leader.
+        || run.workItemId !== undefined
+        || run.roleName !== "leader";
+}
+function roleOwner(roleName) {
+    const normalized = roleName.toLowerCase();
+    if (normalized === "leader")
+        return "leader";
+    if (normalized.includes("review"))
+        return "reviewer";
+    if (normalized.includes("test"))
+        return "tester";
+    return "worker";
+}
+function isRecoveryPending(wakeup, mailbox, failure, notification) {
+    if (failure !== null || notification?.type === "leader-recovery-failed")
+        return false;
+    const reasons = [
+        ...(wakeup?.reasons ?? []),
+        ...(mailbox?.pending?.reasons ?? []),
+        ...(mailbox?.processing?.batch.reasons ?? [])
+    ];
+    return reasons.some((reason) => /(?:recover|stalled|failed|uncertain|orphan)/iu.test(reason));
+}
+function uniqueAttention(items) {
+    const result = [];
+    const seen = new Set();
+    for (const item of items) {
+        if (seen.has(item.id))
+            continue;
+        seen.add(item.id);
+        result.push(item);
+    }
+    return result;
+}

package/dist/scheduler/wakeupQueue.js

@@ -1,5 +1,8 @@
 import { mergePendingWakeup } from "./pendingWakeup.js";
 export function queueLeaderWakeup(store, taskId, reason, now) {
+    if (store.enqueueLeaderWakeup !== undefined) {
+        return store.enqueueLeaderWakeup(taskId, reason, now);
+    }
     const pending = mergePendingWakeup(taskId, reason, now, store.getPendingWakeup(taskId));
     store.savePendingWakeup(pending);
     return pending;