@telorun/runner-core 0.5.2

package/dist/server.js

@@ -0,0 +1,67 @@
+import Fastify from "fastify";
+import cors from "@fastify/cors";
+import websocket from "@fastify/websocket";
+import { capabilitiesRoute } from "./routes/capabilities.js";
+import { healthRoute } from "./routes/health.js";
+import { ioRoute } from "./routes/io.js";
+import { probeRoute } from "./routes/probe.js";
+import { sessionsRoute } from "./routes/sessions.js";
+import { SessionRegistry } from "./session/registry.js";
+export async function buildServer(deps) {
+    const app = Fastify({
+        logger: { level: deps.config.logLevel },
+    });
+    // CORS: SSE and fetch from the editor's browser origin are cross-origin by
+    // default. A runner with no auth is driven by whoever can reach the port, so
+    // default to `*` and let operators narrow via RUNNER_CORS_ORIGINS.
+    await app.register(cors, {
+        origin: deps.config.corsOrigins,
+        methods: ["GET", "POST", "DELETE", "OPTIONS"],
+    });
+    await app.register(websocket);
+    const registry = deps.registry ??
+        new SessionRegistry({
+            maxSessions: deps.config.maxSessions,
+            exitTtlMs: deps.config.exitTtlMs,
+            replayBufferBytes: deps.config.replayBufferBytes,
+        });
+    // Terms are stable across the process — resolve the capabilities once for them
+    // even when `capabilities` is a getter (the route still re-resolves per request).
+    const capabilitiesValue = typeof deps.capabilities === "function" ? deps.capabilities() : deps.capabilities;
+    await app.register(healthRoute(deps.version));
+    await app.register(capabilitiesRoute(deps.capabilities));
+    await app.register(probeRoute({ backend: deps.backend }));
+    await app.register(sessionsRoute({
+        backend: deps.backend,
+        registry,
+        corsOrigins: deps.config.corsOrigins,
+        defaultRegistryUrl: deps.defaultRegistryUrl,
+        validateConfig: deps.validateConfig,
+        // The capabilities document is the single source of the runner's terms;
+        // the session route enforces what /v1/capabilities advertises.
+        terms: capabilitiesValue.terms,
+    }));
+    await app.register(ioRoute({ registry, corsOrigins: deps.config.corsOrigins }));
+    return { app, registry };
+}
+/**
+ * Stop every live session. Used by graceful shutdown — marks each entry
+ * userStopped and stops its backend workload so nothing leaks past process
+ * exit. Backend-neutral: it only touches the abstract `BackendSession`.
+ */
+export async function stopAllSessions(registry, log) {
+    const live = registry.list().filter((e) => e.session !== null && e.exitedAt === null);
+    if (live.length === 0)
+        return;
+    log.info({ count: live.length }, "stopping live sessions before shutdown");
+    await Promise.all(live.map(async (entry) => {
+        entry.userStopped = true;
+        try {
+            await entry.session?.stop();
+        }
+        catch (err) {
+            log.warn({ err, sessionId: entry.sessionId }, "failed to stop session during shutdown");
+        }
+    }));
+}
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

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

package/dist/session/bundle-path.d.ts

@@ -0,0 +1,12 @@
+export declare class BundlePathError extends Error {
+}
+/**
+ * Bundle file paths arrive POSIX-style and untrusted. Guard against traversal
+ * explicitly rather than trusting `path.resolve` — an `entryRelativePath` or
+ * `files[].relativePath` of `../foo` would escape the session's own directory.
+ * Backend-neutral: every backend normalizes paths the same way before placing
+ * files, regardless of how it ultimately delivers the bundle.
+ */
+export declare function normalizeBundlePath(p: string): string;
+export declare function validateSessionId(id: string): void;
+//# sourceMappingURL=bundle-path.d.ts.map

package/dist/session/bundle-path.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bundle-path.d.ts","sourceRoot":"","sources":["../../src/session/bundle-path.ts"],"names":[],"mappings":"AAEA,qBAAa,eAAgB,SAAQ,KAAK;CAAG;AAE7C;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CASrD;AAED,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAIlD"}

package/dist/session/bundle-path.js

@@ -0,0 +1,27 @@
+import { posix } from "node:path";
+export class BundlePathError extends Error {
+}
+/**
+ * Bundle file paths arrive POSIX-style and untrusted. Guard against traversal
+ * explicitly rather than trusting `path.resolve` — an `entryRelativePath` or
+ * `files[].relativePath` of `../foo` would escape the session's own directory.
+ * Backend-neutral: every backend normalizes paths the same way before placing
+ * files, regardless of how it ultimately delivers the bundle.
+ */
+export function normalizeBundlePath(p) {
+    const normalized = posix.normalize(p).replace(/^\/+/, "");
+    if (normalized === "" || normalized === "." || normalized.startsWith("../") || normalized === "..") {
+        throw new BundlePathError(`invalid bundle relativePath '${p}'`);
+    }
+    for (const part of normalized.split("/")) {
+        if (part === "..")
+            throw new BundlePathError(`invalid bundle relativePath '${p}'`);
+    }
+    return normalized;
+}
+export function validateSessionId(id) {
+    if (!/^[a-zA-Z0-9_-]+$/.test(id)) {
+        throw new BundlePathError(`invalid sessionId '${id}' (must match /^[a-zA-Z0-9_-]+$/)`);
+    }
+}
+//# sourceMappingURL=bundle-path.js.map

