@songsid/agend 2.2.0-alpha.9 → 2.2.0-beta.2

package/dist/daemon.js

@@ -1,3 +1,4 @@
+import { AGENT_WHATS_NEW, agendVersion, planWhatsNew, readWhatsNewRecord, recordWhatsNew, whatsNewNotice } from "./agent-whats-new.js";
 import { join, dirname, basename, resolve } from "node:path";
 import { mkdirSync, writeFileSync, readFileSync, readdirSync, existsSync, unlinkSync, rmSync, appendFileSync, statSync, renameSync } from "node:fs";
 import { fileURLToPath } from "node:url";
@@ -77,6 +78,12 @@ const REPLY_GUARD_IDLE_CONFIRM_MS = 60_000;
  * down like a turn the transcript cannot place — never a recovery.
  */
 const TRANSCRIPT_RUNNING_HOLD_MAX_MS = 30 * 60_000;
+/**
+ * #1641: an open turn in the CLI's transcript holds the instance busy (no paste, whatever the pane shows) only while the
+ * transcript is still moving: a turn whose end was missed must not pin the instance busy forever. A live turn writes
+ * often; a long silent tool run shows its own busy row on the pane.
+ */
+export const TRANSCRIPT_OPEN_TURN_QUIET_MS = 15 * 60_000;
 const REPLY_RECOVERY_PROMPT = "[system:reply-required] The previous human-facing turn ended without a successfully delivered reply. Do not redo the work. React with an emoji or use the reply tool exactly once now to send the user a concise conclusion. If no substantive answer is needed, a brief react is sufficient. If you already replied to this message, do nothing. Do not reply to this system instruction except through the react or reply tool.";
 /** Point a resumed CLI at its one backend-native instruction source. */
 /** The outbox evidence for a delivery the CLI's transcript shows taken (#758; #1201 absorbed). */
