@songsid/agend 2.1.2-beta.2 → 2.1.2-beta.21

package/dist/daemon.d.ts

@@ -1,21 +1,65 @@
 import { EventEmitter } from "node:events";
 import type { InstanceConfig, RotationSnapshot } from "./types.js";
-import type { Logger } from "./logger.js";
+import { type Logger } from "./logger.js";
 import { MessageBus } from "./channel/message-bus.js";
 import type { CliBackend, InstanceState, InstanceStateSnapshot } from "./backend/types.js";
 import { HangDetector } from "./hang-detector.js";
 import type { TmuxControlClient } from "./tmux-control.js";
+import type { FleetInstructionsParams } from "./instructions.js";
 /** Point a resumed CLI at its one backend-native instruction source. */
 export declare function buildInstructionReloadNotice(binaryName: string, instanceName: string, instanceDir: string): string;
 export declare const DEFAULT_STUCK_TIMEOUT_MS: number;
 export declare const DEFAULT_STATE_IDLE_DEBOUNCE_MS = 2000;
 export declare const DEFAULT_STATE_SAFETY_SWEEP_MS = 60000;
-/** @deprecated State detection is event-driven; this now aliases the safety sweep. */
-export declare const DEFAULT_STATE_POLL_INTERVAL_MS = 60000;
+/**
+ * Whether two working directories belong to the same project, so a fleet-scoped
+ * decision recorded in one reaches the other. Covers the worktree/checkout
+ * layout AgEnD fleets actually use — `AgEnD`, `AgEnD-dev1`, `AgEnD-dev2`,
+ * `AgEnD-reviewer`, `AgEnD-main` are one project; `DouPo_Server` is not.
+ * Nesting counts too (a subdirectory of a project belongs to it).
+ */
+export declare function sameProjectFamily(a: string, b: string): boolean;
+/**
+ * Pick the decisions worth injecting into one instance's system prompt.
+ *
+ * `scope: "fleet"` previously bypassed the project check outright, so every
+ * instance carried every other project's playbook — measured at 8 of 14 here,
+ * resent on every API call. A fleet decision must now also be relevant: global
+ * (no project_root), the same project, or the same project family.
+ *
+ * `isDispatcher` (a general) opts out of that narrowing on purpose: it routes
+ * work across all projects, so cross-project rules ("X 文件操作由 Y 負責") are
+ * precisely what it must know. Narrowing a general would cause misrouting.
+ */
+export declare function selectRelevantDecisions<T extends {
+    scope?: string;
+    project_root?: string;
+    title: string;
+}>(all: T[], workDir: string, isDispatcher?: boolean): T[];
 /** Read the last real channel inbound timestamp persisted across daemon restarts. */
 export declare function readLastInboundAt(instanceDir: string, now?: number): number | null;
 /** Atomically persist the last real channel inbound timestamp. */
 export declare function writeLastInboundAt(instanceDir: string, timestamp: number): void;
