@tea-agent/loop-agent 0.35.0 → 0.35.1-beta.0

package/dist/worker/console/operation-wait.js

@@ -0,0 +1,241 @@
+import { projectOperationEventSummary, projectOperationForChat, } from "./chat/chat-event-store.js";
+import { isTerminalOperationState, } from "./operation-store.js";
+/**
+ * P2: read-only event-driven long poll on the canonical operation event ring
+ * (2026-08-13 Operator Chat long-run supervision). Server contract bounds:
+ * the model-facing `maxWaitMs` is clamped to [minWaitMs, maxWaitMsBound];
+ * defaults allow the 60–180s model supervision cadence and tests may inject
+ * short bounds.
+ */
+export const DEFAULT_OPERATION_WAIT_MIN_MS = 60_000;
+export const DEFAULT_OPERATION_WAIT_MAX_MS = 180_000;
+export class OperationWaitError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "OperationWaitError";
+    }
+}
+function isFocusedOperation(operation) {
+    return (isTerminalOperationState(operation.state) ||
+        operation.state === "needs-reconcile");
+}
+function settledSummary(input) {
+    const projectedEvents = input.newEvents.length > 0
+        ? input.newEvents.map(projectOperationEventSummary)
+        : [];
+    const nextSeq = input.newEvents.length > 0
+        ? input.newEvents[input.newEvents.length - 1].seq
+        : input.afterSeq;
+    return {
+        operationId: input.operationId,
+        state: input.operation.state,
+        changed: input.changed,
+        timedOut: input.timedOut,
+        events: projectedEvents,
+        nextSeq,
+        operation: projectOperationForChat(input.operation),
+    };
+}
+/**
+ * Deterministic read-only wait over the canonical operation event stream
+ * (AC-003 / AC-004). Completion paths:
+ *  - existing events (seq > afterSeq) → immediate (changed: true);
+ *  - operation terminal/needs-reconcile with unconsumed events → immediate summary (changed: true);
+ *  - operation terminal/needs-reconcile with no new events → immediate summary (changed: false);
+ *  - EVENT_CURSOR_EXPIRED when the cursor fell out of the retained ring;
+ *  - first subscribed event/state change → immediate settle;
+ *  - maxWaitMs elapsed with no change → timedOut: true summary (not a failure).
+ *
+ * Race safety: the listener is registered BEFORE listFrom, closing the
+ * listFrom/subscribe gap; every path settles exactly once through a guarded
+ * `finish`, and listener + timer are always cleaned up on settle.
+ */
+export async function waitForOperationChange(input) {
+    const operationId = input.operationId?.trim();
+    if (!operationId) {
+        throw new OperationWaitError("INVALID_INPUT", "operationId is required");
+    }
+    if (!Number.isInteger(input.afterSeq) || input.afterSeq < 0) {
+        throw new OperationWaitError("INVALID_INPUT", "afterSeq must be a non-negative integer");
+    }
+    const minWaitMs = input.minWaitMs ?? DEFAULT_OPERATION_WAIT_MIN_MS;
+    const maxWaitMsBound = input.maxWaitMsBound ?? DEFAULT_OPERATION_WAIT_MAX_MS;
+    if (!Number.isFinite(minWaitMs) ||
+        !Number.isFinite(maxWaitMsBound) ||
+        minWaitMs < 0 ||
+        maxWaitMsBound < minWaitMs) {
+        throw new OperationWaitError("INVALID_INPUT", "invalid wait bounds");
+    }
+    const rawMaxWaitMs = input.maxWaitMs ?? maxWaitMsBound;
+    if (!Number.isFinite(rawMaxWaitMs) || rawMaxWaitMs < 0) {
+        throw new OperationWaitError("INVALID_INPUT", "maxWaitMs must be a non-negative number");
+    }
+    const maxWaitMs = Math.max(minWaitMs, Math.min(maxWaitMsBound, Math.floor(rawMaxWaitMs)));
+    const afterSeq = input.afterSeq;
+    const operation = await input.operations.get(operationId);
+    if (!operation) {
+        throw new OperationWaitError("NOT_FOUND", `operation not found: ${operationId}`);
+    }
+    const events = input.events;
+    if (isFocusedOperation(operation)) {
+        // Flush unconsumed events before the terminal summary (AC-002): the
+        // caller's cursor must advance past every retained canonical event.
+        const listed = events.listFrom(operationId, afterSeq);
+        if ("error" in listed) {
+            throw new OperationWaitError("EVENT_CURSOR_EXPIRED", "event cursor expired; re-read operation snapshot");
+        }
+        if (listed.events.length > 0) {
+            return settledSummary({
+                operationId,
+                operation,
+                afterSeq,
+                changed: true,
+                timedOut: false,
+                newEvents: listed.events,
+            });
+        }
+        return settledSummary({
+            operationId,
+            operation,
+            afterSeq,
+            changed: false,
+            timedOut: false,
+            newEvents: [],
+        });
+    }
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        let timer;
+        let unsubscribe;
+        const cleanup = () => {
+            if (timer !== undefined) {
+                clearTimeout(timer);
+                timer = undefined;
+            }
+            if (unsubscribe) {
+                unsubscribe();
+                unsubscribe = undefined;
+            }
+        };
+        const finish = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            if (result instanceof OperationWaitError)
+                reject(result);
+            else
+                resolve(result);
+        };
+        const settleWithEvent = (event) => {
+            // Future-cursor guard (AC-003): events at or below the caller's
+            // afterSeq are already consumed and must not settle this wait.
+            if (event.seq <= afterSeq)
+                return;
+            // Listener path: async re-read of the operation for a fresh summary.
+            void (async () => {
+                try {
+                    const current = await input.operations.get(operationId);
+                    finish(settledSummary({
+                        operationId,
+                        operation: current ?? operation,
+                        afterSeq,
+                        changed: true,
+                        timedOut: false,
+                        newEvents: [event],
+                    }));
+                }
+                catch (error) {
+                    finish(error instanceof OperationWaitError
+                        ? error
+                        : new OperationWaitError("INVALID_INPUT", error instanceof Error ? error.message : String(error)));
+                }
+            })();
+        };
+        // Terminal recheck before subscribing: events landing during this await
+        // are still in the ring and are caught by listFrom below.
+        void (async () => {
+            try {
+                const current = await input.operations.get(operationId);
+                if (current && isFocusedOperation(current)) {
+                    // Same terminal flush as the initial path (AC-002): events
+                    // landing during the await are still in the retained ring.
+                    const listed = events.listFrom(operationId, afterSeq);
+                    if ("error" in listed) {
+                        finish(new OperationWaitError("EVENT_CURSOR_EXPIRED", "event cursor expired; re-read operation snapshot"));
+                        return;
+                    }
+                    if (listed.events.length > 0) {
+                        finish(settledSummary({
+                            operationId,
+                            operation: current,
+                            afterSeq,
+                            changed: true,
+                            timedOut: false,
+                            newEvents: listed.events,
+                        }));
+                        return;
+                    }
+                    finish(settledSummary({
+                        operationId,
+                        operation: current,
+                        afterSeq,
+                        changed: false,
+                        timedOut: false,
+                        newEvents: [],
+                    }));
+                    return;
+                }
+                // Subscribe BEFORE listFrom: any event appended after this point
+                // reaches the listener, closing the listFrom/subscribe race.
+                unsubscribe = events.subscribe(operationId, settleWithEvent);
+                const listed = events.listFrom(operationId, afterSeq);
+                if ("error" in listed) {
+                    finish(new OperationWaitError("EVENT_CURSOR_EXPIRED", "event cursor expired; re-read operation snapshot"));
+                    return;
+                }
+                if (listed.events.length > 0) {
+                    finish(settledSummary({
+                        operationId,
+                        operation: current ?? operation,
+                        afterSeq,
+                        changed: true,
+                        timedOut: false,
+                        newEvents: listed.events,
+                    }));
+                    return;
+                }
+                // No events: arm the bounded wait; the listener settles on the
+                // first new event/state change, the timer settles on timeout.
+                timer = setTimeout(() => {
+                    void (async () => {
+                        try {
+                            const latest = await input.operations.get(operationId);
+                            finish(settledSummary({
+                                operationId,
+                                operation: latest ?? operation,
+                                afterSeq,
+                                changed: false,
+                                timedOut: true,
+                                newEvents: [],
+                            }));
+                        }
+                        catch (error) {
+                            finish(error instanceof OperationWaitError
+                                ? error
+                                : new OperationWaitError("INVALID_INPUT", error instanceof Error ? error.message : String(error)));
+                        }
+                    })();
+                }, maxWaitMs);
+                timer.unref?.();
+            }
+            catch (error) {
+                finish(error instanceof OperationWaitError
+                    ? error
+                    : new OperationWaitError("INVALID_INPUT", error instanceof Error ? error.message : String(error)));
+            }
+        })();
+    });
+}