package/dist/session/bundle-path.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bundle-path.js","sourceRoot":"","sources":["../../src/session/bundle-path.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,WAAW,CAAC;AAElC,MAAM,OAAO,eAAgB,SAAQ,KAAK;CAAG;AAE7C;;;;;;GAMG;AACH,MAAM,UAAU,mBAAmB,CAAC,CAAS;IAC3C,MAAM,UAAU,GAAG,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IAC1D,IAAI,UAAU,KAAK,EAAE,IAAI,UAAU,KAAK,GAAG,IAAI,UAAU,CAAC,UAAU,CAAC,KAAK,CAAC,IAAI,UAAU,KAAK,IAAI,EAAE,CAAC;QACnG,MAAM,IAAI,eAAe,CAAC,gCAAgC,CAAC,GAAG,CAAC,CAAC;IAClE,CAAC;IACD,KAAK,MAAM,IAAI,IAAI,UAAU,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;QACzC,IAAI,IAAI,KAAK,IAAI;YAAE,MAAM,IAAI,eAAe,CAAC,gCAAgC,CAAC,GAAG,CAAC,CAAC;IACrF,CAAC;IACD,OAAO,UAAU,CAAC;AACpB,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,EAAU;IAC1C,IAAI,CAAC,kBAAkB,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,CAAC;QACjC,MAAM,IAAI,eAAe,CAAC,sBAAsB,EAAE,mCAAmC,CAAC,CAAC;IACzF,CAAC;AACH,CAAC"}

package/dist/session/byte-ring-buffer.d.ts

@@ -0,0 +1,29 @@
+export interface BufferedBytes {
+    seq: number;
+    bytes: Buffer;
+}
+/**
+ * Byte-capped FIFO ring buffer for raw PTY output replay. Mirrors
+ * EventRingBuffer's eviction-with-gap semantics but stores Buffer slices keyed
+ * by a monotonic seq number — never reused, never reset.
+ *
+ * A client's `?lastSeq=<n>` asks for chunks with seq > n; if the oldest
+ * remaining seq is still > n+1, the gap must be signaled separately.
+ */
+export declare class ByteRingBuffer {
+    private readonly maxBytes;
+    private readonly entries;
+    private totalBytes;
+    private nextSeq;
+    constructor(maxBytes: number);
+    push(bytes: Buffer): BufferedBytes;
+    private evict;
+    replay(afterSeq: number): {
+        entries: BufferedBytes[];
+        hasGap: boolean;
+    };
+    get size(): number;
+    get bytes(): number;
+    get latestSeq(): number;
+}
+//# sourceMappingURL=byte-ring-buffer.d.ts.map

package/dist/session/byte-ring-buffer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"byte-ring-buffer.d.ts","sourceRoot":"","sources":["../../src/session/byte-ring-buffer.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;GAOG;AACH,qBAAa,cAAc;IAKb,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAJrC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAuB;IAC/C,OAAO,CAAC,UAAU,CAAK;IACvB,OAAO,CAAC,OAAO,CAAK;gBAES,QAAQ,EAAE,MAAM;IAM7C,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,aAAa;IASlC,OAAO,CAAC,KAAK;IAUb,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG;QAAE,OAAO,EAAE,aAAa,EAAE,CAAC;QAAC,MAAM,EAAE,OAAO,CAAA;KAAE;IAOvE,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,IAAI,KAAK,IAAI,MAAM,CAElB;IAED,IAAI,SAAS,IAAI,MAAM,CAEtB;CACF"}

package/dist/session/byte-ring-buffer.js

@@ -0,0 +1,54 @@
+/**
+ * Byte-capped FIFO ring buffer for raw PTY output replay. Mirrors
+ * EventRingBuffer's eviction-with-gap semantics but stores Buffer slices keyed
+ * by a monotonic seq number — never reused, never reset.
+ *
+ * A client's `?lastSeq=<n>` asks for chunks with seq > n; if the oldest
+ * remaining seq is still > n+1, the gap must be signaled separately.
+ */
+export class ByteRingBuffer {
+    maxBytes;
+    entries = [];
+    totalBytes = 0;
+    nextSeq = 1;
+    constructor(maxBytes) {
+        this.maxBytes = maxBytes;
+        if (!Number.isInteger(maxBytes) || maxBytes <= 0) {
+            throw new Error(`ByteRingBuffer maxBytes must be a positive integer, got ${maxBytes}`);
+        }
+    }
+    push(bytes) {
+        const seq = this.nextSeq++;
+        const entry = { seq, bytes };
+        this.entries.push(entry);
+        this.totalBytes += bytes.byteLength;
+        this.evict();
+        return entry;
+    }
+    evict() {
+        // Always retain at least the most-recent entry, even if it alone exceeds
+        // maxBytes — same invariant as EventRingBuffer.
+        while (this.totalBytes > this.maxBytes && this.entries.length > 1) {
+            const dropped = this.entries.shift();
+            if (!dropped)
+                break;
+            this.totalBytes -= dropped.bytes.byteLength;
+        }
+    }
+    replay(afterSeq) {
+        const entries = this.entries.filter((e) => e.seq > afterSeq);
+        const oldestSeq = this.entries[0]?.seq ?? this.nextSeq;
+        const hasGap = afterSeq + 1 < oldestSeq;
+        return { entries, hasGap };
+    }
+    get size() {
+        return this.entries.length;
+    }
+    get bytes() {
+        return this.totalBytes;
+    }
+    get latestSeq() {
+        return this.nextSeq - 1;
+    }
+}
+//# sourceMappingURL=byte-ring-buffer.js.map

