@stratusagent/gateway 0.14.7 → 0.14.8

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/session-keys.d.ts

@@ -0,0 +1,101 @@
+import { type JsonObject, type Session } from '@stratusagent/core';
+/**
+ * Recorded on a turn the previous process was still running when it died.
+ *
+ * Exported because "distinguishable" is the whole point: a surface, a
+ * test, or an operator reading `lastError` has to be able to tell a turn
+ * nobody finished apart from one a provider or a tool actually failed, and
+ * matching on prose that lives in one place beats each caller inventing
+ * its own guess at the wording.
+ */
+export declare const ABANDONED_TURN_ERROR = "stratusd stopped while this turn was still running; it was not resumed. Send the message again.";
+/**
+ * The longest `DispatchInput.idempotencyKey` accepted. A platform message id
+ * is far shorter; the bound is so a key cannot be used to grow every row it
+ * is stored on.
+ */
+/**
+ * Recorded on a delegated sub-session that was parked on a human when the
+ * previous process died.
+ *
+ * Its parent — the turn whose `agent.delegate` call was awaiting the reply
+ * — was running, so the restart settles it as abandoned (above). Recovering
+ * the child anyway would re-ask a person to approve a call whose result no
+ * turn will ever read, and then run it: a command executed, tokens spent,
+ * and a reply delivered to nobody. Distinguishable from the parent's error
+ * because the remedy differs — there is no message to send again here;
+ * the parent's is the one to repeat.
+ */
+/**
+ * Session metadata keys the daemon writes for itself, which no external
+ * dispatch may supply.
+ *
+ * Metadata is one bag: the keys a channel attaches to say where a turn is
+ * happening sit beside the ones the kernel, the scheduler, the fallback
+ * wrapper, and `agent.delegate` write to remember what a session *is* —
+ * and the control API forwards a caller's `metadata` into a new session as
+ * given. A caller who can write `delegatedBy` can have the restart sweep
+ * fail its own parked turn as an orphan; one who can write `fallbackActive`
+ * bills its conversation to the fallback model from the first turn. The
+ * scheduler already refused to trust its own keys for exactly this reason
+ * (see `activeFirings`); the durable ones cannot be re-derived in memory,
+ * so they are refused at the door instead.
+ */
+/**
+ * A rolled-over session: the fresh row records where its predecessor's
+ * transcript went, and the archived row records which live id continues
+ * the conversation. See `Gateway.rolloverSession`.
+ */
+export declare const ROLLED_OVER_FROM_METADATA_KEY = "rolledOverFrom";
+export declare const ROLLED_OVER_TO_METADATA_KEY = "rolledOverTo";
+/** The segment a rollover mints into the archived transcript's id. */
+export declare const ROLLED_OVER_SESSION_ID_MARKER = ":rolledover:";
+/**
+ * How long after a rollover a repeated key is still looked for in the
+ * archived transcript. A rollover moves every keyed message out of the
+ * live row, so a redelivery arriving after one would otherwise read as a
+ * new message and run again. Platforms redeliver within minutes — Slack
+ * gives up after about five — and past the window the archive is not
+ * loaded at all, since every new message to the fresh row would pay for a
+ * read that can no longer find anything.
+ */
+export declare const ROLLOVER_REPEAT_WINDOW_MS: number;
+/**
+ * The one refusal for a dispatch naming an agent other than its session's.
+ * Its own type so a repeat attached to a claimant can tell the claimant was
+ * refused for who it named — the item then still has no owner — from the
+ * claimant's turn failing. Internal: callers read the message.
+ */
+export declare class CrossIdentityError extends Error {
+    constructor(sessionId: string, owner: string, claimed: string);
+}
+export declare const crossIdentityError: (sessionId: string, owner: string, claimed: string) => Error;
+/** Where the session's tool calls ran: `local-command`, or a contributed executor's registered name. */
+export declare const EXECUTOR_METADATA_KEY = "executor";
+/**
+ * Marks a sub-agent's session (roadmap 24). Reserved: it is what makes the
+ * daemon deny the session's gated calls without asking anyone, so a caller
+ * that could set it could also clear it.
+ */
+export declare const SUB_AGENT_METADATA_KEY = "subAgent";
+export declare const SUB_AGENT_SESSION_ID_MARKER = ":subagent:";
+/** How many sub-agents one parent turn runs at once unless the host says otherwise. */
+export declare const DEFAULT_SUB_AGENTS_PER_TURN = 4;
+export declare const isSubAgentSession: (session: Pick<Session, "id" | "metadata">) => boolean;
+/**
+ * Tools a sub-agent never gets, whatever its parent holds. `agent.spawn`
+ * would fan out inside a fan-out; `agent.delegate` runs a roster agent
+ * under that agent's own allowlist, which is the way out of a narrowed
+ * slice; `memory.*` would let it persist what nobody reviewed; and
+ * `credential.request` asks a person, which a sub-agent never does.
+ */
+export declare const subAgentNeverGets: (name: string) => boolean;
+export declare const RESERVED_SESSION_METADATA_KEYS: readonly string[];
+/**
+ * The first reserved key `metadata` carries, or undefined when it carries
+ * none. Exported so the control API can refuse the request where the
+ * caller can see it, with the same rule the gateway applies at dispatch.
+ */
+export declare const reservedSessionMetadataKey: (metadata: JsonObject | undefined) => string | undefined;
+export declare const ORPHANED_DELEGATION_ERROR = "stratusd stopped while the turn that delegated this one was still running; the delegation was not resumed. Send the original message again.";
+//# sourceMappingURL=session-keys.d.ts.map

