@stratusagent/gateway 0.14.7 → 0.14.9

package/dist/lifecycle.d.ts

@@ -0,0 +1,130 @@
+import { type StateEnvironment } from '@stratusagent/state';
+/** What a turn cut short by an announced restart records as its failure. */
+export declare const RESTARTING_TURN_ERROR = "Run aborted: stratusd is restarting";
+/** The error a turn still running when a stop's drain window closes is aborted with. */
+export declare const STOPPING_TURN_ERROR = "Run aborted: stratusd is stopping";
+/**
+ * How long an announced restart lets in-flight turns finish before aborting
+ * them. The same as a stop's window (`DEFAULT_STOP_DRAIN_TIMEOUT_MS`), so the
+ * two windows an operator can hit agree.
+ */
+export declare const DEFAULT_RESTART_DRAIN_TIMEOUT_MS = 30000;
+/** How long a roster reload waits on one channel's `reload()`. */
+export declare const DEFAULT_CHANNEL_RELOAD_TIMEOUT_MS = 30000;
+/**
+ * What one channel did with a roster reload. `reloaded`: its `reload()`
+ * resolved. `failed`: it rejected, with the reason. `still-reloading`: it
+ * had not settled within `channelReloadTimeoutMs`, and finishes on its own.
+ */
+export interface ChannelReloadOutcome {
+    name: string;
+    outcome: 'reloaded' | 'failed' | 'still-reloading';
+    reason?: string;
+}
+/**
+ * How long a stop lets in-flight turns finish before aborting them. The
+ * daemon's documented drain ("up to 30 seconds"), and shorter than the
+ * service units' stop timeouts, so the abort happens in this process
+ * rather than as the manager's SIGKILL. That matters beyond the turn's
+ * record: a shell command runs in its own process group, which launchd's
+ * kill of the job does not reach, so only the turn's abort stops it.
+ */
+export declare const DEFAULT_STOP_DRAIN_TIMEOUT_MS = 30000;
+export interface RestartRequest {
+    /** Why, for the log — "plugin stratus-plugin-github enabled". */
+    reason?: string;
+    /** Overrides the gateway's drain window for this restart. */
+    drainTimeoutMs?: number;
+}
+/** What `restart()` announced: the terms the drain is running under. */
+export interface RestartStatus {
+    reason?: string;
+    drainTimeoutMs: number;
+    /** Turns that were running when the restart was announced. */
+    inflight: number;
+}
+/** What the host is handed once the daemon has stopped for a restart. */
+export interface RestartOutcome {
+    reason?: string;
+    /**
+     * Whether everything let go — every turn finished inside the window or
+     * after being aborted at it, every channel stopped, and every plugin
+     * released what it held. False means a turn ignored its abort for a
+     * whole second window, or a channel's stop or a plugin's dispose never
+     * settled or rejected, and the gateway shut down around it; a host
+     * should exit the process rather than start a new daemon beside a turn
+     * still writing, a channel still connected, or a plugin still holding a
+     * browser or a socket.
+     */
+    drained: boolean;
+}
+/** Whether the daemon is taking new work. */
+export interface IntakeState {
+    paused: boolean;
+    /** What a refused message is answered with. Present only while paused. */
+    message?: string;
+    /** When the pause began (ISO 8601). Present only while paused. */
+    since?: string;
+    /**
+     * Whether this pause is the one the daemon started in because its intake
+     * file could not be read. Reported while paused: true only for that pause,
+     * false once a pause written since has replaced it, so `stratus doctor`
+     * can tell a startup warning about the file from a pause someone chose.
+     * Never written to the file.
+     */
+    unreadable?: boolean;
+}
+/** What a paused daemon says when nobody gave it a sentence of its own. */
+export declare const DEFAULT_PAUSED_MESSAGE = "I'm paused right now and not taking new work. Please try again later.";
+/** What a held gateway answers a dispatch with, before it is promoted. */
+export declare const HELD_MESSAGE = "I'm starting up and not taking work yet. Please try again in a moment.";
+/** The longest pause message, so a reply to a refused message stays one. */
+export declare const MAX_PAUSED_MESSAGE_LENGTH = 500;
+/** A pause message the gateway will not take: empty, or too long. */
+export declare class PauseMessageError extends Error {
+    constructor(message: string);
+}
+/**
+ * A dispatch refused because intake is paused. Its message is the sentence
+ * to show whoever sent the work, as it is: a channel posts it as the reply,
+ * not as a failure.
+ */
+export declare class IntakePausedError extends Error {
+    constructor(message: string);
+}
+/**
+ * A dispatch refused because the daemon is restarting or stopping. Channels
+ * stay connected while a restart drains, so they hear people during it, and
+ * this is what tells them the message reached a daemon on its way down: a
+ * channel can say so and keep the message for the next one. Matched by name
+ * there, as channel packages do not import the gateway.
+ */
+export declare class GatewayStoppingError extends Error {
+    /** True for a restart, which comes back on its own; false for a stop. */
+    readonly restarting: boolean;
+    constructor(message: string, restarting: boolean);
+}
+/**
+ * The intake state a previous process left, or open when there is none.
+ *
+ * Fails closed: a file that exists but cannot be read or parsed starts the
+ * daemon paused, with a warning naming it. A pause exists to stop work (a
+ * spending cap, a maintenance window), and a file nobody can read is no
+ * evidence that it was lifted.
+ */
+export declare const readIntakeState: (env: StateEnvironment, warn: (line: string) => void) => Promise<IntakeState>;
+/**
+ * Record a pause durably (0600, replaced in one atomic step), or remove the
+ * record when intake reopens: open is the default, so nothing on disk
+ * means open.
+ */
+export declare const writeIntakeState: (env: StateEnvironment, state: IntakeState) => Promise<void>;
+/**
+ * `restart()` on a gateway whose host gave it no way back. Exported so the
+ * control API can answer it as "not supported here" rather than as a
+ * failure of the daemon.
+ */
+export declare class RestartUnsupportedError extends Error {
+    constructor();
+}
+//# sourceMappingURL=lifecycle.d.ts.map