package/dist/session/byte-ring-buffer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"byte-ring-buffer.js","sourceRoot":"","sources":["../../src/session/byte-ring-buffer.ts"],"names":[],"mappings":"AAKA;;;;;;;GAOG;AACH,MAAM,OAAO,cAAc;IAKI;IAJZ,OAAO,GAAoB,EAAE,CAAC;IACvC,UAAU,GAAG,CAAC,CAAC;IACf,OAAO,GAAG,CAAC,CAAC;IAEpB,YAA6B,QAAgB;QAAhB,aAAQ,GAAR,QAAQ,CAAQ;QAC3C,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,QAAQ,CAAC,IAAI,QAAQ,IAAI,CAAC,EAAE,CAAC;YACjD,MAAM,IAAI,KAAK,CAAC,2DAA2D,QAAQ,EAAE,CAAC,CAAC;QACzF,CAAC;IACH,CAAC;IAED,IAAI,CAAC,KAAa;QAChB,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,EAAE,CAAC;QAC3B,MAAM,KAAK,GAAkB,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC;QAC5C,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACzB,IAAI,CAAC,UAAU,IAAI,KAAK,CAAC,UAAU,CAAC;QACpC,IAAI,CAAC,KAAK,EAAE,CAAC;QACb,OAAO,KAAK,CAAC;IACf,CAAC;IAEO,KAAK;QACX,yEAAyE;QACzE,gDAAgD;QAChD,OAAO,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,QAAQ,IAAI,IAAI,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAClE,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;YACrC,IAAI,CAAC,OAAO;gBAAE,MAAM;YACpB,IAAI,CAAC,UAAU,IAAI,OAAO,CAAC,KAAK,CAAC,UAAU,CAAC;QAC9C,CAAC;IACH,CAAC;IAED,MAAM,CAAC,QAAgB;QACrB,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,GAAG,QAAQ,CAAC,CAAC;QAC7D,MAAM,SAAS,GAAG,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,GAAG,IAAI,IAAI,CAAC,OAAO,CAAC;QACvD,MAAM,MAAM,GAAG,QAAQ,GAAG,CAAC,GAAG,SAAS,CAAC;QACxC,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC;IAC7B,CAAC;IAED,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC;IAC7B,CAAC;IAED,IAAI,KAAK;QACP,OAAO,IAAI,CAAC,UAAU,CAAC;IACzB,CAAC;IAED,IAAI,SAAS;QACX,OAAO,IAAI,CAAC,OAAO,GAAG,CAAC,CAAC;IAC1B,CAAC;CACF"}

package/dist/session/registry.d.ts

@@ -0,0 +1,62 @@
+import { EventEmitter } from "node:events";
+import type { BackendSession } from "../backend.js";
+import { type RunEvent, type RunStatus } from "../contract.js";
+import { ByteRingBuffer, type BufferedBytes } from "./byte-ring-buffer.js";
+import { EventRingBuffer, type BufferedEvent } from "./ring-buffer.js";
+export interface SessionEntry {
+    readonly sessionId: string;
+    readonly createdAt: Date;
+    readonly buffer: EventRingBuffer;
+    readonly byteBuffer: ByteRingBuffer;
+    readonly emitter: EventEmitter;
+    readonly byteEmitter: EventEmitter;
+    /** The live backend workload. Null until `start` resolves; the route writes
+     *  stdin / resize / stop through it. A backend's `writeStdin` is a no-op once
+     *  the workload has terminated, so callers need not null it on exit. */
+    session: BackendSession | null;
+    status: RunStatus;
+    exitedAt: Date | null;
+    userStopped: boolean;
+    evictionTimer: NodeJS.Timeout | null;
+}
+export interface RegistryDeps {
+    maxSessions: number;
+    exitTtlMs: number;
+    replayBufferBytes: number;
+}
+export declare class SessionLimitError extends Error {
+}
+export declare class SessionEvictedError extends Error {
+}
+export declare class SessionRegistry {
+    private readonly deps;
+    private readonly sessions;
+    constructor(deps: RegistryDeps);
+    size(): number;
+    has(sessionId: string): boolean;
+    get(sessionId: string): SessionEntry | undefined;
+    list(): SessionEntry[];
+    /**
+     * Creates a fresh registry entry. Callers are responsible for guarding against
+     * duplicate insertion. Throws SessionLimitError if we're at capacity.
+     */
+    register(args: {
+        sessionId: string;
+    }): SessionEntry;
+    pushBytes(sessionId: string, bytes: Buffer): BufferedBytes | undefined;
+    subscribeBytes(sessionId: string, listener: (b: BufferedBytes) => void): () => void;
+    emit(sessionId: string, event: RunEvent): BufferedEvent | undefined;
+    subscribe(sessionId: string, listener: (e: BufferedEvent) => void): () => void;
+    /** Free a slot at capacity by removing the oldest already-terminated session
+     *  (by exit time). Retained exited sessions are history kept for re-attach, so
+     *  they yield to a new run rather than blocking it; live sessions are never
+     *  evicted. Returns false when every session is still live. */
+    private evictOldestTerminal;
+    private scheduleEviction;
+    /**
+     * Remove an entry immediately (used by shutdown sweeps and startup cleanup).
+     * Returns true if it was present.
+     */
+    remove(sessionId: string): boolean;
+}
+//# sourceMappingURL=registry.d.ts.map

