@caupulican/pi-adaptative 0.86.3 → 0.86.6

package/dist/core/delegation/worker-task-view.js

@@ -0,0 +1,194 @@
+import { Buffer } from "node:buffer";
+import { ATTEMPT_STATUSES, MAX_ORCHESTRATION_COLLECTION_LENGTH, MAX_ORCHESTRATION_DESCRIPTION_LENGTH, MAX_ORCHESTRATION_IDENTIFIER_LENGTH, TASK_STATUSES, WORKER_ROLES, } from "../orchestration/contracts.js";
+import { isPlainRecord } from "../util/value-guards.js";
+import { DEFAULT_WORKER_FLEET_LIMITS } from "./worker-fleet-limits.js";
+/** Keep task views within the same durable session fan-out ceiling as the worker fleet. */
+export const MAX_WORKER_TASK_VIEW_ENTRIES = Math.min(DEFAULT_WORKER_FLEET_LIMITS.maxAgentsPerSession, DEFAULT_WORKER_FLEET_LIMITS.maxQueuedDispatches);
+/** Bound model-facing serialization independently of task-count and field-count limits. */
+export const MAX_WORKER_TASK_VIEW_BYTES = 64 * 1024;
+function boundedString(value, maxLength) {
+    return typeof value === "string" && value.length > 0 ? value.slice(0, maxLength) : undefined;
+}
+function isListedValue(value, allowed) {
+    return typeof value === "string" && allowed.some((candidate) => candidate === value);
+}
+function boundedIdentifierArray(value) {
+    if (!Array.isArray(value))
+        return [];
+    const identifiers = [];
+    for (let index = 0; index < Math.min(value.length, MAX_ORCHESTRATION_COLLECTION_LENGTH); index += 1) {
+        const identifier = boundedString(value[index], MAX_ORCHESTRATION_IDENTIFIER_LENGTH);
+        if (identifier)
+            identifiers.push(identifier);
+    }
+    return identifiers;
+}
+function taskViewCandidate(recordTaskId, value) {
+    if (!isPlainRecord(value) || !isPlainRecord(value.task))
+        return undefined;
+    if (value.task.taskId !== recordTaskId)
+        return undefined;
+    const taskId = boundedString(value.task.taskId, MAX_ORCHESTRATION_IDENTIFIER_LENGTH);
+    const title = boundedString(value.task.title, MAX_ORCHESTRATION_DESCRIPTION_LENGTH);
+    const createdAt = boundedString(value.task.createdAt, MAX_ORCHESTRATION_IDENTIFIER_LENGTH);
+    if (!taskId ||
+        !title ||
+        !createdAt ||
+        !isListedValue(value.task.role, WORKER_ROLES) ||
+        !isListedValue(value.task.status, TASK_STATUSES)) {
+        return undefined;
+    }
+    const verificationOfTaskId = boundedString(value.task.verificationOfTaskId, MAX_ORCHESTRATION_IDENTIFIER_LENGTH);
+    return {
+        attemptIds: value.attemptIds,
+        verification: value.verification,
+        taskId,
+        title,
+        role: value.task.role,
+        status: value.task.status,
+        dependsOn: boundedIdentifierArray(value.task.dependsOn),
+        createdAt,
+        ...(verificationOfTaskId ? { verificationOfTaskId } : {}),
+    };
+}
+function latestExistingAttempt(snapshot, attemptIds) {
+    if (!Array.isArray(attemptIds))
+        return undefined;
+    const firstInspectedIndex = Math.max(0, attemptIds.length - MAX_ORCHESTRATION_COLLECTION_LENGTH);
+    for (let index = attemptIds.length - 1; index >= firstInspectedIndex; index -= 1) {
+        const attemptId = attemptIds[index];
+        if (typeof attemptId !== "string" || !Object.hasOwn(snapshot.attempts, attemptId))
+            continue;
+        return snapshot.attempts[attemptId];
+    }
+    return undefined;
+}
+function projectAttempt(value) {
+    if (!isPlainRecord(value) || !isListedValue(value.status, ATTEMPT_STATUSES))
+        return undefined;
+    const dispatch = isPlainRecord(value.dispatch) ? value.dispatch : undefined;
+    const agentId = boundedString(value.agentId, MAX_ORCHESTRATION_IDENTIFIER_LENGTH) ??
+        boundedString(dispatch?.logicalLaneId, MAX_ORCHESTRATION_IDENTIFIER_LENGTH);
+    const reasonCode = boundedString(value.reasonCode, MAX_ORCHESTRATION_IDENTIFIER_LENGTH);
+    const retry = isPlainRecord(value.retry) ? value.retry : undefined;
+    const retriesUsed = retry?.retriesUsed;
+    const notBefore = boundedString(retry?.notBefore, MAX_ORCHESTRATION_IDENTIFIER_LENGTH);
+    const validRetry = Number.isSafeInteger(retriesUsed) && Number(retriesUsed) > 0 && notBefore;
+    return {
+        ...(agentId ? { agentId } : {}),
+        status: value.status,
+        ...(reasonCode ? { reasonCode } : {}),
+        ...(validRetry ? { retry: { retriesUsed: Number(retriesUsed), notBefore } } : {}),
+    };
+}
+function projectVerification(value) {
+    if (!isPlainRecord(value) || !isListedValue(value.verdict, ["accepted", "rejected", "inconclusive"])) {
+        return undefined;
+    }
+    const verifierTaskId = boundedString(value.verifierTaskId, MAX_ORCHESTRATION_IDENTIFIER_LENGTH);
+    const reasonCode = boundedString(value.reasonCode, MAX_ORCHESTRATION_IDENTIFIER_LENGTH);
+    return verifierTaskId && reasonCode ? { verifierTaskId, verdict: value.verdict, reasonCode } : undefined;
+}
+function projectTask(snapshot, candidate) {
+    const attempt = projectAttempt(latestExistingAttempt(snapshot, candidate.attemptIds));
+    const verificationOutcome = projectVerification(candidate.verification);
+    return {
+        taskId: candidate.taskId,
+        title: candidate.title,
+        role: candidate.role,
+        status: candidate.status,
+        dependsOn: candidate.dependsOn,
+        ...(candidate.verificationOfTaskId ? { verificationOfTaskId: candidate.verificationOfTaskId } : {}),
+        ...(verificationOutcome ? { verificationOutcome } : {}),
+        ...(attempt ? { latestAttempt: attempt } : {}),
+    };
+}
+function compareTasksNewestFirst(left, right) {
+    return right.createdAt.localeCompare(left.createdAt) || left.taskId.localeCompare(right.taskId);
+}
+/** Maintain the worst retained task at index zero, without allocating for the full task history. */
+function admitToNewestWindow(window, selection) {
+    if (window.length < MAX_WORKER_TASK_VIEW_ENTRIES) {
+        window.push(selection);
+        let childIndex = window.length - 1;
+        while (childIndex > 0) {
+            const parentIndex = Math.floor((childIndex - 1) / 2);
+            if (compareTasksNewestFirst(window[childIndex].candidate, window[parentIndex].candidate) <= 0) {
+                break;
+            }
+            [window[parentIndex], window[childIndex]] = [
+                window[childIndex],
+                window[parentIndex],
+            ];
+            childIndex = parentIndex;
+        }
+        return;
+    }
+    if (compareTasksNewestFirst(selection.candidate, window[0].candidate) >= 0)
+        return;
+    window[0] = selection;
+    let parentIndex = 0;
+    while (true) {
+        const leftIndex = parentIndex * 2 + 1;
+        if (leftIndex >= window.length)
+            return;
+        const rightIndex = leftIndex + 1;
+        const worseChildIndex = rightIndex < window.length &&
+            compareTasksNewestFirst(window[rightIndex].candidate, window[leftIndex].candidate) > 0
+            ? rightIndex
+            : leftIndex;
+        if (compareTasksNewestFirst(window[worseChildIndex].candidate, window[parentIndex].candidate) <= 0) {
+            return;
+        }
+        [window[parentIndex], window[worseChildIndex]] = [
+            window[worseChildIndex],
+            window[parentIndex],
+        ];
+        parentIndex = worseChildIndex;
+    }
+}
+const MIN_WORKER_TASK_VIEW_ENVELOPE_BYTES = Buffer.byteLength(JSON.stringify({ totalTasks: 0, omittedTaskCount: 0, tasks: [] }), "utf8");
+function serializedSessionViewByteLength(totalTasks, taskCount, taskBytes) {
+    const envelopeBytes = Buffer.byteLength(JSON.stringify({ totalTasks, omittedTaskCount: totalTasks - taskCount, tasks: [] }), "utf8");
+    return envelopeBytes + taskBytes + Math.max(0, taskCount - 1);
+}
+/**
+ * Derive a provider-neutral, bounded team-task read model from the durable runtime projection.
+ * Every returned field is selected explicitly so execution authority and provider diagnostics
+ * cannot cross this read boundary through object spread.
+ */
+export function projectWorkerTaskSessionView(snapshot) {
+    let totalTasks = 0;
+    const selected = [];
+    for (const taskId in snapshot.tasks) {
+        if (!Object.hasOwn(snapshot.tasks, taskId))
+            continue;
+        totalTasks += 1;
+        const candidate = taskViewCandidate(taskId, snapshot.tasks[taskId]);
+        if (!candidate)
+            continue;
+        const view = projectTask(snapshot, candidate);
+        const serializedByteLength = Buffer.byteLength(JSON.stringify(view), "utf8");
+        if (serializedByteLength + MIN_WORKER_TASK_VIEW_ENVELOPE_BYTES > MAX_WORKER_TASK_VIEW_BYTES)
+            continue;
+        admitToNewestWindow(selected, { candidate, view, serializedByteLength });
+    }
+    selected.sort((left, right) => compareTasksNewestFirst(left.candidate, right.candidate));
+    const tasks = [];
+    let taskBytes = 0;
+    for (const selection of selected) {
+        const nextTaskCount = tasks.length + 1;
+        const nextTaskBytes = taskBytes + selection.serializedByteLength;
+        if (serializedSessionViewByteLength(totalTasks, nextTaskCount, nextTaskBytes) > MAX_WORKER_TASK_VIEW_BYTES) {
+            continue;
+        }
+        tasks.push(selection.view);
+        taskBytes = nextTaskBytes;
+    }
+    return {
+        totalTasks,
+        omittedTaskCount: totalTasks - tasks.length,
+        tasks,
+    };
+}
+//# sourceMappingURL=worker-task-view.js.map