package/dist/lifecycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle.d.ts","sourceRoot":"","sources":["../src/lifecycle.ts"],"names":[],"mappings":"AAUA,OAAO,EAEL,KAAK,gBAAgB,EAGtB,MAAM,qBAAqB,CAAC;AAE7B,4EAA4E;AAC5E,eAAO,MAAM,qBAAqB,wCAAwC,CAAC;AAE3E,wFAAwF;AACxF,eAAO,MAAM,mBAAmB,sCAAsC,CAAC;AAEvE;;;;GAIG;AACH,eAAO,MAAM,gCAAgC,QAAS,CAAC;AACvD,kEAAkE;AAClE,eAAO,MAAM,iCAAiC,QAAS,CAAC;AAExD;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,UAAU,GAAG,QAAQ,GAAG,iBAAiB,CAAC;IACnD,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,6BAA6B,QAAS,CAAC;AAEpD,MAAM,WAAW,cAAc;IAC7B,iEAAiE;IACjE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,6DAA6D;IAC7D,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,wEAAwE;AACxE,MAAM,WAAW,aAAa;IAC5B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,cAAc,EAAE,MAAM,CAAC;IACvB,8DAA8D;IAC9D,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,yEAAyE;AACzE,MAAM,WAAW,cAAc;IAC7B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;;;;;OASG;IACH,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,6CAA6C;AAC7C,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,OAAO,CAAC;IAChB,0EAA0E;IAC1E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,kEAAkE;IAClE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED,2EAA2E;AAC3E,eAAO,MAAM,sBAAsB,0EAA0E,CAAC;AAE9G,0EAA0E;AAC1E,eAAO,MAAM,YAAY,2EAA2E,CAAC;AAErG,4EAA4E;AAC5E,eAAO,MAAM,yBAAyB,MAAM,CAAC;AAE7C,qEAAqE;AACrE,qBAAa,iBAAkB,SAAQ,KAAK;gBAC9B,OAAO,EAAE,MAAM;CAI5B;AAED;;;;GAIG;AACH,qBAAa,iBAAkB,SAAQ,KAAK;gBAC9B,OAAO,EAAE,MAAM;CAI5B;AAED;;;;;;GAMG;AACH,qBAAa,oBAAqB,SAAQ,KAAK;IAC7C,yEAAyE;IACzE,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;gBACjB,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,OAAO;CAKjD;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,eAAe,GAAU,KAAK,gBAAgB,EAAE,MAAM,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,KAAG,OAAO,CAAC,WAAW,CA8B9G,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,GAAU,KAAK,gBAAgB,EAAE,OAAO,WAAW,KAAG,OAAO,CAAC,IAAI,CAe9F,CAAC;AAEF;;;;GAIG;AACH,qBAAa,uBAAwB,SAAQ,KAAK;;CAQjD"}

