maka-agent 0.2.1-dev.91.20261018 → 0.2.2-dev.97.20261024

package/node_modules/@maka/runtime-host/dist/server/goal-coordinator.js

@@ -16,6 +16,7 @@
  * specific language governing permissions and limitations
  * under the License.
  */
+import { HostGoalEventWaitBridge } from './goal-event-waits.js';
 import { randomUUID } from 'node:crypto';
 import { sameGoalControlLease, } from '@maka/core/goal';
 import { GoalContinuationCoordinator, } from '@maka/runtime/goal-continuation';
@@ -24,6 +25,8 @@ import { buildGoalTools } from '@maka/runtime/goal-tools';
 import { isSessionNotFoundError } from '@maka/storage/execution-stores';
 import { authenticateInteractiveGoalAuthorityWriter, } from '@maka/storage/goal-authority';
 import { projectGoalState } from './goal-projection.js';
+import { GOAL_EVENT_WAIT_SUMMARY_LIMITS, } from '../protocol/goal.js';
+import { truncateUtf8 } from '@maka/core/diagnostic-log';
 import { waitForHostedExecutionTerminal } from './hosted-execution-wait.js';
 import { goalTurnOutcomeFromHostedExecution } from './goal-execution-coordinator.js';
 import { buildGoalEvaluationContext } from './goal-evaluation-context.js';
@@ -33,6 +36,7 @@ export class HostGoalCoordinator {
         'goal.query': (input) => this.#query(input.sessionId),
         'goal.arm': (input) => this.#arm(input),
         'goal.control': (input) => this.#control(input),
+        'goal.event-wait.cancel': (input) => this.#cancelEventWait(input),
     };
     manager;
     continuation;