package/dist/core/delegation/worker-task-view.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker-task-view.js","sourceRoot":"","sources":["../../../src/core/delegation/worker-task-view.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAErC,OAAO,EACN,gBAAgB,EAChB,mCAAmC,EACnC,oCAAoC,EACpC,mCAAmC,EACnC,aAAa,EACb,YAAY,GACZ,MAAM,+BAA+B,CAAC;AAEvC,OAAO,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AACxD,OAAO,EAAE,2BAA2B,EAAE,MAAM,0BAA0B,CAAC;AAEvE,2FAA2F;AAC3F,MAAM,CAAC,MAAM,4BAA4B,GAAG,IAAI,CAAC,GAAG,CACnD,2BAA2B,CAAC,mBAAmB,EAC/C,2BAA2B,CAAC,mBAAmB,CAC/C,CAAC;AAEF,2FAA2F;AAC3F,MAAM,CAAC,MAAM,0BAA0B,GAAG,EAAE,GAAG,IAAI,CAAC;AAqDpD,SAAS,aAAa,CAAC,KAAc,EAAE,SAAiB;IACvD,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;AAC9F,CAAC;AAED,SAAS,aAAa,CAA6B,KAAc,EAAE,OAAyB;IAC3F,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,SAAS,KAAK,KAAK,CAAC,CAAC;AACtF,CAAC;AAED,SAAS,sBAAsB,CAAC,KAAc;IAC7C,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IACrC,MAAM,WAAW,GAAa,EAAE,CAAC;IACjC,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,EAAE,mCAAmC,CAAC,EAAE,KAAK,IAAI,CAAC,EAAE,CAAC;QACrG,MAAM,UAAU,GAAG,aAAa,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,mCAAmC,CAAC,CAAC;QACpF,IAAI,UAAU;YAAE,WAAW,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IAC9C,CAAC;IACD,OAAO,WAAW,CAAC;AACpB,CAAC;AAED,SAAS,iBAAiB,CAAC,YAAoB,EAAE,KAAc;IAC9D,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,IAAI,CAAC;QAAE,OAAO,SAAS,CAAC;IAC1E,IAAI,KAAK,CAAC,IAAI,CAAC,MAAM,KAAK,YAAY;QAAE,OAAO,SAAS,CAAC;IACzD,MAAM,MAAM,GAAG,aAAa,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,mCAAmC,CAAC,CAAC;IACrF,MAAM,KAAK,GAAG,aAAa,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,EAAE,oCAAoC,CAAC,CAAC;IACpF,MAAM,SAAS,GAAG,aAAa,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,EAAE,mCAAmC,CAAC,CAAC;IAC3F,IACC,CAAC,MAAM;QACP,CAAC,KAAK;QACN,CAAC,SAAS;QACV,CAAC,aAAa,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,EAAE,YAAY,CAAC;QAC7C,CAAC,aAAa,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,aAAa,CAAC,EAC/C,CAAC;QACF,OAAO,SAAS,CAAC;IAClB,CAAC;IACD,MAAM,oBAAoB,GAAG,aAAa,CAAC,KAAK,CAAC,IAAI,CAAC,oBAAoB,EAAE,mCAAmC,CAAC,CAAC;IACjH,OAAO;QACN,UAAU,EAAE,KAAK,CAAC,UAAU;QAC5B,YAAY,EAAE,KAAK,CAAC,YAAY;QAChC,MAAM;QACN,KAAK;QACL,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,IAAI;QACrB,MAAM,EAAE,KAAK,CAAC,IAAI,CAAC,MAAM;QACzB,SAAS,EAAE,sBAAsB,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC;QACvD,SAAS;QACT,GAAG,CAAC,oBAAoB,CAAC,CAAC,CAAC,EAAE,oBAAoB,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACzD,CAAC;AACH,CAAC;AAED,SAAS,qBAAqB,CAAC,QAA+B,EAAE,UAAmB;IAClF,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,UAAU,CAAC;QAAE,OAAO,SAAS,CAAC;IACjD,MAAM,mBAAmB,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,UAAU,CAAC,MAAM,GAAG,mCAAmC,CAAC,CAAC;IACjG,KAAK,IAAI,KAAK,GAAG,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,KAAK,IAAI,mBAAmB,EAAE,KAAK,IAAI,CAAC,EAAE,CAAC;QAClF,MAAM,SAAS,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC;QACpC,IAAI,OAAO,SAAS,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,QAAQ,EAAE,SAAS,CAAC;YAAE,SAAS;QAC5F,OAAO,QAAQ,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC;IACrC,CAAC;IACD,OAAO,SAAS,CAAC;AAClB,CAAC;AAED,SAAS,cAAc,CAAC,KAAc;IACrC,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,MAAM,EAAE,gBAAgB,CAAC;QAAE,OAAO,SAAS,CAAC;IAC9F,MAAM,QAAQ,GAAG,aAAa,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC;IAC5E,MAAM,OAAO,GACZ,aAAa,CAAC,KAAK,CAAC,OAAO,EAAE,mCAAmC,CAAC;QACjE,aAAa,CAAC,QAAQ,EAAE,aAAa,EAAE,mCAAmC,CAAC,CAAC;IAC7E,MAAM,UAAU,GAAG,aAAa,CAAC,KAAK,CAAC,UAAU,EAAE,mCAAmC,CAAC,CAAC;IACxF,MAAM,KAAK,GAAG,aAAa,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;IACnE,MAAM,WAAW,GAAG,KAAK,EAAE,WAAW,CAAC;IACvC,MAAM,SAAS,GAAG,aAAa,CAAC,KAAK,EAAE,SAAS,EAAE,mCAAmC,CAAC,CAAC;IACvF,MAAM,UAAU,GAAG,MAAM,CAAC,aAAa,CAAC,WAAW,CAAC,IAAI,MAAM,CAAC,WAAW,CAAC,GAAG,CAAC,IAAI,SAAS,CAAC;IAC7F,OAAO;QACN,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC/B,MAAM,EAAE,KAAK,CAAC,MAAM;QACpB,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACrC,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,EAAE,WAAW,EAAE,MAAM,CAAC,WAAW,CAAC,EAAE,SAAS,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACjF,CAAC;AACH,CAAC;AAED,SAAS,mBAAmB,CAAC,KAAc;IAC1C,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC,UAAU,EAAE,UAAU,EAAE,cAAc,CAAU,CAAC,EAAE,CAAC;QAC/G,OAAO,SAAS,CAAC;IAClB,CAAC;IACD,MAAM,cAAc,GAAG,aAAa,CAAC,KAAK,CAAC,cAAc,EAAE,mCAAmC,CAAC,CAAC;IAChG,MAAM,UAAU,GAAG,aAAa,CAAC,KAAK,CAAC,UAAU,EAAE,mCAAmC,CAAC,CAAC;IACxF,OAAO,cAAc,IAAI,UAAU,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,UAAU,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;AAC1G,CAAC;AAED,SAAS,WAAW,CAAC,QAA+B,EAAE,SAA4B;IACjF,MAAM,OAAO,GAAG,cAAc,CAAC,qBAAqB,CAAC,QAAQ,EAAE,SAAS,CAAC,UAAU,CAAC,CAAC,CAAC;IACtF,MAAM,mBAAmB,GAAG,mBAAmB,CAAC,SAAS,CAAC,YAAY,CAAC,CAAC;IACxE,OAAO;QACN,MAAM,EAAE,SAAS,CAAC,MAAM;QACxB,KAAK,EAAE,SAAS,CAAC,KAAK;QACtB,IAAI,EAAE,SAAS,CAAC,IAAI;QACpB,MAAM,EAAE,SAAS,CAAC,MAAM;QACxB,SAAS,EAAE,SAAS,CAAC,SAAS;QAC9B,GAAG,CAAC,SAAS,CAAC,oBAAoB,CAAC,CAAC,CAAC,EAAE,oBAAoB,EAAE,SAAS,CAAC,oBAAoB,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACnG,GAAG,CAAC,mBAAmB,CAAC,CAAC,CAAC,EAAE,mBAAmB,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACvD,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,aAAa,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC9C,CAAC;AACH,CAAC;AAED,SAAS,uBAAuB,CAAC,IAAuB,EAAE,KAAwB;IACjF,OAAO,KAAK,CAAC,SAAS,CAAC,aAAa,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;AACjG,CAAC;AAED,oGAAoG;AACpG,SAAS,mBAAmB,CAAC,MAA2B,EAAE,SAA4B;IACrF,IAAI,MAAM,CAAC,MAAM,GAAG,4BAA4B,EAAE,CAAC;QAClD,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QACvB,IAAI,UAAU,GAAG,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC;QACnC,OAAO,UAAU,GAAG,CAAC,EAAE,CAAC;YACvB,MAAM,WAAW,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,UAAU,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;YACrD,IACC,uBAAuB,CACrB,MAAM,CAAC,UAAU,CAAuB,CAAC,SAAS,EAClD,MAAM,CAAC,WAAW,CAAuB,CAAC,SAAS,CACpD,IAAI,CAAC,EACL,CAAC;gBACF,MAAM;YACP,CAAC;YACD,CAAC,MAAM,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC,CAAC,GAAG;gBAC3C,MAAM,CAAC,UAAU,CAAsB;gBACvC,MAAM,CAAC,WAAW,CAAsB;aACxC,CAAC;YACF,UAAU,GAAG,WAAW,CAAC;QAC1B,CAAC;QACD,OAAO;IACR,CAAC;IACD,IAAI,uBAAuB,CAAC,SAAS,CAAC,SAAS,EAAG,MAAM,CAAC,CAAC,CAAuB,CAAC,SAAS,CAAC,IAAI,CAAC;QAAE,OAAO;IAE1G,MAAM,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC;IACtB,IAAI,WAAW,GAAG,CAAC,CAAC;IACpB,OAAO,IAAI,EAAE,CAAC;QACb,MAAM,SAAS,GAAG,WAAW,GAAG,CAAC,GAAG,CAAC,CAAC;QACtC,IAAI,SAAS,IAAI,MAAM,CAAC,MAAM;YAAE,OAAO;QACvC,MAAM,UAAU,GAAG,SAAS,GAAG,CAAC,CAAC;QACjC,MAAM,eAAe,GACpB,UAAU,GAAG,MAAM,CAAC,MAAM;YAC1B,uBAAuB,CACrB,MAAM,CAAC,UAAU,CAAuB,CAAC,SAAS,EAClD,MAAM,CAAC,SAAS,CAAuB,CAAC,SAAS,CAClD,GAAG,CAAC;YACJ,CAAC,CAAC,UAAU;YACZ,CAAC,CAAC,SAAS,CAAC;QACd,IACC,uBAAuB,CACrB,MAAM,CAAC,eAAe,CAAuB,CAAC,SAAS,EACvD,MAAM,CAAC,WAAW,CAAuB,CAAC,SAAS,CACpD,IAAI,CAAC,EACL,CAAC;YACF,OAAO;QACR,CAAC;QACD,CAAC,MAAM,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC,eAAe,CAAC,CAAC,GAAG;YAChD,MAAM,CAAC,eAAe,CAAsB;YAC5C,MAAM,CAAC,WAAW,CAAsB;SACxC,CAAC;QACF,WAAW,GAAG,eAAe,CAAC;IAC/B,CAAC;AACF,CAAC;AAED,MAAM,mCAAmC,GAAG,MAAM,CAAC,UAAU,CAC5D,IAAI,CAAC,SAAS,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,gBAAgB,EAAE,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC,EACjE,MAAM,CACN,CAAC;AAEF,SAAS,+BAA+B,CAAC,UAAkB,EAAE,SAAiB,EAAE,SAAiB;IAChG,MAAM,aAAa,GAAG,MAAM,CAAC,UAAU,CACtC,IAAI,CAAC,SAAS,CAAC,EAAE,UAAU,EAAE,gBAAgB,EAAE,UAAU,GAAG,SAAS,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC,EACnF,MAAM,CACN,CAAC;IACF,OAAO,aAAa,GAAG,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,SAAS,GAAG,CAAC,CAAC,CAAC;AAC/D,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,4BAA4B,CAAC,QAA+B;IAC3E,IAAI,UAAU,GAAG,CAAC,CAAC;IACnB,MAAM,QAAQ,GAAwB,EAAE,CAAC;IACzC,KAAK,MAAM,MAAM,IAAI,QAAQ,CAAC,KAAK,EAAE,CAAC;QACrC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;YAAE,SAAS;QACrD,UAAU,IAAI,CAAC,CAAC;QAChB,MAAM,SAAS,GAAG,iBAAiB,CAAC,MAAM,EAAE,QAAQ,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC;QACpE,IAAI,CAAC,SAAS;YAAE,SAAS;QACzB,MAAM,IAAI,GAAG,WAAW,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC;QAC9C,MAAM,oBAAoB,GAAG,MAAM,CAAC,UAAU,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC,CAAC;QAC7E,IAAI,oBAAoB,GAAG,mCAAmC,GAAG,0BAA0B;YAAE,SAAS;QACtG,mBAAmB,CAAC,QAAQ,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,oBAAoB,EAAE,CAAC,CAAC;IAC1E,CAAC;IACD,QAAQ,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,uBAAuB,CAAC,IAAI,CAAC,SAAS,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC;IACzF,MAAM,KAAK,GAAqB,EAAE,CAAC;IACnC,IAAI,SAAS,GAAG,CAAC,CAAC;IAClB,KAAK,MAAM,SAAS,IAAI,QAAQ,EAAE,CAAC;QAClC,MAAM,aAAa,GAAG,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC;QACvC,MAAM,aAAa,GAAG,SAAS,GAAG,SAAS,CAAC,oBAAoB,CAAC;QACjE,IAAI,+BAA+B,CAAC,UAAU,EAAE,aAAa,EAAE,aAAa,CAAC,GAAG,0BAA0B,EAAE,CAAC;YAC5G,SAAS;QACV,CAAC;QACD,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;QAC3B,SAAS,GAAG,aAAa,CAAC;IAC3B,CAAC;IACD,OAAO;QACN,UAAU;QACV,gBAAgB,EAAE,UAAU,GAAG,KAAK,CAAC,MAAM;QAC3C,KAAK;KACL,CAAC;AACH,CAAC","sourcesContent":["import { Buffer } from \"node:buffer\";\nimport type { AttemptStatus, OrchestrationTaskStatus, WorkerRole } from \"../orchestration/contracts.ts\";\nimport {\n\tATTEMPT_STATUSES,\n\tMAX_ORCHESTRATION_COLLECTION_LENGTH,\n\tMAX_ORCHESTRATION_DESCRIPTION_LENGTH,\n\tMAX_ORCHESTRATION_IDENTIFIER_LENGTH,\n\tTASK_STATUSES,\n\tWORKER_ROLES,\n} from \"../orchestration/contracts.ts\";\nimport type { TaskRuntimeProjection } from \"../orchestration/task-runtime.ts\";\nimport { isPlainRecord } from \"../util/value-guards.ts\";\nimport { DEFAULT_WORKER_FLEET_LIMITS } from \"./worker-fleet-limits.ts\";\n\n/** Keep task views within the same durable session fan-out ceiling as the worker fleet. */\nexport const MAX_WORKER_TASK_VIEW_ENTRIES = Math.min(\n\tDEFAULT_WORKER_FLEET_LIMITS.maxAgentsPerSession,\n\tDEFAULT_WORKER_FLEET_LIMITS.maxQueuedDispatches,\n);\n\n/** Bound model-facing serialization independently of task-count and field-count limits. */\nexport const MAX_WORKER_TASK_VIEW_BYTES = 64 * 1024;\n\nexport interface WorkerTaskAttemptView {\n\tagentId?: string;\n\tstatus: AttemptStatus;\n\treasonCode?: string;\n\tretry?: {\n\t\tretriesUsed: number;\n\t\tnotBefore: string;\n\t};\n}\n\nexport interface WorkerTaskView {\n\ttaskId: string;\n\ttitle: string;\n\trole: WorkerRole;\n\tstatus: OrchestrationTaskStatus;\n\tdependsOn: readonly string[];\n\tverificationOfTaskId?: string;\n\tverificationOutcome?: {\n\t\tverifierTaskId: string;\n\t\tverdict: VerificationVerdict;\n\t\treasonCode: string;\n\t};\n\tlatestAttempt?: WorkerTaskAttemptView;\n}\n\ntype VerificationVerdict = \"accepted\" | \"rejected\" | \"inconclusive\";\n\ninterface TaskViewCandidate {\n\tattemptIds: unknown;\n\tverification: unknown;\n\ttaskId: string;\n\ttitle: string;\n\trole: WorkerRole;\n\tstatus: OrchestrationTaskStatus;\n\tdependsOn: readonly string[];\n\tcreatedAt: string;\n\tverificationOfTaskId?: string;\n}\n\ninterface TaskViewSelection {\n\tcandidate: TaskViewCandidate;\n\tview: WorkerTaskView;\n\tserializedByteLength: number;\n}\n\nexport interface WorkerTaskSessionView {\n\ttotalTasks: number;\n\tomittedTaskCount: number;\n\ttasks: readonly WorkerTaskView[];\n}\n\nfunction boundedString(value: unknown, maxLength: number): string | undefined {\n\treturn typeof value === \"string\" && value.length > 0 ? value.slice(0, maxLength) : undefined;\n}\n\nfunction isListedValue<const Value extends string>(value: unknown, allowed: readonly Value[]): value is Value {\n\treturn typeof value === \"string\" && allowed.some((candidate) => candidate === value);\n}\n\nfunction boundedIdentifierArray(value: unknown): readonly string[] {\n\tif (!Array.isArray(value)) return [];\n\tconst identifiers: string[] = [];\n\tfor (let index = 0; index < Math.min(value.length, MAX_ORCHESTRATION_COLLECTION_LENGTH); index += 1) {\n\t\tconst identifier = boundedString(value[index], MAX_ORCHESTRATION_IDENTIFIER_LENGTH);\n\t\tif (identifier) identifiers.push(identifier);\n\t}\n\treturn identifiers;\n}\n\nfunction taskViewCandidate(recordTaskId: string, value: unknown): TaskViewCandidate | undefined {\n\tif (!isPlainRecord(value) || !isPlainRecord(value.task)) return undefined;\n\tif (value.task.taskId !== recordTaskId) return undefined;\n\tconst taskId = boundedString(value.task.taskId, MAX_ORCHESTRATION_IDENTIFIER_LENGTH);\n\tconst title = boundedString(value.task.title, MAX_ORCHESTRATION_DESCRIPTION_LENGTH);\n\tconst createdAt = boundedString(value.task.createdAt, MAX_ORCHESTRATION_IDENTIFIER_LENGTH);\n\tif (\n\t\t!taskId ||\n\t\t!title ||\n\t\t!createdAt ||\n\t\t!isListedValue(value.task.role, WORKER_ROLES) ||\n\t\t!isListedValue(value.task.status, TASK_STATUSES)\n\t) {\n\t\treturn undefined;\n\t}\n\tconst verificationOfTaskId = boundedString(value.task.verificationOfTaskId, MAX_ORCHESTRATION_IDENTIFIER_LENGTH);\n\treturn {\n\t\tattemptIds: value.attemptIds,\n\t\tverification: value.verification,\n\t\ttaskId,\n\t\ttitle,\n\t\trole: value.task.role,\n\t\tstatus: value.task.status,\n\t\tdependsOn: boundedIdentifierArray(value.task.dependsOn),\n\t\tcreatedAt,\n\t\t...(verificationOfTaskId ? { verificationOfTaskId } : {}),\n\t};\n}\n\nfunction latestExistingAttempt(snapshot: TaskRuntimeProjection, attemptIds: unknown): unknown {\n\tif (!Array.isArray(attemptIds)) return undefined;\n\tconst firstInspectedIndex = Math.max(0, attemptIds.length - MAX_ORCHESTRATION_COLLECTION_LENGTH);\n\tfor (let index = attemptIds.length - 1; index >= firstInspectedIndex; index -= 1) {\n\t\tconst attemptId = attemptIds[index];\n\t\tif (typeof attemptId !== \"string\" || !Object.hasOwn(snapshot.attempts, attemptId)) continue;\n\t\treturn snapshot.attempts[attemptId];\n\t}\n\treturn undefined;\n}\n\nfunction projectAttempt(value: unknown): WorkerTaskAttemptView | undefined {\n\tif (!isPlainRecord(value) || !isListedValue(value.status, ATTEMPT_STATUSES)) return undefined;\n\tconst dispatch = isPlainRecord(value.dispatch) ? value.dispatch : undefined;\n\tconst agentId =\n\t\tboundedString(value.agentId, MAX_ORCHESTRATION_IDENTIFIER_LENGTH) ??\n\t\tboundedString(dispatch?.logicalLaneId, MAX_ORCHESTRATION_IDENTIFIER_LENGTH);\n\tconst reasonCode = boundedString(value.reasonCode, MAX_ORCHESTRATION_IDENTIFIER_LENGTH);\n\tconst retry = isPlainRecord(value.retry) ? value.retry : undefined;\n\tconst retriesUsed = retry?.retriesUsed;\n\tconst notBefore = boundedString(retry?.notBefore, MAX_ORCHESTRATION_IDENTIFIER_LENGTH);\n\tconst validRetry = Number.isSafeInteger(retriesUsed) && Number(retriesUsed) > 0 && notBefore;\n\treturn {\n\t\t...(agentId ? { agentId } : {}),\n\t\tstatus: value.status,\n\t\t...(reasonCode ? { reasonCode } : {}),\n\t\t...(validRetry ? { retry: { retriesUsed: Number(retriesUsed), notBefore } } : {}),\n\t};\n}\n\nfunction projectVerification(value: unknown): WorkerTaskView[\"verificationOutcome\"] {\n\tif (!isPlainRecord(value) || !isListedValue(value.verdict, [\"accepted\", \"rejected\", \"inconclusive\"] as const)) {\n\t\treturn undefined;\n\t}\n\tconst verifierTaskId = boundedString(value.verifierTaskId, MAX_ORCHESTRATION_IDENTIFIER_LENGTH);\n\tconst reasonCode = boundedString(value.reasonCode, MAX_ORCHESTRATION_IDENTIFIER_LENGTH);\n\treturn verifierTaskId && reasonCode ? { verifierTaskId, verdict: value.verdict, reasonCode } : undefined;\n}\n\nfunction projectTask(snapshot: TaskRuntimeProjection, candidate: TaskViewCandidate): WorkerTaskView {\n\tconst attempt = projectAttempt(latestExistingAttempt(snapshot, candidate.attemptIds));\n\tconst verificationOutcome = projectVerification(candidate.verification);\n\treturn {\n\t\ttaskId: candidate.taskId,\n\t\ttitle: candidate.title,\n\t\trole: candidate.role,\n\t\tstatus: candidate.status,\n\t\tdependsOn: candidate.dependsOn,\n\t\t...(candidate.verificationOfTaskId ? { verificationOfTaskId: candidate.verificationOfTaskId } : {}),\n\t\t...(verificationOutcome ? { verificationOutcome } : {}),\n\t\t...(attempt ? { latestAttempt: attempt } : {}),\n\t};\n}\n\nfunction compareTasksNewestFirst(left: TaskViewCandidate, right: TaskViewCandidate): number {\n\treturn right.createdAt.localeCompare(left.createdAt) || left.taskId.localeCompare(right.taskId);\n}\n\n/** Maintain the worst retained task at index zero, without allocating for the full task history. */\nfunction admitToNewestWindow(window: TaskViewSelection[], selection: TaskViewSelection): void {\n\tif (window.length < MAX_WORKER_TASK_VIEW_ENTRIES) {\n\t\twindow.push(selection);\n\t\tlet childIndex = window.length - 1;\n\t\twhile (childIndex > 0) {\n\t\t\tconst parentIndex = Math.floor((childIndex - 1) / 2);\n\t\t\tif (\n\t\t\t\tcompareTasksNewestFirst(\n\t\t\t\t\t(window[childIndex] as TaskViewSelection).candidate,\n\t\t\t\t\t(window[parentIndex] as TaskViewSelection).candidate,\n\t\t\t\t) <= 0\n\t\t\t) {\n\t\t\t\tbreak;\n\t\t\t}\n\t\t\t[window[parentIndex], window[childIndex]] = [\n\t\t\t\twindow[childIndex] as TaskViewSelection,\n\t\t\t\twindow[parentIndex] as TaskViewSelection,\n\t\t\t];\n\t\t\tchildIndex = parentIndex;\n\t\t}\n\t\treturn;\n\t}\n\tif (compareTasksNewestFirst(selection.candidate, (window[0] as TaskViewSelection).candidate) >= 0) return;\n\n\twindow[0] = selection;\n\tlet parentIndex = 0;\n\twhile (true) {\n\t\tconst leftIndex = parentIndex * 2 + 1;\n\t\tif (leftIndex >= window.length) return;\n\t\tconst rightIndex = leftIndex + 1;\n\t\tconst worseChildIndex =\n\t\t\trightIndex < window.length &&\n\t\t\tcompareTasksNewestFirst(\n\t\t\t\t(window[rightIndex] as TaskViewSelection).candidate,\n\t\t\t\t(window[leftIndex] as TaskViewSelection).candidate,\n\t\t\t) > 0\n\t\t\t\t? rightIndex\n\t\t\t\t: leftIndex;\n\t\tif (\n\t\t\tcompareTasksNewestFirst(\n\t\t\t\t(window[worseChildIndex] as TaskViewSelection).candidate,\n\t\t\t\t(window[parentIndex] as TaskViewSelection).candidate,\n\t\t\t) <= 0\n\t\t) {\n\t\t\treturn;\n\t\t}\n\t\t[window[parentIndex], window[worseChildIndex]] = [\n\t\t\twindow[worseChildIndex] as TaskViewSelection,\n\t\t\twindow[parentIndex] as TaskViewSelection,\n\t\t];\n\t\tparentIndex = worseChildIndex;\n\t}\n}\n\nconst MIN_WORKER_TASK_VIEW_ENVELOPE_BYTES = Buffer.byteLength(\n\tJSON.stringify({ totalTasks: 0, omittedTaskCount: 0, tasks: [] }),\n\t\"utf8\",\n);\n\nfunction serializedSessionViewByteLength(totalTasks: number, taskCount: number, taskBytes: number): number {\n\tconst envelopeBytes = Buffer.byteLength(\n\t\tJSON.stringify({ totalTasks, omittedTaskCount: totalTasks - taskCount, tasks: [] }),\n\t\t\"utf8\",\n\t);\n\treturn envelopeBytes + taskBytes + Math.max(0, taskCount - 1);\n}\n\n/**\n * Derive a provider-neutral, bounded team-task read model from the durable runtime projection.\n * Every returned field is selected explicitly so execution authority and provider diagnostics\n * cannot cross this read boundary through object spread.\n */\nexport function projectWorkerTaskSessionView(snapshot: TaskRuntimeProjection): WorkerTaskSessionView {\n\tlet totalTasks = 0;\n\tconst selected: TaskViewSelection[] = [];\n\tfor (const taskId in snapshot.tasks) {\n\t\tif (!Object.hasOwn(snapshot.tasks, taskId)) continue;\n\t\ttotalTasks += 1;\n\t\tconst candidate = taskViewCandidate(taskId, snapshot.tasks[taskId]);\n\t\tif (!candidate) continue;\n\t\tconst view = projectTask(snapshot, candidate);\n\t\tconst serializedByteLength = Buffer.byteLength(JSON.stringify(view), \"utf8\");\n\t\tif (serializedByteLength + MIN_WORKER_TASK_VIEW_ENVELOPE_BYTES > MAX_WORKER_TASK_VIEW_BYTES) continue;\n\t\tadmitToNewestWindow(selected, { candidate, view, serializedByteLength });\n\t}\n\tselected.sort((left, right) => compareTasksNewestFirst(left.candidate, right.candidate));\n\tconst tasks: WorkerTaskView[] = [];\n\tlet taskBytes = 0;\n\tfor (const selection of selected) {\n\t\tconst nextTaskCount = tasks.length + 1;\n\t\tconst nextTaskBytes = taskBytes + selection.serializedByteLength;\n\t\tif (serializedSessionViewByteLength(totalTasks, nextTaskCount, nextTaskBytes) > MAX_WORKER_TASK_VIEW_BYTES) {\n\t\t\tcontinue;\n\t\t}\n\t\ttasks.push(selection.view);\n\t\ttaskBytes = nextTaskBytes;\n\t}\n\treturn {\n\t\ttotalTasks,\n\t\tomittedTaskCount: totalTasks - tasks.length,\n\t\ttasks,\n\t};\n}\n"]}