package/dist/lifecycle.js

@@ -0,0 +1,147 @@
+/*
+ * Restart, stop and pause: the errors a cut-short turn records, the drain
+ * windows, what a restart or a roster reload reports, and the intake state a
+ * paused daemon keeps on disk. Moved out of `index.ts` as is; `index.ts`
+ * re-exports the public names, so the package's surface is unchanged.
+ */
+import { randomBytes } from 'node:crypto';
+import { mkdir, readFile, rename, rm } from 'node:fs/promises';
+import path from 'node:path';
+import { intakeStatePath, syncDirectory, writeFileSynced, } from '@stratusagent/state';
+/** What a turn cut short by an announced restart records as its failure. */
+export const RESTARTING_TURN_ERROR = 'Run aborted: stratusd is restarting';
+/** The error a turn still running when a stop's drain window closes is aborted with. */
+export const STOPPING_TURN_ERROR = 'Run aborted: stratusd is stopping';
+/**
+ * How long an announced restart lets in-flight turns finish before aborting
+ * them. The same as a stop's window (`DEFAULT_STOP_DRAIN_TIMEOUT_MS`), so the
+ * two windows an operator can hit agree.
+ */
+export const DEFAULT_RESTART_DRAIN_TIMEOUT_MS = 30_000;
+/** How long a roster reload waits on one channel's `reload()`. */
+export const DEFAULT_CHANNEL_RELOAD_TIMEOUT_MS = 30_000;
+/**
+ * How long a stop lets in-flight turns finish before aborting them. The
+ * daemon's documented drain ("up to 30 seconds"), and shorter than the
+ * service units' stop timeouts, so the abort happens in this process
+ * rather than as the manager's SIGKILL. That matters beyond the turn's
+ * record: a shell command runs in its own process group, which launchd's
+ * kill of the job does not reach, so only the turn's abort stops it.
+ */
+export const DEFAULT_STOP_DRAIN_TIMEOUT_MS = 30_000;
+/** What a paused daemon says when nobody gave it a sentence of its own. */
+export const DEFAULT_PAUSED_MESSAGE = "I'm paused right now and not taking new work. Please try again later.";
+/** What a held gateway answers a dispatch with, before it is promoted. */
+export const HELD_MESSAGE = "I'm starting up and not taking work yet. Please try again in a moment.";
+/** The longest pause message, so a reply to a refused message stays one. */
+export const MAX_PAUSED_MESSAGE_LENGTH = 500;
+/** A pause message the gateway will not take: empty, or too long. */
+export class PauseMessageError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'PauseMessageError';
+    }
+}
+/**
+ * A dispatch refused because intake is paused. Its message is the sentence
+ * to show whoever sent the work, as it is: a channel posts it as the reply,
+ * not as a failure.
+ */
+export class IntakePausedError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'IntakePausedError';
+    }
+}
+/**
+ * A dispatch refused because the daemon is restarting or stopping. Channels
+ * stay connected while a restart drains, so they hear people during it, and
+ * this is what tells them the message reached a daemon on its way down: a
+ * channel can say so and keep the message for the next one. Matched by name
+ * there, as channel packages do not import the gateway.
+ */
+export class GatewayStoppingError extends Error {
+    /** True for a restart, which comes back on its own; false for a stop. */
+    restarting;
+    constructor(message, restarting) {
+        super(message);
+        this.name = 'GatewayStoppingError';
+        this.restarting = restarting;
+    }
+}
+/**
+ * The intake state a previous process left, or open when there is none.
+ *
+ * Fails closed: a file that exists but cannot be read or parsed starts the
+ * daemon paused, with a warning naming it. A pause exists to stop work (a
+ * spending cap, a maintenance window), and a file nobody can read is no
+ * evidence that it was lifted.
+ */
+export const readIntakeState = async (env, warn) => {
+    const file = intakeStatePath(env);
+    let raw;
+    try {
+        raw = await readFile(file, 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            return { paused: false };
+        }
+        warn(`intake: ${file} could not be read (${error.message}); starting paused. Resume intake to clear it.`);
+        return { paused: true, since: new Date().toISOString(), unreadable: true };
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        // Only a pause is ever written here (resuming removes the file), so
+        // anything else in it is not a record this build wrote, and the same
+        // rule as an unreadable file applies.
+        if (typeof parsed !== 'object' || parsed === null || parsed.paused !== true) {
+            warn(`intake: ${file} does not hold a pause record; starting paused. Resume intake to clear it.`);
+            return { paused: true, since: new Date().toISOString(), unreadable: true };
+        }
+        return {
+            paused: true,
+            ...(typeof parsed.message === 'string' && parsed.message.trim().length > 0 ? { message: parsed.message } : {}),
+            since: typeof parsed.since === 'string' ? parsed.since : new Date().toISOString(),
+        };
+    }
+    catch {
+        warn(`intake: ${file} is not valid JSON; starting paused. Resume intake to clear it.`);
+        return { paused: true, since: new Date().toISOString(), unreadable: true };
+    }
+};
+/**
+ * Record a pause durably (0600, replaced in one atomic step), or remove the
+ * record when intake reopens: open is the default, so nothing on disk
+ * means open.
+ */
+export const writeIntakeState = async (env, state) => {
+    const file = intakeStatePath(env);
+    if (!state.paused) {
+        await rm(file, { force: true });
+        return;
+    }
+    await mkdir(path.dirname(file), { recursive: true, mode: 0o700 });
+    const staging = `${file}.${randomBytes(8).toString('hex')}`;
+    try {
+        await writeFileSynced(staging, `${JSON.stringify(state)}\n`, { flag: 'wx', mode: 0o600 });
+        await rename(staging, file);
+        await syncDirectory(path.dirname(file));
+    }
+    finally {
+        await rm(staging, { force: true });
+    }
+};
+/**
+ * `restart()` on a gateway whose host gave it no way back. Exported so the
+ * control API can answer it as "not supported here" rather than as a
+ * failure of the daemon.
+ */
+export class RestartUnsupportedError extends Error {
+    constructor() {
+        super('This daemon cannot restart itself: the host that started it did not say how. '
+            + 'Restart it from the service manager (stratus service stop, then start) or from the terminal it runs in.');
+        this.name = 'RestartUnsupportedError';
+    }
+}
+//# sourceMappingURL=lifecycle.js.map