package/dist/session/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/session/registry.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AACpD,OAAO,EAAc,KAAK,QAAQ,EAAE,KAAK,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3E,OAAO,EAAE,cAAc,EAAE,KAAK,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAC3E,OAAO,EAAE,eAAe,EAAE,KAAK,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAEvE,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,EAAE,IAAI,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAC;IACjC,QAAQ,CAAC,UAAU,EAAE,cAAc,CAAC;IACpC,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC;IAC/B,QAAQ,CAAC,WAAW,EAAE,YAAY,CAAC;IAEnC;;4EAEwE;IACxE,OAAO,EAAE,cAAc,GAAG,IAAI,CAAC;IAC/B,MAAM,EAAE,SAAS,CAAC;IAClB,QAAQ,EAAE,IAAI,GAAG,IAAI,CAAC;IACtB,WAAW,EAAE,OAAO,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC,OAAO,GAAG,IAAI,CAAC;CACtC;AAED,MAAM,WAAW,YAAY;IAC3B,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAaD,qBAAa,iBAAkB,SAAQ,KAAK;CAAG;AAC/C,qBAAa,mBAAoB,SAAQ,KAAK;CAAG;AAEjD,qBAAa,eAAe;IAGd,OAAO,CAAC,QAAQ,CAAC,IAAI;IAFjC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAmC;gBAE/B,IAAI,EAAE,YAAY;IAE/C,IAAI,IAAI,MAAM;IAId,GAAG,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO;IAI/B,GAAG,CAAC,SAAS,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS;IAIhD,IAAI,IAAI,YAAY,EAAE;IAItB;;;OAGG;IACH,QAAQ,CAAC,IAAI,EAAE;QAAE,SAAS,EAAE,MAAM,CAAA;KAAE,GAAG,YAAY;IA6BnD,SAAS,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS;IAqBtE,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,CAAC,EAAE,aAAa,KAAK,IAAI,GAAG,MAAM,IAAI;IAOnF,IAAI,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,GAAG,aAAa,GAAG,SAAS;IAenE,SAAS,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,CAAC,EAAE,aAAa,KAAK,IAAI,GAAG,MAAM,IAAI;IAO9E;;;mEAG+D;IAC/D,OAAO,CAAC,mBAAmB;IAU3B,OAAO,CAAC,gBAAgB;IAUxB;;;OAGG;IACH,MAAM,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO;CAOnC"}

package/dist/session/registry.js

@@ -0,0 +1,156 @@
+import { EventEmitter } from "node:events";
+import { isTerminal } from "../contract.js";
+import { ByteRingBuffer } from "./byte-ring-buffer.js";
+import { EventRingBuffer } from "./ring-buffer.js";
+const EVENT_EMITTED = "event";
+const BYTES_EMITTED = "chunk";
+/** Cap on a single buffered byte chunk. Without this, one huge workload
+ *  burst (`cat largefile`) could be admitted as one entry; the ring
+ *  buffer's "retain at least one" invariant would then keep that one
+ *  oversized entry resident regardless of `replayBufferBytes`. Splitting
+ *  on push means the cap actually bounds memory and the eviction loop
+ *  has fine-grained units to drop. */
+const MAX_PUSH_CHUNK = 64 * 1024;
+export class SessionLimitError extends Error {
+}
+export class SessionEvictedError extends Error {
+}
+export class SessionRegistry {
+    deps;
+    sessions = new Map();
+    constructor(deps) {
+        this.deps = deps;
+    }
+    size() {
+        return this.sessions.size;
+    }
+    has(sessionId) {
+        return this.sessions.has(sessionId);
+    }
+    get(sessionId) {
+        return this.sessions.get(sessionId);
+    }
+    list() {
+        return [...this.sessions.values()];
+    }
+    /**
+     * Creates a fresh registry entry. Callers are responsible for guarding against
+     * duplicate insertion. Throws SessionLimitError if we're at capacity.
+     */
+    register(args) {
+        if (this.sessions.size >= this.deps.maxSessions && !this.evictOldestTerminal()) {
+            throw new SessionLimitError(`runner is at its configured max of ${this.deps.maxSessions} concurrent sessions`);
+        }
+        const entry = {
+            sessionId: args.sessionId,
+            createdAt: new Date(),
+            buffer: new EventRingBuffer(this.deps.replayBufferBytes),
+            byteBuffer: new ByteRingBuffer(this.deps.replayBufferBytes),
+            emitter: new EventEmitter(),
+            byteEmitter: new EventEmitter(),
+            session: null,
+            status: { kind: "starting" },
+            exitedAt: null,
+            userStopped: false,
+            evictionTimer: null,
+        };
+        // Many transient SSE / WS subscribers per session is normal — bump the
+        // default 10-listener warning to a high cap so the alarm still fires
+        // for a real listener leak. 256 is well above the realistic concurrent-
+        // tab count and well below "obviously a bug".
+        entry.emitter.setMaxListeners(256);
+        entry.byteEmitter.setMaxListeners(256);
+        this.sessions.set(args.sessionId, entry);
+        return entry;
+    }
+    pushBytes(sessionId, bytes) {
+        const entry = this.sessions.get(sessionId);
+        if (!entry)
+            return undefined;
+        if (bytes.byteLength <= MAX_PUSH_CHUNK) {
+            const buffered = entry.byteBuffer.push(bytes);
+            entry.byteEmitter.emit(BYTES_EMITTED, buffered);
+            return buffered;
+        }
+        // Split the chunk into MAX_PUSH_CHUNK-sized slices, each getting its
+        // own seq. Returns the last buffered piece for the caller's bookkeeping.
+        let last;
+        for (let off = 0; off < bytes.byteLength; off += MAX_PUSH_CHUNK) {
+            const slice = bytes.subarray(off, Math.min(off + MAX_PUSH_CHUNK, bytes.byteLength));
+            // subarray shares memory with the parent buffer; copy so the ring's
+            // entry doesn't pin the original allocation past eviction.
+            last = entry.byteBuffer.push(Buffer.from(slice));
+            entry.byteEmitter.emit(BYTES_EMITTED, last);
+        }
+        return last;
+    }
+    subscribeBytes(sessionId, listener) {
+        const entry = this.sessions.get(sessionId);
+        if (!entry)
+            throw new SessionEvictedError(`session '${sessionId}' not in registry`);
+        entry.byteEmitter.on(BYTES_EMITTED, listener);
+        return () => entry.byteEmitter.off(BYTES_EMITTED, listener);
+    }
+    emit(sessionId, event) {
+        const entry = this.sessions.get(sessionId);
+        if (!entry)
+            return undefined;
+        const buffered = entry.buffer.push(event);
+        if (event.type === "status") {
+            entry.status = event.status;
+            if (isTerminal(event.status)) {
+                entry.exitedAt = new Date();
+                this.scheduleEviction(entry);
+            }
+        }
+        entry.emitter.emit(EVENT_EMITTED, buffered);
+        return buffered;
+    }
+    subscribe(sessionId, listener) {
+        const entry = this.sessions.get(sessionId);
+        if (!entry)
+            throw new SessionEvictedError(`session '${sessionId}' not in registry`);
+        entry.emitter.on(EVENT_EMITTED, listener);
+        return () => entry.emitter.off(EVENT_EMITTED, listener);
+    }
+    /** Free a slot at capacity by removing the oldest already-terminated session
+     *  (by exit time). Retained exited sessions are history kept for re-attach, so
+     *  they yield to a new run rather than blocking it; live sessions are never
+     *  evicted. Returns false when every session is still live. */
+    evictOldestTerminal() {
+        let oldest;
+        for (const entry of this.sessions.values()) {
+            if (entry.exitedAt === null)
+                continue;
+            if (!oldest || entry.exitedAt < oldest.exitedAt)
+                oldest = entry;
+        }
+        if (!oldest)
+            return false;
+        return this.remove(oldest.sessionId);
+    }
+    scheduleEviction(entry) {
+        if (entry.evictionTimer)
+            return;
+        entry.evictionTimer = setTimeout(() => {
+            this.sessions.delete(entry.sessionId);
+        }, this.deps.exitTtlMs);
+        // Allow process exit even if evictions are pending — they are pure state,
+        // not work.
+        entry.evictionTimer.unref?.();
+    }
+    /**
+     * Remove an entry immediately (used by shutdown sweeps and startup cleanup).
+     * Returns true if it was present.
+     */
+    remove(sessionId) {
+        const entry = this.sessions.get(sessionId);
+        if (!entry)
+            return false;
+        if (entry.evictionTimer)
+            clearTimeout(entry.evictionTimer);
+        this.sessions.delete(sessionId);
+        return true;
+    }
+}
+//# sourceMappingURL=registry.js.map

