@0xmaxma/claude-gateway 1.8.2 → 1.8.3

package/dist/agent/turn-stream.d.ts

@@ -0,0 +1,202 @@
+/**
+ * Resumable turn streams (#421).
+ *
+ * A streamed turn used to be bound to exactly one HTTP request: every event was
+ * written straight to `res` behind an `if (!clientGone)` guard, so a client
+ * disconnect (or the soft timeout, which set the same flag) discarded the rest
+ * of the turn even though it kept running server-side and landed in history.
+ *
+ * A TurnStream decouples the two: the producer always records into an ordered,
+ * sequence-numbered buffer, and a *sink* — the thing that writes to a socket —
+ * is attached, detached and re-attached independently. A new SSE connection can
+ * therefore replay the tail from a cursor and then keep receiving live events,
+ * with no gap and no duplicate at the seam (attach() replays and installs in one
+ * synchronous block, so no event can slip between the two).
+ */
+import { ApiAttachment, StreamEvent } from '../types';
+/** Max events retained per turn before the oldest are evicted. */
+export declare const TURN_BUFFER_MAX_EVENTS = 2000;
+/** Max approximate payload bytes retained per turn (heavy tool output). */
+export declare const TURN_BUFFER_MAX_BYTES: number;
+/** How long a completed turn stays replayable after its terminal frame. */
+export declare const TURN_REPLAY_GRACE_MS = 120000;
+/** A buffered event plus its per-turn sequence number. */
+export interface SeqEvent {
+    seq: number;
+    event: StreamEvent;
+    /**
+     * Terminal `error` frames only: the original Error, so an in-process sink can
+     * hand callers the real object (with its `code`) rather than a re-wrapped
+     * message. SSE sinks ignore it and serialise `event` alone.
+     */
+    error?: Error;
+}
+/** Whatever is currently writing a turn's events out (an SSE response, a test spy). */
+export interface TurnSink {
+    /** A non-terminal event. */
+    write(e: SeqEvent): void;
+    /** The terminal `result` / `error` frame. The sink should close after this. */
+    finish(e: SeqEvent): void;
+    /**
+     * Another connection took over this turn. Optional: sinks that own a socket
+     * should close it, otherwise the displaced connection hangs open with no
+     * terminal frame ever coming — it is no longer the one being written to.
+     */
+    displaced?(): void;
+}
+export type AttachFailure = 'truncated' | 'ahead';
+/**
+ * One in-flight (or recently completed) turn: its ordered event buffer, its
+ * terminal frame once known, and the sink currently draining it.
+ */
+export declare class TurnStream {
+    /** The registry key this turn is filed under — see turnStreamKey(). */
+    readonly key: string;
+    readonly requestId: string;
+    readonly startedAt: number;
+    private readonly events;
+    private nextSeq;
+    /**
+     * seq of the NEWEST event evicted so far — eviction walks the head forward, so
+     * this advances with each drop. Anything at or below it is unreplayable, which
+     * is exactly the comparison attach() makes.
+     */
+    private evictedThroughSeq;
+    private bytes;
+    private terminalEvent;
+    private sink;
+    constructor(
+    /** The registry key this turn is filed under — see turnStreamKey(). */
+    key: string, requestId: string);
+    get isComplete(): boolean;
+    get lastSeq(): number;
+    /** Record a non-terminal event and, if a sink is attached, write it out. */
+    emit(event: StreamEvent): void;
+    /**
+     * Record the terminal frame (`result` or `error`), flush it to the sink and
+     * detach — the turn is over, and anything that attaches later replays instead.
+     */
+    complete(event: StreamEvent, error?: Error): void;
+    /**
+     * Replay everything after `afterSeq`, then install `sink` as the live one.
+     * Deliberately synchronous end to end: an event produced during an `await`
+     * here would land in the buffer but miss the sink (gap) or arrive twice (dup).
+     *
+     * Returns `'truncated'` — installing nothing — when `afterSeq` names an event
+     * the buffer has already evicted: the caller asked to continue seamlessly from
+     * a point that no longer exists, and that promise cannot be honoured.
+     *
+     * `afterSeq === 0` is exempt. It claims to have seen nothing, so there is no
+     * seam to break, and refusing it is what turned the headline case — a reload
+     * during a long turn — into a dead end: history holds no assistant row while
+     * the turn is still running, so the client was sent somewhere with nothing in
+     * it. It gets whatever the buffer still holds instead; the first replayed
+     * frame's `seq` is > 1 exactly when older events were dropped, and the terminal
+     * `result` carries the turn's full text regardless.
+     *
+     * Returns `'ahead'` when `afterSeq` runs past the last event this turn has
+     * produced. Seq numbering restarts at 1 for every turn, so a client that
+     * reloads and replays a cursor held over from an earlier turn would otherwise
+     * attach successfully, match no event, and still be handed the terminal frame
+     * — the final answer with every delta silently missing.
+     *
+     * This catches a stale cursor only when the new turn is *shorter* than the old
+     * one; a cursor from turn N sits inside turn N+1 the moment N+1 has emitted
+     * that many events, and no seq comparison can tell that apart from a genuine
+     * resume. Identity is what separates them, which is why the resume endpoint
+     * requires `request_id` whenever `after_seq > 0`.
+     */
+    attach(sink: TurnSink, afterSeq: number): AttachFailure | null;
+    /**
+     * Detach `sink` if it is still the live one. Passing the sink (rather than
+     * clearing unconditionally) keeps a stale `res.on('close')` from a superseded
+     * connection from silencing the sink that replaced it.
+     */
+    detach(sink: TurnSink): void;
+    private evictIfOverCap;
+}
+/**
+ * Registry key for a turn. Every producer namespaces its session ids, because
+ * one registry serves them all: the API path files under `api`, a channel turn
+ * under its channel name. Without the prefix the two id spaces shared one
+ * keyspace and a collision would let one producer's turn evict or terminate the
+ * other's — a claim the old comments here asserted could not happen while
+ * complete()'s guard below existed precisely because it could.
+ *
+ * The chat id is deliberately NOT part of the key: an API session id is minted
+ * by the gateway inside a single `api-{chatId}` index and cannot be presented
+ * for another chat (see apiSessionExists), so the namespace prefix already makes
+ * every key unique.
+ */
+export declare function turnStreamKey(namespace: string, sessionId: string): string;
+/**
+ * Per-session registry of turn streams, with the completed-turn grace window.
+ *
+ * Keyed by turnStreamKey(); each record carries its request id, so a client that
+ * re-attaches can assert it is resuming the turn it thinks it is.
+ */
+export declare class TurnStreamRegistry {
+    private readonly graceMs;
+    private readonly turns;
+    private readonly releaseTimers;
+    constructor(graceMs?: number);
+    /**
+     * Begin a new turn, replacing (and un-scheduling) any previous record for the
+     * key so a fresh turn never inherits the last one's buffer — the same reason
+     * `pendingApiAttachments` is cleared at the top of every turn.
+     *
+     * This also ends the previous turn's replay grace window early: a session
+     * holds at most one turn, so nothing of turn N survives once turn N+1 starts.
+     * A client that resumes turn N by name (`request_id`) therefore gets
+     * TURN_MISMATCH — not a replay of N, and not a replay of N+1 either. A client
+     * that resumes by cursor alone cannot be told apart from one legitimately
+     * following N+1, which is why the resume endpoint requires the request id
+     * alongside a non-zero cursor. Documented in API.md under "Resuming an
+     * interrupted stream"; history is the fallback.
+     */
+    start(key: string, requestId: string): TurnStream;
+    get(key: string): TurnStream | undefined;
+    /**
+     * Record the terminal frame and keep the turn replayable for the grace window.
+     *
+     * Takes the TurnStream itself, not a key: a turn superseded by the next one on
+     * the same session finishes late often enough, and it must terminate its OWN
+     * record, never the one that replaced it.
+     */
+    complete(turn: TurnStream, event: StreamEvent, error?: Error): void;
+    /**
+     * Terminal frame + immediate release, for a producer whose turns nothing can
+     * re-attach to: the cross-channel live view files under its channel namespace,
+     * and the resume endpoint only ever looks under `api`. Holding that buffer for
+     * the grace window would retain up to the full per-turn cap (2,000 events /
+     * ~4 MB) for two minutes with no code path able to replay a byte of it.
+     *
+     * Same superseded-turn guard as complete(): a late finisher releases its OWN
+     * record, never the one that replaced it.
+     */
+    completeAndRelease(turn: TurnStream, event: StreamEvent, error?: Error): void;
+    /** Drop the record and its grace timer. */
+    release(key: string): void;
+    clear(): void;
+}
+/** Terminal frame for a turn that finished normally. */
+export declare function resultEvent(text: string, attachments: ApiAttachment[]): StreamEvent;
+/** Terminal frame for a turn that failed, carrying the Error's `code` when it has one. */
+export declare function errorEvent(err: Error): StreamEvent;
+/** The `code` property producers attach to their Errors, when it is a string. */
+export declare function errorCode(err: unknown): string | undefined;
+/**
+ * The callback shape every streaming producer in AgentRunner emits into. `seq`
+ * is the event's per-turn sequence number — the cursor a client passes back to
+ * `GET …/sessions/:sessionId/stream?after_seq=` to resume without a gap.
+ */
+export interface ApiStreamCallbacks {
+    onChunk: (event: StreamEvent, seq?: number) => void;
+    onDone: (fullText: string, attachments: ApiAttachment[], seq?: number) => void;
+    onError: (err: Error, seq?: number) => void;
+    /** Another connection resumed this turn; this one is no longer being written to. */
+    onDisplaced?: () => void;
+}
+/** Adapt a callback trio into a sink a TurnStream can drive. */
+export declare function callbackSink(callbacks: ApiStreamCallbacks): TurnSink;
+//# sourceMappingURL=turn-stream.d.ts.map

