nexus-agentd 0.2.6 → 0.3.1

package/dist/run-store.js

@@ -1,6 +1,19 @@
 import { randomUUID } from 'node:crypto';
-import { chmod, mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import { chmod, mkdir, readFile, rename, unlink, writeFile } from 'node:fs/promises';
 import path from 'node:path';
+import { ArtifactStore, artifactStorePathForRunStore } from './artifact-store.js';
+export { ArtifactStore, artifactStorePathForRunStore } from './artifact-store.js';
+/** Coarse bucket used by the console filter and list grouping. */
+export function artifactKind(mediaType) {
+    const type = String(mediaType || '').toLowerCase();
+    if (type.startsWith('image/'))
+        return 'image';
+    if (type.startsWith('video/'))
+        return 'video';
+    if (type.startsWith('audio/'))
+        return 'audio';
+    return 'file';
+}
 const STATES = new Set([
     'created',
     'running',
@@ -14,17 +27,43 @@ const MAX_OUTPUT_CHARS = 256 * 1024;
 const MAX_SUMMARY_CHARS = 600;
 export class RunStore {
     filePath;
-    maxRuns;
-    maxTaskChars;
     runs = new Map();
     initialized = false;
     dirty = false;
     persistTimer;
     writeQueue = Promise.resolve();
-    constructor(filePath, maxRuns = 1000, maxTaskChars = 1024 * 1024) {
+    artifactStore;
+    maxRuns;
+    maxTaskChars;
+    historyRetentionDays;
+    historyMaxBytes;
+    now;
+    lastWriteMs = 0;
+    writeFailures = 0;
+    historyBytes = 0;
+    constructor(filePath, maxRunsOrOptions = 1000, maxTaskCharsOrOptions = undefined, suppliedOptions = {}) {
         this.filePath = filePath;
-        this.maxRuns = maxRuns;
-        this.maxTaskChars = maxTaskChars;
+        const positionalOptions = typeof maxRunsOrOptions === 'object' ? maxRunsOrOptions : { ...suppliedOptions };
+        if (typeof maxTaskCharsOrOptions === 'object') {
+            Object.assign(positionalOptions, maxTaskCharsOrOptions);
+        }
+        this.maxRuns = positiveInteger(typeof maxRunsOrOptions === 'number'
+            ? maxRunsOrOptions
+            : positionalOptions.maxRuns, 1000);
+        this.maxTaskChars = positiveInteger(typeof maxTaskCharsOrOptions === 'number'
+            ? maxTaskCharsOrOptions
+            : maxTaskCharsOrOptions?.maxTaskChars ?? positionalOptions.maxTaskChars, 1024 * 1024);
+        this.historyRetentionDays = nonNegativeNumber(positionalOptions.historyRetentionDays, undefined);
+        this.historyMaxBytes = nonNegativeInteger(positionalOptions.historyMaxBytes, undefined);
+        this.now = positionalOptions.now || Date.now;
+        const artifactRoot = positionalOptions.rootDir ||
+            positionalOptions.artifactRootDir ||
+            artifactStorePathForRunStore(filePath);
+        this.artifactStore = new ArtifactStore(artifactRoot, {
+            ...positionalOptions,
+            onViewsChanged: (runId, views) => this.applyArtifactViews(runId, views),
+            isRunActive: (runId) => isActive(this.runs.get(runId)?.state)
+        });
     }
     async init() {
         if (this.initialized)
@@ -52,8 +91,7 @@ export class RunStore {
                 }
             }
         }
-        this.initialized = true;
-        const now = Date.now();
+        const now = this.now();
         for (const [id, run] of this.runs) {
             if (!isActive(run.state))
                 continue;
@@ -68,6 +106,16 @@ export class RunStore {
             });
             this.dirty = true;
         }
+        await this.artifactStore.init();
+        for (const [id, run] of this.runs) {
+            const views = this.artifactStore.restoreRun(id, run.artifacts);
+            if (JSON.stringify(run.artifacts) !== JSON.stringify(views)) {
+                run.artifacts = views;
+                run.artifactCount = views.length;
+                this.dirty = true;
+            }
+        }
+        this.initialized = true;
         this.prune();
         if (!(await fileExists(this.filePath)))
             this.dirty = true;
@@ -76,7 +124,7 @@ export class RunStore {
     }
     create(input) {
         this.assertInitialized();
-        const now = Date.now();
+        const now = this.now();
         const taskTruncated = input.task.length > this.maxTaskChars;
         const run = {
             id: randomUUID(),
@@ -89,6 +137,7 @@ export class RunStore {
             ownerKeyId: input.ownerKeyId,
             task: taskTruncated ? input.task.slice(0, this.maxTaskChars) : input.task,
             taskTruncated: taskTruncated || undefined,
+            retryOfRunId: input.retryOfRunId,
             inputAttachmentCount: input.inputAttachmentCount || undefined,
             state: 'running',
             progress: { phase: '已接收', message: '任务已交给智能体' },
@@ -109,10 +158,15 @@ export class RunStore {
         const output = patch.output === undefined
             ? current.output
             : clipTail(patch.output, MAX_OUTPUT_CHARS);
-        const updatedAt = patch.updatedAt ?? Date.now();
+        const updatedAt = patch.updatedAt ?? this.now();
+        const normalizedPatch = structuredClone(patch);
+        if (patch.artifacts !== undefined) {
+            normalizedPatch.artifacts = this.artifactStore.mergeViews(id, patch.artifacts, false);
+            normalizedPatch.artifactCount = normalizedPatch.artifacts.length;
+        }
         const next = {
             ...current,
-            ...structuredClone(patch),
+            ...normalizedPatch,
             output,
             resultSummary: output ? summarize(output) : current.resultSummary,
             updatedAt
@@ -120,11 +174,119 @@ export class RunStore {
         if (patch.endedAt !== undefined) {
             next.durationMs = Math.max(0, patch.endedAt - next.startedAt);
         }
-        this.runs.delete(id);
+        // Preserve creation order as the stable tie-breaker for same-ms tasks.
         this.runs.set(id, next);
         this.changed();
         return publicDetail(next);
     }
+    /** Queue payload snapshots without blocking the protocol sink. */
+    recordArtifacts(runId, artifacts) {
+        this.assertInitialized();
+        if (!this.runs.has(runId))
+            return undefined;
+        return this.artifactStore.recordArtifacts(runId, artifacts);
+    }
+    artifactViews(runId) {
+        this.assertInitialized();
+        if (!this.runs.has(runId))
+            return undefined;
+        return this.artifactStore.views(runId);
+    }
+    async readArtifact(runId, artifactId) {
+        this.assertInitialized();
+        if (!this.runs.has(runId))
+            return undefined;
+        return this.artifactStore.readArtifact(runId, artifactId);
+    }
+    /** Flat, newest-first artifact index across all retained runs. */
+    listArtifacts(query = {}) {
+        this.assertInitialized();
+        const needle = String(query.query || '').trim().toLowerCase();
+        const limit = Math.min(200, Math.max(1, Number(query.limit) || 50));
+        const offset = Math.max(0, Math.floor(Number(query.offset) || 0));
+        const rows = [];
+        for (const run of this.runs.values()) {
+            for (const view of run.artifacts || []) {
+                if (!view.id)
+                    continue;
+                if (query.agentId && run.agentId !== query.agentId)
+                    continue;
+                const kind = artifactKind(view.mediaType);
+                if (query.kind && query.kind !== 'all' && kind !== query.kind)
+                    continue;
+                if (needle) {
+                    const haystack = `${view.name || ''} ${view.filename || ''}`.toLowerCase();
+                    if (!haystack.includes(needle))
+                        continue;
+                }
+                rows.push({
+                    id: view.id,
+                    runId: run.id,
+                    agentId: run.agentId,
+                    agentName: run.agentName,
+                    runState: run.state,
+                    runStartedAt: run.startedAt,
+                    name: view.name,
+                    filename: view.filename,
+                    mediaType: view.mediaType,
+                    size: view.size,
+                    kind,
+                    downloadable: view.downloadable === true,
+                    storageStatus: view.storageStatus,
+                    createdAt: view.createdAt
+                });
+            }
+        }
+        rows.sort((left, right) => (right.createdAt || 0) - (left.createdAt || 0));
+        return { artifacts: rows.slice(offset, offset + limit), total: rows.length };
+    }
+    /** Delete one artifact's payload and record entry; the run record stays. */
+    async removeArtifact(runId, artifactId) {
+        this.assertInitialized();
+        if (!this.runs.has(runId))
+            return false;
+        return this.artifactStore.removeArtifact(runId, artifactId);
+    }
+    getOwnerKeyId(runId) {
+        this.assertInitialized();
+        return this.runs.get(runId)?.ownerKeyId;
+    }
+    metrics() {
+        const artifactStoreStats = this.artifactStore.stats();
+        return {
+            // This is the last successfully persisted JSON size. A dirty store
+            // reports that size until its queued write completes, avoiding a
+            // full-history serialization on every metrics poll.
+            historyBytes: this.historyBytes,
+            retainedRuns: this.runs.size,
+            pendingWrites: (this.dirty ? 1 : 0) + artifactStoreStats.pendingWrites,
+            lastWriteMs: this.lastWriteMs,
+            writeFailures: this.writeFailures,
+            artifactStoreStats
+        };
+    }
+    stats() {
+        return this.metrics();
+    }
+    setRetryOfRunId(runId, retryOfRunId) {
+        return this.update(runId, { retryOfRunId });
+    }
+    /**
+     * Remove a terminal run record and its stored artifacts. Active runs are
+     * refused so a live turn cannot lose its progress tracking.
+     */
+    deleteRun(id) {
+        this.assertInitialized();
+        const run = this.runs.get(id);
+        if (!run)
+            return undefined;
+        if (isActive(run.state))
+            return undefined;
+        this.runs.delete(id);
+        this.artifactStore.removeRun(id);
+        this.changed();
+        return publicDetail(run);
+    }
     get(id) {
         this.assertInitialized();
         const run = this.runs.get(id);
@@ -134,8 +296,10 @@ export class RunStore {
         this.assertInitialized();
         const needle = String(query.query || '').trim().toLowerCase();
         const limit = Math.min(200, Math.max(1, Number(query.limit) || 50));
+        const offset = Math.max(0, Math.floor(Number(query.offset) || 0));
         const matched = Array.from(this.runs.values())
             .reverse()
+            .sort((left, right) => right.startedAt - left.startedAt)
             .filter((run) => !query.agentId || run.agentId === query.agentId)
             .filter((run) => !query.sessionId || run.sessionId === query.sessionId)
             .filter((run) => !query.state || run.state === query.state)
@@ -153,7 +317,7 @@ export class RunStore {
             if (run.state === 'failed')
                 stats.failed++;
         }
-        const runs = matched.slice(0, limit).map(publicView);
+        const runs = matched.slice(offset, offset + limit).map(publicView);
         return { runs, total, stats };
     }
     async flush() {
@@ -161,6 +325,11 @@ export class RunStore {
         if (this.persistTimer)
             clearTimeout(this.persistTimer);
         this.persistTimer = undefined;
+        if (this.dirty)
+            await this.persist();
+        await this.artifactStore.flush();
+        // Successful artifact commits update run metadata via the callback
+        // above, so persist those storage facts as well.
         if (this.dirty)
             await this.persist();
         await this.writeQueue;
@@ -174,6 +343,7 @@ export class RunStore {
             !Array.isArray(parsed.runs)) {
             throw new InvalidRunFileError('Invalid Agent Nexus run history file');
         }
+        this.historyBytes = Buffer.byteLength(raw);
         for (const value of parsed.runs) {
             const run = normalizeRun(value);
             if (run)
@@ -198,12 +368,39 @@ export class RunStore {
         this.persistTimer.unref?.();
     }
     prune() {
-        while (this.runs.size > this.maxRuns) {
-            const terminal = Array.from(this.runs.entries()).find(([, run]) => !isActive(run.state));
+        const removeOldestTerminal = (predicate) => {
+            const terminal = Array.from(this.runs.entries())
+                .filter(([, run]) => !isActive(run.state) && predicate(run))
+                .sort(([, left], [, right]) => left.updatedAt - right.updatedAt)[0];
             if (!terminal)
-                break;
+                return false;
             this.runs.delete(terminal[0]);
+            this.artifactStore.removeRun(terminal[0]);
             this.dirty = true;
+            return true;
+        };
+        while (this.runs.size > this.maxRuns) {
+            if (!removeOldestTerminal(() => true))
+                break;
+        }
+        if (this.historyRetentionDays !== undefined) {
+            const cutoff = this.now() - this.historyRetentionDays * 24 * 60 * 60 * 1000;
+            while (removeOldestTerminal((run) => (run.endedAt ?? run.updatedAt) <= cutoff)) { }
+        }
+        if (this.historyMaxBytes !== undefined) {
+            const historyBytes = () => Buffer.byteLength(JSON.stringify(Array.from(this.runs.values())));
+            while (historyBytes() > this.historyMaxBytes) {
+                if (!removeOldestTerminal(() => true)) {
+                    console.error(JSON.stringify({
+                        level: 'warn',
+                        event: 'run_history_budget_exceeded',
+                        bytes: historyBytes(),
+                        budget: this.historyMaxBytes,
+                        activeRunsProtected: Array.from(this.runs.values()).filter((run) => isActive(run.state)).length
+                    }));
+                    break;
+                }
+            }
         }
     }
     persist() {
@@ -216,13 +413,22 @@ export class RunStore {
         };
         const serialized = `${JSON.stringify(payload, null, 2)}\n`;
         const write = async () => {
+            const startedAt = this.now();
             const temp = `${this.filePath}.${process.pid}.${randomUUID()}.tmp`;
-            await writeFile(temp, serialized, { encoding: 'utf8', mode: 0o600 });
-            await rename(temp, this.filePath);
-            await chmod(this.filePath, 0o600).catch(() => undefined);
+            try {
+                await writeFile(temp, serialized, { encoding: 'utf8', mode: 0o600 });
+                await rename(temp, this.filePath);
+                await chmod(this.filePath, 0o600).catch(() => undefined);
+                this.historyBytes = Buffer.byteLength(serialized);
+                this.lastWriteMs = Math.max(0, this.now() - startedAt);
+            }
+            finally {
+                await unlink(temp).catch(() => undefined);
+            }
         };
         const next = this.writeQueue.then(write, write).catch((error) => {
             this.dirty = true;
+            this.writeFailures++;
             throw error;
         });
         this.writeQueue = next.catch(() => undefined);
@@ -232,6 +438,19 @@ export class RunStore {
         if (!this.initialized)
             throw new Error('RunStore is not initialized');
     }
+    applyArtifactViews(runId, views) {
+        const run = this.runs.get(runId);
+        if (!run)
+            return;
+        run.artifacts = structuredClone(views);
+        run.artifactCount = run.artifacts.length;
+        run.updatedAt = this.now();
+        if (!this.initialized) {
+            this.dirty = true;
+            return;
+        }
+        this.changed();
+    }
 }
 export function runStorePathForConfig(configPath) {
     const absolute = path.resolve(configPath);
@@ -263,13 +482,26 @@ function normalizeRun(value) {
         artifactCount: Number.isFinite(run.artifactCount) ? run.artifactCount : 0
     };
 }
+function positiveInteger(value, fallback) {
+    return Number.isFinite(value) && Number(value) > 0 ? Math.floor(Number(value)) : fallback;
+}
+function nonNegativeInteger(value, fallback) {
+    return Number.isFinite(value) && Number(value) >= 0 ? Math.floor(Number(value)) : fallback;
+}
+function nonNegativeNumber(value, fallback) {
+    return Number.isFinite(value) && Number(value) >= 0 ? Number(value) : fallback;
+}
 function publicView(run) {
-    const { ownerKeyId: _ownerKeyId, output: _output, artifacts: _artifacts, ...view } = run;
-    return structuredClone(view);
+    const { ownerKeyId: _ownerKeyId, task, output: _output, artifacts: _artifacts, ...view } = run;
+    return structuredClone({ ...view, taskPreview: task.slice(0, 240),
+        // Remote errors/progress can be large too; full values remain in details.
+        error: view.error?.slice(0, 600),
+        progress: { ...view.progress, phase: view.progress.phase.slice(0, 120), message: view.progress.message?.slice(0, 600) }
+    });
 }
 function publicDetail(run) {
     const { ownerKeyId: _ownerKeyId, ...detail } = run;
-    return structuredClone(detail);
+    return structuredClone({ ...detail, taskPreview: run.task.slice(0, 240) });
 }
 function summarize(value) {
     const compact = value.replace(/\s+/g, ' ').trim();

package/dist/server/auth-policy.d.ts

@@ -0,0 +1,27 @@
+import type { IncomingMessage } from 'node:http';
+import { AdminSessionStore } from '../auth.js';
+import type { AgentdControlPlane } from '../control-plane.js';
+import type { AgentdApiKeyPrincipal, AgentdConfig } from '../types.js';
+export declare const ADMIN_COOKIE = "agent_nexus_admin";
+export interface FailureLimiter {
+    assertAllowed(key: string): void;
+    failure(key: string): void;
+    success(key: string): void;
+}
+export declare function authenticateAdmin(request: IncomingMessage, sessions: AdminSessionStore): void;
+export declare function authenticateApiKey(request: IncomingMessage, config: AgentdConfig, controlPlane: AgentdControlPlane | undefined, limiter: FailureLimiter): AgentdApiKeyPrincipal;
+export declare function fallbackApiKey(config: AgentdConfig, secret: string): AgentdApiKeyPrincipal | undefined;
+export declare function assertAgentScope(principal: AgentdApiKeyPrincipal, agentId: string): void;
+export declare function isInitialized(config: AgentdConfig, controlPlane?: AgentdControlPlane): boolean;
+export declare function needsAdminSetup(config: AgentdConfig, controlPlane?: AgentdControlPlane): any;
+export declare function consoleHost(request: IncomingMessage): import("url").URL;
+export declare function isDirectConsoleHost(request: IncomingMessage, config: AgentdConfig, hostname: string): boolean;
+export declare function assertConsoleHost(request: IncomingMessage, config: AgentdConfig): void;
+export declare function assertTrustedOrigin(request: IncomingMessage, config: AgentdConfig): void;
+export declare function originMatchesHost(origin: string, request: IncomingMessage): boolean;
+export declare function cookieValue(request: IncomingMessage, name: string): string;
+export declare function adminCookie(value: string, ttlMs: number, config: AgentdConfig): string;
+export declare function clearAdminCookie(config: AgentdConfig): string;
+export declare function isMutating(method?: string): method is "POST" | "PUT" | "PATCH" | "DELETE";
+export declare function remoteKey(request: IncomingMessage): string;
+export declare function stringHeader(value: string | string[] | undefined): string;

package/dist/server/auth-policy.js

@@ -0,0 +1,143 @@
+import { timingSafeEqual } from 'node:crypto';
+import { RequestError } from './validation.js';
+export const ADMIN_COOKIE = 'agent_nexus_admin';
+export function authenticateAdmin(request, sessions) {
+    const id = cookieValue(request, ADMIN_COOKIE);
+    if (!id || !sessions.has(id))
+        throw new RequestError(401, 'Admin session is required');
+}
+export function authenticateApiKey(request, config, controlPlane, limiter) {
+    const rateKey = remoteKey(request);
+    limiter.assertAllowed(rateKey);
+    const value = stringHeader(request.headers.authorization);
+    if (!value.startsWith('Bearer ')) {
+        limiter.failure(rateKey);
+        throw new RequestError(401, 'Bearer API Key is required');
+    }
+    const secret = value.slice(7);
+    // A live control plane is authoritative, including a negative decision.
+    const principal = controlPlane
+        ? controlPlane.authenticateApiKey(secret)
+        : fallbackApiKey(config, secret);
+    if (!principal) {
+        limiter.failure(rateKey);
+        throw new RequestError(401, 'Invalid API Key');
+    }
+    limiter.success(rateKey);
+    return principal;
+}
+export function fallbackApiKey(config, secret) {
+    for (const key of config.apiKeys || []) {
+        if (key.enabled && safeEqual(key.secret, secret)) {
+            return { id: key.id, scope: structuredClone(key.scope) };
+        }
+    }
+    if (!config.apiKeys?.some((key) => key.id === 'legacy') && config.authToken && safeEqual(config.authToken, secret)) {
+        return { id: 'legacy', scope: { allAgents: true, agentIds: [] } };
+    }
+    return undefined;
+}
+export function assertAgentScope(principal, agentId) {
+    if (!principal.scope.allAgents && !principal.scope.agentIds.includes(agentId)) {
+        throw new RequestError(403, 'API Key is not authorized for this agent');
+    }
+}
+export function isInitialized(config, controlPlane) {
+    return controlPlane?.isInitialized() ?? config.initialized;
+}
+export function needsAdminSetup(config, controlPlane) {
+    const value = controlPlane?.needsAdminSetup;
+    return typeof value === 'function' ? value.call(controlPlane) : !config.adminPasswordHash;
+}
+export function consoleHost(request) {
+    const host = stringHeader(request.headers.host);
+    try {
+        if (!/^(?:\[[0-9a-fA-F:.]+\]|[a-zA-Z0-9.-]+)(?::\d{1,5})?$/.test(host))
+            throw new Error();
+        const url = new URL(`http://${host}`);
+        return url;
+    }
+    catch {
+        throw new RequestError(403, 'Console Host is not allowed');
+    }
+}
+export function isDirectConsoleHost(request, config, hostname) {
+    const local = request.socket.localAddress?.replace(/^::ffff:/, '');
+    const hosts = new Set(['localhost', '127.0.0.1', '[::1]', config.listen.host, local, local && `[${local}]`]);
+    hosts.delete('0.0.0.0');
+    hosts.delete('::');
+    return hosts.has(hostname);
+}
+export function assertConsoleHost(request, config) {
+    const url = consoleHost(request);
+    if (!isDirectConsoleHost(request, config, url.hostname) && !config.publicOrigins?.some((origin) => originMatchesHost(origin, request))) {
+        throw new RequestError(403, 'Console Host is not allowed');
+    }
+}
+export function assertTrustedOrigin(request, config) {
+    const origin = stringHeader(request.headers.origin);
+    if (!origin)
+        throw new RequestError(403, 'Same-origin request is required');
+    let parsed;
+    try {
+        parsed = new URL(origin);
+        if (!['http:', 'https:'].includes(parsed.protocol) || parsed.origin !== origin)
+            throw new Error();
+    }
+    catch {
+        throw new RequestError(403, 'Request origin is invalid');
+    }
+    const host = consoleHost(request);
+    const direct = parsed.protocol === 'http:' && isDirectConsoleHost(request, config, host.hostname);
+    if (!originMatchesHost(origin, request) || (!direct && !config.publicOrigins?.includes(origin))) {
+        throw new RequestError(403, 'Cross-origin admin request is not allowed');
+    }
+}
+export function originMatchesHost(origin, request) {
+    const parsed = new URL(origin);
+    return new URL(`${parsed.protocol}//${stringHeader(request.headers.host)}`).origin === parsed.origin;
+}
+export function cookieValue(request, name) {
+    const cookie = stringHeader(request.headers.cookie);
+    for (const part of cookie.split(';')) {
+        const index = part.indexOf('=');
+        if (index < 0 || part.slice(0, index).trim() !== name)
+            continue;
+        return part.slice(index + 1).trim();
+    }
+    return '';
+}
+export function adminCookie(value, ttlMs, config) {
+    return [
+        `${ADMIN_COOKIE}=${value}`,
+        'Path=/',
+        'HttpOnly',
+        'SameSite=Strict',
+        `Max-Age=${Math.floor(ttlMs / 1000)}`,
+        ...(config.secureAdminCookies ? ['Secure'] : [])
+    ].join('; ');
+}
+export function clearAdminCookie(config) {
+    return [
+        `${ADMIN_COOKIE}=`,
+        'Path=/',
+        'HttpOnly',
+        'SameSite=Strict',
+        'Max-Age=0',
+        ...(config.secureAdminCookies ? ['Secure'] : [])
+    ].join('; ');
+}
+export function isMutating(method) {
+    return method === 'POST' || method === 'PUT' || method === 'PATCH' || method === 'DELETE';
+}
+export function remoteKey(request) {
+    return request.socket.remoteAddress || 'unknown';
+}
+export function stringHeader(value) {
+    return Array.isArray(value) ? value[0] || '' : value || '';
+}
+function safeEqual(left, right) {
+    const a = Buffer.from(left);
+    const b = Buffer.from(right);
+    return a.length === b.length && timingSafeEqual(a, b);
+}

package/dist/server/connection.d.ts

@@ -0,0 +1,8 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { SessionManager } from '../session.js';
+/**
+ * Own the lifecycle of one session event connection. Authentication and quota
+ * admission happen in the data route; this module is responsible only for
+ * replay, authorization revocation, heartbeats, and releasing the slot.
+ */
+export declare function streamSessionEvents(request: IncomingMessage, response: ServerResponse, sessions: SessionManager, sessionId: string, after: string | undefined, release: () => void, watchAuthorization: (close: () => void) => (() => void)): void;

package/dist/server/connection.js

@@ -0,0 +1,67 @@
+import { createSseWriter } from '../sse-writer.js';
+/**
+ * Own the lifecycle of one session event connection. Authentication and quota
+ * admission happen in the data route; this module is responsible only for
+ * replay, authorization revocation, heartbeats, and releasing the slot.
+ */
+export function streamSessionEvents(request, response, sessions, sessionId, after, release, watchAuthorization) {
+    response.writeHead(200, {
+        'Content-Type': 'text/event-stream; charset=utf-8',
+        'Cache-Control': 'no-cache, no-transform',
+        Connection: 'keep-alive',
+        'X-Accel-Buffering': 'no'
+    });
+    response.flushHeaders?.();
+    let unsubscribe = () => { };
+    let unwatch = () => { };
+    let heartbeat;
+    let closed = false;
+    const close = () => {
+        if (closed)
+            return;
+        closed = true;
+        clearInterval(heartbeat);
+        unsubscribe();
+        unwatch();
+        writer.stop();
+        request.off('close', close);
+        response.off('close', close);
+        request.socket.off('error', close);
+        response.destroy();
+        release();
+    };
+    const writer = createSseWriter(response, close);
+    const writeEvent = (event) => writer.write(`id: ${event.id}\nevent: ${event.type}\ndata: ${JSON.stringify(event)}\n\n`);
+    request.once('close', close);
+    response.once('close', close);
+    request.socket.once('error', close);
+    try {
+        unwatch = watchAuthorization(close);
+        if (closed)
+            return;
+        const replay = sessions.eventReplay(sessionId, after);
+        if (replay.reset) {
+            // Keep this control frame bounded even when a snapshot has large
+            // output. Reconnect with the advertised cursor and snapshot URL.
+            writer.write(`id: ${replay.latestId}\nevent: reset\ndata: ${JSON.stringify({
+                ...replay.reset,
+                earliestId: replay.earliestId,
+                latestId: replay.latestId,
+                snapshotUrl: `/v1/sessions/${encodeURIComponent(sessionId)}`
+            })}\n\n`);
+        }
+        else {
+            for (const event of replay.events)
+                if (!writeEvent(event))
+                    break;
+        }
+        if (closed)
+            return;
+        unsubscribe = sessions.subscribe(sessionId, writeEvent);
+        heartbeat = setInterval(() => writer.write(': heartbeat\n\n'), 15_000);
+        heartbeat.unref?.();
+    }
+    catch {
+        close();
+    }
+}