package/dist/session/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/session/registry.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAG3C,OAAO,EAAE,UAAU,EAAiC,MAAM,gBAAgB,CAAC;AAC3E,OAAO,EAAE,cAAc,EAAsB,MAAM,uBAAuB,CAAC;AAC3E,OAAO,EAAE,eAAe,EAAsB,MAAM,kBAAkB,CAAC;AA0BvE,MAAM,aAAa,GAAG,OAAO,CAAC;AAC9B,MAAM,aAAa,GAAG,OAAO,CAAC;AAE9B;;;;;sCAKsC;AACtC,MAAM,cAAc,GAAG,EAAE,GAAG,IAAI,CAAC;AAEjC,MAAM,OAAO,iBAAkB,SAAQ,KAAK;CAAG;AAC/C,MAAM,OAAO,mBAAoB,SAAQ,KAAK;CAAG;AAEjD,MAAM,OAAO,eAAe;IAGG;IAFZ,QAAQ,GAAG,IAAI,GAAG,EAAwB,CAAC;IAE5D,YAA6B,IAAkB;QAAlB,SAAI,GAAJ,IAAI,CAAc;IAAG,CAAC;IAEnD,IAAI;QACF,OAAO,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC;IAC5B,CAAC;IAED,GAAG,CAAC,SAAiB;QACnB,OAAO,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;IACtC,CAAC;IAED,GAAG,CAAC,SAAiB;QACnB,OAAO,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;IACtC,CAAC;IAED,IAAI;QACF,OAAO,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC;IACrC,CAAC;IAED;;;OAGG;IACH,QAAQ,CAAC,IAA2B;QAClC,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,IAAI,IAAI,CAAC,IAAI,CAAC,WAAW,IAAI,CAAC,IAAI,CAAC,mBAAmB,EAAE,EAAE,CAAC;YAC/E,MAAM,IAAI,iBAAiB,CACzB,sCAAsC,IAAI,CAAC,IAAI,CAAC,WAAW,sBAAsB,CAClF,CAAC;QACJ,CAAC;QACD,MAAM,KAAK,GAAiB;YAC1B,SAAS,EAAE,IAAI,CAAC,SAAS;YACzB,SAAS,EAAE,IAAI,IAAI,EAAE;YACrB,MAAM,EAAE,IAAI,eAAe,CAAC,IAAI,CAAC,IAAI,CAAC,iBAAiB,CAAC;YACxD,UAAU,EAAE,IAAI,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC,iBAAiB,CAAC;YAC3D,OAAO,EAAE,IAAI,YAAY,EAAE;YAC3B,WAAW,EAAE,IAAI,YAAY,EAAE;YAC/B,OAAO,EAAE,IAAI;YACb,MAAM,EAAE,EAAE,IAAI,EAAE,UAAU,EAAE;YAC5B,QAAQ,EAAE,IAAI;YACd,WAAW,EAAE,KAAK;YAClB,aAAa,EAAE,IAAI;SACpB,CAAC;QACF,uEAAuE;QACvE,qEAAqE;QACrE,wEAAwE;QACxE,8CAA8C;QAC9C,KAAK,CAAC,OAAO,CAAC,eAAe,CAAC,GAAG,CAAC,CAAC;QACnC,KAAK,CAAC,WAAW,CAAC,eAAe,CAAC,GAAG,CAAC,CAAC;QACvC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,EAAE,KAAK,CAAC,CAAC;QACzC,OAAO,KAAK,CAAC;IACf,CAAC;IAED,SAAS,CAAC,SAAiB,EAAE,KAAa;QACxC,MAAM,KAAK,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QAC3C,IAAI,CAAC,KAAK;YAAE,OAAO,SAAS,CAAC;QAC7B,IAAI,KAAK,CAAC,UAAU,IAAI,cAAc,EAAE,CAAC;YACvC,MAAM,QAAQ,GAAG,KAAK,CAAC,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YAC9C,KAAK,CAAC,WAAW,CAAC,IAAI,CAAC,aAAa,EAAE,QAAQ,CAAC,CAAC;YAChD,OAAO,QAAQ,CAAC;QAClB,CAAC;QACD,qEAAqE;QACrE,yEAAyE;QACzE,IAAI,IAA+B,CAAC;QACpC,KAAK,IAAI,GAAG,GAAG,CAAC,EAAE,GAAG,GAAG,KAAK,CAAC,UAAU,EAAE,GAAG,IAAI,cAAc,EAAE,CAAC;YAChE,MAAM,KAAK,GAAG,KAAK,CAAC,QAAQ,CAAC,GAAG,EAAE,IAAI,CAAC,GAAG,CAAC,GAAG,GAAG,cAAc,EAAE,KAAK,CAAC,UAAU,CAAC,CAAC,CAAC;YACpF,oEAAoE;YACpE,2DAA2D;YAC3D,IAAI,GAAG,KAAK,CAAC,UAAU,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;YACjD,KAAK,CAAC,WAAW,CAAC,IAAI,CAAC,aAAa,EAAE,IAAI,CAAC,CAAC;QAC9C,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IAED,cAAc,CAAC,SAAiB,EAAE,QAAoC;QACpE,MAAM,KAAK,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QAC3C,IAAI,CAAC,KAAK;YAAE,MAAM,IAAI,mBAAmB,CAAC,YAAY,SAAS,mBAAmB,CAAC,CAAC;QACpF,KAAK,CAAC,WAAW,CAAC,EAAE,CAAC,aAAa,EAAE,QAAQ,CAAC,CAAC;QAC9C,OAAO,GAAG,EAAE,CAAC,KAAK,CAAC,WAAW,CAAC,GAAG,CAAC,aAAa,EAAE,QAAQ,CAAC,CAAC;IAC9D,CAAC;IAED,IAAI,CAAC,SAAiB,EAAE,KAAe;QACrC,MAAM,KAAK,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QAC3C,IAAI,CAAC,KAAK;YAAE,OAAO,SAAS,CAAC;QAC7B,MAAM,QAAQ,GAAG,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAC1C,IAAI,KAAK,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;YAC5B,KAAK,CAAC,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC;YAC5B,IAAI,UAAU,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC;gBAC7B,KAAK,CAAC,QAAQ,GAAG,IAAI,IAAI,EAAE,CAAC;gBAC5B,IAAI,CAAC,gBAAgB,CAAC,KAAK,CAAC,CAAC;YAC/B,CAAC;QACH,CAAC;QACD,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,aAAa,EAAE,QAAQ,CAAC,CAAC;QAC5C,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED,SAAS,CAAC,SAAiB,EAAE,QAAoC;QAC/D,MAAM,KAAK,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QAC3C,IAAI,CAAC,KAAK;YAAE,MAAM,IAAI,mBAAmB,CAAC,YAAY,SAAS,mBAAmB,CAAC,CAAC;QACpF,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC,aAAa,EAAE,QAAQ,CAAC,CAAC;QAC1C,OAAO,GAAG,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,aAAa,EAAE,QAAQ,CAAC,CAAC;IAC1D,CAAC;IAED;;;mEAG+D;IACvD,mBAAmB;QACzB,IAAI,MAAgC,CAAC;QACrC,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,QAAQ,CAAC,MAAM,EAAE,EAAE,CAAC;YAC3C,IAAI,KAAK,CAAC,QAAQ,KAAK,IAAI;gBAAE,SAAS;YACtC,IAAI,CAAC,MAAM,IAAI,KAAK,CAAC,QAAQ,GAAG,MAAM,CAAC,QAAS;gBAAE,MAAM,GAAG,KAAK,CAAC;QACnE,CAAC;QACD,IAAI,CAAC,MAAM;YAAE,OAAO,KAAK,CAAC;QAC1B,OAAO,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IACvC,CAAC;IAEO,gBAAgB,CAAC,KAAmB;QAC1C,IAAI,KAAK,CAAC,aAAa;YAAE,OAAO;QAChC,KAAK,CAAC,aAAa,GAAG,UAAU,CAAC,GAAG,EAAE;YACpC,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;QACxC,CAAC,EAAE,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QACxB,0EAA0E;QAC1E,YAAY;QACZ,KAAK,CAAC,aAAa,CAAC,KAAK,EAAE,EAAE,CAAC;IAChC,CAAC;IAED;;;OAGG;IACH,MAAM,CAAC,SAAiB;QACtB,MAAM,KAAK,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QAC3C,IAAI,CAAC,KAAK;YAAE,OAAO,KAAK,CAAC;QACzB,IAAI,KAAK,CAAC,aAAa;YAAE,YAAY,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC;QAC3D,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;QAChC,OAAO,IAAI,CAAC;IACd,CAAC;CACF"}