package/dist/agent/turn-stream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"turn-stream.d.ts","sourceRoot":"","sources":["../../src/agent/turn-stream.ts"],"names":[],"mappings":"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"}

package/dist/agent/turn-stream.js

@@ -0,0 +1,322 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TurnStreamRegistry = exports.TurnStream = exports.TURN_REPLAY_GRACE_MS = exports.TURN_BUFFER_MAX_BYTES = exports.TURN_BUFFER_MAX_EVENTS = void 0;
+exports.turnStreamKey = turnStreamKey;
+exports.resultEvent = resultEvent;
+exports.errorEvent = errorEvent;
+exports.errorCode = errorCode;
+exports.callbackSink = callbackSink;
+/** Max events retained per turn before the oldest are evicted. */
+exports.TURN_BUFFER_MAX_EVENTS = 2000;
+/** Max approximate payload bytes retained per turn (heavy tool output). */
+exports.TURN_BUFFER_MAX_BYTES = 4 * 1024 * 1024;
+/** How long a completed turn stays replayable after its terminal frame. */
+exports.TURN_REPLAY_GRACE_MS = 120000;
+/** Fraction of the cap evicted at once, so eviction is amortised O(1) per event. */
+const EVICT_BATCH_RATIO = 0.1;
+/**
+ * One in-flight (or recently completed) turn: its ordered event buffer, its
+ * terminal frame once known, and the sink currently draining it.
+ */
+class TurnStream {
+    constructor(
+    /** The registry key this turn is filed under — see turnStreamKey(). */
+    key, requestId) {
+        this.key = key;
+        this.requestId = requestId;
+        this.startedAt = Date.now();
+        this.events = [];
+        this.nextSeq = 1;
+        /**
+         * seq of the NEWEST event evicted so far — eviction walks the head forward, so
+         * this advances with each drop. Anything at or below it is unreplayable, which
+         * is exactly the comparison attach() makes.
+         */
+        this.evictedThroughSeq = 0;
+        this.bytes = 0;
+        this.terminalEvent = null;
+        this.sink = null;
+    }
+    get isComplete() {
+        return this.terminalEvent !== null;
+    }
+    get lastSeq() {
+        return this.nextSeq - 1;
+    }
+    /** Record a non-terminal event and, if a sink is attached, write it out. */
+    emit(event) {
+        if (this.terminalEvent)
+            return; // nothing may follow the terminal frame
+        const e = { seq: this.nextSeq++, event, bytes: approxSize(event) };
+        this.events.push(e);
+        this.bytes += e.bytes;
+        this.evictIfOverCap();
+        this.sink?.write(e);
+    }
+    /**
+     * Record the terminal frame (`result` or `error`), flush it to the sink and
+     * detach — the turn is over, and anything that attaches later replays instead.
+     */
+    complete(event, error) {
+        if (this.terminalEvent)
+            return;
+        const e = { seq: this.nextSeq++, event, ...(error ? { error } : {}) };
+        this.terminalEvent = e;
+        const sink = this.sink;
+        this.sink = null;
+        sink?.finish(e);
+    }
+    /**
+     * Replay everything after `afterSeq`, then install `sink` as the live one.
+     * Deliberately synchronous end to end: an event produced during an `await`
+     * here would land in the buffer but miss the sink (gap) or arrive twice (dup).
+     *
+     * Returns `'truncated'` — installing nothing — when `afterSeq` names an event
+     * the buffer has already evicted: the caller asked to continue seamlessly from
+     * a point that no longer exists, and that promise cannot be honoured.
+     *
+     * `afterSeq === 0` is exempt. It claims to have seen nothing, so there is no
+     * seam to break, and refusing it is what turned the headline case — a reload
+     * during a long turn — into a dead end: history holds no assistant row while
+     * the turn is still running, so the client was sent somewhere with nothing in
+     * it. It gets whatever the buffer still holds instead; the first replayed
+     * frame's `seq` is > 1 exactly when older events were dropped, and the terminal
+     * `result` carries the turn's full text regardless.
+     *
+     * Returns `'ahead'` when `afterSeq` runs past the last event this turn has
+     * produced. Seq numbering restarts at 1 for every turn, so a client that
+     * reloads and replays a cursor held over from an earlier turn would otherwise
+     * attach successfully, match no event, and still be handed the terminal frame
+     * — the final answer with every delta silently missing.
+     *
+     * This catches a stale cursor only when the new turn is *shorter* than the old
+     * one; a cursor from turn N sits inside turn N+1 the moment N+1 has emitted
+     * that many events, and no seq comparison can tell that apart from a genuine
+     * resume. Identity is what separates them, which is why the resume endpoint
+     * requires `request_id` whenever `after_seq > 0`.
+     */
+    attach(sink, afterSeq) {
+        if (afterSeq > this.lastSeq)
+            return 'ahead';
+        if (afterSeq > 0 && afterSeq < this.evictedThroughSeq)
+            return 'truncated';
+        // Retire whoever held the slot before the replay, so the displaced socket
+        // closes instead of waiting forever for a terminal frame it will not get.
+        const previous = this.sink;
+        if (previous && previous !== sink) {
+            this.sink = null;
+            try {
+                previous.displaced?.();
+            }
+            catch { /* already gone */ }
+        }
+        for (const e of this.events) {
+            if (e.seq > afterSeq)
+                sink.write(e);
+        }
+        if (this.terminalEvent) {
+            sink.finish(this.terminalEvent);
+            return null;
+        }
+        this.sink = sink;
+        return null;
+    }
+    /**
+     * Detach `sink` if it is still the live one. Passing the sink (rather than
+     * clearing unconditionally) keeps a stale `res.on('close')` from a superseded
+     * connection from silencing the sink that replaced it.
+     */
+    detach(sink) {
+        if (this.sink === sink)
+            this.sink = null;
+    }
+    evictIfOverCap() {
+        if (this.events.length <= exports.TURN_BUFFER_MAX_EVENTS && this.bytes <= exports.TURN_BUFFER_MAX_BYTES)
+            return;
+        const batch = Math.max(1, Math.floor(exports.TURN_BUFFER_MAX_EVENTS * EVICT_BATCH_RATIO));
+        while (this.events.length > 0 &&
+            (this.events.length > exports.TURN_BUFFER_MAX_EVENTS - batch || this.bytes > exports.TURN_BUFFER_MAX_BYTES)) {
+            const dropped = this.events.shift();
+            this.bytes -= dropped.bytes;
+            this.evictedThroughSeq = dropped.seq;
+        }
+    }
+}
+exports.TurnStream = TurnStream;
+/**
+ * Registry key for a turn. Every producer namespaces its session ids, because
+ * one registry serves them all: the API path files under `api`, a channel turn
+ * under its channel name. Without the prefix the two id spaces shared one
+ * keyspace and a collision would let one producer's turn evict or terminate the
+ * other's — a claim the old comments here asserted could not happen while
+ * complete()'s guard below existed precisely because it could.
+ *
+ * The chat id is deliberately NOT part of the key: an API session id is minted
+ * by the gateway inside a single `api-{chatId}` index and cannot be presented
+ * for another chat (see apiSessionExists), so the namespace prefix already makes
+ * every key unique.
+ */
+function turnStreamKey(namespace, sessionId) {
+    return `${namespace}:${sessionId}`;
+}
+/**
+ * Per-session registry of turn streams, with the completed-turn grace window.
+ *
+ * Keyed by turnStreamKey(); each record carries its request id, so a client that
+ * re-attaches can assert it is resuming the turn it thinks it is.
+ */
+class TurnStreamRegistry {
+    constructor(graceMs = exports.TURN_REPLAY_GRACE_MS) {
+        this.graceMs = graceMs;
+        this.turns = new Map();
+        this.releaseTimers = new Map();
+    }
+    /**
+     * Begin a new turn, replacing (and un-scheduling) any previous record for the
+     * key so a fresh turn never inherits the last one's buffer — the same reason
+     * `pendingApiAttachments` is cleared at the top of every turn.
+     *
+     * This also ends the previous turn's replay grace window early: a session
+     * holds at most one turn, so nothing of turn N survives once turn N+1 starts.
+     * A client that resumes turn N by name (`request_id`) therefore gets
+     * TURN_MISMATCH — not a replay of N, and not a replay of N+1 either. A client
+     * that resumes by cursor alone cannot be told apart from one legitimately
+     * following N+1, which is why the resume endpoint requires the request id
+     * alongside a non-zero cursor. Documented in API.md under "Resuming an
+     * interrupted stream"; history is the fallback.
+     */
+    start(key, requestId) {
+        this.release(key);
+        const turn = new TurnStream(key, requestId);
+        this.turns.set(key, turn);
+        return turn;
+    }
+    get(key) {
+        return this.turns.get(key);
+    }
+    /**
+     * Record the terminal frame and keep the turn replayable for the grace window.
+     *
+     * Takes the TurnStream itself, not a key: a turn superseded by the next one on
+     * the same session finishes late often enough, and it must terminate its OWN
+     * record, never the one that replaced it.
+     */
+    complete(turn, event, error) {
+        turn.complete(event, error);
+        // Only the current record earns a grace timer; a superseded one is already
+        // unreachable and would otherwise schedule a release for its successor.
+        if (this.turns.get(turn.key) !== turn)
+            return;
+        const timer = setTimeout(() => this.release(turn.key), this.graceMs);
+        timer.unref?.();
+        this.releaseTimers.set(turn.key, timer);
+    }
+    /**
+     * Terminal frame + immediate release, for a producer whose turns nothing can
+     * re-attach to: the cross-channel live view files under its channel namespace,
+     * and the resume endpoint only ever looks under `api`. Holding that buffer for
+     * the grace window would retain up to the full per-turn cap (2,000 events /
+     * ~4 MB) for two minutes with no code path able to replay a byte of it.
+     *
+     * Same superseded-turn guard as complete(): a late finisher releases its OWN
+     * record, never the one that replaced it.
+     */
+    completeAndRelease(turn, event, error) {
+        turn.complete(event, error);
+        if (this.turns.get(turn.key) === turn)
+            this.release(turn.key);
+    }
+    /** Drop the record and its grace timer. */
+    release(key) {
+        const timer = this.releaseTimers.get(key);
+        if (timer) {
+            clearTimeout(timer);
+            this.releaseTimers.delete(key);
+        }
+        this.turns.delete(key);
+    }
+    clear() {
+        for (const timer of this.releaseTimers.values())
+            clearTimeout(timer);
+        this.releaseTimers.clear();
+        this.turns.clear();
+    }
+}
+exports.TurnStreamRegistry = TurnStreamRegistry;
+/** Cheap stand-in for the serialised size — exact bytes aren't worth the hot-path cost. */
+function approxSize(event) {
+    switch (event.type) {
+        case 'text_delta':
+        case 'thinking':
+            return event.text.length + 32;
+        case 'result':
+            return event.text.length + 32 + (event.attachments?.length ?? 0) * 128;
+        case 'error':
+        case 'timeout':
+            return event.message.length + 32;
+        case 'tool_use':
+            return event.name.length + event.id.length + (event.input ? JSON.stringify(event.input).length : 0) + 32;
+    }
+}
+/** Terminal frame for a turn that finished normally. */
+function resultEvent(text, attachments) {
+    return attachments.length ? { type: 'result', text, attachments } : { type: 'result', text };
+}
+/** Terminal frame for a turn that failed, carrying the Error's `code` when it has one. */
+function errorEvent(err) {
+    const code = errorCode(err);
+    return code ? { type: 'error', message: err.message, code } : { type: 'error', message: err.message };
+}
+/** The `code` property producers attach to their Errors, when it is a string. */
+function errorCode(err) {
+    const code = err?.code;
+    return typeof code === 'string' ? code : undefined;
+}
+/** Best-effort message for a terminal frame that is not a `result`. */
+function terminalMessage(event) {
+    return 'message' in event ? event.message : `Turn ended (${event.type})`;
+}
+/**
+ * Rebuild an Error for a terminal frame whose original Error is not available —
+ * a replayed `error` frame reaches a sink as data, not as the live throw. The
+ * frame's `code` is copied back onto it so a resumed client learns the same
+ * thing the original connection did.
+ */
+function terminalError(event) {
+    const err = new Error(terminalMessage(event));
+    if (event.type === 'error' && event.code)
+        Object.assign(err, { code: event.code });
+    return err;
+}
+/** Adapt a callback trio into a sink a TurnStream can drive. */
+function callbackSink(callbacks) {
+    return {
+        write: (e) => {
+            try {
+                callbacks.onChunk(e.event, e.seq);
+            }
+            catch { /* sink gone */ }
+        },
+        finish: (e) => {
+            try {
+                if (e.event.type === 'result') {
+                    callbacks.onDone(e.event.text, e.event.attachments ?? [], e.seq);
+                }
+                else {
+                    // `error` — and anything else that ever ends up terminal. A sink that
+                    // is handed a terminal frame it does not recognise must still be told
+                    // the turn is over, or an SSE response stays open forever.
+                    callbacks.onError(e.error ?? terminalError(e.event), e.seq);
+                }
+            }
+            catch { /* sink gone */ }
+        },
+        displaced: () => {
+            try {
+                callbacks.onDisplaced?.();
+            }
+            catch { /* sink gone */ }
+        },
+    };
+}
+//# sourceMappingURL=turn-stream.js.map