package/dist/worker/console/operator-actions.js

@@ -19,6 +19,7 @@ import { deriveTaskIdentityFromPrd, nextTaskIdRevision, } from "./prd-identity.j
 import { appendEngineeringCliArgs, buildDraftFromTaskIntake, parseEngineeringBoundaryFromParams, } from "./prd-intake-bridge.js";
 import { resolveSiblingAgentWorkerBin } from "./sibling-controller.js";
 import { projectOperationEventSummary, projectOperationForChat, } from "./chat/chat-event-store.js";
+import { OperationWaitError, waitForOperationChange, } from "./operation-wait.js";
 import { MutationGateReceiptStore } from "./mutation-gate-receipt-store.js";
 import { assessAutonomousExecutionEligibility, deriveEligibilityFactsFromDagSpec, } from "./dag-execution-receipt.js";
 import { issueHumanGateToken, mutationGatePayloadHash, verifyHumanGateToken, } from "./human-gate-token.js";
@@ -516,6 +517,63 @@ export async function dispatchOperatorAction(ctx, req) {
                 }),
             };
         }
+        case "operationWait": {
+            const operationId = str(p.operationId);
+            if (!operationId)
+                return invalid(action, "operationId is required");
+            const rawAfterSeq = p.afterSeq ?? 0;
+            const afterSeq = typeof rawAfterSeq === "number" ? rawAfterSeq : Number(rawAfterSeq);
+            const rawMaxWaitMs = p.maxWaitMs;
+            const maxWaitMs = typeof rawMaxWaitMs === "number"
+                ? rawMaxWaitMs
+                : rawMaxWaitMs === undefined
+                    ? undefined
+                    : Number(rawMaxWaitMs);
+            try {
+                const result = await waitForOperationChange({
+                    operations: ctx.operations,
+                    events: ctx.events,
+                    operationId,
+                    afterSeq,
+                    maxWaitMs,
+                });
+                return {
+                    kind: "sync",
+                    status: 200,
+                    body: operatorSucceeded(action, result),
+                };
+            }
+            catch (error) {
+                if (error instanceof OperationWaitError) {
+                    if (error.code === "NOT_FOUND") {
+                        return {
+                            kind: "error",
+                            status: 404,
+                            body: operatorFailed({
+                                command: action,
+                                outcome: "not-found",
+                                code: "NOT_FOUND",
+                                message: error.message,
+                            }),
+                        };
+                    }
+                    if (error.code === "EVENT_CURSOR_EXPIRED") {
+                        return {
+                            kind: "error",
+                            status: 410,
+                            body: operatorFailed({
+                                command: action,
+                                outcome: "blocked",
+                                code: "EVENT_CURSOR_EXPIRED",
+                                message: error.message,
+                            }),
+                        };
+                    }
+                    return invalid(action, error.message);
+                }
+                throw error;
+            }
+        }
         case "inspect": {
             const body = await runReadCli(ctx, ["inspect", "--json"], "inspect");
             return { kind: "sync", status: body.ok ? 200 : 400, body };