package/dist/core/delegation/worker-terminal-handoff-coordinator.d.ts

@@ -0,0 +1,55 @@
+import { type LaneRecord } from "../autonomy/lane-tracker.ts";
+export interface WorkerTerminalHandoff {
+    terminalAttemptId: string;
+    parentAgentId: string;
+    childAgentId: string;
+    record: LaneRecord;
+}
+/** Per-entry ceiling; combined with the durable attempt cap this bounds retained memory to 4 MiB. */
+export declare const MAX_WORKER_TERMINAL_HANDOFF_BYTES: number;
+export type WorkerTerminalHandoffDelivery = "delivered" | "retained";
+export type WorkerTerminalHandoffRetention = "retained" | "replay";
+export interface WorkerTerminalHandoffDrainResult {
+    attempted: number;
+    delivered: number;
+    errors: number;
+    retained: number;
+}
+export interface WorkerTerminalHandoffRehydrationResult {
+    added: number;
+    replayed: number;
+    drain: WorkerTerminalHandoffDrainResult;
+}
+export interface WorkerTerminalHandoffCoordinatorOptions {
+    deliver(handoff: Readonly<WorkerTerminalHandoff>): WorkerTerminalHandoffDelivery;
+    onDeliveryError?(handoff: Readonly<WorkerTerminalHandoff>, error: unknown): void;
+}
+/**
+ * Bounded process-local outbox for parent terminal handoffs. Delivery is driven only by explicit
+ * terminal, capacity, state-change, and recovery calls; this owner never creates a timer or poll.
+ */
+export declare class WorkerTerminalHandoffCoordinator {
+    private readonly options;
+    private readonly pending;
+    private draining;
+    private redrainRequested;
+    private disposed;
+    constructor(options: WorkerTerminalHandoffCoordinatorOptions);
+    get retainedCount(): number;
+    retained(): WorkerTerminalHandoff[];
+    /** Retain one terminal handoff snapshot. Structurally identical pending replays are inert; conflicts fail closed. */
+    retain(handoff: WorkerTerminalHandoff): WorkerTerminalHandoffRetention;
+    /**
+     * Atomically adopt a durable recovery snapshot, then make one explicit delivery pass. Repeated
+     * attempt IDs in the recovery snapshot must carry structurally equivalent data.
+     */
+    rehydrate(handoffs: readonly WorkerTerminalHandoff[]): WorkerTerminalHandoffRehydrationResult;
+    /** Explicit terminal/capacity/state-change event. Reentrant signals coalesce into a redrain. */
+    signal(): WorkerTerminalHandoffDrainResult;
+    clear(): void;
+    dispose(): void;
+    private assertActive;
+    private assertCapacity;
+    private reportDeliveryError;
+}
+//# sourceMappingURL=worker-terminal-handoff-coordinator.d.ts.map