package/dist/session-keys.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-keys.d.ts","sourceRoot":"","sources":["../src/session-keys.ts"],"names":[],"mappings":"AAOA,OAAO,EAGL,KAAK,UAAU,EAEf,KAAK,OAAO,EAGb,MAAM,oBAAoB,CAAC;AAY5B;;;;;;;;GAQG;AACH,eAAO,MAAM,oBAAoB,oGACkE,CAAC;AAEpG;;;;GAIG;AAEH;;;;;;;;;;;GAWG;AACH;;;;;;;;;;;;;;GAcG;AACH;;;;GAIG;AACH,eAAO,MAAM,6BAA6B,mBAAmB,CAAC;AAC9D,eAAO,MAAM,2BAA2B,iBAAiB,CAAC;AAC1D,sEAAsE;AACtE,eAAO,MAAM,6BAA6B,iBAAiB,CAAC;AAE5D;;;;;;;;GAQG;AACH,eAAO,MAAM,yBAAyB,QAAiB,CAAC;AAExD;;;;;GAKG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;gBAC/B,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;CAI9D;AAED,eAAO,MAAM,kBAAkB,GAAI,WAAW,MAAM,EAAE,OAAO,MAAM,EAAE,SAAS,MAAM,KAAG,KACpC,CAAC;AAEpD,wGAAwG;AACxG,eAAO,MAAM,qBAAqB,aAAa,CAAC;AAEhD;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,aAAa,CAAC;AACjD,eAAO,MAAM,2BAA2B,eAAe,CAAC;AACxD,uFAAuF;AACvF,eAAO,MAAM,2BAA2B,IAAI,CAAC;AAE7C,eAAO,MAAM,iBAAiB,GAAI,SAAS,IAAI,CAAC,OAAO,EAAE,IAAI,GAAG,UAAU,CAAC,KAAG,OAC2B,CAAC;AAE1G;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,GAAI,MAAM,MAAM,KAAG,OAIP,CAAC;AAE3C,eAAO,MAAM,8BAA8B,EAAE,SAAS,MAAM,EA8B3D,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,0BAA0B,GAAI,UAAU,UAAU,GAAG,SAAS,KAAG,MAAM,GAAG,SAGgB,CAAC;AAExG,eAAO,MAAM,yBAAyB,gJACyG,CAAC"}

package/dist/session-keys.js