package/dist/lifecycle.js.map

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

package/dist/merge-batch.d.ts

@@ -0,0 +1,60 @@
+import { type ImageAttachment, type Session } from '@stratusagent/core';
+import type { DispatchInput } from './types.ts';
+/** A dispatch absorbed into a merged turn, waiting for its outcome. */
+export interface MergeJoiner {
+    input: DispatchInput;
+    resolve: (session: Session) => void;
+    reject: (error: unknown) => void;
+}
+export interface MergeBatch {
+    agentId: string | undefined;
+    /** The dispatch that opened the batch and runs it, unless it is steered. */
+    leader: MergeJoiner;
+    /**
+     * Nothing was queued on the session's chain when it opened, so nothing
+     * can be ahead of it: the chain is first in, first out. Only such a batch
+     * is steered (card 948); one behind other work waits its turn.
+     */
+    firstInLine: boolean;
+    absorbed: MergeJoiner[];
+    /**
+     * Taken by the turn running ahead of it (card 948), which settles every
+     * caller in it: the leader's place on the chain then runs nothing.
+     */
+    steered: boolean;
+    /** Every image in the batch so far, leader's first. */
+    images: ImageAttachment[];
+    /** Characters of the merged user message so far, separators included. */
+    chars: number;
+}
+/**
+ * The most text one merged user message may hold (card 423). The runner's
+ * overflow recovery can drop earlier transcript but never part of the
+ * newest message, so a batch must not grow that message past what one
+ * message could be on its own: this is Slack's own message-length limit.
+ * A single message longer than this still runs, alone, as it would have
+ * without merging.
+ */
+export declare const MERGED_TEXT_BUDGET_CHARS = 40000;
+/** Separator between merged messages; counted against the text budget. */
+export declare const MERGED_SEPARATOR = "\n\n";
+/**
+ * Whether `images` all fit the replay budget together. A merged turn's
+ * images are one message's, and the runner empties whatever falls outside
+ * the budget before the provider sees it, so a batch that would overflow
+ * must not take the message that overflows it (card 423).
+ */
+export declare const fitsReplayBudget: (images: readonly ImageAttachment[]) => boolean;
+/** A signal that aborts once every one of `signals` has. */
+export declare const allAborted: (signals: readonly AbortSignal[]) => AbortSignal;
+/**
+ * `allAborted` for callers that keep joining: a turn that takes in messages
+ * at its tool steps (card 948) is cancelled only once every caller in it
+ * is, the ones who joined late included. A caller joining with no signal
+ * can never cancel, so from then on neither can the turn.
+ */
+export declare const joinableSignal: (initial: readonly AbortSignal[]) => {
+    signal: AbortSignal;
+    join: (signal: AbortSignal | undefined) => void;
+};
+//# sourceMappingURL=merge-batch.d.ts.map