package/dist/core/delegation/worker-terminal-handoff-coordinator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker-terminal-handoff-coordinator.d.ts","sourceRoot":"","sources":["../../../src/core/delegation/worker-terminal-handoff-coordinator.ts"],"names":[],"mappings":"AACA,OAAO,EAAsC,KAAK,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAGlG,MAAM,WAAW,qBAAqB;IACrC,iBAAiB,EAAE,MAAM,CAAC;IAC1B,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,UAAU,CAAC;CACnB;AAED,qGAAqG;AACrG,eAAO,MAAM,iCAAiC,QAAY,CAAC;AAE3D,MAAM,MAAM,6BAA6B,GAAG,WAAW,GAAG,UAAU,CAAC;AACrE,MAAM,MAAM,8BAA8B,GAAG,UAAU,GAAG,QAAQ,CAAC;AAEnE,MAAM,WAAW,gCAAgC;IAChD,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,sCAAsC;IACtD,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,gCAAgC,CAAC;CACxC;AAED,MAAM,WAAW,uCAAuC;IACvD,OAAO,CAAC,OAAO,EAAE,QAAQ,CAAC,qBAAqB,CAAC,GAAG,6BAA6B,CAAC;IACjF,eAAe,CAAC,CAAC,OAAO,EAAE,QAAQ,CAAC,qBAAqB,CAAC,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAAC;CACjF;AAkCD;;;GAGG;AACH,qBAAa,gCAAgC;IAC5C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA0C;IAClE,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA4C;IACpE,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,gBAAgB,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAS;IAEzB,YAAY,OAAO,EAAE,uCAAuC,EAE3D;IAED,IAAI,aAAa,IAAI,MAAM,CAE1B;IAED,QAAQ,IAAI,qBAAqB,EAAE,CAElC;IAED,qHAAqH;IACrH,MAAM,CAAC,OAAO,EAAE,qBAAqB,GAAG,8BAA8B,CAcrE;IAED;;;OAGG;IACH,SAAS,CAAC,QAAQ,EAAE,SAAS,qBAAqB,EAAE,GAAG,sCAAsC,CAuB5F;IAED,gGAAgG;IAChG,MAAM,IAAI,gCAAgC,CAoDzC;IAED,KAAK,IAAI,IAAI,CAGZ;IAED,OAAO,IAAI,IAAI,CAGd;IAED,OAAO,CAAC,YAAY;IAIpB,OAAO,CAAC,cAAc;IAKtB,OAAO,CAAC,mBAAmB;CAO3B"}