@@ -0,0 +1,148 @@
+/*
+ * What the gateway reserves on a session: the metadata keys a caller may not
+ * set, the id markers and keys of rolled-over and sub-agent sessions, and the
+ * errors a turn or a delegation cut short by a stopped daemon records. Moved
+ * out of `index.ts` as is; `index.ts` re-exports the public names, so the
+ * package's surface is unchanged.
+ */
+import { CONTEXT_FLOOR_METADATA_KEY, CONTEXT_SUMMARY_METADATA_KEY, PENDING_APPROVAL_METADATA_KEY, SESSION_TAINTED_BY_METADATA_KEY, SESSION_TRUST_METADATA_KEY, } from '@stratusagent/core';
+import { CREDENTIAL_REQUEST_TOOL_NAME, DELEGATE_TOOL_NAME, DELEGATED_BY_METADATA_KEY, DELEGATION_DEPTH_METADATA_KEY, ROOT_SESSION_ID_METADATA_KEY, SCHEDULE_ID_METADATA_KEY, SCHEDULED_TURN_METADATA_KEY, } from '@stratusagent/agents';
+import { FALLBACK_ACTIVE_METADATA_KEY } from '@stratusagent/state';
+/**
+ * Recorded on a turn the previous process was still running when it died.
+ *
+ * Exported because "distinguishable" is the whole point: a surface, a
+ * test, or an operator reading `lastError` has to be able to tell a turn
+ * nobody finished apart from one a provider or a tool actually failed, and
+ * matching on prose that lives in one place beats each caller inventing
+ * its own guess at the wording.
+ */
+export const ABANDONED_TURN_ERROR = 'stratusd stopped while this turn was still running; it was not resumed. Send the message again.';
+/**
+ * The longest `DispatchInput.idempotencyKey` accepted. A platform message id
+ * is far shorter; the bound is so a key cannot be used to grow every row it
+ * is stored on.
+ */
+/**
+ * Recorded on a delegated sub-session that was parked on a human when the
+ * previous process died.
+ *
+ * Its parent — the turn whose `agent.delegate` call was awaiting the reply
+ * — was running, so the restart settles it as abandoned (above). Recovering
+ * the child anyway would re-ask a person to approve a call whose result no
+ * turn will ever read, and then run it: a command executed, tokens spent,
+ * and a reply delivered to nobody. Distinguishable from the parent's error
+ * because the remedy differs — there is no message to send again here;
+ * the parent's is the one to repeat.
+ */
+/**
+ * Session metadata keys the daemon writes for itself, which no external
+ * dispatch may supply.
+ *
+ * Metadata is one bag: the keys a channel attaches to say where a turn is
+ * happening sit beside the ones the kernel, the scheduler, the fallback
+ * wrapper, and `agent.delegate` write to remember what a session *is* —
+ * and the control API forwards a caller's `metadata` into a new session as
+ * given. A caller who can write `delegatedBy` can have the restart sweep
+ * fail its own parked turn as an orphan; one who can write `fallbackActive`
+ * bills its conversation to the fallback model from the first turn. The
+ * scheduler already refused to trust its own keys for exactly this reason
+ * (see `activeFirings`); the durable ones cannot be re-derived in memory,
+ * so they are refused at the door instead.
+ */
+/**
+ * A rolled-over session: the fresh row records where its predecessor's
+ * transcript went, and the archived row records which live id continues
+ * the conversation. See `Gateway.rolloverSession`.
+ */
+export const ROLLED_OVER_FROM_METADATA_KEY = 'rolledOverFrom';
+export const ROLLED_OVER_TO_METADATA_KEY = 'rolledOverTo';
+/** The segment a rollover mints into the archived transcript's id. */
+export const ROLLED_OVER_SESSION_ID_MARKER = ':rolledover:';
+/**
+ * How long after a rollover a repeated key is still looked for in the
+ * archived transcript. A rollover moves every keyed message out of the
+ * live row, so a redelivery arriving after one would otherwise read as a
+ * new message and run again. Platforms redeliver within minutes — Slack
+ * gives up after about five — and past the window the archive is not
+ * loaded at all, since every new message to the fresh row would pay for a
+ * read that can no longer find anything.
+ */
+export const ROLLOVER_REPEAT_WINDOW_MS = 60 * 60 * 1000;
+/**
+ * The one refusal for a dispatch naming an agent other than its session's.
+ * Its own type so a repeat attached to a claimant can tell the claimant was
+ * refused for who it named — the item then still has no owner — from the
+ * claimant's turn failing. Internal: callers read the message.
+ */
+export class CrossIdentityError extends Error {
+    constructor(sessionId, owner, claimed) {
+        super(`Session ${sessionId} belongs to agent ${owner}, not ${claimed} — sessions never cross agent identities.`);
+        this.name = 'CrossIdentityError';
+    }
+}
+export const crossIdentityError = (sessionId, owner, claimed) => new CrossIdentityError(sessionId, owner, claimed);
+/** Where the session's tool calls ran: `local-command`, or a contributed executor's registered name. */
+export const EXECUTOR_METADATA_KEY = 'executor';
+/**
+ * Marks a sub-agent's session (roadmap 24). Reserved: it is what makes the
+ * daemon deny the session's gated calls without asking anyone, so a caller
+ * that could set it could also clear it.
+ */
+export const SUB_AGENT_METADATA_KEY = 'subAgent';
+export const SUB_AGENT_SESSION_ID_MARKER = ':subagent:';
+/** How many sub-agents one parent turn runs at once unless the host says otherwise. */
+export const DEFAULT_SUB_AGENTS_PER_TURN = 4;
+export const isSubAgentSession = (session) => session.metadata?.[SUB_AGENT_METADATA_KEY] === true && session.id.includes(SUB_AGENT_SESSION_ID_MARKER);
+/**
+ * Tools a sub-agent never gets, whatever its parent holds. `agent.spawn`
+ * would fan out inside a fan-out; `agent.delegate` runs a roster agent
+ * under that agent's own allowlist, which is the way out of a narrowed
+ * slice; `memory.*` would let it persist what nobody reviewed; and
+ * `credential.request` asks a person, which a sub-agent never does.
+ */
+export const subAgentNeverGets = (name) => name === 'agent.spawn'
+    || name === DELEGATE_TOOL_NAME
+    || name.startsWith('memory.')
+    || name === CREDENTIAL_REQUEST_TOOL_NAME;
+export const RESERVED_SESSION_METADATA_KEYS = [
+    PENDING_APPROVAL_METADATA_KEY,
+    FALLBACK_ACTIVE_METADATA_KEY,
+    DELEGATED_BY_METADATA_KEY,
+    ROOT_SESSION_ID_METADATA_KEY,
+    DELEGATION_DEPTH_METADATA_KEY,
+    SCHEDULED_TURN_METADATA_KEY,
+    SCHEDULE_ID_METADATA_KEY,
+    // The trust label is the runner's to write and only ever goes down; a
+    // caller who could seed it would be seeding it upward.
+    SESSION_TRUST_METADATA_KEY,
+    SESSION_TAINTED_BY_METADATA_KEY,
+    ROLLED_OVER_FROM_METADATA_KEY,
+    ROLLED_OVER_TO_METADATA_KEY,
+    // Which executor ran the turn's tool calls is the daemon's record of
+    // where a command ran, and the one audit question a caller must not be
+    // able to answer for it.
+    EXECUTOR_METADATA_KEY,
+    // The context floor is an index into a specific transcript, so it means
+    // nothing next to a different one. Reserved for both halves of that: a
+    // caller cannot seed it, and a rollover drops it with the transcript it
+    // indexed — otherwise the fresh session inherits an absolute floor over
+    // no messages and, once it grows past that index, silently stops sending
+    // its own earliest turns, with no overflow and no trim event to say so.
+    CONTEXT_FLOOR_METADATA_KEY,
+    // The summary that stands in below that floor, for both of the same
+    // reasons, and one more: the model reads it as something it wrote itself,
+    // so a caller who could seed it could put words in the agent's mouth.
+    CONTEXT_SUMMARY_METADATA_KEY,
+    SUB_AGENT_METADATA_KEY,
+];
+/**
+ * The first reserved key `metadata` carries, or undefined when it carries
+ * none. Exported so the control API can refuse the request where the
+ * caller can see it, with the same rule the gateway applies at dispatch.
+ */
+export const reservedSessionMetadataKey = (metadata) => metadata === undefined
+    ? undefined
+    : RESERVED_SESSION_METADATA_KEYS.find((key) => Object.prototype.hasOwnProperty.call(metadata, key));
+export const ORPHANED_DELEGATION_ERROR = 'stratusd stopped while the turn that delegated this one was still running; the delegation was not resumed. Send the original message again.';
+//# sourceMappingURL=session-keys.js.map

package/dist/session-keys.js.map

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