@@ -50,7 +54,7 @@ export class HostGoalCoordinator {
     /**
      * Token count per Session as of the last continuation read, which is what a
      * settling Turn reports so the Goal can measure its budget. It is not a
-     * baseline for a new Goal: only an evaluation writes here, so a Session that
+     * baseline for a new Goal: only evaluation context reads refresh it. A Session that
      * has never run one has no entry, and `tokensBaselinePending` on the Goal is
      * what carries that until the first Turn carrying it settles.
      */
@@ -60,6 +64,10 @@ export class HostGoalCoordinator {
     #queuedAuthorityCommits = new Map();
     #persistenceLane = Promise.resolve();
     #persistenceFailure;
+    eventWaitBridge;
+    #jointLane = Promise.resolve();
+    #jointBusy = false;
+    #deferredGoalChanges = [];
     #prepared = false;
     #draining = false;
     constructor(options) {
@@ -84,6 +92,28 @@ export class HostGoalCoordinator {
         const tokenCache = this.#tokenCache;
         this.continuation = new GoalContinuationCoordinator({
             goalManager: this.manager,
+            eventWait: {
+                isGated: (sessionId) => !!this.#authorityBySession.get(sessionId)?.record.activeEventWait,
+                ownsSource: (sessionId, turnId, controlLease) => {
+                    const record = this.#authorityBySession.get(sessionId)?.record;
+                    const gate = record?.activeEventWait;
+                    return (record?.goal.status === 'active' &&
+                        !!gate &&
+                        !gate.settled &&
+                        gate.sourceExecution.sessionId === sessionId &&
+                        gate.sourceExecution.turnId === turnId &&
+                        sameGoalControlLease(gate.controlLease, controlLease) &&
+                        sameGoalControlLease(record.controlLease, controlLease));
+                },
+                settleCompleted: async (sessionId, turnId, controlLease) => {
+                    if (!this.eventWaitBridge)
+                        throw new Error('Event wait persistence is unavailable');
+                    await this.eventWaitBridge.settleCompleted(sessionId, turnId, controlLease);
+                },
+            },
+            mutateGoal: (operation) => this.#mutateGoal(() => operation({
+                recordPendingContinuation: (pending) => this.#recordPendingContinuation(pending, () => this.#flushGoalPersistence()),
+            })),
             acquireActivity: () => this.#acquireResidency(),
             evaluator: options.evaluator,
             getRecentContext: async (sessionId) => {
@@ -104,13 +134,63 @@ export class HostGoalCoordinator {
                 settleCurrentExecution: (sessionId, turnId) => this.#settleCurrentExecution(sessionId, turnId),
             },
         });
-        this.tools = Object.freeze(buildGoalTools({
-            goalManager: this.manager,
-            goalContinuation: this.continuation,
-            isAvailable: () => !this.#draining,
-            flush: (sessionId) => this.#flushGoalState(sessionId),
-            now,
-        }));
+        if (options.stores.eventWaitStore && options.stores.runtimeEventStore) {
+            this.eventWaitBridge = new HostGoalEventWaitBridge({
+                stores: {
+                    eventWaitStore: options.stores.eventWaitStore,
+                    runtimeEventStore: options.stores.runtimeEventStore,
+                    agentRunStore: options.stores.agentRunStore,
+                },
+                authority: (sessionId) => this.#authorityBySession.get(sessionId),
+                changed: this.#onProjectionChanged,
+                mutate: (sessionId, operation) => this.#mutateWait(sessionId, operation),
+                settleAdditional: (sessionId, tokensNow, controlLease) => this.#mutateGoal(async () => {
+                    const goal = this.manager.get(sessionId);
+                    if (goal?.status === 'active' &&
+                        this.manager.matchesControlLease(sessionId, controlLease))
+                        this.manager.settleTurn(sessionId, {
+                            checkpoint: { goalId: goal.id, revision: goal.revision },
+                            verdict: 'continue',
+                            tokensNow,
+                            reason: goal.lastReason ?? 'Explicit event wait remains outstanding.',
+                        });
+                }),
+                getTokens: async (sessionId, throughTurnId) => {
+                    const { messages } = await options.readSessionContext(sessionId);
+                    return tokenCount(messages, throughTurnId);
+                },
+                gate: (sessionId) => this.continuation.gateEventWait(sessionId),
+                canRegister: (sessionId, turnId) => this.continuation.mutationStanding(sessionId, turnId).kind === 'held',
+                deliver: (pending) => this.continuation.recoverPendingContinuation(pending),
+                pause: (sessionId, reason, controlLease, waitId) => this.#mutateGoal(async () => {
+                    if (!this.manager.matchesControlLease(sessionId, controlLease) ||
+                        this.#authorityBySession.get(sessionId)?.record.activeEventWait?.waitId !== waitId)
+                        return;
+                    this.manager.pause(sessionId, { reason });
+                    this.continuation.invalidateSession(sessionId);
+                }),
+                onError: (error) => {
+                    this.#persistenceFailure ??= error;
+                    this.#requestDrain();
+                },
+                now,
+                newId: this.#newId,
+            }, options.eventWaitSources);
+        }
+        this.tools = Object.freeze([
+            ...buildGoalTools({
+                goalManager: this.manager,
+                goalContinuation: this.continuation,
+                isAvailable: () => !this.#draining,
+                // These tool implementations execute inside the same lane as joint writes.
+                flush: () => this.#flushGoalPersistence(),
+                now,
+            }).map((tool) => ({
+                ...tool,
+                impl: (input, context) => this.#mutateGoal(() => tool.impl(input, context)),
+            })),
+            ...(this.eventWaitBridge?.tools ?? []),
+        ]);
     }
     async prepareRecovery() {
         if (this.#prepared)
@@ -167,10 +247,128 @@ export class HostGoalCoordinator {
                 this.continuation.recoverActiveGoal(snapshot.record.goal.sessionId);
             }
         }
+        await this.eventWaitBridge?.start();
     }
     readProjection(sessionId) {
+        // Canonical/query callers hold the Session lane. Do not wait for the
+        // mutation lane here: a committed wait write can have a delayed receipt
+        // while Root admission must still publish and start. #project rechecks the
+        // adopted binding after I/O and excludes durably admitted/suppressed waits.
+        return this.#project(sessionId);
+    }
+    async #project(sessionId) {
+        const authority = this.#authorityBySession.get(sessionId);
+        const gate = authority?.record.activeEventWait;
+        const wait = gate && this.#stores.eventWaitStore
+            ? await this.#stores.eventWaitStore.read({ sessionId, waitId: gate.waitId })
+            : undefined;
         const goal = this.manager.get(sessionId);
