@stratusagent/gateway 0.11.4 → 0.11.6

package/dist/sessions.d.ts

@@ -0,0 +1,225 @@
+import type { Session, SessionStatus, SessionStore } from '@stratusagent/core';
+/**
+ * Sessions hold complete conversations (prompts, replies, tool output,
+ * provider replay state) — owner-only, like the credentials file. The file
+ * chmods cover databases created earlier under a looser umask too;
+ * directories the stores create are born 0700.
+ *
+ * Exported because the layout migration writes the same files from
+ * `@stratusagent/state` before any store is open, and a second hand-rolled
+ * chmod loop is how one of the two ends up leaving a sidecar readable.
+ */
+export declare const tightenSqliteFile: (filePath: string) => void;
+/**
+ * Durable session storage on node:sqlite (unflagged on Node 22.13+). The
+ * whole session — messages, status, and metadata, including provider replay
+ * state like the Anthropic raw-turn cache — round-trips as one JSON body,
+ * so a conversation resumed after a daemon restart replays exactly.
+ */
+export interface SqliteSessionStoreOptions {
+    /**
+     * The state home this file sits under, when it is one Stratus derived —
+     * `~/.stratus`, or whatever `--state-dir` made the home. Given it, the
+     * parent directory is tightened to owner-only even when it already exists
+     * (mkdir's mode only applies to what it creates, and an upgrade over a
+     * looser install must not stay world-readable) and every component below
+     * the home is required to be real, through `assertDerivedStatePath`.
+     *
+     * Left out for a caller-supplied path: a shared parent like `/tmp` or a
+     * project directory must never be chmodded implicitly, and its layout is
+     * not ours to have opinions about.
+     *
+     * Replaces `perAgent`, which approximated "did Stratus derive this path"
+     * and got the split wrong: the home is the *operator's* path and may be a
+     * link to another disk, so it is followed, while everything below it is a
+     * name Stratus chose, where nothing legitimate is a link. Naming the home
+     * says which is which, and says it about every component rather than the
+     * last one — so `fleet.db`, which lives directly in the home and was
+     * checked by neither boolean, is covered like any other derived name.
+     */
+    stateHome?: string;
+    /**
+     * Whether `stateHome` is itself Stratus's to tighten — true for the
+     * default `~/.stratus`, false for a state directory a caller supplied,
+     * which may sit in a shared parent that must not be chmodded from under
+     * whoever else uses it.
+     *
+     * Only about that one directory. Everything *below* the home is a
+     * directory Stratus created and is tightened either way, which is why
+     * this is not the same question as `stateHome` and cannot be folded into
+     * it: a caller-supplied state directory still gets `agents/<id>/` at
+     * `0700`, and still refuses a link there.
+     */
+    ownedHome?: boolean;
+}
+export declare class SqliteSessionStore implements SessionStore {
+    private readonly db;
+    constructor(filePath: string, options?: SqliteSessionStoreOptions);
+    private write;
+    create(input: Omit<Session, 'createdAt' | 'updatedAt'>): Promise<Session>;
+    get(id: string): Promise<Session | undefined>;
+    save(session: Session): Promise<void>;
+    /**
+     * The same save, handing back the row as it was written.
+     *
+     * For a caller that has to mirror it: the sharded store keeps the fleet
+     * index in step, and an index holding a timestamp the store does not is
+     * drift the startup reconcile would have to clean up every boot.
+     */
+    saveReturning(session: Session): Promise<Session>;
+    /**
+     * Session ids in a state, oldest first — the index a restarting daemon
+     * sweeps for turns parked on a human. The `status` column carries it, so
+     * no conversation body is deserialized to answer the question.
+     */
+    listIdsByStatus(status: SessionStatus): Promise<string[]>;
+    /**
+     * Every row's routing and lifecycle columns, no bodies — what the
+     * startup reconcile compares this shard against the fleet index with.
+     */
+    rows(): SessionIndexRow[];
+    close(): void;
+}
+/** One session's routing and lifecycle, as the fleet index holds it. */
+export interface SessionIndexRow {
+    id: string;
+    agentId: string;
+    status: SessionStatus;
+    createdAt: string;
+    updatedAt: string;
+}
+/**
+ * Thrown when a session id another agent already holds is claimed.
+ *
+ * Sessions never cross agent identities — the dispatcher says so when it
+ * finds the conversation, and this is the same rule at the durable seam,
+ * where a shared database's primary key used to enforce it for free.
+ */
+export declare class SessionIdTakenError extends Error {
+    constructor(sessionId: string, heldBy: string, claimedBy: string);
+}
+/**
+ * The fleet's session index, in `fleet.db` beside the schedules.
+ *
+ * Its own connection rather than a table on the schedule store, for the
+ * reason the schedule store gives for its own: `stratus schedules` opens
+ * that file from another process, and WAL is what makes two connections on
+ * one file routine.
+ */
+export declare class FleetSessionIndex {
+    private readonly db;
+    constructor(filePath: string, options?: SqliteSessionStoreOptions);
+    /**
+     * Claim an id for an agent, or refuse it.
+     *
+     * The claim is the create's single transactional authority: it lands
+     * before the shard write, so a crash between the two leaves a claim with
+     * no conversation — which the reconcile releases — rather than a
+     * conversation no lookup can reach. Re-claiming an id this agent already
+     * holds is genuinely a no-op: `create` on an existing id is how a caller
+     * re-opens its own session, and `save` claims every id it writes.
+     *
+     * Taking the id is all this does. It deliberately does NOT write the row
+     * it was handed, because the id it is claiming may already have a
+     * conversation: overwriting that row's status and timestamps here would
+     * announce a transition the shard write has not made yet, and a write
+     * that then fails leaves the live daemon answering from a lifecycle row
+     * no store agrees with — a pending session missing from recovery until
+     * the next restart reconciles it. The row is written by the caller,
+     * after the shard write, from what the store actually stored.
+     */
+    claim(row: SessionIndexRow): void;
+    /** Write the row as it now stands. Called after every shard write. */
+    record(row: SessionIndexRow): void;
+    /** Drop a claim — a reconcile releasing an id whose conversation never landed. */
+    release(id: string): void;
+    agentFor(id: string): string | undefined;
+    rows(): SessionIndexRow[];
+    idsByStatus(status: SessionStatus): string[];
+    countByStatus(): Record<string, number>;
+    lastActivityByAgent(): Record<string, {
+        lastActiveAt: string;
+        activeSessions: number;
+    }>;
+    list(agentId?: string, limit?: number): Array<Pick<Session, 'id' | 'status' | 'createdAt' | 'updatedAt'> & {
+        agentId: string;
+    }>;
+    close(): void;
+}
+/** What a startup reconcile put back in step, for the daemon's log. */
+export interface SessionReconcileReport {
+    /** Claims released: an id in the index whose conversation never landed. */
+    released: string[];
+    /** Sessions re-indexed: a conversation the index had lost, or disagreed about. */
+    reindexed: string[];
+}
+export interface ShardedSessionStoreOptions {
+    /** Where `agents/` and `fleet.db` live. The default is `~/.stratus`. */
+    stateDir: string;
+    /**
+     * Whether that directory is dedicated Stratus state and may be tightened
+     * to owner-only — see {@link SqliteSessionStoreOptions}.
+     */
+    ownedDirectory?: boolean;
+}
+/**
+ * The fleet's session store: one SQLite database per agent, behind the
+ * `SessionStore` every runner already takes, with the fleet-wide reads the
+ * control API and the restart sweeps need answered across all of them.
+ *
+ * A runner is handed *this* — and every write goes to the store opened on
+ * its own agent's path. What the facade adds is the set of questions that
+ * were never about one agent: which agent holds an id, how many sessions
+ * are in each state, when each agent last did anything, and which ids are
+ * parked or abandoned fleet-wide.
+ */
+export declare class ShardedSessionStore implements SessionStore {
+    private readonly stateDir;
+    private readonly ownedDirectory;
+    private readonly index;
+    private readonly shards;
+    constructor(options: ShardedSessionStoreOptions);
+    /**
+     * One agent's store, opened on first use and kept open.
+     *
+     * Opened lazily because a roster's agents are not all busy: a daemon
+     * with forty souls should hold descriptors for the ones that have
+     * conversations, not for every id on disk.
+     */
+    private shardFor;
+    create(input: Omit<Session, 'createdAt' | 'updatedAt'>): Promise<Session>;
+    get(id: string): Promise<Session | undefined>;
+    save(session: Session): Promise<void>;
+    listIdsByStatus(status: SessionStatus): Promise<string[]>;
+    countByStatus(): Record<string, number>;
+    lastActivityByAgent(): Record<string, {
+        lastActiveAt: string;
+        activeSessions: number;
+    }>;
+    list(agentId?: string, limit?: number): Array<Pick<Session, 'id' | 'status' | 'createdAt' | 'updatedAt'> & {
+        agentId: string;
+    }>;
+    /**
+     * Put the index and the shards back in step, before anything reads
+     * either. Two durable writes stand where one atomic primary key used to,
+     * and this is what makes a crash between them resolve one way rather
+     * than leaving them to disagree:
+     *
+     * - a claim whose conversation never landed is released, freeing the id;
+     * - a conversation the index has lost — or disagrees with — is
+     *   re-indexed from the shard, which is the record;
+     * - the same id in two agents' shards is refused loudly, naming both,
+     *   because picking one would silently hand somebody else's conversation
+     *   to whoever asks for that id next.
+     */
+    reconcile(): Promise<SessionReconcileReport>;
+    /**
+     * Which agents have a store on disk — the roster is not the answer, on
+     * purpose: the gateway keeps a missing soul's sessions when it drops the
+     * soul, and a recovery sweep that skipped those would strand exactly the
+     * conversations nobody is watching.
+     */
+    private shardedAgentIds;
+    close(): void;
+}
+//# sourceMappingURL=sessions.d.ts.map

package/dist/sessions.d.ts.map

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