package/dist/core/delegation/worker-terminal-handoff-coordinator.js

@@ -0,0 +1,179 @@
+import { isDeepStrictEqual } from "node:util";
+import { isLaneRecord, isLaneTerminalStatus } from "../autonomy/lane-tracker.js";
+import { MAX_ORCHESTRATION_ATTEMPTS, MAX_ORCHESTRATION_IDENTIFIER_LENGTH } from "../orchestration/contracts.js";
+/** Per-entry ceiling; combined with the durable attempt cap this bounds retained memory to 4 MiB. */
+export const MAX_WORKER_TERMINAL_HANDOFF_BYTES = 16 * 1024;
+function assertIdentifier(value, label) {
+    if (typeof value !== "string" ||
+        !value ||
+        value.trim() !== value ||
+        value.length > MAX_ORCHESTRATION_IDENTIFIER_LENGTH) {
+        throw new TypeError(`${label} must be a bounded non-empty canonical string.`);
+    }
+}
+function snapshotHandoff(handoff) {
+    assertIdentifier(handoff.terminalAttemptId, "Worker terminal attempt ID");
+    assertIdentifier(handoff.parentAgentId, "Worker terminal parent agent ID");
+    assertIdentifier(handoff.childAgentId, "Worker terminal child agent ID");
+    if (!isLaneRecord(handoff.record)) {
+        throw new TypeError("Worker terminal handoff requires a valid lane record.");
+    }
+    if (!isLaneTerminalStatus(handoff.record.status)) {
+        throw new TypeError("Worker terminal handoff requires a terminal lane record.");
+    }
+    const snapshot = { ...handoff, record: { ...handoff.record } };
+    if (Buffer.byteLength(JSON.stringify(snapshot), "utf-8") > MAX_WORKER_TERMINAL_HANDOFF_BYTES) {
+        throw new TypeError(`Worker terminal handoff exceeds its ${MAX_WORKER_TERMINAL_HANDOFF_BYTES} byte limit.`);
+    }
+    return snapshot;
+}
+function cloneHandoff(handoff) {
+    return { ...handoff, record: { ...handoff.record } };
+}
+/**
+ * Bounded process-local outbox for parent terminal handoffs. Delivery is driven only by explicit
+ * terminal, capacity, state-change, and recovery calls; this owner never creates a timer or poll.
+ */
+export class WorkerTerminalHandoffCoordinator {
+    constructor(options) {
+        this.pending = new Map();
+        this.draining = false;
+        this.redrainRequested = false;
+        this.disposed = false;
+        this.options = options;
+    }
+    get retainedCount() {
+        return this.pending.size;
+    }
+    retained() {
+        return [...this.pending.values()].map(cloneHandoff);
+    }
+    /** Retain one terminal handoff snapshot. Structurally identical pending replays are inert; conflicts fail closed. */
+    retain(handoff) {
+        this.assertActive();
+        const snapshot = snapshotHandoff(handoff);
+        const existing = this.pending.get(snapshot.terminalAttemptId);
+        if (existing) {
+            if (isDeepStrictEqual(existing, snapshot))
+                return "replay";
+            throw new Error(`Worker terminal handoff attempt ${snapshot.terminalAttemptId} conflicts with its retained payload.`);
+        }
+        this.assertCapacity(this.pending.size + 1);
+        this.pending.set(snapshot.terminalAttemptId, snapshot);
+        if (this.draining)
+            this.redrainRequested = true;
+        return "retained";
+    }
+    /**
+     * Atomically adopt a durable recovery snapshot, then make one explicit delivery pass. Repeated
+     * attempt IDs in the recovery snapshot must carry structurally equivalent data.
+     */
+    rehydrate(handoffs) {
+        this.assertActive();
+        const staged = new Map(this.pending);
+        const additions = [];
+        let replayed = 0;
+        for (const handoff of handoffs) {
+            const snapshot = snapshotHandoff(handoff);
+            const existing = staged.get(snapshot.terminalAttemptId);
+            if (existing) {
+                if (!isDeepStrictEqual(existing, snapshot)) {
+                    throw new Error(`Worker terminal handoff attempt ${snapshot.terminalAttemptId} conflicts with its retained payload.`);
+                }
+                replayed += 1;
+                continue;
+            }
+            this.assertCapacity(staged.size + 1);
+            staged.set(snapshot.terminalAttemptId, snapshot);
+            additions.push(snapshot);
+        }
+        for (const handoff of additions)
+            this.pending.set(handoff.terminalAttemptId, handoff);
+        return { added: additions.length, replayed, drain: this.signal() };
+    }
+    /** Explicit terminal/capacity/state-change event. Reentrant signals coalesce into a redrain. */
+    signal() {
+        if (this.disposed)
+            return { attempted: 0, delivered: 0, errors: 0, retained: 0 };
+        if (this.draining) {
+            this.redrainRequested = true;
+            return { attempted: 0, delivered: 0, errors: 0, retained: this.pending.size };
+        }
+        let attempted = 0;
+        let delivered = 0;
+        let errors = 0;
+        let stagnantPasses = 0;
+        this.draining = true;
+        this.redrainRequested = true;
+        try {
+            while (this.redrainRequested && !this.disposed) {
+                this.redrainRequested = false;
+                const batch = [...this.pending.values()];
+                let passChanged = false;
+                for (const retained of batch) {
+                    if (this.disposed || this.pending.get(retained.terminalAttemptId) !== retained)
+                        continue;
+                    attempted += 1;
+                    let result;
+                    try {
+                        result = this.options.deliver(cloneHandoff(retained));
+                        if (result !== "delivered" && result !== "retained") {
+                            throw new TypeError("Worker terminal handoff delivery returned an invalid result.");
+                        }
+                    }
+                    catch (error) {
+                        errors += 1;
+                        this.reportDeliveryError(retained, error);
+                        continue;
+                    }
+                    if (result !== "delivered" || this.pending.get(retained.terminalAttemptId) !== retained)
+                        continue;
+                    this.pending.delete(retained.terminalAttemptId);
+                    delivered += 1;
+                    passChanged = true;
+                }
+                if (passChanged || batch.some((entry) => this.pending.get(entry.terminalAttemptId) !== entry)) {
+                    stagnantPasses = 0;
+                }
+                else {
+                    stagnantPasses += 1;
+                }
+                // A self-signalling retained callback cannot spin forever. One unchanged redrain is enough
+                // to observe every synchronous state mutation that preceded the nested signal.
+                if (this.redrainRequested && stagnantPasses >= 2)
+                    this.redrainRequested = false;
+            }
+        }
+        finally {
+            this.draining = false;
+            this.redrainRequested = false;
+        }
+        return { attempted, delivered, errors, retained: this.pending.size };
+    }
+    clear() {
+        this.pending.clear();
+        this.redrainRequested = false;
+    }
+    dispose() {
+        this.disposed = true;
+        this.clear();
+    }
+    assertActive() {
+        if (this.disposed)
+            throw new Error("Worker terminal handoff coordinator is disposed.");
+    }
+    assertCapacity(size) {
+        if (size <= MAX_ORCHESTRATION_ATTEMPTS)
+            return;
+        throw new Error(`Worker terminal handoff retention reached its ${MAX_ORCHESTRATION_ATTEMPTS} attempt limit.`);
+    }
+    reportDeliveryError(handoff, error) {
+        try {
+            this.options.onDeliveryError?.(cloneHandoff(handoff), error);
+        }
+        catch {
+            // Diagnostics cannot consume or unblock a retained terminal handoff.
+        }
+    }
+}
+//# sourceMappingURL=worker-terminal-handoff-coordinator.js.map