-        return goal ? projectGoalState(goal) : null;
+        if (!goal)
+            return null;
+        const projection = projectGoalState(goal);
+        const current = this.#authorityBySession.get(sessionId);
+        if (!wait ||
+            !gate ||
+            !current ||
+            current.record.activeEventWait?.waitId !== gate.waitId ||
+            !sameGoalControlLease(current.record.controlLease, wait.record.goalControlLease) ||
+            !this.manager.matchesControlLease(sessionId, wait.record.goalControlLease) ||
+            wait.record.delivery ||
+            wait.record.status === 'cancelled' ||
+            !['active', 'waiting'].includes(goal.status))
+            return projection;
+        const r = wait.record, observation = r.observation;
+        // Checking is an attempt reservation, not a new source fact. Its retained
+        // checkpoint describes the last completed observation until this read settles.
+        const observationOutcome = observation?.outcome === 'checking' && observation.lastObservedAt !== null
+            ? observation.consecutiveErrors > 0
+                ? 'unknown'
+                : 'pending'
+            : observation?.outcome;
+        return {
+            ...projection,
+            eventWait: {
+                waitId: r.waitId,
+                controlGeneration: r.goalControlLease.generation,
+                waitRevision: wait.authorityRevision,
+                resource: {
+                    providerId: r.resource.providerId,
+                    resourceType: r.resource.resourceType,
+                    resourceId: truncateUtf8(r.resource.resourceId, GOAL_EVENT_WAIT_SUMMARY_LIMITS.resourceIdBytes, '…'),
+                },
+                reason: gate.reason,
+                deadlineAt: r.deadlineAt,
+                phase: r.status === 'waiting' ? 'observing' : 'awaiting_admission',
+                observation: r.status !== 'waiting'
+                    ? null
+                    : {
+                        state: observationOutcome === 'unknown'
+                            ? 'unknown'
+                            : observationOutcome === 'pending'
+                                ? 'pending'
+                                : 'checking',
+                        lastObservedAt: observation?.lastObservedAt ?? null,
+                        reasonCode: observation?.reason
+                            ? truncateUtf8(observation.reason, GOAL_EVENT_WAIT_SUMMARY_LIMITS.reasonCodeBytes, '…')
+                            : null,
+                    },
+                outcome: r.status === 'resolved'
+                    ? r.resolution.outcome
+                    : r.status === 'expired'
+                        ? 'expired'
+                        : null,
+            },
+        };
+    }
+    #cancelEventWait(input) {
+        return this.#sessionAdmission.run(input.sessionId, () => this.#mutateGoal(async () => {
+            if (this.#draining)
+                return hostDraining();
+            let header;
+            try {
+                header = await this.#stores.sessionStore.readHeaderSnapshot(input.sessionId);
+            }
+            catch (error) {
+                if (isSessionNotFoundError(error))
+                    return notFound('Session does not exist');
+                throw error;
+            }
+            if (header.isArchived)
+                return sessionArchived('Archived Session cannot cancel a wait');
+            const wait = await this.#stores.eventWaitStore?.read({
+                sessionId: input.sessionId,
+                waitId: input.waitId,
+            });
+            const current = this.#authorityBySession.get(input.sessionId)?.record;
+            let outcome = 'conflict';
+            if (wait?.record.goalControlLease.goalId === input.goalId &&
+                wait.record.goalControlLease.generation === input.controlGeneration) {
+                if (wait.record.delivery?.kind === 'admitted')
+                    outcome = 'already_admitted';
+                else if (wait.record.status === 'cancelled' ||
+                    wait.record.delivery?.kind === 'suppressed')
+                    outcome = 'already_cancelled';
+                else if (current?.activeEventWait?.waitId === input.waitId &&
+                    current.goal.id === input.goalId &&
+                    current.controlLease.generation === input.controlGeneration &&
+                    current.goal.revision === input.expectedGoalRevision) {
+                    this.manager.pause(input.sessionId, {
+                        reason: 'Event wait cancelled. The background task keeps running.',
+                    });
+                    this.continuation.invalidateSession(input.sessionId);
+                    await this.#flushGoalPersistence();
+                    outcome = 'cancelled';
+                }
+            }
+            return {
+                ok: true,
+                result: {
+                    sessionId: input.sessionId,
+                    outcome,
+                    goal: await this.#project(input.sessionId),
+                },
+            };
+        }));
     }
     beginObservedTurn(sessionId, turnId) {
         return this.continuation.beginObservedTurn(sessionId, turnId);
@@ -284,6 +482,7 @@ export class HostGoalCoordinator {
             return;
         this.#draining = true;
         this.#recoveryAbort.abort();
+        this.eventWaitBridge?.beginDrain();
         this.continuation.dispose();
         this.manager.dispose();
         this.#tokenCache.clear();
@@ -295,6 +494,8 @@ export class HostGoalCoordinator {
         this.beginDrain();
         return Promise.all([
             this.continuation.close(),
+            this.eventWaitBridge?.close(),
+            this.#jointLane,
             this.#flushGoalState(),
             ...this.#recoveryWaits,
         ]).then(() => undefined);
@@ -312,7 +513,7 @@ export class HostGoalCoordinator {
             }
             return {
                 ok: true,
-                result: { sessionId, goal: this.readProjection(sessionId) },
+                result: { sessionId, goal: await this.readProjection(sessionId) },
             };
         });
     }
