@songsid/agend 2.1.4-beta.2 → 2.1.4-beta.20

package/dist/daemon.d.ts

@@ -11,6 +11,10 @@ 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;
+/** Coalesce one cosmetic-redraw burst before comparing the visible pane. */
+export declare const PERIODIC_REDRAW_PROBE_MS = 25;
+/** A foreground server/port-forward should hand control back or be acknowledged. */
+export declare const DEFAULT_BLOCKING_PROCESS_GRACE_MS: number;
 /**
  * Whether two working directories belong to the same project, so a fleet-scoped
  * decision recorded in one reaches the other. Covers the worktree/checkout
@@ -62,11 +66,13 @@ export declare function writeLastInboundAt(instanceDir: string, timestamp: numbe
 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;
+    private thresholdMs;
     private lastActivityAt;
     private pausedAt;
     constructor(thresholdMs: number, lastActivityAt?: number);
     recordActivity(now?: number): void;
+    /** Apply a new idle threshold and start a fresh countdown from this update. */
+    reconfigure(thresholdMs: number, now?: number): void;
     observe(state: InstanceState, now?: number): boolean;
     markPaused(now?: number): void;
     markAwake(now?: number): void;
@@ -142,10 +148,13 @@ export declare class PaneStateMachine {
      *   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.
+     * @param opts.forceBusy the backend has positively identified a still-running
+     *   foreground tool even though its TUI keeps an old ready footer visible.
      */
     observe(pane: string, now?: number, opts?: {
         settled?: boolean;
         changeAt?: number;
+        forceBusy?: boolean;
     }): InstanceStateSnapshot;
     /** Record pane motion from tmux control mode without capturing pane content. */
     recordOutput(now?: number): InstanceStateSnapshot;
@@ -258,6 +267,30 @@ export declare class InteractivePromptDetector {
     observe(pane: string, now?: number, outputAt?: number): InteractivePromptDetection | null;
     reset(): void;
 }
+export interface BlockingProcessDetection {
+    activity: string;
+    evidence: string;
+    blockedForMs: number;
+}
+/**
+ * Detect a foreground shell tool which has become a long-lived server.
+ *
+ * Unlike the generic pane-stuck clock, this clock deliberately survives new
+ * output: access logs and `Handling connection` lines are exactly why a
+ * foreground server can remain blocked forever without ever looking silent.
+ * Once a server marker is seen, the still-running tool identity is the stable
+ * signal; the marker may scroll out of the 32-row pane.
+ */
+export declare class BlockingProcessDetector {
+    private readonly graceMs;
+    private activity;
+    private evidence;
+    private detectedAt;
+    private notified;
+    constructor(graceMs?: number);
+    observe(pane: string, activity: string | null, now?: number): BlockingProcessDetection | null;
+    reset(): void;
+}
 export declare class Daemon extends EventEmitter {
     private name;
     private config;
@@ -317,6 +350,7 @@ export declare class Daemon extends EventEmitter {
     /** Fallback safety sweep used only when no shared tmux control client exists. */
     private instanceStateMonitorTimer;
     private instanceStateIdleTimer;
+    private instanceStateOutputProbeTimer;
     private instanceStateStuckTimer;
     private instanceStateOutputListener;
     private instanceStateOutputEventName;
@@ -327,6 +361,7 @@ export declare class Daemon extends EventEmitter {
     private instanceStateReadyPattern;
     private instanceStateBusyPattern;
     private instanceStateMonitorActive;
+    private sessionCheckpointWarningEmitted;
     private statePollInFlight;
     private turnHadInbound;
     private turnOutboundDelivered;
@@ -342,6 +377,20 @@ export declare class Daemon extends EventEmitter {
      * would silently no-op exactly when we most need to stop feeding the CLI.
      */
     private pausePending;
+    /**
+     * An auth failure was detected and nothing has resolved it yet.
+     *
+     * Separate from `pausePending` because it must outlive it: the deferred pause
+     * clears `pausePending` as soon as it fires, but if that pause is refused the
+     * instance is still auth-broken and must not resume raising alarms.
+     */
+    private authFailureUnresolved;
+    /**
+     * Let the next pause() proceed from a stuck pane. Set only for the auth-deferred
+     * pause — see the pausePending consumption site for why waiting for idle there
+     * is waiting forever.
+     */
+    private pauseAllowStuck;
     private pauseWakeState;
     private pauseWakeTransition;
     private modelOverride;
@@ -353,6 +402,12 @@ export declare class Daemon extends EventEmitter {
      *  and ⏳/👀/✅ reactions live here). It does NOT cover the other writers that
      *  reach the pane — {@link paneWriteLock} does. */
     private pasteLock;
+    /**
+     * Fleet cancellation epoch. Queue entries retain the epoch they arrived with;
+     * advancing it invalidates only work received before the cancel, never a new
+     * user message which arrives immediately afterwards.
+     */
+    private deliveryEpoch;
     /** Mutual exclusion for *every* write into the pane, whichever subsystem it
      *  comes from. See PaneWriteLock for why interleaving is destructive. */
     private readonly paneWriteLock;
@@ -362,8 +417,20 @@ export declare class Daemon extends EventEmitter {
     private lastBuiltInstructions;
     private pasteQueueDepth;
     private firstDeliveryDelay;
+    /** Orders /steer pastes against each other. Deliberately NOT pasteLock:
+     *  a steer must not queue behind the normal deliveries it exists to
+     *  overtake. Pane-level exclusion still comes from paneWriteLock inside
+     *  deliverMessage, so a steer and a normal delivery can never interleave
+     *  their PTY writes — the steer just doesn't wait for idle. */
+    private steerLock;
+    /** Tool lines shown in the channel processing bubble for the current turn. */
+    private readonly turnProgress;
+    private lastProgressBroadcast;
+    private progressBroadcastTimer;
+    private lastProgressBroadcastAt;
     private errorMonitorTimer;
     private readonly interactivePromptDetector;
+    private readonly blockingProcessDetector;
     /** Same 5-min gate the error monitor uses, so a dead MCP server alerts once. */
     private static readonly MCP_DEATH_COOLDOWN_MS;
     private lastMcpDeathNotifiedAt;
@@ -489,12 +556,30 @@ export declare class Daemon extends EventEmitter {
      * that message, which is what the user asked for anyway.
      */
     sendEscape(): Promise<void>;
+    /**
+     * Drop every not-yet-started pane delivery which predates a user cancel.
+     * Promise chains cannot be removed, so entries become generation-checked
+     * no-ops. An entry already past its check is allowed to finish its current PTY
+     * transaction; the interrupt key still cancels the CLI generation.
+     */
+    clearPendingDeliveries(fleetEpoch?: number): void;
+    private captureDeliveryEpoch;
+    private isDeliveryEpochCurrent;
+    private queueRawPaste;
     /** Send the backend-specific graceful quit command/key sequence. */
     private sendQuitSequence;
     stop(): Promise<void>;
     getHangDetector(): HangDetector | null;
     getInstanceState(): InstanceState | "paused";
     getInstanceStateSnapshot(): InstanceStateSnapshot;
+    /**
+     * Answer a FleetManager state query. Most callers only need the cached state,
+     * but lifecycle decisions such as post-reply Cancel retirement need an
+     * authoritative pane observation: after startup the last transition can stay
+     * "working" even though the CLI has since settled without emitting another
+     * control-mode output record.
+     */
+    private respondToInstanceStateQuery;
     /** 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
@@ -524,6 +609,13 @@ export declare class Daemon extends EventEmitter {
     /** Relay the pane's final text to the channel, marked as a daemon proxy reply. */
     private sendProxyReply;
     private clearInstanceStateIdleTimer;
+    private clearInstanceStateOutputProbeTimer;
+    /**
+     * Periodic status-line hooks can generate `%output` without changing a single
+     * visible cell. Probe the pane once per burst: a changed capture is real work;
+     * an identical ready capture remains idle and emits no state edge.
+     */
+    private scheduleInstanceStateOutputProbe;
     private clearInstanceStateStuckTimer;
     private scheduleInstanceStateStuckDeadline;
     private scheduleInstanceStateIdleCapture;
@@ -542,14 +634,48 @@ export declare class Daemon extends EventEmitter {
      * 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.
+     * Primarily cosmetic. The foreground-process detector also uses a current
+     * shell activity as one of several positive signals, but never makes a state
+     * decision from an arbitrary activity label alone.
      *
      * 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;
+    /** Effective tool_progress level, hardened against junk config values.
+     *  Off unless explicitly enabled: an update must never make bubbles start
+     *  listing tool activity the operator did not ask to broadcast. */
+    private toolProgressLevel;
+    /**
+     * Apply a tool-progress setting without restarting the CLI session.
+     *
+     * Drop the current accumulator at the boundary: verbose entries may contain
+     * command previews which must not survive a downgrade to standard/off, and a
+     * newly enabled level should start with a clean, internally consistent list.
+     */
+    updateToolProgress(level: InstanceConfig["tool_progress"]): void;
+    /** Snapshot the configuration actually owned by this live daemon. */
+    getConfigSnapshot(): InstanceConfig;
+    /**
+     * Apply the whitelisted hot configuration carried by FleetManager IPC.
+     * null removes an optional value; invalid/unlisted fields are ignored rather
+     * than allowing another client on the per-instance socket to mutate cold
+     * process/session settings.
+     */
+    applyConfigUpdate(value: unknown): void;
+    /**
+     * Accumulate one semantic progress line for the channel bubble and schedule
+     * a coalesced broadcast. Separate from publishActivity on purpose: that one
+     * is the single-line statusline detail (terse, operator-facing), this is the
+     * multi-line channel list (semantic, argument-free at `standard`) — see
+     * tool-progress.ts for why the two labellers must not merge.
+     */
+    private recordToolProgress;
+    /** Coalesce progress broadcasts: at most one per 3s, trailing edge kept. */
+    private scheduleProgressBroadcast;
+    private broadcastToolProgress;
+    /** New turn (or turn over): drop the list and tell the fleet to clear it. */
+    private resetToolProgress;
     /**
      * Options for every system-initiated paste (startup notice, session snapshot,
      * runtime-dialog keys).
@@ -561,12 +687,43 @@ export declare class Daemon extends EventEmitter {
      */
     private systemPasteOptions;
     private summarizeTool;
+    /**
+     * The one place an inbound message grows its metadata wrapper ([user:]/
+     * [from:] prefix, pending reactions, handoff metadata, reply instructions).
+     * Both the normal queued path (pushChannelMessage) and /steer go through
+     * 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.
+     */
+    private formatInboundMessage;
+    /**
+     * /steer: interject into the CURRENT turn instead of queueing for idle.
+     *
+     * Differences from pushChannelMessage, and nothing else:
+     *  - serialized on steerLock, not pasteLock — it must overtake, not queue
+     *  - deliverMessage runs with { steer: true }, which takes the busy branch
+     *    that pastes immediately (the codex native-queue transaction) instead of
+     *    waiting for idle. Verification and silent-loss fallback are the ones
+     *    that path already has: pane-capture visibility check, then one
+     *    idle-gated redelivery — so on a TUI that swallows busy input the steer
+     *    degrades to "next message after this turn", never silently vanishes.
+     *
+     * The steered text goes through formatInboundMessage so the agent sees a
+     * normal inbound message, with a steering notice prepended for context.
+     */
+    steerMessage(content: string, meta: Record<string, string>, deliveryEpoch?: number): void;
+    /**
+     * /btw: submit a separately-labelled side question immediately while asking
+     * the agent not to change the active task. Claude's native `/btw` opens a
+     * branchAndResume panel whose answer never reaches the channel or transcript,
+     * so channel delivery intentionally uses a normal wrapped inbound instead.
+     */
+    btwMessage(content: string, meta: Record<string, string>, deliveryEpoch?: number): void;
     /**
      * Push an inbound channel message to a specific MCP session.
      * If targetSession is provided, only send to the matching socket.
      * Otherwise send to the instance's own session (this.name).
      */
-    pushChannelMessage(content: string, meta: Record<string, string>, _targetSession?: string): void;
+    pushChannelMessage(content: string, meta: Record<string, string>, _targetSession?: string, deliveryEpoch?: number): void;
     /**
      * Deliver a single message and drive its status reactions:
      *   ⏳ message_queued    — CLI busy; queued locally or by the backend
@@ -584,6 +741,15 @@ export declare class Daemon extends EventEmitter {
      * serial in both cases so separate PTY writes can never overlap.
      */
     private deliverMessage;
+    /**
+     * A raw `%output` silence check is authoritative for ordinary TUIs. It is not
+     * for a backend such as agy whose status-line hook periodically redraws an
+     * identical screen. In that case trust an idle pane-state snapshot only when
+     * it was captured after both the latest output and the latest control-client
+     * observation reset.
+     */
+    private isPaneIdleForDelivery;
+    private waitForPaneIdleForDelivery;
     /**
      * The write half of a delivery: paste → Enter → confirm, with retries.
      *