+/**
+ * Render the handoff/routing metadata that rides along with an inbound message
+ * into the block actually pasted into the agent's pane.
+ *
+ * These fields were all populated by the sender (outbound-handlers builds them
+ * into `ipcMeta`) and delivered over IPC, but never rendered — so the receiving
+ * agent could not see them, and several documented flows could not work:
+ *
+ * - `report_result` requires a `correlation_id` the agent had no way to know, so
+ *   the "correlation_id not recognized" warning fired on essentially every call.
+ * - Delegation cancel buttons are retired by correlation id, so they never retired.
+ * - `react`, `edit_message` and `reply.reply_to` need `message_id`, which the tool
+ *   descriptions tell the agent to take "from the inbound block".
+ * - `download_attachment` needs `attachment_file_id`.
+ * - `requires_reply` was invisible, so a delegated task looked like an FYI.
+ *
+ * Only non-empty fields are emitted, so a plain user message gains at most a
+ * message_id line.
+ */
+export declare function renderHandoffMetadata(meta: Record<string, string>): string;
 /** Headless inactivity timer used by the daemon and unit tests. */
 export declare class AutoPauseController {
     private readonly thresholdMs;
@@ -36,16 +80,32 @@ export declare class AutoPauseController {
  * Pane motion wins over a ready match because several backends keep their ready
  * marker in a persistent header/footer while generating. A stable ready pane is
  * idle; changing content is working; stable non-ready content eventually sticks.
+ *
+ * ## Why an optional busy pattern exists
+ *
+ * "Motion wins" degrades badly when a backend's ready marker is *always* on
+ * screen. `stuck` requires `!ready`, so for such a backend the state can only ever
+ * be idle or working — the stuck edge, and with it `handleStuckTransition` and the
+ * hang notification, is unreachable. A frozen CLI is then reported as idle, which
+ * also clears pending work: the message the user sent is quietly booked as done.
+ *
+ * claude-code was exactly this case (see ClaudeCodeBackend.getReadyPattern). A
+ * backend that can point at a marker meaning "generating right now" supplies
+ * `getBusyPattern()`, and that match vetoes ready regardless of what the ready
+ * pattern says.
  */
 export declare class PaneStateMachine {
     private readonly stuckTimeoutMs;
     private readonly readyPattern;
+    private readonly busyPattern;
     private lastPaneHash;
     private lastPaneChangeAt;
     private lastObservedAt;
     private stateChangedAt;
     private currentState;
-    constructor(readyPattern: RegExp, stuckTimeoutMs?: number, now?: number);
+    constructor(readyPattern: RegExp, stuckTimeoutMs?: number, now?: number, busyPattern?: RegExp | null);
+    /** Ready, unless the backend can positively see that it is still generating. */
+    private isReady;
     observe(pane: string, now?: number): InstanceStateSnapshot;
     /** Record pane motion from tmux control mode without capturing pane content. */
     recordOutput(now?: number): InstanceStateSnapshot;
@@ -83,13 +143,13 @@ export declare class Daemon extends EventEmitter {
     private topicMode;
     private backend?;
     private controlClient?;
+    private runtimeIdentity?;
     private logger;
     private tmuxSessionName;
     private tmux;
     private ipcServer;
     private messageBus;
     private transcriptMonitor;
-    private toolTracker;
     private guardian;
     private adapter;
     private pendingIpcRequests;
@@ -97,6 +157,8 @@ export declare class Daemon extends EventEmitter {
     private lastThreadId;
     private lastAdapterId;
     private pendingAckMessage;
+    /** Last activity published to the fleet manager; null when nothing is running. */
+    private currentActivity;
     private toolStatusMessageId;
     private toolStatusLines;
     private toolStatusDebounce;
@@ -110,9 +172,19 @@ export declare class Daemon extends EventEmitter {
     private lastSpawnAt;
     private crashTimestamps;
     private healthCheckPaused;
+    private lastHealthErrorNotifyAt;
     /** CLI pane availability, independent from the daemon process and tri-state. */
     private processStatus;
     private spawning;
+    /**
+     * Resolves when the in-flight spawn finishes; null when none is running.
+     *
+     * `spawning` alone can only be polled. Delivery needs to *wait*, and a boolean
+     * poll would either busy-loop or race the flag being cleared.
+     */
+    private spawnSettled;
+    private resolveSpawnSettled;
+    private spawnDepth;
     private skipResume;
     private backgroundSessionRecoveryAttempted;
     /** Whether the last spawn started a fresh session (not resumed). */
@@ -134,10 +206,18 @@ export declare class Daemon extends EventEmitter {
     private instanceStateIdleDebounceMs;
     private instanceStateStuckTimeoutMs;
     private instanceStateReadyPattern;
+    private instanceStateBusyPattern;
     private instanceStateMonitorActive;
     private statePollInFlight;
     private autoPauseController;
     private pauseRequested;
+    /**
+     * Sticky "pause as soon as possible" (auth failure). Unlike pauseRequested —
+     * which the state monitor clears whenever the pane is not idle — this survives
+     * busy/stuck states, because an auth error fires mid-turn and a plain pause()
+     * would silently no-op exactly when we most need to stop feeding the CLI.
+     */
+    private pausePending;
     private pauseWakeState;
     private pauseWakeTransition;
     private modelOverride;
@@ -145,7 +225,13 @@ export declare class Daemon extends EventEmitter {
     private recentEvents;
     private recentToolActivity;
     private snapshotConsumed;
+    /** Orders inbound channel messages against each other (queue-depth accounting
+     *  and ⏳/👀/✅ reactions live here). It does NOT cover the other writers that
+     *  reach the pane — {@link paneWriteLock} does. */
     private pasteLock;
+    /** Mutual exclusion for *every* write into the pane, whichever subsystem it
+     *  comes from. See PaneWriteLock for why interleaving is destructive. */
+    private readonly paneWriteLock;
     private pendingInstructionsUpdate;
     private pendingInstructionsNotice;
     private warmupNeeded;
@@ -153,6 +239,10 @@ export declare class Daemon extends EventEmitter {
     private pasteQueueDepth;
     private firstDeliveryDelay;
     private errorMonitorTimer;
+    /** Same 5-min gate the error monitor uses, so a dead MCP server alerts once. */
+    private static readonly MCP_DEATH_COOLDOWN_MS;
+    private lastMcpDeathNotifiedAt;
+    private mcpDeathNotifiedForPid;
     /** Prevent in-flight monitor callbacks from re-arming after a pause. */
     private runtimeMonitorsFrozen;
     private errorWaitingForRecovery;
@@ -177,14 +267,42 @@ export declare class Daemon extends EventEmitter {
     private lastDetectedErrorType;
     private static errorPatternKey;
     private clearErrorRecoveryGate;
-    constructor(name: string, config: InstanceConfig, instanceDir: string, topicMode?: boolean, backend?: CliBackend | undefined, controlClient?: TmuxControlClient | undefined, rootLogger?: Logger);
+    constructor(name: string, config: InstanceConfig, instanceDir: string, topicMode?: boolean, backend?: CliBackend | undefined, controlClient?: TmuxControlClient | undefined, rootLogger?: Logger, runtimeIdentity?: FleetInstructionsParams["runtimeIdentity"]);
     start(): Promise<void>;
+    /**
+     * Detect a CRASHED MCP server and report it once.
+     *
+     * The MCP server writes its pid to channel.mcp.pid at startup and unlinks it on
+     * a clean exit, so "file present + pid dead" specifically means it died without
+     * cleaning up (crash / OOM / SIGKILL). A missing file is either "not started
+     * yet" or "exited cleanly" — neither is an incident, and an orphan exit implies
+     * the CLI itself died, which the crash detector already covers.
+     *
+     * The daemon deliberately does NOT try to respawn it: MCP is a stdio protocol
+     * where the CLI spawns the server and owns its pipes, so a daemon-spawned
+     * process would have no client reading it. Only the CLI can restore its own
+     * tools — hence notify, and let the operator decide about restarting.
+     */
+    private checkMcpServerAlive;
     private startHealthCheck;
     /**
      * Publish pane-process availability separately from idle/working/stuck.
      * A dead remain-on-exit pane still contains the old ready prompt, so allowing
      * the pane monitor to capture it would re-create a false idle state.
      */
+    /**
+     * Announce that this instance is no longer being supervised.
+     *
+     * Four health-check exits set `healthCheckPaused = true` and returned without
+     * telling anyone: a clean CLI exit, `max_retries <= 0`, crash retries exhausted,
+     * and the instance directory being deleted. Only the crash-LOOP case emitted an
+     * event, so a fleet could quietly contain a dead instance that still looked fine
+     * on the dashboard — while messages routed to it queued or failed with a bare ❌.
+     *
+     * `crash_loop` already had this treatment; this is the same bridge for the other
+     * four, carrying a human-readable cause and the operator's next step.
+     */
+    private emitSupervisionEnded;
     private setProcessStatus;
     /**
      * Periodically scan PTY output for backend-defined error patterns.
@@ -211,6 +329,12 @@ export declare class Daemon extends EventEmitter {
      * Interrupt the CLI's current generation (cancel button / `/cancel`).
      * Direct tmux key event (not a paste) so it registers as the interrupt key.
      * kiro-cli interrupts on Ctrl+C; the others (claude-code, codex, …) on Escape.
+     *
+     * Deliberately NOT taken through `paneWriteLock`. Cancel is the user's way out
+     * of a pane that is busy or wedged — queueing it behind the very delivery chain
+     * it exists to unblock would make the button useless exactly when it is needed.
+     * The cost is accepted: an Escape landing between a paste and its Enter discards
+     * that message, which is what the user asked for anyway.
      */
     sendEscape(): Promise<void>;
     /** Send the backend-specific graceful quit command/key sequence. */
@@ -220,6 +344,12 @@ export declare class Daemon extends EventEmitter {
     getInstanceState(): InstanceState | "paused";
     getInstanceStateSnapshot(): InstanceStateSnapshot;
     /** Gracefully stop the CLI while keeping its remain-on-exit tmux window. */
+    /**
+     * Mark the instance to pause as soon as its pane is idle. Used for auth
+     * failures: pause() alone no-ops while the CLI is busy/stuck, which is the
+     * usual state when the error surfaces. Cleared by a successful pause or wake.
+     */
+    requestPauseWhenIdle(): void;
     pause(): Promise<void>;
     /** Respawn the CLI in the preserved window and block until its prompt is ready. */
     wake(timeoutMs?: number): Promise<void>;
@@ -239,6 +369,28 @@ export declare class Daemon extends EventEmitter {
     /** Restore the same monitor objects after wake without adding event listeners. */
     private resumeRuntimeMonitors;
     getMessageBus(): MessageBus;
+    /**
+     * Tell the fleet manager what this instance is doing right now, for the live
+     * progress line on the cancel button.
+     *
+     * Purely cosmetic — nothing decides anything from it, so it is fine that only
+     * backends with a transcript feed report at all (claude-code today). For the
+     * rest the progress line keeps showing just elapsed time.
+     *
+     * Repeats are dropped: the ticker only edits the channel message when the text
+     * changes, and a stream of identical broadcasts would defeat that.
+     */
+    private publishActivity;
+    /**
+     * Options for every system-initiated paste (startup notice, session snapshot,
+     * runtime-dialog keys).
+     *
+     * One place, so the three call sites cannot drift apart on it. Backends with a
+     * native input queue do not get the retry Enter: on those, a second bare Enter
+     * is not the no-op the retry assumed but a queue mutation — the same reason
+     * `deliverMessage` refuses to probe for busy with one.
+     */
+    private systemPasteOptions;
     private summarizeTool;
     private addToolStatus;
     /** Debounce tool status updates to avoid channel rate limits */
@@ -254,23 +406,52 @@ export declare class Daemon extends EventEmitter {
     pushChannelMessage(content: string, meta: Record<string, string>, _targetSession?: string): void;
     /**
      * Deliver a single message and drive its status reactions:
-     *   ⏳ message_queued    — CLI busy; queued, waiting for idle
+     *   ⏳ message_queued    — CLI busy; queued locally or by the backend
      *   👀 message_delivered — pasted + Enter sent; agent now has it
-     *   ✅ message_confirmed — idle→busy transition observed; agent is processing
+     *   ✅ message_confirmed — processing observed, or native queue handoff succeeded
      *   ❌ message_failed    — tmux window gone, paste retries exhausted
      * Returns true once the message is in the CLI, false only on real delivery failure.
      *
      * Bug A (silent message loss): paste failures retry with backoff (window recovery)
      * and emit `message_failed` if all attempts fail.
-     * Busy handling (UX): we never force-paste into a busy CLI and never give up on a
-     * busy one — we show ⏳ and wait for idle indefinitely (a genuinely hung CLI is the
-     * hang detector's job; a user who can't wait presses Cancel → Escape → idle). The
-     * pasteLock is serial, so later messages naturally queue behind this wait.
+     * Busy handling (UX): backends without a native input queue show ⏳ and wait for
+     * idle indefinitely (a genuinely hung CLI is the hang detector's job). Backends
+     * that explicitly support queued input receive one complete paste+Enter transaction
+     * immediately and own the application-level queue themselves. The pasteLock remains
+     * serial in both cases so separate PTY writes can never overlap.
      */
     private deliverMessage;
+    /**
+     * The write half of a delivery: paste → Enter → confirm, with retries.
+     *
+     * Always called under {@link paneWriteLock}. Split out from `deliverMessage`
+     * precisely so the lock's scope is visible at the call site rather than being
+     * an invariant maintained by comments.
+     */
+    private writeMessageToPane;
+    /**
+     * True when a busy native-queue paste appears to have landed: Codex shows a
+     * `↳` queue marker, or a distinctive slice of the pasted text is on screen.
+     * Used only to detect silent paste loss — not as a general ready check.
+     */
+    private nativeQueuePasteVisible;
     /** Re-resolve this instance's tmux window by name (stale id after crash/respawn). */
     private recoverWindow;
-    /** Poll up to ~2s (200ms × 10) for the pane to emit output after `since`. */
+    /**
+     * Poll up to ~2s (200ms × 10) for the pane to emit output after `since`.
+     *
+     * A `false` here is not "no output" — it is read as **"the message was pasted but
+     * never submitted"**, which re-sends Enter and then reports ❌ to the user. So a
+     * false negative costs a possible double submit and a failure notice for a
+     * message that actually arrived.
+     *
+     * That is exactly what a control-mode reconnect used to produce. `connect()`
+     * drops every output timestamp, so `hasOutputSince` answers `false` for a pane
+     * that did react — the evidence was thrown away, not absent. Blind time is
+     * therefore not counted against the budget: after a reset the poll restarts from
+     * the moment observation resumed. A hard wall-clock cap keeps a reconnect loop
+     * from extending this forever.
+     */
     private confirmBusyAfterEnter;
     private getWindowId;
     /** Find the IPC socket for a given sessionName */
@@ -288,6 +469,31 @@ export declare class Daemon extends EventEmitter {
      * This replaces the old system-prompt injection approach.
      */
     private injectSnapshotMessage;
+    /**
+     * Depth, not a flag: the wake path marks a spawn and then calls trySpawn, which
+     * marks another. With a plain boolean the inner one's completion would clear the
+     * latch while the outer spawn was still dismissing dialogs, releasing delivery
+     * into exactly the window this exists to close.
+     */
+    private beginSpawn;
+    private endSpawn;
+    /**
+     * Hold until the CLI has finished starting up.
+     *
+     * Startup is not a quiet period: `dismissDialogsUntilReady` is clicking through
+     * trust prompts and session pickers. A pane showing a modal dialog produces no
+     * output, so `waitUntilIdle` reports it idle and a queued message gets pasted
+     * *into the dialog* — where the text is discarded and the Enter picks a menu
+     * item. The paste and the Enter both "succeed", so this loses the message
+     * without even a ❌.
+     *
+     * The pane write lock (#414) does not cover this: it serialises each key
+     * sequence, but it is released between one dialog and the next.
+     *
+     * Bounded, and called BEFORE the pane lock is taken — waiting on the spawn while
+     * holding the lock the spawn itself needs would deadlock.
+     */
+    private waitForSpawnToSettle;
     /** Spawn a CLI window. Returns true if --resume was used successfully. */
     private spawnClaudeWindow;
     /** Kill the entire process tree of the current tmux pane (CLI + MCP server). */