package/dist/session/ring-buffer.d.ts

@@ -0,0 +1,37 @@
+import type { RunEvent } from "../contract.js";
+export interface BufferedEvent {
+    id: number;
+    event: RunEvent;
+    bytes: number;
+}
+/**
+ * Byte-capped FIFO ring buffer for SSE replay. Each entry tracks its
+ * serialized byte size; when a new entry would push total bytes past the cap,
+ * oldest entries are evicted until it fits. Entries are never split.
+ *
+ * Ids are assigned monotonically starting at 1 — never reused, never reset.
+ * A client's `Last-Event-ID: <n>` asks for events with id > n; if the oldest
+ * remaining id is still > n+1, the gap must be signaled separately.
+ */
+export declare class EventRingBuffer {
+    private readonly maxBytes;
+    private readonly entries;
+    private totalBytes;
+    private nextId;
+    constructor(maxBytes: number);
+    push(event: RunEvent): BufferedEvent;
+    private evict;
+    /**
+     * Returns entries with id > afterId, in insertion order.
+     * If `hasGap` is true, the caller should emit a `gap` marker before replay
+     * because events between afterId+1 and the first returned id have been evicted.
+     */
+    replay(afterId: number): {
+        entries: BufferedEvent[];
+        hasGap: boolean;
+    };
+    get size(): number;
+    get bytes(): number;
+    get latestId(): number;
+}
+//# sourceMappingURL=ring-buffer.d.ts.map

