commandmate 0.47.2 → 0.48.0

package/dist/server/src/lib/session/waiting-episode-state.js

@@ -12,11 +12,23 @@
  *
  * So the edge is detected exactly once, here, by {@link observeWaitingEdge}, and
  * everything else either reads {@link getWaitingEpisode} or subscribes with
- * {@link onWaitingTransition}. There is one caller today —
- * `worktree-status-helper`, on the list API's per-instance probe — and it passes
- * the *composed* verdict (scraper OR structured), so a wait that only the
- * agent's own events can see opens an episode exactly like one the screen
- * scraper read.
+ * {@link onWaitingTransition}. The observers are `worktree-status-helper`, on
+ * the list API's per-instance probe — it passes the *composed* verdict (scraper
+ * OR structured), so a wait that only the agent's own events can see opens an
+ * episode exactly like one the screen scraper read — and `response-checker`
+ * (#1790), which opens the episode for a prompt it saved and closes it when it
+ * records a reply.
+ *
+ * Issue #3798 added the agent's own turn transitions as closers: a `stop` that
+ * ended the turn an episode belongs to closes it in the same synchronous step
+ * that records the stop (`waiting-episode-binding`), so a tool whose reply
+ * arrives on a hook closes its wait with no browser open. That needs each
+ * episode to carry an identity and the turn it belongs to; see "identity and
+ * attribution" below. The screen observers — the status probe, the response
+ * poller and now the Auto-Yes poller — go through the same module's
+ * observation tables (`observeWaiting`), which refuse a reading made against an
+ * episode that has moved since the observer started; {@link observeWaitingEdge}
+ * stays for the callers and suites written against #1786.
  *
  * ## Where #1788 / #1790 plug in
  *
@@ -40,6 +52,17 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.onWaitingTransition = onWaitingTransition;
+exports.onWaitingEpisodeTransition = onWaitingEpisodeTransition;
+exports.openEpisode = openEpisode;
+exports.closeEpisode = closeEpisode;
+exports.replaceEpisode = replaceEpisode;
+exports.rebindEpisode = rebindEpisode;
+exports.updateEpisodeKind = updateEpisodeKind;
+exports.getWaitingEpisodeRecord = getWaitingEpisodeRecord;
+exports.getEpisodeVersion = getEpisodeVersion;
+exports.snapshotEpisodeVersions = snapshotEpisodeVersions;
+exports.getLastClosedEpisode = getLastClosedEpisode;
+exports.registerEpisodeBindingResolver = registerEpisodeBindingResolver;
 exports.observeWaitingEdge = observeWaitingEdge;
 exports.getWaitingEpisode = getWaitingEpisode;
 exports.hasOpenWaitingEpisode = hasOpenWaitingEpisode;
@@ -53,6 +76,30 @@ const logger = (0, logger_1.createLogger)('waiting-episode-state');
 const episodes = (0, global_state_1.getOrInitGlobal)('__sessionWaitingEpisodes', () => new Map());
 /** Subscribers to the edge. See the module docblock. */
 const listeners = (0, global_state_1.getOrInitGlobal)('__sessionWaitingTransitionListeners', () => new Set());
+const metas = (0, global_state_1.getOrInitGlobal)('__sessionWaitingEpisodeMeta', () => new WeakMap());
+const versions = (0, global_state_1.getOrInitGlobal)('__sessionWaitingEpisodeVersions', () => new Map());
+const lastClosed = (0, global_state_1.getOrInitGlobal)('__sessionWaitingEpisodeLastClosed', () => new Map());
+const episodeSeq = (0, global_state_1.getOrInitGlobal)('__sessionWaitingEpisodeSeq', () => ({
+    value: 0,
+    nonce: Math.random().toString(36).slice(2, 10),
+}));
+const episodeListeners = (0, global_state_1.getOrInitGlobal)('__sessionWaitingEpisodeListeners', () => new Set());
+/** The binding used when no resolver is registered: nothing is known. */
+const UNKNOWN_BINDING = {
+    kind: 'unattributed',
+    generation: { kind: 'none' },
+    lastClosedTurnId: null,
+};
+function nextEpisodeId() {
+    episodeSeq.value += 1;
+    return `wep-${episodeSeq.nonce}-${episodeSeq.value}`;
+}
+function keyOf(parts) {
+    return (0, auto_yes_state_1.buildCompositeKey)(parts.worktreeId, parts.cliToolId, parts.instanceId);
+}
+function bumpVersion(key) {
+    versions.set(key, (versions.get(key) ?? 0) + 1);
+}
 /**
  * Subscribe to waiting edges.
  *
@@ -64,23 +111,257 @@ function onWaitingTransition(listener) {
         listeners.delete(listener);
     };
 }
+/**
+ * Subscribe to waiting edges with the episode's identity (Issue #3798).
+ *
+ * The same crossings `onWaitingTransition` delivers, in the same order, with
+ * the cause, the episode ids and the close reason added.
+ */
+function onWaitingEpisodeTransition(listener) {
+    episodeListeners.add(listener);
+    return () => {
+        episodeListeners.delete(listener);
+    };
+}
 /** Notify subscribers, containing anything they throw. */
 function emit(transition) {
+    const { cause: _cause, episodeId: _id, previousEpisodeId: _prev, closeReason: _reason, ...plain } = transition;
     for (const listener of listeners) {
+        try {
+            listener(plain);
+        }
+        catch (error) {
+            logListenerFailure(transition, error);
+        }
+    }
+    for (const listener of episodeListeners) {
         try {
             listener(transition);
         }
         catch (error) {
-            logger.error('waiting-transition-listener-failed', {
-                worktreeId: transition.worktreeId,
-                cliToolId: transition.cliToolId,
-                instanceId: transition.instanceId ?? transition.cliToolId,
-                waiting: transition.waiting,
-                error: error instanceof Error ? error.message : String(error),
-            });
+            logListenerFailure(transition, error);
         }
     }
 }
+function logListenerFailure(transition, error) {
+    logger.error('waiting-transition-listener-failed', {
+        worktreeId: transition.worktreeId,
+        cliToolId: transition.cliToolId,
+        instanceId: transition.instanceId ?? transition.cliToolId,
+        waiting: transition.waiting,
+        error: error instanceof Error ? error.message : String(error),
+    });
+}
+/**
+ * Open an episode (Issue #3798). Low-level: the caller has decided there is
+ * none open and what it is bound to. Emits the opening edge.
+ */
+function openEpisode(parts, next, at) {
+    const key = keyOf(parts);
+    const view = { since: next.since, kind: next.kind };
+    const meta = {
+        episodeId: nextEpisodeId(),
+        openedAt: at,
+        boundAt: at,
+        binding: next.binding,
+        openedBy: next.openedBy,
+        promptScreenKey: next.promptScreenKey ?? null,
+    };
+    episodes.set(key, view);
+    metas.set(view, meta);
+    bumpVersion(key);
+    emit({
+        worktreeId: parts.worktreeId,
+        cliToolId: parts.cliToolId,
+        instanceId: parts.instanceId,
+        waiting: true,
+        since: view.since,
+        kind: view.kind,
+        at,
+        cause: 'opened',
+        episodeId: meta.episodeId,
+        previousEpisodeId: null,
+        closeReason: null,
+    });
+    return { ...view, ...meta };
+}
+/**
+ * Close the open episode when it is still `expectedId` (Issue #3798). A closer
+ * that names the episode it decided about cannot close a later one.
+ *
+ * @returns Whether an episode was closed
+ */
+function closeEpisode(parts, expectedId, reason, at) {
+    const key = keyOf(parts);
+    const view = episodes.get(key);
+    if (view === undefined)
+        return false;
+    const meta = metaOf(view);
+    if (meta.episodeId !== expectedId)
+        return false;
+    episodes.delete(key);
+    lastClosed.set(key, { at, promptScreenKey: meta.promptScreenKey });
+    bumpVersion(key);
+    emit({
+        worktreeId: parts.worktreeId,
+        cliToolId: parts.cliToolId,
+        instanceId: parts.instanceId,
+        waiting: false,
+        since: null,
+        kind: null,
+        at,
+        cause: 'closed',
+        episodeId: null,
+        previousEpisodeId: meta.episodeId,
+        closeReason: reason,
+    });
+    return true;
+}
+/**
+ * Put a new episode in place of `expectedId` as one operation (Issue #3798):
+ * listeners hear a single opening edge for the new wait and no closing one
+ * in between, so nothing reports "nobody is waiting" mid-swap.
+ *
+ * @returns The new episode, or null when `expectedId` is no longer open
+ */
+function replaceEpisode(parts, expectedId, next, reason, at) {
+    const key = keyOf(parts);
+    const old = episodes.get(key);
+    if (old === undefined)
+        return null;
+    const oldMeta = metaOf(old);
+    if (oldMeta.episodeId !== expectedId)
+        return null;
+    lastClosed.set(key, { at, promptScreenKey: oldMeta.promptScreenKey });
+    const view = { since: next.since, kind: next.kind };
+    const meta = {
+        episodeId: nextEpisodeId(),
+        openedAt: at,
+        boundAt: at,
+        binding: next.binding,
+        openedBy: next.openedBy,
+        promptScreenKey: next.promptScreenKey ?? null,
+    };
+    episodes.set(key, view);
+    metas.set(view, meta);
+    bumpVersion(key);
+    emit({
+        worktreeId: parts.worktreeId,
+        cliToolId: parts.cliToolId,
+        instanceId: parts.instanceId,
+        waiting: true,
+        since: view.since,
+        kind: view.kind,
+        at,
+        cause: 'replaced',
+        episodeId: meta.episodeId,
+        previousEpisodeId: oldMeta.episodeId,
+        closeReason: reason,
+    });
+    return { ...view, ...meta };
+}
+/**
+ * Change what the open episode `expectedId` is bound to (Issue #3798). Not an
+ * edge: the wait goes on, so nothing is emitted and `since` stays.
+ *
+ * @returns Whether the episode was rebound
+ */
+function rebindEpisode(parts, expectedId, binding, at) {
+    const key = keyOf(parts);
+    const view = episodes.get(key);
+    if (view === undefined)
+        return false;
+    const meta = metaOf(view);
+    if (meta.episodeId !== expectedId)
+        return false;
+    meta.binding = binding;
+    meta.boundAt = at;
+    bumpVersion(key);
+    return true;
+}
+/**
+ * Refresh the kind of the open episode `expectedId` (Issue #3798, I10). The
+ * wait goes on: no edge, and the version does not move.
+ *
+ * @returns Whether the episode was still open
+ */
+function updateEpisodeKind(parts, expectedId, kind) {
+    const view = episodes.get(keyOf(parts));
+    if (view === undefined || metaOf(view).episodeId !== expectedId)
+        return false;
+    view.kind = kind;
+    return true;
+}
+/**
+ * The meta of an episode in the map. An episode put there without one (a test
+ * that wrote the map directly) is given an unattributed identity on first read.
+ */
+function metaOf(view) {
+    let meta = metas.get(view);
+    if (meta === undefined) {
+        meta = {
+            episodeId: nextEpisodeId(),
+            openedAt: view.since,
+            boundAt: view.since,
+            binding: UNKNOWN_BINDING,
+            openedBy: 'legacy-edge',
+            promptScreenKey: null,
+        };
+        metas.set(view, meta);
+    }
+    return meta;
+}
+/** The open episode with its identity and binding, or null (Issue #3798). */
+function getWaitingEpisodeRecord(worktreeId, cliToolId, instanceId) {
+    const view = episodes.get((0, auto_yes_state_1.buildCompositeKey)(worktreeId, cliToolId, instanceId));
+    if (view === undefined)
+        return null;
+    const meta = metaOf(view);
+    return { since: view.since, kind: view.kind, ...meta, binding: meta.binding };
+}
+/** The instance's episode version: it moves on every open, close, replacement and rebind. */
+function getEpisodeVersion(worktreeId, cliToolId, instanceId) {
+    return versions.get((0, auto_yes_state_1.buildCompositeKey)(worktreeId, cliToolId, instanceId)) ?? 0;
+}
+/**
+ * Every instance version of one worktree, as of now (Issue #3798): the status
+ * probe fixes them before it lists the tmux sessions. An instance missing from
+ * the map is at version 0.
+ */
+function snapshotEpisodeVersions(worktreeId) {
+    const prefix = `${worktreeId}${auto_yes_state_1.COMPOSITE_KEY_SEPARATOR}`;
+    const snapshot = new Map();
+    for (const [key, version] of versions) {
+        if (key.startsWith(prefix))
+            snapshot.set(key, version);
+    }
+    return snapshot;
+}
+/** The last episode that ended for this instance, or null. */
+function getLastClosedEpisode(worktreeId, cliToolId, instanceId) {
+    return lastClosed.get((0, auto_yes_state_1.buildCompositeKey)(worktreeId, cliToolId, instanceId)) ?? null;
+}
+/** Install the binding resolver `observeWaitingEdge` uses. The last one wins. */
+function registerEpisodeBindingResolver(resolver) {
+    globalThis.__sessionWaitingEpisodeBindingResolver = resolver;
+}
+function resolveBinding(parts, at) {
+    const resolver = globalThis.__sessionWaitingEpisodeBindingResolver;
+    if (resolver === undefined)
+        return UNKNOWN_BINDING;
+    try {
+        return resolver(parts, at);
+    }
+    catch (error) {
+        logger.warn('waiting-episode-binding-resolve-failed', {
+            worktreeId: parts.worktreeId,
+            cliToolId: parts.cliToolId,
+            instanceId: parts.instanceId ?? parts.cliToolId,
+            error: error instanceof Error ? error.message : String(error),
+        });
+        return UNKNOWN_BINDING;
+    }
+}
 /**
  * Record this poll's waiting verdict and answer when the current wait began.
  *
@@ -89,16 +370,23 @@ function emit(transition) {
  * `since` and emit nothing, so a listener hears one event per wait rather than
  * one per poll.
  *
+ * Issue #3798: an episode opened here is bound by the registered resolver
+ * (`waiting-episode-binding`), so the turn transitions can end it. The
+ * production observers no longer call it: they go through
+ * `waiting-episode-binding`'s `observeWaiting`, which also checks that the
+ * episode has not moved since they started and that the frame does not
+ * predate the close of what it shows.
+ *
  * @returns The episode's `since` while waiting, or null when it is not.
  */
 function observeWaitingEdge({ worktreeId, cliToolId, instanceId, waiting, kind = null, structuredSince = null, now = Date.now(), }) {
-    const key = (0, auto_yes_state_1.buildCompositeKey)(worktreeId, cliToolId, instanceId);
+    const parts = { worktreeId, cliToolId, instanceId };
+    const key = keyOf(parts);
     const existing = episodes.get(key);
     if (!waiting) {
         if (existing === undefined)
             return null;
-        episodes.delete(key);
-        emit({ worktreeId, cliToolId, instanceId, waiting: false, since: null, kind: null, at: now });
+        closeEpisode(parts, metaOf(existing).episodeId, 'screen-cleared', now);
         return null;
     }
     if (existing !== undefined) {
@@ -109,8 +397,7 @@ function observeWaitingEdge({ worktreeId, cliToolId, instanceId, waiting, kind =
         return existing.since;
     }
     const since = structuredSince ?? now;
-    episodes.set(key, { since, kind });
-    emit({ worktreeId, cliToolId, instanceId, waiting: true, since, kind, at: now });
+    openEpisode(parts, { since, kind, binding: resolveBinding(parts, now), openedBy: 'legacy-edge' }, now);
     return since;
 }
 /**
@@ -152,8 +439,11 @@ function hasOpenWaitingEpisode(worktreeId) {
  */
 function clearWaitingEpisodes() {
     episodes.clear();
+    versions.clear();
+    lastClosed.clear();
 }
 /** Drop every subscriber. Test seam, paired with {@link clearWaitingEpisodes}. */
 function clearWaitingTransitionListeners() {
     listeners.clear();
+    episodeListeners.clear();
 }

package/dist/server/src/lib/session/waiting-episode-verdict.js

@@ -0,0 +1,174 @@
+"use strict";
+/**
+ * The T table (Issue #3798, design §2.4): what one turn transition's outcome
+ * does to the open waiting episode. Pure — it reads the outcome, the episode's
+ * binding and the current generation, and writes nothing. Applying the verdict
+ * is `waiting-episode-binding`'s job (Issue #3864 split it out of there).
+ *
+ * Design: `docs/design/issue-3798-waiting-episode.md`.
+ *
+ * @module lib/session/waiting-episode-verdict
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sameGeneration = sameGeneration;
+exports.verdictForOutcome = verdictForOutcome;
+function sameGeneration(a, b) {
+    if (a.kind === 'none' || b.kind === 'none')
+        return a.kind === b.kind;
+    return a.at === b.at;
+}
+const NONE = { action: 'none' };
+const close = (reason) => ({ action: 'close', reason });
+/** The previous record's turn id, for the D and F columns. Null for `none`. */
+function previousTurnId(previous) {
+    return previous.kind === 'none' ? null : previous.turnId;
+}
+/** T1–T5: a turn opened. */
+function verdictForOpened(outcome, binding) {
+    const { previous, turnId: n, event } = outcome;
+    const asTurnN = { kind: 'turn', generation: outcome.generation, turnId: n };
+    if (binding.kind === 'screen')
+        return NONE;
+    if (binding.kind === 'turn' && binding.turnId === n)
+        return { action: 'unmatched' }; // ※1
+    const p = previousTurnId(previous);
+    const tookOverRecord = previous.kind === 'dialog-only' || previous.kind === 'display-only';
+    // D: the record this turn took over (R3-4). Only T2 / T3 / T4 have one (※5).
+    const isD = binding.kind === 'dialog-only' && binding.recordTurnId === p;
+    // T5 (R1-9): a turn replaced while it was open ends every wait but a screen's.
+    if (previous.kind === 'open-same-session' || previous.kind === 'open-other-session') {
+        return isD ? { action: 'unmatched' } : close('turn-superseded');
+    }
+    // T4 (R2-4): a prompt ends them too; the turn model drops every decision here.
+    if (event === 'user_prompt_submit')
+        return close('turn-superseded');
+    if (binding.kind === 'turn')
+        return close('turn-superseded');
+    if (binding.kind === 'dialog-only') {
+        if (!isD)
+            return close('turn-superseded');
+        return tookOverRecord ? { action: 'rebind', binding: asTurnN } : { action: 'unmatched' }; // T1: ※5
+    }
+    // unattributed — F: nothing opened between the wait and this turn (R2-4).
+    return binding.lastClosedTurnId === p ? { action: 'rebind', binding: asTurnN } : close('turn-superseded');
+}
+/** T9–T11: a stop with no turn open. */
+function verdictForStopWithoutTurn(outcome, binding) {
+    const { previous } = outcome;
+    const p = previousTurnId(previous);
+    switch (previous.kind) {
+        case 'closed':
+            // T9: B (R1-2) and F (R2-1).
+            if (binding.kind === 'turn' && binding.turnId === p)
+                return close('turn-stop');
+            if (binding.kind === 'unattributed' && binding.lastClosedTurnId === p)
+                return close('turn-stop');
+            if (binding.kind === 'dialog-only' && binding.recordTurnId === p)
+                return { action: 'unmatched' }; // ※5
+            return NONE;
+        case 'dialog-only':
+            // T10: D, F and G.
+            if (binding.kind === 'dialog-only' && binding.recordTurnId === p)
+                return close('turn-stop');
+            if (binding.kind === 'unattributed')
+                return close('turn-stop');
+            return NONE;
+        case 'display-only':
+        case 'none':
+            // T11: D (R3-4) and F.
+            if (binding.kind === 'dialog-only' && binding.recordTurnId === p)
+                return close('turn-stop');
+            if (binding.kind === 'unattributed' && binding.lastClosedTurnId === p)
+                return close('turn-stop');
+            return NONE;
+        default:
+            // An open turn is `stopped` / `stop-rejected`, never this outcome.
+            return { action: 'unmatched' };
+    }
+}
+/** T19 / T20 and the rest of the generation fence. */
+function verdictForGenerationFenced(outcome, binding) {
+    // T19 / T20 (R2-8): a session start in the same process keeps a screen.
+    if (outcome.source === 'session-start' && binding.kind === 'screen') {
+        return sameGeneration(binding.generation, outcome.generation)
+            ? NONE
+            : { action: 'rebind', binding: { ...binding, generation: outcome.generation } };
+    }
+    return sameGeneration(binding.generation, outcome.generation) ? NONE : close('generation');
+}
+/** T7. */
+function verdictForRestored(outcome, binding) {
+    // T7: a wait opened under the discarded turn belongs to the one put back.
+    return binding.kind === 'turn' && binding.turnId === outcome.discardedTurnId
+        ? { action: 'rebind', binding: { ...binding, turnId: outcome.restoredTurnId } }
+        : NONE;
+}
+/** T8. */
+function verdictForStopped(outcome, binding) {
+    // T8.
+    return binding.kind === 'turn' && binding.turnId === outcome.turnId ? close('turn-stop') : NONE;
+}
+/** T13. */
+function verdictForSessionEnded(outcome, binding) {
+    // T13.
+    return binding.kind === 'turn' && binding.turnId === outcome.turnId ? close('turn-session-end') : NONE;
+}
+/** T15 / T16. */
+function verdictForDecisionOpened(outcome, binding, current) {
+    // T15 / T16 (R3-6): a dialog the hook reported for a wait the screen showed first.
+    return outcome.recordKind === 'dialog-only' && binding.kind === 'unattributed'
+        ? {
+            action: 'rebind',
+            binding: { kind: 'dialog-only', generation: current, recordTurnId: outcome.recordTurnId, sessionId: null },
+        }
+        : NONE;
+}
+/** T17 / T18. */
+function verdictForDecisionAnswered(outcome, binding) {
+    // T17 / T18 (R3-3): an explicit answer that left nothing pending.
+    if (outcome.before === 0 || outcome.remaining > 0)
+        return NONE;
+    const bound = (binding.kind === 'turn' && binding.turnId === outcome.recordTurnId) ||
+        (binding.kind === 'dialog-only' && binding.recordTurnId === outcome.recordTurnId);
+    return bound ? close('decision-settled') : NONE;
+}
+/** Rows that close a binding of another generation (the I column). */
+const CLOSES_OTHER_GENERATION = new Set([
+    'opened',
+    'stopped',
+    'stop-without-turn',
+    'session-ended',
+]);
+/** The T table (design §2.4): one outcome on the open episode. */
+function verdictForOutcome(outcome, binding, current) {
+    if (outcome.kind === 'generation-fenced')
+        return verdictForGenerationFenced(outcome, binding);
+    if (!sameGeneration(binding.generation, current)) {
+        return CLOSES_OTHER_GENERATION.has(outcome.kind) ? close('generation') : NONE;
+    }
+    switch (outcome.kind) {
+        case 'opened':
+            return verdictForOpened(outcome, binding);
+        case 'restored':
+            return verdictForRestored(outcome, binding);
+        case 'stopped':
+            return verdictForStopped(outcome, binding);
+        case 'stop-without-turn':
+            return verdictForStopWithoutTurn(outcome, binding);
+        case 'session-ended':
+            return verdictForSessionEnded(outcome, binding);
+        case 'decision-opened':
+            return verdictForDecisionOpened(outcome, binding, current);
+        case 'decision-answered':
+            return verdictForDecisionAnswered(outcome, binding);
+        case 'continued':
+        case 'stop-rejected':
+        case 'session-end-rejected':
+        case 'none':
+            // T6, T12, T14, T21.
+            return NONE;
+        default:
+            outcome;
+            return NONE;
+    }
+}