package/dist/agent/turn-stream.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"turn-stream.js","sourceRoot":"","sources":["../../src/agent/turn-stream.ts"],"names":[],"mappings":"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"}

package/dist/api/apps-router.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"apps-router.d.ts","sourceRoot":"","sources":["../../src/api/apps-router.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAqB,MAAM,SAAS,CAAC;AACpD,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAElC,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAChD,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAgDzD,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,YAAY,EACtB,SAAS,EAAE,YAAY,EACvB,cAAc,EAAE,cAAc,EAC9B,OAAO,EAAE,MAAM,EAAE,GAChB,MAAM,CAwbR"}
+{"version":3,"file":"apps-router.d.ts","sourceRoot":"","sources":["../../src/api/apps-router.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAqB,MAAM,SAAS,CAAC;AACpD,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAElC,OAAO,EAAE,YAAY,EAAY,MAAM,kBAAkB,CAAC;AAC1D,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AA+DzD,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,YAAY,EACtB,SAAS,EAAE,YAAY,EACvB,cAAc,EAAE,cAAc,EAC9B,OAAO,EAAE,MAAM,EAAE,GAChB,MAAM,CAwbR"}

package/dist/api/apps-router.js

@@ -4,6 +4,18 @@ exports.createAppsRouter = createAppsRouter;
 const express_1 = require("express");
 const auth_1 = require("./auth");
 const compose_generator_1 = require("../apps/compose-generator");
+/**
+ * Attach this boot's restore failure to an app entry, when one is recorded, so
+ * an app the gateway tried and failed to start is distinguishable from one an
+ * operator deliberately stopped (issue #425). Absent on every healthy app, so
+ * the response shape is unchanged for existing consumers.
+ */
+function withRestoreFailure(installer, entry) {
+    const failure = installer.getRestoreFailure(entry.name);
+    if (!failure)
+        return entry;
+    return { ...entry, restoreError: failure.error, restoreFailedAt: failure.at };
+}
 /**
  * Parse a request-body `ports` field into a validated host-port override map.
  * Returns undefined when absent. Throws (→ 400) on a non-object, a non-integer
@@ -85,7 +97,7 @@ function createAppsRouter(registry, installer, registryClient, apiKeys) {
             // Reconcile each stored status against the live Docker runtime so a
             // container that crashed/was killed externally no longer reports running.
             const reconciled = await installer.reconcileStatuses(apps);
-            res.json({ apps: reconciled });
+            res.json({ apps: reconciled.map((e) => withRestoreFailure(installer, e)) });
         }
         catch (err) {
             res.status(500).json({ error: err.message });
@@ -186,7 +198,7 @@ function createAppsRouter(registry, installer, registryClient, apiKeys) {
             }
             // Reconcile the stored status against the live Docker runtime before return.
             const reconciled = await installer.reconcileStatus(entry);
-            res.json(reconciled);
+            res.json(withRestoreFailure(installer, reconciled));
         }
         catch (err) {
             res.status(500).json({ error: err.message });