@@ -330,7 +531,7 @@ export class HostGoalCoordinator {
      * after it is the first the Goal drives.
      */
     #arm(input) {
-        return this.#sessionAdmission.run(input.sessionId, async () => {
+        return this.#sessionAdmission.run(input.sessionId, () => this.#mutateGoal(async () => {
             // Admission is a queue, and the composition begins to drain without
             // waiting for it to empty. An arm let through before that can still be
             // waiting behind another operation when the Goal manager is disposed,
@@ -358,15 +559,14 @@ export class HostGoalCoordinator {
             if (created.kind === 'unfinished') {
                 return operationConflict(`Session already has an unfinished Goal in status ${created.goal.status}`);
             }
-            await this.#flushGoalState(input.sessionId);
             return {
                 ok: true,
                 result: { sessionId: input.sessionId, goal: projectGoalState(created.goal) },
             };
-        });
+        }));
     }
     #control(input) {
-        return this.#sessionAdmission.run(input.sessionId, async () => {
+        return this.#sessionAdmission.run(input.sessionId, () => this.#mutateGoal(async () => {
             let header;
             try {
                 header = await this.#stores.sessionStore.readHeaderSnapshot(input.sessionId);
@@ -405,28 +605,43 @@ export class HostGoalCoordinator {
             if (!changed) {
                 return operationConflict(`Goal cannot ${input.action} from status ${current.status}`);
             }
-            await this.#flushGoalState(input.sessionId);
             return {
                 ok: true,
                 result: { sessionId: input.sessionId, goal: projectGoalState(changed) },
             };
-        });
+        }));
     }
     #enqueueGoalState(goal, controlLease) {
+        if (this.#jointBusy) {
+            this.#deferredGoalChanges.push([goal, controlLease]);
+            return;
+        }
         const current = this.#authorityBySession.get(goal.sessionId);
         this.#enqueueAuthorityCommit(goal.sessionId, {
             schemaVersion: 1,
             goal,
             controlLease,
+            ...(current?.record.activeEventWait &&
+                sameGoalControlLease(current.record.controlLease, controlLease) &&
+                ['active', 'waiting'].includes(goal.status)
+                ? { activeEventWait: current.record.activeEventWait }
+                : {}),
             currentExecution: current?.record.goal.id === goal.id && goal.revision >= current.record.goal.revision
                 ? current.record.currentExecution
                 : null,
-            pendingContinuation: current?.record.goal.id === goal.id && goal.revision === current.record.goal.revision
-                ? current.record.pendingContinuation
+            pendingContinuation: current?.record.goal.id === goal.id &&
+                sameGoalControlLease(current.record.controlLease, controlLease) &&
+                ['active', 'waiting'].includes(goal.status) &&
+                current.record.pendingContinuation &&
+                (goal.revision === current.record.goal.revision || current.record.activeEventWait)
+                ? {
+                    ...current.record.pendingContinuation,
+                    checkpoint: { goalId: goal.id, revision: goal.revision },
+                }
                 : null,
         });
     }
