crewly 1.20.105 → 1.20.107

package/dist/cli/backend/src/services/restart/in-flight-turn-tracker.service.js

@@ -0,0 +1,246 @@
+/**
+ * In-Flight Turn Tracker
+ *
+ * Remembers, per agent session, the messages that were written into the
+ * agent's PTY (or handed to an in-process runtime) and whether the agent has
+ * finished the turn they started.
+ *
+ * Why this exists: the persistent message queue only protects messages that
+ * have not been delivered yet. Once a message is in the PTY it is off the
+ * queue, so a restart during the agent's turn used to lose the turn with no
+ * trace — the owner DM'd Ella at 01:38:30, a restart at 01:39:31 killed her
+ * mid-turn, and nothing picked it back up (2026-09-24). The drain and the
+ * interrupted-turn resume both read from here.
+ *
+ * Turn completion is decided by a {@link TurnProbe}, not by events alone:
+ * - the ActivityMonitor `agent:idle` event is a *prompt* to re-probe, never a
+ *   verdict — it fires on a 30s poll and is force-emitted after 15 minutes of
+ *   continuous output even when the agent is still working;
+ * - a reply (report-status / reply-slack / chat) is not a verdict either — an
+ *   agent says "on it" and keeps working, which is exactly the Ella case;
+ * - in-process (crewly-agent) turns end precisely when their promise settles,
+ *   so the caller reports that directly via {@link completeMessage}.
+ *
+ * @module services/restart/in-flight-turn-tracker
+ */
+import { LoggerService } from '../core/logger.service.js';
+import { SAFE_RESTART } from '../../constants.js';
+/** Marker that opens every scheduler / reconciler / status ping. */
+const SYSTEM_MARKER = /^\s*\[SYSTEM\b/;
+/**
+ * Build a one-line preview of a delivered message.
+ *
+ * @param text - Delivered text
+ * @returns Whitespace-collapsed text, cut to SAFE_RESTART.PREVIEW_CHARS
+ */
+export function previewOf(text) {
+    const flat = text.replace(/\s+/g, ' ').trim();
+    return flat.length > SAFE_RESTART.PREVIEW_CHARS ? `${flat.slice(0, SAFE_RESTART.PREVIEW_CHARS - 1)}…` : flat;
+}
+/**
+ * Tracks in-flight agent turns. Singleton; all state is in memory.
+ */
+export class InFlightTurnTracker {
+    static instance = null;
+    logger;
+    turns = new Map();
+    probe = null;
+    constructor() {
+        this.logger = LoggerService.getInstance().createComponentLogger('InFlightTurnTracker');
+    }
+    /**
+     * Get the singleton instance.
+     *
+     * @returns The tracker
+     */
+    static getInstance() {
+        if (!InFlightTurnTracker.instance) {
+            InFlightTurnTracker.instance = new InFlightTurnTracker();
+        }
+        return InFlightTurnTracker.instance;
+    }
+    /**
+     * Reset the singleton (tests only).
+     */
+    static resetInstance() {
+        InFlightTurnTracker.instance = null;
+    }
+    /**
+     * Install the probe used to decide whether a PTY session is still mid-turn.
+     *
+     * @param probe - Probe function, or null to remove
+     */
+    setProbe(probe) {
+        this.probe = probe;
+    }
+    /**
+     * Record a message that was just written into an agent's PTY or handed to
+     * its in-process runtime.
+     *
+     * Callers should {@link settle} the session *before* writing: if the agent
+     * is resting, whatever was still open belonged to a finished turn and is
+     * dropped, so a restart never resumes a message that was already answered.
+     * (After the write the echo makes the PTY look busy, so settling then
+     * proves nothing.)
+     *
+     * @param sessionName - Agent session
+     * @param text - Exactly what was delivered
+     * @param runtime - How it was delivered
+     * @param now - Current time (ms)
+     * @returns The recorded message (pass it to completeMessage for in-process turns)
+     */
+    recordDelivery(sessionName, text, runtime = 'pty', now = Date.now()) {
+        const message = {
+            deliveredAt: now,
+            text,
+            preview: previewOf(text),
+            systemEvent: SYSTEM_MARKER.test(text),
+        };
+        const turn = this.turns.get(sessionName);
+        if (!turn) {
+            this.turns.set(sessionName, { sessionName, runtime, since: now, messages: [message] });
+            return message;
+        }
+        turn.runtime = runtime;
+        turn.messages.push(message);
+        while (turn.messages.length > SAFE_RESTART.MAX_OPEN_MESSAGES_PER_SESSION) {
+            turn.messages.shift();
+        }
+        turn.since = turn.messages[0].deliveredAt;
+        return message;
+    }
+    /**
+     * Attach queue metadata to the most recent open delivery whose text matches.
+     * Called by the queue processor after a successful delivery so the resume
+     * path can re-enqueue with the original source (Slack thread etc.).
+     *
+     * @param sessionName - Agent session
+     * @param text - The delivered text (as passed to sendMessageToAgent)
+     * @param meta - Queue metadata
+     * @returns True if a matching delivery was found
+     */
+    annotate(sessionName, text, meta) {
+        const turn = this.turns.get(sessionName);
+        if (!turn)
+            return false;
+        for (let i = turn.messages.length - 1; i >= 0; i--) {
+            const msg = turn.messages[i];
+            if (msg.text === text) {
+                Object.assign(msg, meta, { systemEvent: meta.systemEvent ?? msg.systemEvent });
+                return true;
+            }
+        }
+        return false;
+    }
+    /**
+     * Mark one delivery as finished (in-process runtimes report this exactly).
+     *
+     * @param sessionName - Agent session
+     * @param message - The object returned by recordDelivery
+     */
+    completeMessage(sessionName, message) {
+        const turn = this.turns.get(sessionName);
+        if (!turn)
+            return;
+        turn.messages = turn.messages.filter((m) => m !== message);
+        if (turn.messages.length === 0) {
+            this.turns.delete(sessionName);
+        }
+        else {
+            turn.since = turn.messages[0].deliveredAt;
+        }
+    }
+    /**
+     * Drop every open delivery for a session (turn over, or session gone).
+     *
+     * @param sessionName - Agent session
+     * @param reason - Why, for the debug log
+     */
+    markTurnComplete(sessionName, reason) {
+        if (this.turns.delete(sessionName)) {
+            this.logger.debug('Turn complete', { sessionName, reason });
+        }
+    }
+    /**
+     * Re-check one session with the probe and drop its open deliveries if the
+     * agent is resting or its session is gone. In-process turns are left alone:
+     * only their promise can end them.
+     *
+     * @param sessionName - Agent session
+     * @param now - Current time (ms)
+     * @returns True if the session is still mid-turn afterwards
+     */
+    settle(sessionName, now = Date.now()) {
+        const turn = this.turns.get(sessionName);
+        if (!turn)
+            return false;
+        if (turn.runtime === 'in-process')
+            return true;
+        const newest = turn.messages[turn.messages.length - 1];
+        if (newest && now - newest.deliveredAt < SAFE_RESTART.TURN_START_GRACE_MS)
+            return true;
+        if (!this.probe)
+            return true;
+        let verdict;
+        try {
+            verdict = this.probe(sessionName);
+        }
+        catch (error) {
+            // A probe that throws cannot prove the turn is over — keep waiting.
+            this.logger.warn('Turn probe failed; treating session as busy', {
+                sessionName,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            return true;
+        }
+        if (verdict === 'busy')
+            return true;
+        this.markTurnComplete(sessionName, verdict === 'gone' ? 'session gone' : 'agent resting');
+        return false;
+    }
+    /**
+     * Settle every tracked session and return those still mid-turn.
+     *
+     * @param now - Current time (ms)
+     * @returns Snapshot of in-flight turns, oldest first
+     */
+    getMidTurn(now = Date.now()) {
+        for (const sessionName of [...this.turns.keys()]) {
+            this.settle(sessionName, now);
+        }
+        return this.snapshot();
+    }
+    /**
+     * Snapshot of every open turn without probing.
+     *
+     * @returns Copies of the open turns, oldest first
+     */
+    snapshot() {
+        return [...this.turns.values()]
+            .map((t) => ({ ...t, messages: t.messages.map((m) => ({ ...m })) }))
+            .sort((a, b) => a.since - b.since);
+    }
+    /**
+     * Re-probe a session whenever the ActivityMonitor reports it idle, so a
+     * finished turn is forgotten promptly instead of lingering until the next
+     * delivery. The event only triggers the probe; it never decides alone.
+     *
+     * @param source - Event bus emitting 'eventPublished'
+     * @returns Function that detaches the listener
+     */
+    attachEventSource(source) {
+        const listener = (event) => {
+            if (event?.type === 'agent:idle' && typeof event.sessionName === 'string') {
+                this.settle(event.sessionName);
+            }
+        };
+        source.on('eventPublished', listener);
+        return () => {
+            if (source.off)
+                source.off('eventPublished', listener);
+            else
+                source.removeListener?.('eventPublished', listener);
+        };
+    }
+}
+//# sourceMappingURL=in-flight-turn-tracker.service.js.map

package/dist/cli/backend/src/services/restart/in-flight-turn-tracker.service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"in-flight-turn-tracker.service.js","sourceRoot":"","sources":["../../../../../../backend/src/services/restart/in-flight-turn-tracker.service.ts"],"names":[],"mappings":"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"}

package/dist/cli/backend/src/services/restart/restart-drain.service.d.ts

@@ -0,0 +1,176 @@
+/**
+ * Restart Drain Service
+ *
+ * Owns the "safe restart" state of the process:
+ * - a delivery pause: once shutdown starts, nothing new is written into an
+ *   agent's PTY — messages stay on the persistent queues instead;
+ * - the drain: wait until no agent is mid-turn, capped by a timeout, and
+ *   interruptible by a second signal;
+ * - restart readiness for operators (`GET /api/system/restart-readiness`);
+ * - a hook through which the REST restart endpoint asks the server for the
+ *   same graceful, drained shutdown a SIGTERM gets.
+ *
+ * "Queue empty" is not "safe to restart": a delivered message is off the
+ * queue while the agent is still working on it (2026-09-24, Ella). Readiness
+ * therefore reports in-flight turns, not queue depth.
+ *
+ * @module services/restart/restart-drain
+ */
+import { type InFlightTurn } from './in-flight-turn-tracker.service.js';
+/** How a drain ended. */
+export type DrainOutcome = 'drained' | 'timed-out' | 'skipped' | 'disabled';
+/** Result of a drain. */
+export interface DrainResult {
+    /** How it ended */
+    outcome: DrainOutcome;
+    /** Time spent waiting (ms) */
+    waitedMs: number;
+    /** Turns still in flight when the drain ended (to be persisted and resumed) */
+    remaining: InFlightTurn[];
+}
+/** Options for {@link RestartDrainService.drain}. */
+export interface DrainOptions {
+    /** Maximum wait (ms); 0 skips the wait */
+    timeoutMs: number;
+    /** Re-check interval (ms) */
+    pollMs?: number;
+    /** Interval for the repeated "still waiting" log line (ms) */
+    logIntervalMs?: number;
+    /** Clock (tests) */
+    now?: () => number;
+    /** Sleep (tests) */
+    sleep?: (ms: number) => Promise<void>;
+}
+/** One agent the readiness endpoint reports as busy. */
+export interface BusyAgent {
+    /** Agent session name */
+    session: string;
+    /** ISO time of the oldest open delivery */
+    since: string;
+    /** Preview of the most recent open delivery */
+    messagePreview: string;
+}
+/** Body of `GET /api/system/restart-readiness`. */
+export interface RestartReadiness {
+    /** True when no agent is mid-turn */
+    safe: boolean;
+    /** Agents mid-turn */
+    busyAgents: BusyAgent[];
+    /** Messages waiting on the persistent queues (they survive a restart) */
+    queued: number;
+    /** True when a shutdown drain is already running */
+    draining: boolean;
+}
+/** Options for a graceful shutdown requested through the service. */
+export interface GracefulShutdownRequest {
+    /** Why (for logs) */
+    reason: string;
+    /** Process exit code at the end of shutdown */
+    exitCode?: number;
+}
+/**
+ * Resolve the drain timeout from the environment.
+ *
+ * @param env - Environment (defaults to process.env)
+ * @returns Timeout in ms; 0 disables the wait. Invalid or negative values fall back to the default.
+ *
+ * @example
+ * ```typescript
+ * resolveRestartDrainMs({ CREWLY_RESTART_DRAIN_MS: '0' }); // 0
+ * resolveRestartDrainMs({}); // 120000
+ * ```
+ */
+export declare function resolveRestartDrainMs(env?: NodeJS.ProcessEnv): number;
+/**
+ * Process-wide safe-restart state. Singleton.
+ */
+export declare class RestartDrainService {
+    private readonly tracker;
+    private static instance;
+    private readonly logger;
+    private paused;
+    private pauseReason;
+    private draining;
+    private skipRequested;
+    private wakeSleeper;
+    private queueCounter;
+    private shutdownHandler;
+    private constructor();
+    /**
+     * Get the singleton instance.
+     *
+     * @returns The service
+     */
+    static getInstance(): RestartDrainService;
+    /**
+     * Reset the singleton (tests only).
+     */
+    static resetInstance(): void;
+    /**
+     * Whether deliveries into agent PTYs are paused (shutdown in progress).
+     *
+     * @returns True while paused
+     */
+    isDeliveryPaused(): boolean;
+    /**
+     * Whether the drain wait is running right now.
+     *
+     * @returns True during the wait
+     */
+    isDraining(): boolean;
+    /**
+     * Stop writing new messages into agent PTYs. Idempotent; never undone in
+     * this process (the next boot starts unpaused).
+     *
+     * @param reason - Why (for logs)
+     */
+    pauseDelivery(reason: string): void;
+    /**
+     * Ask a running drain to stop waiting (second signal, supervisor escalation).
+     *
+     * @param reason - Why (for logs)
+     * @returns True if a drain was running and will now end
+     */
+    requestSkip(reason: string): boolean;
+    /**
+     * Register the counter used for `queued` in readiness.
+     *
+     * @param counter - Returns the number of messages on the persistent queues
+     */
+    setQueueCounter(counter: (() => number) | null): void;
+    /**
+     * Register the server's graceful-shutdown entry point.
+     *
+     * @param handler - Runs the drained shutdown and exits the process
+     */
+    setShutdownHandler(handler: ((request: GracefulShutdownRequest) => Promise<void>) | null): void;
+    /**
+     * Run the server's graceful (drained) shutdown, if one is registered.
+     *
+     * @param request - Reason and exit code
+     * @returns True if a handler was registered and has been started
+     */
+    requestGracefulShutdown(request: GracefulShutdownRequest): boolean;
+    /**
+     * Current restart readiness.
+     *
+     * @returns Busy agents, queued count, and whether a restart is safe now
+     */
+    getReadiness(): RestartReadiness;
+    /**
+     * Wait until no agent is mid-turn, the timeout passes, or a skip arrives.
+     * Pauses delivery first (idempotent) so the set of turns can only shrink.
+     *
+     * @param options - Timeout and test hooks
+     * @returns How it ended and the turns still in flight
+     */
+    drain(options: DrainOptions): Promise<DrainResult>;
+    /**
+     * Sleep, but wake early when a skip is requested.
+     *
+     * @param sleep - Injected sleep (tests), or null for a cancellable timer
+     * @param ms - Duration
+     */
+    private sleepUnlessSkipped;
+}
+//# sourceMappingURL=restart-drain.service.d.ts.map

package/dist/cli/backend/src/services/restart/restart-drain.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"restart-drain.service.d.ts","sourceRoot":"","sources":["../../../../../../backend/src/services/restart/restart-drain.service.ts"],"names":[],"mappings":"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"}