package/dist/merge-batch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"merge-batch.d.ts","sourceRoot":"","sources":["../src/merge-batch.ts"],"names":[],"mappings":"AAOA,OAAO,EAA4B,KAAK,eAAe,EAAE,KAAK,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAClG,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD,uEAAuE;AACvE,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,aAAa,CAAC;IACrB,OAAO,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,CAAC;IACpC,MAAM,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CAClC;AAED,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,4EAA4E;IAC5E,MAAM,EAAE,WAAW,CAAC;IACpB;;;;OAIG;IACH,WAAW,EAAE,OAAO,CAAC;IACrB,QAAQ,EAAE,WAAW,EAAE,CAAC;IACxB;;;OAGG;IACH,OAAO,EAAE,OAAO,CAAC;IACjB,uDAAuD;IACvD,MAAM,EAAE,eAAe,EAAE,CAAC;IAC1B,yEAAyE;IACzE,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,wBAAwB,QAAS,CAAC;AAE/C,0EAA0E;AAC1E,eAAO,MAAM,gBAAgB,SAAS,CAAC;AAEvC;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,GAAI,QAAQ,SAAS,eAAe,EAAE,KAAG,OAC+E,CAAC;AAEtJ,4DAA4D;AAC5D,eAAO,MAAM,UAAU,GAAI,SAAS,SAAS,WAAW,EAAE,KAAG,WAA6C,CAAC;AAE3G;;;;;GAKG;AACH,eAAO,MAAM,cAAc,GAAI,SAAS,SAAS,WAAW,EAAE,KAAG;IAAE,MAAM,EAAE,WAAW,CAAC;IAAC,IAAI,EAAE,CAAC,MAAM,EAAE,WAAW,GAAG,SAAS,KAAK,IAAI,CAAA;CAwBtI,CAAC"}

package/dist/merge-batch.js