-    async #recordPendingContinuation(pending) {
+    async #recordPendingContinuation(pending, flush = () => this.#flushGoalState()) {
         const sessionId = this.manager.getSessionIdByGoalId(pending.checkpoint.goalId);
         const authority = sessionId ? this.#authorityBySession.get(sessionId) : undefined;
         if (!authority ||
@@ -440,34 +655,36 @@ export class HostGoalCoordinator {
             currentExecution: null,
             pendingContinuation: pending,
         });
-        await this.#flushGoalState(sessionId);
+        await flush();
     }
-    async #clearPendingContinuation(sessionId, controlLease) {
-        const authority = this.#authorityBySession.get(sessionId);
-        if (!authority ||
-            !sameGoalControlLease(authority.record.controlLease, controlLease) ||
-            !authority.record.pendingContinuation) {
-            return;
-        }
-        this.#enqueueAuthorityCommit(sessionId, {
-            ...authority.record,
-            pendingContinuation: null,
+    #clearPendingContinuation(sessionId, controlLease) {
+        return this.#mutateGoal(() => {
+            const authority = this.#authorityBySession.get(sessionId);
+            if (!authority ||
+                !sameGoalControlLease(authority.record.controlLease, controlLease) ||
+                !authority.record.pendingContinuation) {
+                return;
+            }
+            this.#enqueueAuthorityCommit(sessionId, {
+                ...authority.record,
+                pendingContinuation: null,
+            });
         });
-        await this.#flushGoalState(sessionId);
     }
-    async #recordCurrentExecution(current) {
-        const authority = this.#authorityBySession.get(current.execution.sessionId);
-        if (!authority ||
-            authority.record.goal.id !== current.checkpoint.goalId ||
-            !sameGoalControlLease(authority.record.controlLease, current.controlLease)) {
-            throw new Error('Goal execution no longer matches its durable authority');
-        }
-        this.#enqueueAuthorityCommit(current.execution.sessionId, {
-            ...authority.record,
-            currentExecution: current,
-            pendingContinuation: null,
+    #recordCurrentExecution(current) {
+        return this.#mutateGoal(() => {
+            const authority = this.#authorityBySession.get(current.execution.sessionId);
+            if (!authority ||
+                authority.record.goal.id !== current.checkpoint.goalId ||
+                !sameGoalControlLease(authority.record.controlLease, current.controlLease)) {
+                throw new Error('Goal execution no longer matches its durable authority');
+            }
+            this.#enqueueAuthorityCommit(current.execution.sessionId, {
+                ...authority.record,
+                currentExecution: current,
+                pendingContinuation: null,
+            });
         });
-        await this.#flushGoalState(current.execution.sessionId);
     }
     async #recoverCurrentExecution(current) {
         const durableAdmission = await this.#stores.agentRunStore.readRootTurnAdmission(current.execution.sessionId, current.execution.turnId);
@@ -504,15 +721,18 @@ export class HostGoalCoordinator {
             .finally(() => this.#recoveryWaits.delete(tracked));
         this.#recoveryWaits.add(tracked);
     }
-    async #settleCurrentExecution(sessionId, turnId) {
-        const authority = this.#authorityBySession.get(sessionId);
-        if (!authority || authority.record.currentExecution?.execution.turnId !== turnId)
-            return;
-        this.#enqueueAuthorityCommit(sessionId, {
-            ...authority.record,
-            currentExecution: null,
+    #settleCurrentExecution(sessionId, turnId) {
+        return this.#mutateGoal(() => {
+            // A revoked registration can finish while a new wait commit is awaiting acknowledgement.
+            // Read the adopted authority inside the lane before clearing this Turn's ownership.
+            const authority = this.#authorityBySession.get(sessionId);
+            if (!authority || authority.record.currentExecution?.execution.turnId !== turnId)
+                return;
+            this.#enqueueAuthorityCommit(sessionId, {
+                ...authority.record,
+                currentExecution: null,
+            });
         });