package/dist/session/ring-buffer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ring-buffer.d.ts","sourceRoot":"","sources":["../../src/session/ring-buffer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE/C,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,QAAQ,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;GAQG;AACH,qBAAa,eAAe;IAKd,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAJrC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAuB;IAC/C,OAAO,CAAC,UAAU,CAAK;IACvB,OAAO,CAAC,MAAM,CAAK;gBAEU,QAAQ,EAAE,MAAM;IAM7C,IAAI,CAAC,KAAK,EAAE,QAAQ,GAAG,aAAa;IAUpC,OAAO,CAAC,KAAK;IAab;;;;OAIG;IACH,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG;QAAE,OAAO,EAAE,aAAa,EAAE,CAAC;QAAC,MAAM,EAAE,OAAO,CAAA;KAAE;IAOtE,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,IAAI,KAAK,IAAI,MAAM,CAElB;IAED,IAAI,QAAQ,IAAI,MAAM,CAErB;CACF"}

package/dist/session/ring-buffer.js

@@ -0,0 +1,64 @@
+/**
+ * Byte-capped FIFO ring buffer for SSE replay. Each entry tracks its
+ * serialized byte size; when a new entry would push total bytes past the cap,
+ * oldest entries are evicted until it fits. Entries are never split.
+ *
+ * Ids are assigned monotonically starting at 1 — never reused, never reset.
+ * A client's `Last-Event-ID: <n>` asks for events with id > n; if the oldest
+ * remaining id is still > n+1, the gap must be signaled separately.
+ */
+export class EventRingBuffer {
+    maxBytes;
+    entries = [];
+    totalBytes = 0;
+    nextId = 1;
+    constructor(maxBytes) {
+        this.maxBytes = maxBytes;
+        if (!Number.isInteger(maxBytes) || maxBytes <= 0) {
+            throw new Error(`EventRingBuffer maxBytes must be a positive integer, got ${maxBytes}`);
+        }
+    }
+    push(event) {
+        const id = this.nextId++;
+        const bytes = Buffer.byteLength(JSON.stringify(event), "utf8");
+        const entry = { id, event, bytes };
+        this.entries.push(entry);
+        this.totalBytes += bytes;
+        this.evict();
+        return entry;
+    }
+    evict() {
+        // Invariant: always retain at least the most-recently-pushed entry, even
+        // if it alone exceeds maxBytes. A single oversized event (a huge log
+        // chunk) is still more useful to a reconnecting client than an empty
+        // buffer, and the alternative (drop-and-gap) would surface as a spurious
+        // "earlier output truncated" banner immediately after a big write.
+        while (this.totalBytes > this.maxBytes && this.entries.length > 1) {
+            const dropped = this.entries.shift();
+            if (!dropped)
+                break;
+            this.totalBytes -= dropped.bytes;
+        }
+    }
+    /**
+     * Returns entries with id > afterId, in insertion order.
+     * If `hasGap` is true, the caller should emit a `gap` marker before replay
+     * because events between afterId+1 and the first returned id have been evicted.
+     */
+    replay(afterId) {
+        const entries = this.entries.filter((e) => e.id > afterId);
+        const oldestId = this.entries[0]?.id ?? this.nextId;
+        const hasGap = afterId + 1 < oldestId;
+        return { entries, hasGap };
+    }
+    get size() {
+        return this.entries.length;
+    }
+    get bytes() {
+        return this.totalBytes;
+    }
+    get latestId() {
+        return this.nextId - 1;
+    }
+}
+//# sourceMappingURL=ring-buffer.js.map

