@songsid/agend 2.1.2-beta.9 → 2.1.2

package/dist/daemon.d.ts

@@ -11,12 +11,55 @@ export declare function buildInstructionReloadNotice(binaryName: string, instanc
 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;
@@ -37,17 +80,73 @@ 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.
+ */
+/**
+ * A shell command reduced to the part that is safe to show: the program, and a
+ * subcommand when there is one.
+ *
+ *   curl -H "Bearer sk-ant-…" https://api.com   →  curl
+ *   npm test --env=API_KEY=xxx                  →  npm test
+ *   git push origin main                        →  git push
+ *
+ * Arguments are dropped wholesale rather than filtered, because there is no
+ * reliable way to tell a secret from an ordinary argument: tokens, bearer
+ * headers, connection strings and `--password=` values all look like text. The
+ * progress line is posted to a chat channel and, for a public one, so is
+ * anything in it — so the rule is "never the arguments", not "not the arguments
+ * that look dangerous".
+ *
+ * A second token is kept only when it is a bare word (`push`, `test`), which is
+ * what a subcommand looks like and what a flag, path, URL, assignment or quoted
+ * string does not. Everything after it goes, including `git push ORIGIN MAIN`.
  */
+export declare function shellCommandLabel(command: string): string;
 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);
-    observe(pane: string, now?: number): InstanceStateSnapshot;
+    constructor(readyPattern: RegExp, stuckTimeoutMs?: number, now?: number, busyPattern?: RegExp | null);
+    /** Ready, unless the backend can positively see that it is still generating. */
+    private isReady;
+    /**
+     * @param now when this observation is being evaluated — drives the idle and
+     *   stuck decisions.
+     * @param opts.changeAt when the content is believed to have changed, if that
+     *   is earlier than `now` (the tmux output timestamp). Only the elapsed-time
+     *   clock uses it; defaults to `now`.
+     * @param opts.settled the caller knows no output has arrived for the debounce
+     *   window, so "the content differs from the last capture" says nothing about
+     *   whether the CLI is still generating — decide on the patterns instead.
+     *
+     *   Captures are event-driven, not periodic: the one taken 2s after output
+     *   stops is compared against a capture that may be a minute old, so it
+     *   *always* differs. Without this flag that difference reads as "still
+     *   working" and a finished turn would not be seen as idle until the next 60s
+     *   safety sweep. Output timestamps are the honest liveness signal here, and
+     *   the caller has them.
+     */
+    observe(pane: string, now?: number, opts?: {
+        settled?: boolean;
+        changeAt?: number;
+    }): InstanceStateSnapshot;
     /** Record pane motion from tmux control mode without capturing pane content. */
     recordOutput(now?: number): InstanceStateSnapshot;
     snapshot(now?: number): InstanceStateSnapshot;
@@ -77,6 +176,27 @@ export declare class FirstDeliveryDelay {
 }
 /** Redact likely credentials and control sequences before pane text reaches logs. */
 export declare function sanitizePaneTail(pane: string, lineCount?: number): string[];
+export type InteractivePromptKind = "sudo_password" | "password" | "confirmation" | "press_enter";
+export interface InteractivePromptDetection {
+    kind: InteractivePromptKind;
+    prompt: string;
+}
+/**
+ * Detect terminal prompts that require a human, but only after the pane tail is
+ * unchanged and no control-mode output has arrived for the full grace period.
+ * This prevents prose such as "the installer asks [Y/n]" from notifying while
+ * an agent is still writing it.
+ */
+export declare class InteractivePromptDetector {
+    private readonly stableMs;
+    private signature;
+    private stableSince;
+    private lastOutputAt;
+    private notifiedSignature;
+    constructor(stableMs?: number);
+    observe(pane: string, now?: number, outputAt?: number): InteractivePromptDetection | null;
+    reset(): void;
+}
 export declare class Daemon extends EventEmitter {
     private name;
     private config;
@@ -91,7 +211,6 @@ export declare class Daemon extends EventEmitter {
     private ipcServer;
     private messageBus;
     private transcriptMonitor;
-    private toolTracker;
     private guardian;
     private adapter;
     private pendingIpcRequests;
@@ -99,6 +218,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;
@@ -112,9 +233,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). */
@@ -136,10 +267,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;
@@ -147,7 +286,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;
@@ -155,6 +300,26 @@ export declare class Daemon extends EventEmitter {
     private pasteQueueDepth;
     private firstDeliveryDelay;
     private errorMonitorTimer;
+    private readonly interactivePromptDetector;
+    /** 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;
+    /**
+     * Ceiling on how long a dead MCP server waits for an idle window before the
+     * auto-restart fires anyway. A toolless instance cannot reply or report, so
+     * whatever a very long turn produces is stranded until the restart happens —
+     * past this point interrupting the turn costs less than staying mute.
+     */
+    private static readonly MCP_RESTART_MAX_WAIT_MS;
+    /**
+     * Sticky "restart to revive the MCP server as soon as the pane idles" — same
+     * shape as pausePending, because the death is usually detected mid-turn when
+     * an immediate restart would destroy in-flight work. Cleared when the server
+     * turns up alive again (operator restarted, CLI reconnected) before we fire.
+     */
+    private mcpRestartPending;
+    private mcpRestartStaleTimer;
     /** Prevent in-flight monitor callbacks from re-arming after a pause. */
     private runtimeMonitorsFrozen;
     private errorWaitingForRecovery;
@@ -164,6 +329,8 @@ export declare class Daemon extends EventEmitter {
     /** Whether this instance is in an abnormal error state (auto-pause is normal). */
     get isErrorState(): boolean;
     get isPaused(): boolean;
+    /** Current CLI process state for status surfaces and recovery commands. */
+    getProcessStatus(): "running" | "crashed" | "stopped";
     get lastPausedAt(): number | null;
     private getPauseWakeState;
     /** Whether this instance is in a crash loop (3+ consecutive crashes). */
@@ -181,12 +348,50 @@ export declare class Daemon extends EventEmitter {
     private clearErrorRecoveryGate;
     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;
+    /**
+     * Arm an automatic instance restart to revive a dead MCP server. Fires on the
+     * next busy→idle edge — or immediately when the pane is already idle, which is
+     * the common case for a collab/chat instance parked between messages (no edge
+     * would ever come). A turn that outlives MCP_RESTART_MAX_WAIT_MS is
+     * force-restarted: see that constant for why staying mute costs more.
+     */
+    private armMcpRestartWhenIdle;
+    private fireMcpRestartRequest;
+    private clearMcpRestartRequest;
     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.
@@ -213,6 +418,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. */
@@ -222,6 +433,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>;
@@ -241,6 +458,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 */
@@ -271,9 +510,37 @@ export declare class Daemon extends EventEmitter {
      * 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 */
@@ -291,6 +558,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). */