package/dist/core/delegation/worker-terminal-handoff-coordinator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker-terminal-handoff-coordinator.js","sourceRoot":"","sources":["../../../src/core/delegation/worker-terminal-handoff-coordinator.ts"],"names":[],"mappings":"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","sourcesContent":["import { isDeepStrictEqual } from \"node:util\";\nimport { isLaneRecord, isLaneTerminalStatus, type LaneRecord } from \"../autonomy/lane-tracker.ts\";\nimport { MAX_ORCHESTRATION_ATTEMPTS, MAX_ORCHESTRATION_IDENTIFIER_LENGTH } from \"../orchestration/contracts.ts\";\n\nexport interface WorkerTerminalHandoff {\n\tterminalAttemptId: string;\n\tparentAgentId: string;\n\tchildAgentId: string;\n\trecord: LaneRecord;\n}\n\n/** Per-entry ceiling; combined with the durable attempt cap this bounds retained memory to 4 MiB. */\nexport const MAX_WORKER_TERMINAL_HANDOFF_BYTES = 16 * 1024;\n\nexport type WorkerTerminalHandoffDelivery = \"delivered\" | \"retained\";\nexport type WorkerTerminalHandoffRetention = \"retained\" | \"replay\";\n\nexport interface WorkerTerminalHandoffDrainResult {\n\tattempted: number;\n\tdelivered: number;\n\terrors: number;\n\tretained: number;\n}\n\nexport interface WorkerTerminalHandoffRehydrationResult {\n\tadded: number;\n\treplayed: number;\n\tdrain: WorkerTerminalHandoffDrainResult;\n}\n\nexport interface WorkerTerminalHandoffCoordinatorOptions {\n\tdeliver(handoff: Readonly<WorkerTerminalHandoff>): WorkerTerminalHandoffDelivery;\n\tonDeliveryError?(handoff: Readonly<WorkerTerminalHandoff>, error: unknown): void;\n}\n\nfunction assertIdentifier(value: unknown, label: string): asserts value is string {\n\tif (\n\t\ttypeof value !== \"string\" ||\n\t\t!value ||\n\t\tvalue.trim() !== value ||\n\t\tvalue.length > MAX_ORCHESTRATION_IDENTIFIER_LENGTH\n\t) {\n\t\tthrow new TypeError(`${label} must be a bounded non-empty canonical string.`);\n\t}\n}\n\nfunction snapshotHandoff(handoff: WorkerTerminalHandoff): WorkerTerminalHandoff {\n\tassertIdentifier(handoff.terminalAttemptId, \"Worker terminal attempt ID\");\n\tassertIdentifier(handoff.parentAgentId, \"Worker terminal parent agent ID\");\n\tassertIdentifier(handoff.childAgentId, \"Worker terminal child agent ID\");\n\tif (!isLaneRecord(handoff.record)) {\n\t\tthrow new TypeError(\"Worker terminal handoff requires a valid lane record.\");\n\t}\n\tif (!isLaneTerminalStatus(handoff.record.status)) {\n\t\tthrow new TypeError(\"Worker terminal handoff requires a terminal lane record.\");\n\t}\n\tconst snapshot = { ...handoff, record: { ...handoff.record } };\n\tif (Buffer.byteLength(JSON.stringify(snapshot), \"utf-8\") > MAX_WORKER_TERMINAL_HANDOFF_BYTES) {\n\t\tthrow new TypeError(`Worker terminal handoff exceeds its ${MAX_WORKER_TERMINAL_HANDOFF_BYTES} byte limit.`);\n\t}\n\treturn snapshot;\n}\n\nfunction cloneHandoff(handoff: WorkerTerminalHandoff): WorkerTerminalHandoff {\n\treturn { ...handoff, record: { ...handoff.record } };\n}\n\n/**\n * Bounded process-local outbox for parent terminal handoffs. Delivery is driven only by explicit\n * terminal, capacity, state-change, and recovery calls; this owner never creates a timer or poll.\n */\nexport class WorkerTerminalHandoffCoordinator {\n\tprivate readonly options: WorkerTerminalHandoffCoordinatorOptions;\n\tprivate readonly pending = new Map<string, WorkerTerminalHandoff>();\n\tprivate draining = false;\n\tprivate redrainRequested = false;\n\tprivate disposed = false;\n\n\tconstructor(options: WorkerTerminalHandoffCoordinatorOptions) {\n\t\tthis.options = options;\n\t}\n\n\tget retainedCount(): number {\n\t\treturn this.pending.size;\n\t}\n\n\tretained(): WorkerTerminalHandoff[] {\n\t\treturn [...this.pending.values()].map(cloneHandoff);\n\t}\n\n\t/** Retain one terminal handoff snapshot. Structurally identical pending replays are inert; conflicts fail closed. */\n\tretain(handoff: WorkerTerminalHandoff): WorkerTerminalHandoffRetention {\n\t\tthis.assertActive();\n\t\tconst snapshot = snapshotHandoff(handoff);\n\t\tconst existing = this.pending.get(snapshot.terminalAttemptId);\n\t\tif (existing) {\n\t\t\tif (isDeepStrictEqual(existing, snapshot)) return \"replay\";\n\t\t\tthrow new Error(\n\t\t\t\t`Worker terminal handoff attempt ${snapshot.terminalAttemptId} conflicts with its retained payload.`,\n\t\t\t);\n\t\t}\n\t\tthis.assertCapacity(this.pending.size + 1);\n\t\tthis.pending.set(snapshot.terminalAttemptId, snapshot);\n\t\tif (this.draining) this.redrainRequested = true;\n\t\treturn \"retained\";\n\t}\n\n\t/**\n\t * Atomically adopt a durable recovery snapshot, then make one explicit delivery pass. Repeated\n\t * attempt IDs in the recovery snapshot must carry structurally equivalent data.\n\t */\n\trehydrate(handoffs: readonly WorkerTerminalHandoff[]): WorkerTerminalHandoffRehydrationResult {\n\t\tthis.assertActive();\n\t\tconst staged = new Map(this.pending);\n\t\tconst additions: WorkerTerminalHandoff[] = [];\n\t\tlet replayed = 0;\n\t\tfor (const handoff of handoffs) {\n\t\t\tconst snapshot = snapshotHandoff(handoff);\n\t\t\tconst existing = staged.get(snapshot.terminalAttemptId);\n\t\t\tif (existing) {\n\t\t\t\tif (!isDeepStrictEqual(existing, snapshot)) {\n\t\t\t\t\tthrow new Error(\n\t\t\t\t\t\t`Worker terminal handoff attempt ${snapshot.terminalAttemptId} conflicts with its retained payload.`,\n\t\t\t\t\t);\n\t\t\t\t}\n\t\t\t\treplayed += 1;\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\tthis.assertCapacity(staged.size + 1);\n\t\t\tstaged.set(snapshot.terminalAttemptId, snapshot);\n\t\t\tadditions.push(snapshot);\n\t\t}\n\t\tfor (const handoff of additions) this.pending.set(handoff.terminalAttemptId, handoff);\n\t\treturn { added: additions.length, replayed, drain: this.signal() };\n\t}\n\n\t/** Explicit terminal/capacity/state-change event. Reentrant signals coalesce into a redrain. */\n\tsignal(): WorkerTerminalHandoffDrainResult {\n\t\tif (this.disposed) return { attempted: 0, delivered: 0, errors: 0, retained: 0 };\n\t\tif (this.draining) {\n\t\t\tthis.redrainRequested = true;\n\t\t\treturn { attempted: 0, delivered: 0, errors: 0, retained: this.pending.size };\n\t\t}\n\n\t\tlet attempted = 0;\n\t\tlet delivered = 0;\n\t\tlet errors = 0;\n\t\tlet stagnantPasses = 0;\n\t\tthis.draining = true;\n\t\tthis.redrainRequested = true;\n\t\ttry {\n\t\t\twhile (this.redrainRequested && !this.disposed) {\n\t\t\t\tthis.redrainRequested = false;\n\t\t\t\tconst batch = [...this.pending.values()];\n\t\t\t\tlet passChanged = false;\n\t\t\t\tfor (const retained of batch) {\n\t\t\t\t\tif (this.disposed || this.pending.get(retained.terminalAttemptId) !== retained) continue;\n\t\t\t\t\tattempted += 1;\n\t\t\t\t\tlet result: WorkerTerminalHandoffDelivery;\n\t\t\t\t\ttry {\n\t\t\t\t\t\tresult = this.options.deliver(cloneHandoff(retained));\n\t\t\t\t\t\tif (result !== \"delivered\" && result !== \"retained\") {\n\t\t\t\t\t\t\tthrow new TypeError(\"Worker terminal handoff delivery returned an invalid result.\");\n\t\t\t\t\t\t}\n\t\t\t\t\t} catch (error) {\n\t\t\t\t\t\terrors += 1;\n\t\t\t\t\t\tthis.reportDeliveryError(retained, error);\n\t\t\t\t\t\tcontinue;\n\t\t\t\t\t}\n\t\t\t\t\tif (result !== \"delivered\" || this.pending.get(retained.terminalAttemptId) !== retained) continue;\n\t\t\t\t\tthis.pending.delete(retained.terminalAttemptId);\n\t\t\t\t\tdelivered += 1;\n\t\t\t\t\tpassChanged = true;\n\t\t\t\t}\n\n\t\t\t\tif (passChanged || batch.some((entry) => this.pending.get(entry.terminalAttemptId) !== entry)) {\n\t\t\t\t\tstagnantPasses = 0;\n\t\t\t\t} else {\n\t\t\t\t\tstagnantPasses += 1;\n\t\t\t\t}\n\t\t\t\t// A self-signalling retained callback cannot spin forever. One unchanged redrain is enough\n\t\t\t\t// to observe every synchronous state mutation that preceded the nested signal.\n\t\t\t\tif (this.redrainRequested && stagnantPasses >= 2) this.redrainRequested = false;\n\t\t\t}\n\t\t} finally {\n\t\t\tthis.draining = false;\n\t\t\tthis.redrainRequested = false;\n\t\t}\n\t\treturn { attempted, delivered, errors, retained: this.pending.size };\n\t}\n\n\tclear(): void {\n\t\tthis.pending.clear();\n\t\tthis.redrainRequested = false;\n\t}\n\n\tdispose(): void {\n\t\tthis.disposed = true;\n\t\tthis.clear();\n\t}\n\n\tprivate assertActive(): void {\n\t\tif (this.disposed) throw new Error(\"Worker terminal handoff coordinator is disposed.\");\n\t}\n\n\tprivate assertCapacity(size: number): void {\n\t\tif (size <= MAX_ORCHESTRATION_ATTEMPTS) return;\n\t\tthrow new Error(`Worker terminal handoff retention reached its ${MAX_ORCHESTRATION_ATTEMPTS} attempt limit.`);\n\t}\n\n\tprivate reportDeliveryError(handoff: WorkerTerminalHandoff, error: unknown): void {\n\t\ttry {\n\t\t\tthis.options.onDeliveryError?.(cloneHandoff(handoff), error);\n\t\t} catch {\n\t\t\t// Diagnostics cannot consume or unblock a retained terminal handoff.\n\t\t}\n\t}\n}\n"]}