package/dist/session/ring-buffer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ring-buffer.js","sourceRoot":"","sources":["../../src/session/ring-buffer.ts"],"names":[],"mappings":"AAQA;;;;;;;;GAQG;AACH,MAAM,OAAO,eAAe;IAKG;IAJZ,OAAO,GAAoB,EAAE,CAAC;IACvC,UAAU,GAAG,CAAC,CAAC;IACf,MAAM,GAAG,CAAC,CAAC;IAEnB,YAA6B,QAAgB;QAAhB,aAAQ,GAAR,QAAQ,CAAQ;QAC3C,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,QAAQ,CAAC,IAAI,QAAQ,IAAI,CAAC,EAAE,CAAC;YACjD,MAAM,IAAI,KAAK,CAAC,4DAA4D,QAAQ,EAAE,CAAC,CAAC;QAC1F,CAAC;IACH,CAAC;IAED,IAAI,CAAC,KAAe;QAClB,MAAM,EAAE,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC;QACzB,MAAM,KAAK,GAAG,MAAM,CAAC,UAAU,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC,CAAC;QAC/D,MAAM,KAAK,GAAkB,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;QAClD,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACzB,IAAI,CAAC,UAAU,IAAI,KAAK,CAAC;QACzB,IAAI,CAAC,KAAK,EAAE,CAAC;QACb,OAAO,KAAK,CAAC;IACf,CAAC;IAEO,KAAK;QACX,yEAAyE;QACzE,qEAAqE;QACrE,qEAAqE;QACrE,yEAAyE;QACzE,mEAAmE;QACnE,OAAO,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,QAAQ,IAAI,IAAI,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAClE,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;YACrC,IAAI,CAAC,OAAO;gBAAE,MAAM;YACpB,IAAI,CAAC,UAAU,IAAI,OAAO,CAAC,KAAK,CAAC;QACnC,CAAC;IACH,CAAC;IAED;;;;OAIG;IACH,MAAM,CAAC,OAAe;QACpB,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,GAAG,OAAO,CAAC,CAAC;QAC3D,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,IAAI,IAAI,CAAC,MAAM,CAAC;QACpD,MAAM,MAAM,GAAG,OAAO,GAAG,CAAC,GAAG,QAAQ,CAAC;QACtC,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC;IAC7B,CAAC;IAED,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC;IAC7B,CAAC;IAED,IAAI,KAAK;QACP,OAAO,IAAI,CAAC,UAAU,CAAC;IACzB,CAAC;IAED,IAAI,QAAQ;QACV,OAAO,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC;IACzB,CAAC;CACF"}

package/dist/session/session-id.d.ts

@@ -0,0 +1,3 @@
+/** Generates a short, DNS- and Kubernetes-safe session id. */
+export declare function generateSessionId(): string;
+//# sourceMappingURL=session-id.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"session-id.d.ts","sourceRoot":"","sources":["../../src/session/session-id.ts"],"names":[],"mappings":"AAYA,8DAA8D;AAC9D,wBAAgB,iBAAiB,IAAI,MAAM,CAM1C"}

package/dist/session/session-id.js

@@ -0,0 +1,19 @@
+import { randomBytes } from "node:crypto";
+// Lowercase RFC 4648 base32 alphabet. Every character is valid in a DNS label
+// and an RFC 1123 Kubernetes resource name, so the id drops straight into both
+// `<id>.<domain>` session hostnames and `telo-run-<id>` container/pod names.
+const ALPHABET = "abcdefghijklmnopqrstuvwxyz234567";
+// 12 chars × 5 bits ≈ 60 bits of entropy. Collisions are negligible across the
+// concurrently-active session set (there is no dedup check, so the id must be
+// unique on its own) while staying far shorter than the previous UUID.
+const SESSION_ID_LENGTH = 12;
+/** Generates a short, DNS- and Kubernetes-safe session id. */
+export function generateSessionId() {
+    const bytes = randomBytes(SESSION_ID_LENGTH);
+    let id = "";
+    // 256 is a multiple of 32, so `byte % 32` indexes the alphabet without bias.
+    for (let i = 0; i < SESSION_ID_LENGTH; i++)
+        id += ALPHABET[bytes[i] % 32];
+    return id;
+}
+//# sourceMappingURL=session-id.js.map

package/dist/session/session-id.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-id.js","sourceRoot":"","sources":["../../src/session/session-id.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE1C,8EAA8E;AAC9E,+EAA+E;AAC/E,6EAA6E;AAC7E,MAAM,QAAQ,GAAG,kCAAkC,CAAC;AAEpD,+EAA+E;AAC/E,8EAA8E;AAC9E,uEAAuE;AACvE,MAAM,iBAAiB,GAAG,EAAE,CAAC;AAE7B,8DAA8D;AAC9D,MAAM,UAAU,iBAAiB;IAC/B,MAAM,KAAK,GAAG,WAAW,CAAC,iBAAiB,CAAC,CAAC;IAC7C,IAAI,EAAE,GAAG,EAAE,CAAC;IACZ,6EAA6E;IAC7E,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,iBAAiB,EAAE,CAAC,EAAE;QAAE,EAAE,IAAI,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC;IAC1E,OAAO,EAAE,CAAC;AACZ,CAAC"}

package/dist/sse/channel.d.ts

@@ -0,0 +1,11 @@
+import type { FastifyReply, FastifyRequest } from "fastify";
+import { type SessionRegistry } from "../session/registry.js";
+export interface SseStreamArgs {
+    registry: SessionRegistry;
+    req: FastifyRequest;
+    reply: FastifyReply;
+    sessionId: string;
+    corsOrigins: string[] | "*";
+}
+export declare function streamSessionEvents(args: SseStreamArgs): Promise<void>;
+//# sourceMappingURL=channel.d.ts.map

package/dist/sse/channel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"channel.d.ts","sourceRoot":"","sources":["../../src/sse/channel.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAG5D,OAAO,EAAuB,KAAK,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAKnF,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,eAAe,CAAC;IAC1B,GAAG,EAAE,cAAc,CAAC;IACpB,KAAK,EAAE,YAAY,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,EAAE,GAAG,GAAG,CAAC;CAC7B;AAED,wBAAsB,mBAAmB,CAAC,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAuF5E"}