@@ -1237,6 +1244,11 @@ export class Daemon extends EventEmitter {
     turnReplyGuard = new TurnReplyGuard();
     /** #1510: turn boundaries from the CLI's transcript, for a backend whose guard reads its turn end there. */
     transcriptTurns = new TranscriptTurnLedger();
+    /** #1641: when this launch's transcript monitor last read anything (a turn boundary, a tool, assistant text); performance.now(). */
+    transcriptActivityAt = 0;
+    /** #1641: the launch and composer a stuck pane's idle evidence is about, and since when (performance.now()); see recoverStuck. */
+    stuckRecoveryKey = null;
+    stuckRecoverySince = 0;
     /** #1510: since when (monotonic) this generation has been held as running in the transcript. */
     transcriptRunningSince = null;
     /** Prevent a visible stale XML fragment from being recovered on later turns. */
@@ -1388,6 +1400,8 @@ export class Daemon extends EventEmitter {
     recentPastes = [];
     pendingInstructionsUpdate;
     pendingInstructionsNotice = false;
+    /** #1633: the one-time "what's new for you" notice, pasted before the next real delivery; recorded once pasted. */
+    pendingWhatsNew = null;
     // Whether the warmup steering-reload notice should be injected after spawn.
     // Set in trySpawn by comparing the freshly-built instructions against the
     // last value the agent was told about (prev-instructions). Skipped when
@@ -5041,9 +5055,68 @@ export class Daemon extends EventEmitter {
     buildTranscriptMonitor(source) {
         const monitor = new TranscriptMonitor(this.instanceDir, this.logger, source);
         this.transcriptTurns.reset();
-        monitor.on("turns", (turns) => this.transcriptTurns.observe(turns));
+        this.transcriptActivityAt = 0;
+        // Monotonic: a wall-clock correction must neither end nor extend the open-turn hold (#1641 R1).
+        const touch = () => { this.transcriptActivityAt = performance.now(); };
+        monitor.on("turns", (turns) => { this.transcriptTurns.observe(turns, performance.now()); touch(); });
+        // #1641 R2: a re-baselined source starts over, and so does what it said (an open turn read before is withdrawn).
+        monitor.on("reset", () => { if (this.transcriptMonitor === monitor) {
+            this.transcriptTurns.reset();
+            this.transcriptActivityAt = 0;
+        } });
+        for (const event of ["tool_use", "tool_result", "assistant_text"])
+            monitor.on(event, touch);
         return monitor;
     }
+    /**
+     * #1641: what the CLI's own transcript (codex's rollout) says about its turn. `open`: a turn started and has not ended,
+     * and the transcript moved within TRANSCRIPT_OPEN_TURN_QUIET_MS. `closed`: every turn read since this launch's monitor
+     * began has ended. `unknown`: not a transcript backend, nothing followed, or an open turn gone quiet (a missed end).
+     */
+    transcriptTurnState(now = performance.now()) {
+        if (this.backend?.turnEndFromTranscript !== true || this.transcriptMonitor?.following() !== true)
+            return "unknown";
+        // #1641 R2: an empty ledger after a baseline that could not see the current turn's start is not "closed".
+        if (this.transcriptMonitor.turnStateKnown?.() !== true)
+            return "unknown";
+        const since = this.transcriptTurns.openSince();
+        if (since === null)
+            return "closed";
+        return now - Math.max(since, this.transcriptActivityAt) < TRANSCRIPT_OPEN_TURN_QUIET_MS ? "open" : "unknown";
+    }
+    /**
+     * #1641: a stuck pane that is in fact an idle CLI (a footer this build cannot read) must not stay stuck for hours with
+     * every delivery parked behind it. It recovers when the backend sees its own live, EMPTY composer with no busy, queued
+     * or dialog marker (isStableUnknownLayoutIdlePane) AND the transcript shows no open turn — or, with no transcript to
+     * ask, that same composer held unchanged for UNKNOWN_LAYOUT_STABLE_MS (#978's rule). An open turn never recovers.
+     */
+    recoverStuck(pane, snapshot, changeAt, turn) {
+        const machine = this.instanceStateMachine;
+        const idleComposer = this.backend?.isStableUnknownLayoutIdlePane?.(pane) === true;
+        // The resume load (#1031: `Resuming session…` over the same composer) is input that is not open yet (#1641 R1).
+        if (!machine || !idleComposer || turn === "open" || this.inputTransientInPane(pane)) {
+            this.stuckRecoveryKey = null;
+            return snapshot;
+        }
+        // The evidence is about this launch and this screen. Once it holds, it keeps holding — a still pane reads stuck
+        // again at the next sweep (its footer is still unreadable) and must not start the window over (#1641 R1).
+        const mono = performance.now();
+        const key = `${this.spawnGeneration}:${this.launchAttempt}\n${pane.replace(/⋆/gu, "").replace(/[ \t]+$/gmu, "")}`;
+        if (key !== this.stuckRecoveryKey) {
+            this.stuckRecoveryKey = key;
+            this.stuckRecoverySince = mono;
+        }
+        if (turn === "unknown" && mono - this.stuckRecoverySince < UNKNOWN_LAYOUT_STABLE_MS)
+            return snapshot;
+        // A footer this build cannot read stays unreadable: the same still pane reads stuck again at every sweep and is
+        // recovered again. Only the edge into idle is news.
+        const fields = { evidence: turn === "closed" ? "transcript_no_open_turn" : "stable_empty_composer", unchangedForMs: snapshot.unchangedForMs };
+        if (this.instanceState !== "idle")
+            this.logger.info(fields, "Stuck instance recovered — the CLI shows its idle composer and is not running a turn (#1641)");
+        else
+            this.logger.debug(fields, "Still idle on its unreadable footer — the stuck reading was recovered again (#1641)");
+        return machine.observe(pane, Date.now(), { settled: true, changeAt, forceReady: true });
+    }
     replyCompletionGuardEnabled() {
         return this.config.reply_completion_guard !== false
             && this.backend?.replyCompletionGuard === true;
@@ -5425,7 +5498,9 @@ export class Daemon extends EventEmitter {
                     // a pair every ~1.6s for as long as the repaint lasted (#1116). Real
                     // work cannot hide behind this: it changes the layout, the next
                     // output arms another probe, and the debounce capture still fires.
-                    if (this.instanceState === "idle" && this.backend?.isPeriodicRedrawIdlePane?.(pane) === true)
+                    // #1641: never while the transcript shows a turn running — that idle-looking screen is mid-turn.
+                    if (this.instanceState === "idle" && this.backend?.isPeriodicRedrawIdlePane?.(pane) === true
+                        && this.transcriptTurnState() !== "open")
                         return;
                     // A second burst overtook the probe. Do not bless its stale capture as
                     // idle: continuous output is the safer working signal, while the next
@@ -5458,6 +5533,10 @@ export class Daemon extends EventEmitter {
             // decisions about *now*. The old double-observe expressed that by calling
             // observe twice, which silently disabled the "content moved" branch.
             const structuredPeriodicIdle = this.backend?.isPeriodicRedrawIdlePane;
+            // #1641: the transcript outranks the pane: while it shows the turn running, no reading of this pane is idle (codex
+            // hides its status row while streaming, leaving the idle composer and footer in view mid-turn).
+            const transcriptTurn = this.transcriptTurnState();
+            const transcriptBusy = transcriptTurn === "open";
             let snapshot;
             if (deliveryFallback !== null) {
                 // A missing footer cannot fall through to a broad ready match. All
@@ -5466,7 +5545,7 @@ export class Daemon extends EventEmitter {
                     settled: true,
                     changeAt: observedChangeAt,
                     forceReady: deliveryFallback,
-                    forceBusy: !deliveryFallback || paneActivity !== null,
+                    forceBusy: !deliveryFallback || paneActivity !== null || transcriptBusy,
                 });
             }
             else if (structuredPeriodicIdle && reason === "output_probe") {
@@ -5488,6 +5567,7 @@ export class Daemon extends EventEmitter {
                         snapshot = this.instanceStateMachine.observe(pane, Date.now(), {
                             settled: true,
                             changeAt: observedChangeAt,
+                            forceBusy: transcriptBusy,
                         });
                     }
                 }
@@ -5521,6 +5601,7 @@ export class Daemon extends EventEmitter {
                             settled: true,
                             changeAt: observedChangeAt,
                             forceReady: true,
+                            forceBusy: transcriptBusy,
                         });
                     }
                     else {
@@ -5569,6 +5650,7 @@ export class Daemon extends EventEmitter {
                     snapshot = this.instanceStateMachine.observe(pane, Date.now(), {
                         settled: true,
                         changeAt: observedChangeAt,
+                        forceBusy: transcriptBusy,
                     });
                 }
                 else {
@@ -5586,9 +5668,11 @@ export class Daemon extends EventEmitter {
                 snapshot = this.instanceStateMachine.observe(pane, Date.now(), {
                     settled,
                     changeAt: observedChangeAt,
-                    forceBusy: paneActivity !== null,
+                    forceBusy: paneActivity !== null || transcriptBusy,
                 });
             }
+            if (snapshot.state === "stuck")
+                snapshot = this.recoverStuck(pane, snapshot, observedChangeAt, transcriptTurn);
             this.applyInstanceStateSnapshot(snapshot, pane);
             // Backends without a transcript feed can still say what they are doing, if
             // their TUI names it. Free-riding on a capture that already happened: no
@@ -6011,12 +6095,14 @@ export class Daemon extends EventEmitter {
      * here — a steered message must read EXACTLY like a queued one to the
      * agent, or the two drift apart in what the agent is told about replying.
      */
+    /** #1650: how this instance talks to the fleet — MCP tools, or agend-agent commands (agent_mode: cli). */
+    agentMode() { return this.config.agent_mode === "cli" ? "cli" : "mcp"; }
     formatInboundMessage(content, meta) {
         const user = meta.user || "unknown";
         const fromInstance = meta.from_instance;
         let formatted;
         if (fromInstance) {
-            formatted = formatCrossInstanceInboundMessage(content, meta);
+            formatted = formatCrossInstanceInboundMessage(content, meta, this.agentMode());
         }
         else {
             const via = meta.source ? ` via ${meta.source}` : "";
@@ -6029,7 +6115,10 @@ export class Daemon extends EventEmitter {
                 formatted = `[Recent reactions: ${meta.pending_reactions}]\n${formatted}`;
             }
             formatted += renderHandoffMetadata(meta);
-            formatted += "\n(Reply using the reply tool — do NOT respond with direct text)";
+            // #1650: a CLI-mode agent has no reply tool — it answers with the agend-agent command.
+            formatted += this.agentMode() === "cli"
+                ? '\n(Reply with agend-agent reply "…" — do NOT respond with direct text)'
+                : "\n(Reply using the reply tool — do NOT respond with direct text)";
         }
         if (meta.reply_to_text) {
             formatted += `\n(reply_to: "${meta.reply_to_text}")`;
@@ -6291,6 +6380,23 @@ export class Daemon extends EventEmitter {
                     if (!this.isDeliveryEpochCurrent(deliveryEpoch))
                         return;
                 }
+                const whatsNew = this.pendingWhatsNew ? this.currentWhatsNew(this.pendingWhatsNew) : null;
+                if (whatsNew) {
+                    // #1633: here, inside the delivery lock and ahead of a real delivery — never into a busy turn, never to an
+                    // instance nobody writes to. Recorded only once pasted: a failed or cancelled paste stays pending.
+                    const pasted = await this.deliverMessage(whatsNew.notice, undefined, { deliveryEpoch });
+                    if (pasted && this.pendingWhatsNew === whatsNew) {
+                        this.pendingWhatsNew = null;
+                        try {
+                            recordWhatsNew(this.instanceDir, whatsNew.ids, whatsNew.version);
+                        }
+                        catch (err) {
+                            this.logger.warn({ err }, "what's-new record not written — the notice may repeat once");
+                        }
+                    }
+                    if (!this.isDeliveryEpochCurrent(deliveryEpoch))
+                        return;
+                }
                 const status = channelStatus(meta);
                 // A fresh delivery begins a fresh turn — its bubble must not inherit
                 // the previous turn's tool list.
@@ -10426,6 +10532,49 @@ export class Daemon extends EventEmitter {
         }
         catch { /* non-fatal */ }
     }
+    /**
+     * #1633 (#1639 review): the pending notice as the record stands NOW, just before the paste — it was decided at launch,
+     * and the record may have changed while the delivery waited. Unreadable → nothing is sent (and nothing pending);
+     * entries recorded meanwhile are dropped from it; none left → nothing.
+     */
+    currentWhatsNew(pending) {
+        const record = readWhatsNewRecord(this.instanceDir);
+        if (record === "unreadable") {
+            this.pendingWhatsNew = null;
+            return null;
+        }
+        const known = new Set(record?.announced ?? []);
+        const ids = pending.ids.filter(id => !known.has(id));
+        if (!ids.length) {
+            this.pendingWhatsNew = null;
+            return null;
+        }
+        if (ids.length === pending.ids.length)
+            return pending;
+        const narrowed = { notice: whatsNewNotice(pending.version, AGENT_WHATS_NEW.filter(e => ids.includes(e.id))), ids, version: pending.version };
+        this.pendingWhatsNew = narrowed;
+        return narrowed;
+    }
+    /** #1633: what this instance has not been told about its AgEnD version yet (see agent-whats-new.ts). */
+    prepareWhatsNew(fresh, version = agendVersion()) {
+        try {
+            const plan = planWhatsNew({ record: readWhatsNewRecord(this.instanceDir), fresh, version });
+            if (!plan) {
+                this.pendingWhatsNew = null;
+                return;
+            }
+            if ("silent" in plan) {
+                recordWhatsNew(this.instanceDir, plan.silent, plan.version);
+                this.pendingWhatsNew = null;
+                return;
+            }
+            this.pendingWhatsNew = plan;
+            this.logger.info({ entries: plan.ids }, "what's-new notice pending for the next delivery");
+        }
+        catch (err) {
+            this.logger.debug({ err }, "what's-new not prepared");
+        }
+    }
     async trySpawnInsideGate(reuseWindow = false, startupTimeoutMs) {
         this.startupAdmission?.();
         const launchFence = this.launchFenceEpoch;
@@ -10435,6 +10584,8 @@ export class Daemon extends EventEmitter {
         // instructionsReloadedOnResume) so the warmup steering-reload can be
         // skipped when nothing changed.
         this.lastBuiltInstructions = backendConfig.instructions ?? "";
+        // #1633: decided before prev-instructions is first written — its absence is what says "never launched before".
+        this.prepareWhatsNew(!existsSync(join(this.instanceDir, "prev-instructions")));
         {
             const prevFile = join(this.instanceDir, "prev-instructions");
             let prev = "";