@wowyuarm/dsh-agent-team 0.1.8 → 0.1.10

package/packages/agent-team/lib/context-management.js

@@ -0,0 +1,382 @@
+/**
+ * Context-management coordinator: the one deep module that turns a Member's
+ * successful `context_rollover` tool result into its next private context
+ * generation.
+ *
+ * Authority split (see docs/architecture.md):
+ * - the Team ledger owns the Member→Session binding and rollover audit;
+ * - the Session log projection owns intent, checkpoints, and delivery state;
+ * - this coordinator owns only process locks and is always reconstructible.
+ *
+ * The coordinator reacts exclusively after the successful `tool/result` is
+ * durably appended — never inside a tool body — so a render/finalize failure
+ * can never outrun result durability. The actual swap waits for the
+ * containing turn to end and the Agent to be idle, captures later input so no
+ * old-generation model request opens, and then reuses the Member lifecycle:
+ * commit rollover operation → dispose old Agent → archive old Session →
+ * create/activate the new generation → deliver the handoff first.
+ * @module @wowyuarm/dsh-agent-team/context-management
+ */
+import { SessionId as SessionIdBrand } from '@deepseek-ai/dsh-session';
+import { createHash } from 'node:crypto';
+import { AGENT_TEAM_PLUGIN_ID, createCheckpointContinuationMessage, createHandoffMessage, isAgentTeamContextSource } from "./context-source.js";
+import { CONTEXT_CHECKPOINT_TOOL_NAME, CONTEXT_ROLLOVER_TOOL_NAME, continuationDelivered, foldContextProjection, } from "./context-projection.js";
+/** Stable summary of the one-shot rollover pressure notice (ticket 03 wires delivery). */
+export const CONTEXT_PRESSURE_NOTICE_SUMMARY = 'Context pressure: prepare a handoff';
+export class ContextManagementCoordinator {
+    options;
+    members = new Map();
+    capturedInput = new Map();
+    /** Per-member latch for the in-process scheduling→delivery window. */
+    scheduledContinuations = new Set();
+    disposed = false;
+    constructor(options) {
+        this.options = options;
+    }
+    /** Whether one Member has a pending or in-flight rollover; tools use this to reject. */
+    isTransitioning(memberId) {
+        return this.members.has(memberId);
+    }
+    /**
+     * Root `session/event` observer for Member Sessions. The store's dispatch
+     * carrier is untagged, so the Host maps session ids to Members and calls
+     * this for every Member event. All reactions are gated on the projection
+     * state, which itself only records successful durable pairs.
+     */
+    onSessionEvent(memberId, agent, event) {
+        if (this.disposed)
+            return;
+        if (event.type === 'tool/result') {
+            this.onToolResult(memberId, agent, event);
+            return;
+        }
+        if (event.type === 'user/message') {
+            this.onUserMessage(memberId, agent, event);
+            return;
+        }
+        if (event.type === 'turn/end') {
+            this.onTurnEnd(memberId, agent);
+        }
+    }
+    /** Build the first handoff message of one generation; the lifecycle delivers it. */
+    handoffMessageFor(plan) {
+        return createHandoffMessage({
+            handoff: plan.handoff,
+            previousSessionId: plan.previousSessionId,
+            newSessionId: plan.newSessionId,
+            trigger: plan.trigger,
+            handoffEventSeq: plan.handoffEventSeq,
+            ...(plan.checkpointRef === undefined ? {} : { checkpointRef: plan.checkpointRef }),
+            ...(plan.relatedFiles.length === 0 ? {} : { relatedFiles: plan.relatedFiles }),
+        });
+    }
+    /**
+     * Whether one Agent's pending transition requires the admission gate: a
+     * pending rollover must stop old-generation turns from admitting queued
+     * input. The gate arms only for the old-generation Agent instance — the
+     * new generation activates mid-swap and must be free to consume the
+     * handoff and carried input immediately.
+     */
+    needsAdmissionGate(agent) {
+        const memberId = this.options.memberForAgent(agent)?.memberId;
+        if (memberId === undefined)
+            return false;
+        return this.members.get(memberId)?.agent === agent;
+    }
+    /**
+     * Capture the inbox messages queued for an old generation at its turn-stop
+     * boundary: non-Team input is preserved verbatim for delivery after the
+     * handoff; stale Team notices are dropped because the new generation
+     * rederives the Inbox from ledger facts. Removing them from the inbox lets
+     * the turn close cleanly instead of admitting another old-generation step.
+     */
+    captureQueuedInput(agent) {
+        const memberId = this.options.memberForAgent(agent)?.memberId;
+        if (memberId === undefined)
+            return [];
+        if (this.members.get(memberId)?.agent !== agent)
+            return [];
+        const removed = [...agent.inbox.nextStep, ...agent.inbox.nextTurn];
+        for (const message of removed)
+            agent.inbox.remove(message.id);
+        return this.captureInput(agent, removed);
+    }
+    /**
+     * Capture messages a racing pre-step already claimed from the inbox before
+     * rejecting that old-generation step. A rejected step's claimed message is
+     * otherwise neither discarded nor re-emitted, so the gate preserves it here.
+     */
+    captureClaimedInput(agent, messages) {
+        return this.captureInput(agent, messages);
+    }
+    captureInput(agent, messages) {
+        const memberId = this.options.memberForAgent(agent)?.memberId;
+        if (memberId === undefined)
+            return [];
+        if (this.members.get(memberId)?.agent !== agent)
+            return [];
+        const preserved = [];
+        for (const message of messages) {
+            if (this.isTeamNotice(message))
+                continue;
+            preserved.push(message);
+        }
+        if (preserved.length > 0)
+            this.capturedInput.set(memberId, [...(this.capturedInput.get(memberId) ?? []), ...preserved]);
+        return preserved;
+    }
+    /** Drain the captured input of one Member for delivery after the handoff. */
+    drainCapturedInput(memberId) {
+        const captured = this.capturedInput.get(memberId) ?? [];
+        this.capturedInput.delete(memberId);
+        return captured;
+    }
+    /**
+     * Whether one queued message is a Team-owned notice the rederived Inbox
+     * replaces. Handoff and continuation envelopes carry the same plugin
+     * attribution but are ordinary delivered context the new generation keeps, so
+     * they are excluded rather than dropped.
+     */
+    isTeamNotice(message) {
+        const source = message.source;
+        return source.kind === 'plugin' && source.plugin === AGENT_TEAM_PLUGIN_ID && !isAgentTeamContextSource(message);
+    }
+    /** Drop one Member's bookkeeping; the Host calls this on dispose/removal. */
+    stopTracking(memberId) {
+        this.members.delete(memberId);
+        this.capturedInput.delete(memberId);
+    }
+    dispose() {
+        this.disposed = true;
+        this.members.clear();
+        this.capturedInput.clear();
+    }
+    onToolResult(memberId, agent, event) {
+        if (event.data.error !== undefined)
+            return;
+        const member = this.options.memberForAgent(agent);
+        if (member === undefined)
+            return;
+        const state = this.options.projectionForMember(memberId, member.sessionId);
+        if (state?.pending === null || state === undefined)
+            return;
+        const pending = state.pending;
+        // React only to the intent's own result landing durably, and only once.
+        if (pending.resultSeq !== event.seq)
+            return;
+        if (this.members.has(memberId))
+            return;
+        this.members.set(memberId, {
+            agent,
+            intent: {
+                toolCallId: pending.toolCallId,
+                resultSeq: pending.resultSeq,
+                turn: pending.turn,
+                handoff: pending.handoff,
+                ...(pending.checkpointRef === undefined ? {} : { checkpointRef: pending.checkpointRef }),
+                relatedFiles: pending.relatedFiles,
+            },
+            turnEnded: false,
+        });
+    }
+    onUserMessage(memberId, _agent, event) {
+        // Quiet-continuation delivery bookkeeping is projection-owned; the
+        // coordinator only repairs a crash gap after restart, which the Host
+        // performs through repairContinuations during activation.
+        void memberId;
+        void event;
+    }
+    onTurnEnd(memberId, agent) {
+        // Checkpoint continuations first: a turn that resolved checkpoints owes
+        // each of them exactly one quiet next-turn follow-up. The projection's
+        // continuations state deduplicates across restarts; this in-memory latch
+        // closes the same-process window between scheduling and the delivery
+        // event landing in the log.
+        this.scheduleCheckpointContinuations(memberId, agent);
+        const transition = this.members.get(memberId);
+        if (transition === undefined || transition.turnEnded)
+            return;
+        const member = this.options.memberForAgent(agent);
+        if (member === undefined || transition.agent !== agent)
+            return;
+        transition.turnEnded = true;
+        // Wait for true idle (the turn-end event fires before the driver fully
+        // converges), then perform the swap off the session-event dispatch path.
+        void agent.whenIdle().then(() => {
+            if (this.disposed)
+                return;
+            const current = this.members.get(memberId);
+            if (current === undefined || current !== transition)
+                return;
+            if (this.options.agentForMember(memberId) !== agent)
+                return;
+            void this.performTransition(memberId, member, transition);
+        }, error => {
+            this.options.log(`context rollover idle wait failed: ${error instanceof Error ? error.message : String(error)} (member ${memberId})`);
+            this.members.delete(memberId);
+        });
+    }
+    /**
+     * Quiet follow-ups for checkpoints resolved by the turn that just ended.
+     * A successful `context_checkpoint` result concludes its turn; the Host
+     * continues work in the next turn with one host-generated notice. The
+     * projection folds delivery (the continuation user/message event), so a
+     * restart repairs a missing follow-up through repairContinuations without
+     * duplicating a delivered one; this live path latches per checkpoint in
+     * memory for the scheduling window.
+     */
+    scheduleCheckpointContinuations(memberId, agent) {
+        const member = this.options.memberForAgent(agent);
+        if (member === undefined)
+            return;
+        const state = this.options.projectionForMember(memberId, member.sessionId);
+        if (state === undefined)
+            return;
+        for (const checkpoint of state.checkpoints) {
+            if (checkpoint.turnEndSeq === -1)
+                continue;
+            if (continuationDelivered(state, checkpoint.checkpointRef))
+                continue;
+            const latch = `${memberId}:${checkpoint.checkpointRef}`;
+            if (this.scheduledContinuations.has(latch))
+                continue;
+            this.scheduledContinuations.add(latch);
+            // The turn/end observer fires inside the session append publication
+            // (a synchronous followup would reenter the publishing append), and a
+            // next-turn message queued while the driver is still converging never
+            // latches a wake — the loop replays only maintenance/abort latches. So
+            // the continuation waits for true idle, then queues its own turn: the
+            // same discipline the rollover path uses.
+            void agent.whenIdle().then(() => {
+                if (this.disposed)
+                    return;
+                try {
+                    agent.followup(createCheckpointContinuationMessage(checkpoint.checkpointRef));
+                }
+                catch (error) {
+                    this.scheduledContinuations.delete(latch);
+                    this.options.log(`context continuation scheduling failed: ${error instanceof Error ? error.message : String(error)} (member ${memberId})`);
+                }
+            }, () => {
+                this.scheduledContinuations.delete(latch);
+            });
+        }
+    }
+    async performTransition(memberId, member, transition) {
+        // Stable rollover identity derives from the previous Session and the
+        // successful tool call: a result seq is session-local and would collide
+        // across generations. Both inputs are unconstrained strings (provider
+        // call ids carry arbitrary lengths and characters; Session ids are
+        // caller-branded), so the pair is JSON-encoded — no delimiter can alias
+        // across the two fields — and hashed to a fixed-length url-safe hex
+        // digest instead of being embedded verbatim: the derived Session id and
+        // request id stay bounded and collision-resistant.
+        const stableKey = createHash('sha256').update(JSON.stringify([member.sessionId, transition.intent.toolCallId])).digest('hex');
+        const newSessionId = SessionIdBrand(`agent-team-rollover-${stableKey}`);
+        const plan = {
+            previousSessionId: member.sessionId,
+            newSessionId,
+            handoff: transition.intent.handoff,
+            handoffEventSeq: transition.intent.resultSeq,
+            trigger: 'model',
+            relatedFiles: transition.intent.relatedFiles,
+            ...(transition.intent.checkpointRef === undefined ? {} : { checkpointRef: transition.intent.checkpointRef }),
+            requestId: `agent-team:rollover:${stableKey}`,
+            carriedInput: this.drainCapturedInput(memberId),
+        };
+        const swap = this.options.executeTransition(memberId, plan);
+        transition.swapping = swap;
+        try {
+            await swap;
+            this.members.delete(memberId);
+        }
+        catch (error) {
+            this.options.log(`context rollover failed, leaving the previous generation recoverable: ${error instanceof Error ? error.message : String(error)} (member ${memberId})`);
+            this.members.delete(memberId);
+        }
+    }
+    /**
+     * Crash-recovery hook the Host runs during Member activation: re-derive
+     * pending intent from the projection and finish a transition that a restart
+     * interrupted after the successful result was durable.
+     */
+    recoverPendingTransition(memberId, agent, sessionId) {
+        if (this.disposed || this.members.has(memberId))
+            return;
+        const state = this.options.projectionForMember(memberId, sessionId);
+        if (state?.pending === null || state === undefined)
+            return;
+        const pending = state.pending;
+        if (pending.turnEndSeq === -1) {
+            // The containing turn never ended durably; treat the intent as still
+            // waiting and observe the live events from here.
+            this.members.set(memberId, {
+                agent,
+                intent: {
+                    toolCallId: pending.toolCallId,
+                    resultSeq: pending.resultSeq,
+                    turn: pending.turn,
+                    handoff: pending.handoff,
+                    ...(pending.checkpointRef === undefined ? {} : { checkpointRef: pending.checkpointRef }),
+                    relatedFiles: pending.relatedFiles,
+                },
+                turnEnded: false,
+            });
+            return;
+        }
+        // The turn already ended before the crash; the Agent is idle at
+        // activation, so the swap can proceed directly.
+        const member = this.options.memberForAgent(agent);
+        if (member === undefined)
+            return;
+        const transition = {
+            agent,
+            intent: {
+                toolCallId: pending.toolCallId,
+                resultSeq: pending.resultSeq,
+                turn: pending.turn,
+                handoff: pending.handoff,
+                ...(pending.checkpointRef === undefined ? {} : { checkpointRef: pending.checkpointRef }),
+                relatedFiles: pending.relatedFiles,
+            },
+            turnEnded: true,
+        };
+        this.members.set(memberId, transition);
+        void this.performTransition(memberId, member, transition);
+    }
+    /**
+     * Crash-recovery for quiet continuations: schedule the follow-up for one
+     * resolved checkpoint exactly once when the result was durable but the
+     * delivery never landed. The projection's continuations state is the
+     * durable delivery record — a checkpoint whose delivery event exists in the
+     * log is never re-scheduled.
+     */
+    repairContinuations(agent, state) {
+        if (this.disposed)
+            return;
+        const memberId = this.options.memberForAgent(agent)?.memberId;
+        if (memberId === undefined)
+            return;
+        for (const checkpoint of state.checkpoints) {
+            if (checkpoint.turnEndSeq === -1)
+                continue;
+            if (continuationDelivered(state, checkpoint.checkpointRef))
+                continue;
+            const latch = `${memberId}:${checkpoint.checkpointRef}`;
+            if (this.scheduledContinuations.has(latch))
+                continue;
+            this.scheduledContinuations.add(latch);
+            try {
+                agent.followup(createCheckpointContinuationMessage(checkpoint.checkpointRef));
+            }
+            catch (error) {
+                this.scheduledContinuations.delete(latch);
+                this.options.log(`context continuation repair failed: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+    }
+}
+/** Tool names this module owns; the preset validation requires all of them. */
+export const CONTEXT_TOOL_NAMES = Object.freeze([CONTEXT_CHECKPOINT_TOOL_NAME, CONTEXT_ROLLOVER_TOOL_NAME, 'context_timeline']);
+/** Re-exported for Host wiring: cold-fold helper for archived ancestors. */
+export { foldContextProjection };