-        await this.#flushGoalState(sessionId);
     }
     #enqueueAuthorityCommit(sessionId, record) {
         const current = this.#authorityBySession.get(sessionId);
@@ -595,6 +815,56 @@ export class HostGoalCoordinator {
         })
             .finally(() => residency.release());
     }
+    #mutateGoal(operation) {
+        const task = this.#jointLane.then(async () => {
+            await this.#flushGoalPersistence();
+            const result = await operation();
+            await this.#flushGoalPersistence();
+            return result;
+        });
+        this.#jointLane = task.catch(() => undefined);
+        return task;
+    }
+    #mutateWait(sessionId, operation) {
+        const task = this.#jointLane.then(async () => {
+            this.#jointBusy = true;
+            try {
+                // This task owns the joint lane; only prior ordinary writes can be awaited here.
+                await this.#flushGoalPersistence();
+                const result = await operation();
+                this.#adoptWaitAuthority(result.goal);
+                return result;
+            }
+            finally {
+                this.#jointBusy = false;
+                for (const [goal, lease] of this.#deferredGoalChanges.splice(0))
+                    this.#enqueueGoalState(goal, lease);
+            }
+        });
+        this.#jointLane = task.catch(() => undefined);
+        return task;
+    }
+    #adoptWaitAuthority(snapshot) {
+        const current = this.#authorityBySession.get(snapshot.record.goal.sessionId);
+        // Root admission may commit while an idempotent queue operation is returning.
+        if (current && current.authorityRevision > snapshot.authorityRevision)
+            return;
+        this.#authorityBySession.set(snapshot.record.goal.sessionId, snapshot);
+        // A control operation may have changed the live manager while I/O was pending.
+        if (!this.#deferredGoalChanges.some(([g]) => g.sessionId === snapshot.record.goal.sessionId)) {
+            this.manager.adoptAuthority(snapshot.record.goal, snapshot.record.controlLease);
+            this.#syncResidency(snapshot.record.goal, this.#acquireResidency);
+        }
+        this.#onProjectionChanged(snapshot.record.goal.sessionId);
+    }
+    async admitted(input) {
+        if (input.descriptor.kind !== 'goal' || !input.descriptor.eventWait)
+            return;
+        const snapshot = await this.#store.read(input.sessionId);
+        if (!snapshot)
+            throw new Error('Admitted event wait lost Goal authority');
+        this.#adoptWaitAuthority(snapshot);
+    }
     async #deleteOrphanedAuthority(snapshot) {
         const result = await this.#store.commit({
             sessionId: snapshot.record.goal.sessionId,
@@ -606,6 +876,12 @@ export class HostGoalCoordinator {
         }
     }
     async #flushGoalState(_sessionId) {
+        // A control change made during a joint operation is enqueued in its finally block.
+        // Acknowledge it only after that operation and the resulting ordinary write finish.
+        await this.#jointLane;
+        await this.#flushGoalPersistence();
+    }
+    async #flushGoalPersistence() {
         await this.#persistenceLane;
         if (this.#persistenceFailure !== undefined)
             throw this.#persistenceFailure;
@@ -621,8 +897,22 @@ export class HostGoalCoordinator {
         this.#residencies.delete(goal.sessionId);
     }
 }
-function tokenCount(messages) {
-    return messages.reduce((total, message) => {
+function tokenCount(messages, throughTurnId) {
+    // Root admission can release the Session before Goal settlement reads its facts.
+    // Keep later user Turns out of this Turn's baseline, including when the wait
+    // source spans multiple physical Runs through handoff.
+    let end = messages.length;
+    if (throughTurnId !== undefined) {
+        while (end > 0) {
+            const message = messages[end - 1];
+            if ('turnId' in message && message.turnId === throughTurnId)
+                break;
+            end--;
+        }
+    }
+    if (throughTurnId !== undefined && end === 0)
+        throw new Error('Completed Goal Turn is missing from token accounting facts');
+    return messages.slice(0, end).reduce((total, message) => {
         if (message.type !== 'token_usage')
             return total;
         return total + (message.total ?? message.input + message.output);