@@ -0,0 +1,59 @@
+/*
+ * A merged turn's batch: the dispatch that opened it and the ones absorbed
+ * into it while it waits, and the rules a batch grows by. Moved out of
+ * index.ts as is so the dispatch path split out of `createGateway` can name
+ * them; index.ts does not re-export them.
+ */
+import { imagesWithinReplayBudget } from '@stratusagent/core';
+/**
+ * The most text one merged user message may hold (card 423). The runner's
+ * overflow recovery can drop earlier transcript but never part of the
+ * newest message, so a batch must not grow that message past what one
+ * message could be on its own: this is Slack's own message-length limit.
+ * A single message longer than this still runs, alone, as it would have
+ * without merging.
+ */
+export const MERGED_TEXT_BUDGET_CHARS = 40_000;
+/** Separator between merged messages; counted against the text budget. */
+export const MERGED_SEPARATOR = '\n\n';
+/**
+ * Whether `images` all fit the replay budget together. A merged turn's
+ * images are one message's, and the runner empties whatever falls outside
+ * the budget before the provider sees it, so a batch that would overflow
+ * must not take the message that overflows it (card 423).
+ */
+export const fitsReplayBudget = (images) => images.length === 0 || imagesWithinReplayBudget([{ id: '', createdAt: '', role: 'user', content: '', images: [...images] }]).size === images.length;
+/** A signal that aborts once every one of `signals` has. */
+export const allAborted = (signals) => joinableSignal(signals).signal;
+/**
+ * `allAborted` for callers that keep joining: a turn that takes in messages
+ * at its tool steps (card 948) is cancelled only once every caller in it
+ * is, the ones who joined late included. A caller joining with no signal
+ * can never cancel, so from then on neither can the turn.
+ */
+export const joinableSignal = (initial) => {
+    const controller = new AbortController();
+    const signals = [...initial];
+    let uncancellable = false;
+    const check = () => {
+        if (!uncancellable && !controller.signal.aborted && signals.every((signal) => signal.aborted)) {
+            controller.abort(signals[signals.length - 1]?.reason);
+        }
+    };
+    for (const signal of signals) {
+        signal.addEventListener('abort', check, { once: true });
+    }
+    check();
+    return {
+        signal: controller.signal,
+        join: (signal) => {
+            if (signal === undefined) {
+                uncancellable = true;
+                return;
+            }
+            signals.push(signal);
+            signal.addEventListener('abort', check, { once: true });
+        },
+    };
+};
+//# sourceMappingURL=merge-batch.js.map

package/dist/merge-batch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"merge-batch.js","sourceRoot":"","sources":["../src/merge-batch.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,wBAAwB,EAAsC,MAAM,oBAAoB,CAAC;AAgClG;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,MAAM,CAAC;AAE/C,0EAA0E;AAC1E,MAAM,CAAC,MAAM,gBAAgB,GAAG,MAAM,CAAC;AAEvC;;;;;GAKG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,MAAkC,EAAW,EAAE,CAC9E,MAAM,CAAC,MAAM,KAAK,CAAC,IAAI,wBAAwB,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,SAAS,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,EAAE,EAAE,MAAM,EAAE,CAAC,GAAG,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,MAAM,CAAC,MAAM,CAAC;AAEtJ,4DAA4D;AAC5D,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,OAA+B,EAAe,EAAE,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC;AAE3G;;;;;GAKG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,OAA+B,EAA4E,EAAE;IAC1I,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;IACzC,MAAM,OAAO,GAAG,CAAC,GAAG,OAAO,CAAC,CAAC;IAC7B,IAAI,aAAa,GAAG,KAAK,CAAC;IAC1B,MAAM,KAAK,GAAG,GAAS,EAAE;QACvB,IAAI,CAAC,aAAa,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,OAAO,IAAI,OAAO,CAAC,KAAK,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC;YAC9F,UAAU,CAAC,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;QACxD,CAAC;IACH,CAAC,CAAC;IACF,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;QAC7B,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;IAC1D,CAAC;IACD,KAAK,EAAE,CAAC;IACR,OAAO;QACL,MAAM,EAAE,UAAU,CAAC,MAAM;QACzB,IAAI,EAAE,CAAC,MAAM,EAAE,EAAE;YACf,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;gBACzB,aAAa,GAAG,IAAI,CAAC;gBACrB,OAAO;YACT,CAAC;YACD,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;YACrB,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;QAC1D,CAAC;KACF,CAAC;AACJ,CAAC,CAAC"}