package/dist/core/delegation/worker-tree-budget-coordinator.d.ts

@@ -1,4 +1,4 @@
-import type { SharedCapabilityBudget } from "../orchestration/capability-gateway.ts";
+import { type SharedCapabilityBudget } from "../orchestration/capability-gateway.ts";
 import type { AttemptUsageSnapshot, RiskBudget } from "../orchestration/contracts.ts";
 export declare class WorkerTreeBudgetExceededError extends Error {
     readonly field: "maxTokens" | "maxCostUsd" | "maxToolCalls" | "maxWallClockMs" | "maxAttempts";
@@ -40,7 +40,7 @@ export declare class WorkerTreeBudgetCoordinator {
     private reserveProviderBudget;
     private drainWaiters;
     private detachAbort;
-    private totalTokens;
+    private budgetedTokens;
     private reservedTokens;
     private assertAvailable;
 }

package/dist/core/delegation/worker-tree-budget-coordinator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"worker-tree-budget-coordinator.d.ts","sourceRoot":"","sources":["../../../src/core/delegation/worker-tree-budget-coordinator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAGX,sBAAsB,EACtB,MAAM,wCAAwC,CAAC;AAChD,OAAO,KAAK,EAAE,oBAAoB,EAAE,UAAU,EAAE,MAAM,+BAA+B,CAAC;AAGtF,qBAAa,6BAA8B,SAAQ,KAAK;IACvD,QAAQ,CAAC,KAAK,EAAE,WAAW,GAAG,YAAY,GAAG,cAAc,GAAG,gBAAgB,GAAG,aAAa,CAAC;IAE/F,YAAY,KAAK,EAAE,6BAA6B,CAAC,OAAO,CAAC,EAAE,OAAO,EAAE,MAAM,EAIzE;CACD;AAmBD,MAAM,WAAW,oBAAoB;IACpC,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,oBAAoB,CAAC;CAC5B;AAED,MAAM,WAAW,0BAA0B;IAC1C,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE;QAAE,WAAW,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC,CAAC;IAC1D,QAAQ,EAAE,QAAQ,CACjB,MAAM,CACL,MAAM,EACN;QACC,SAAS,EAAE,MAAM,CAAC;QAClB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,QAAQ,EAAE;YAAE,aAAa,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC;QACrC,aAAa,EAAE,SAAS,MAAM,EAAE,CAAC;KACjC,CACD,CACD,CAAC;IACF,WAAW,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE;QAAE,KAAK,CAAC,EAAE,oBAAoB,CAAA;KAAE,CAAC,CAAC,CAAC;CACxE;AAaD,2FAA2F;AAC3F,wBAAgB,4BAA4B,CAC3C,QAAQ,EAAE,0BAA0B,EACpC,WAAW,EAAE,MAAM,GACjB,oBAAoB,EAAE,CAYxB;AAiCD,oGAAoG;AACpG,qBAAa,2BAA2B;IACvC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAsC;IAE5D,UAAU,CAAC,IAAI,EAAE;QAChB,WAAW,EAAE,MAAM,CAAC;QACpB,SAAS,EAAE,MAAM,CAAC;QAClB,MAAM,EAAE,UAAU,CAAC;QACnB,KAAK,EAAE,SAAS,oBAAoB,EAAE,CAAC;QACvC,YAAY,EAAE,oBAAoB,CAAC;KACnC,GAAG,sBAAsB,CA4BzB;IAED,OAAO,CAAC,kBAAkB;IAa1B,OAAO,CAAC,qBAAqB;IAmC7B,OAAO,CAAC,YAAY;IA4CpB,OAAO,CAAC,WAAW;IAInB,OAAO,CAAC,WAAW;IAInB,OAAO,CAAC,cAAc;IAItB,OAAO,CAAC,eAAe;CA2BvB"}
+{"version":3,"file":"worker-tree-budget-coordinator.d.ts","sourceRoot":"","sources":["../../../src/core/delegation/worker-tree-budget-coordinator.ts"],"names":[],"mappings":"AAKA,OAAO,EAIN,KAAK,sBAAsB,EAC3B,MAAM,wCAAwC,CAAC;AAChD,OAAO,KAAK,EAAE,oBAAoB,EAAE,UAAU,EAAE,MAAM,+BAA+B,CAAC;AAGtF,qBAAa,6BAA8B,SAAQ,KAAK;IACvD,QAAQ,CAAC,KAAK,EAAE,WAAW,GAAG,YAAY,GAAG,cAAc,GAAG,gBAAgB,GAAG,aAAa,CAAC;IAE/F,YAAY,KAAK,EAAE,6BAA6B,CAAC,OAAO,CAAC,EAAE,OAAO,EAAE,MAAM,EAIzE;CACD;AAmBD,MAAM,WAAW,oBAAoB;IACpC,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,oBAAoB,CAAC;CAC5B;AAED,MAAM,WAAW,0BAA0B;IAC1C,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE;QAAE,WAAW,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC,CAAC;IAC1D,QAAQ,EAAE,QAAQ,CACjB,MAAM,CACL,MAAM,EACN;QACC,SAAS,EAAE,MAAM,CAAC;QAClB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,QAAQ,EAAE;YAAE,aAAa,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC;QACrC,aAAa,EAAE,SAAS,MAAM,EAAE,CAAC;KACjC,CACD,CACD,CAAC;IACF,WAAW,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE;QAAE,KAAK,CAAC,EAAE,oBAAoB,CAAA;KAAE,CAAC,CAAC,CAAC;CACxE;AAED,2FAA2F;AAC3F,wBAAgB,4BAA4B,CAC3C,QAAQ,EAAE,0BAA0B,EACpC,WAAW,EAAE,MAAM,GACjB,oBAAoB,EAAE,CAYxB;AAMD,oGAAoG;AACpG,qBAAa,2BAA2B;IACvC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAsC;IAE5D,UAAU,CAAC,IAAI,EAAE;QAChB,WAAW,EAAE,MAAM,CAAC;QACpB,SAAS,EAAE,MAAM,CAAC;QAClB,MAAM,EAAE,UAAU,CAAC;QACnB,KAAK,EAAE,SAAS,oBAAoB,EAAE,CAAC;QACvC,YAAY,EAAE,oBAAoB,CAAC;KACnC,GAAG,sBAAsB,CA+BzB;IAED,OAAO,CAAC,kBAAkB;IAa1B,OAAO,CAAC,qBAAqB;IAmC7B,OAAO,CAAC,YAAY;IA4CpB,OAAO,CAAC,WAAW;IAInB,OAAO,CAAC,cAAc;IAItB,OAAO,CAAC,cAAc;IAItB,OAAO,CAAC,eAAe;CA2BvB"}