package/dist/recovery.d.ts

@@ -0,0 +1,49 @@
+import { type AgentRunner, type AgentRuntimeContext, type EventBus, type JsonObject, type RunAbortedError, type Session } from '@stratusagent/core';
+import type { AgentSource } from './agent-source.ts';
+import type { SchedulerRuntime } from './schedules.ts';
+import type { ShardedSessionStore } from './sessions.ts';
+import type { DispatchInput } from './types.ts';
+import { type RuntimeConfig } from '@stratusagent/state';
+/** What restart recovery closes over in `createGateway`. */
+export interface RecoveryDeps {
+    log: (line: string) => void;
+    warn: (line: string) => void;
+    bus: EventBus;
+    store: ShardedSessionStore;
+    scheduler: SchedulerRuntime;
+    effectiveApprovalTimeoutMs: number;
+    refreshAgent: (agentId: string) => Promise<AgentSource>;
+    runtimeContextFor: (source: AgentSource, config: RuntimeConfig, onFallback: boolean, metadata: JsonObject | undefined, subAgent?: boolean) => AgentRuntimeContext;
+    runnerFor: (config: RuntimeConfig, agentId: string, subAgent?: boolean) => AgentRunner;
+    withWatchdog: <T>(sessionId: string, external: AbortSignal | undefined, idleEnabled: boolean, fallbackStreams: boolean, run: (signal: AbortSignal) => Promise<T>) => Promise<T>;
+    isStopping: () => boolean;
+    trackTurn: (sessionId: string, controller: AbortController) => void;
+    untrackTurn: (sessionId: string, controller: AbortController) => void;
+    getAbortingWith: () => string | undefined;
+    shutdownAbort: () => RunAbortedError;
+    activeTurns: Map<string, string>;
+    onTurnRuntime: <T>(sessionId: string, runtime: {
+        source: AgentSource;
+        config: RuntimeConfig;
+    }, work: () => Promise<T>) => Promise<T>;
+    getOrphanedAtStart: () => ReadonlySet<string>;
+    runtimeForAgent: (source: AgentSource) => Promise<RuntimeConfig>;
+    watchdogStreamsFor: (session: Pick<Session, 'metadata'> | undefined, config: RuntimeConfig) => {
+        switchedToFallback: boolean;
+        effectiveStreams: boolean;
+        fallbackStreams: boolean;
+    };
+    reachesHarness: (config: RuntimeConfig, switchedToFallback: boolean) => boolean;
+    onSessionChain: <T>(sessionId: string, work: () => Promise<T>, released?: () => boolean) => Promise<T>;
+}
+export declare const createRecovery: ({ log, warn, bus, store, scheduler, effectiveApprovalTimeoutMs, refreshAgent, runtimeContextFor, runnerFor, withWatchdog, isStopping, trackTurn, untrackTurn, getAbortingWith, shutdownAbort, activeTurns, onTurnRuntime, getOrphanedAtStart, runtimeForAgent, watchdogStreamsFor, reachesHarness, onSessionChain, }: RecoveryDeps) => {
+    recoverParkedTurns: (orphaned: ReadonlySet<string>) => Promise<void>;
+    listOrphanedDelegations: () => Promise<Set<string>>;
+    listAbandonedTurns: () => Promise<string[]>;
+    failAbandonedTurns: (abandoned: string[]) => Promise<void>;
+    settleRepeat: (sessionId: string, idempotencyKey: string, agentId: string | undefined, turnId: string | undefined, onRepeat: DispatchInput["onRepeat"]) => Promise<Session | undefined>;
+    archivedRepeat: (session: Session, idempotencyKey: string) => Promise<Session | undefined>;
+    settleUnfinished: (session: Session) => Promise<Session>;
+};
+export type Recovery = ReturnType<typeof createRecovery>;
+//# sourceMappingURL=recovery.d.ts.map

package/dist/recovery.d.ts.map

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