nexus-agentd 0.2.5 → 0.3.0

package/dist/process-tree.js

@@ -3,30 +3,39 @@ const DEFAULT_GRACE_MS = 2_000;
 const FORCE_KILL_WAIT_MS = 1_000;
 export async function terminateProcessTree(child, options = {}) {
     const pid = child.pid;
-    if (!pid || hasExited(child))
+    if (!pid)
         return;
     const graceMs = Math.max(0, options.graceMs ?? DEFAULT_GRACE_MS);
     if (process.platform === 'win32') {
+        // Once a Windows process has exited taskkill can no longer address its
+        // descendants by the parent's PID. Callers should tear down before
+        // exit when they need Windows tree semantics.
+        if (hasExited(child))
+            return;
         await taskkill(pid, false);
         if (await waitForExit(child, graceMs))
             return;
         await taskkill(pid, true);
-        await waitForExit(child, FORCE_KILL_WAIT_MS);
-        return;
+        if (await waitForExit(child, FORCE_KILL_WAIT_MS))
+            return;
+        throw new Error(`Failed to terminate process ${pid}`);
     }
     if (options.ownsProcessGroup === true) {
         signalUnixGroup(pid, 'SIGTERM');
         if (await waitForUnixGroupExit(pid, graceMs))
             return;
         signalUnixGroup(pid, 'SIGKILL');
-        await waitForUnixGroupExit(pid, FORCE_KILL_WAIT_MS);
-        return;
+        if (await waitForUnixGroupExit(pid, FORCE_KILL_WAIT_MS))
+            return;
+        throw new Error(`Failed to terminate process group ${pid}`);
     }
     signalUnix(child, 'SIGTERM');
     if (await waitForExit(child, graceMs))
         return;
     signalUnix(child, 'SIGKILL');
-    await waitForExit(child, FORCE_KILL_WAIT_MS);
+    if (await waitForExit(child, FORCE_KILL_WAIT_MS))
+        return;
+    throw new Error(`Failed to terminate process ${pid}`);
 }
 function signalUnix(child, signal) {
     try {

package/dist/run-store.d.ts

@@ -1,5 +1,8 @@
-import type { AgentdProtocol, AgentdRunDetail, AgentdRunView, AgentdSessionState } from './types.js';
-interface StoredRun extends AgentdRunDetail {
+import { ArtifactStore, type ArtifactReadResult, type ArtifactStoreMetrics, type ArtifactStoreOptions, type StoredArtifactView } from './artifact-store.js';
+import type { AgentdArtifact, AgentdProtocol, AgentdRunDetail, AgentdRunView, AgentdSessionState } from './types.js';
+export { ArtifactStore, artifactStorePathForRunStore } from './artifact-store.js';
+export type { ArtifactReadResult, ArtifactStorageStatus, ArtifactStoreMetrics, ArtifactStoreIo, ArtifactStoreOptions, StoredArtifactView } from './artifact-store.js';
+interface StoredRun extends Omit<AgentdRunDetail, 'taskPreview'> {
     ownerKeyId: string;
 }
 export interface CreateRunInput {
@@ -12,6 +15,17 @@ export interface CreateRunInput {
     ownerKeyId: string;
     task: string;
     inputAttachmentCount?: number;
+    retryOfRunId?: string;
+}
+export interface RunStoreOptions extends ArtifactStoreOptions {
+    /** History count cap; the positional maxRuns argument takes precedence. */
+    maxRuns?: number;
+    /** Task text cap; the positional maxTaskChars argument takes precedence. */
+    maxTaskChars?: number;
+    /** Terminal run metadata retention duration. Active runs are protected. */
+    historyRetentionDays?: number;
+    /** JSON run-history byte budget, independent from artifact payload bytes. */
+    historyMaxBytes?: number;
 }
 export interface RunListQuery {
     agentId?: string;
@@ -19,24 +33,60 @@ export interface RunListQuery {
     state?: AgentdSessionState;
     query?: string;
     limit?: number;
+    offset?: number;
 }
 export declare class RunStore {
     readonly filePath: string;
-    private readonly maxRuns;
-    private readonly maxTaskChars;
     private readonly runs;
     private initialized;
     private dirty;
     private persistTimer?;
     private writeQueue;
-    constructor(filePath: string, maxRuns?: number, maxTaskChars?: number);
+    readonly artifactStore: ArtifactStore;
+    private readonly maxRuns;
+    private readonly maxTaskChars;
+    private readonly historyRetentionDays?;
+    private readonly historyMaxBytes?;
+    private readonly now;
+    private lastWriteMs;
+    private writeFailures;
+    private historyBytes;
+    constructor(filePath: string, maxRuns?: number, maxTaskChars?: number | RunStoreOptions, options?: RunStoreOptions);
+    constructor(filePath: string, options?: RunStoreOptions);
     init(): Promise<void>;
     create(input: CreateRunInput): AgentdRunDetail;
-    update(id: string, patch: Partial<Pick<StoredRun, 'protocolSessionId' | 'state' | 'progress' | 'output' | 'error' | 'artifacts' | 'artifactCount' | 'updatedAt' | 'endedAt' | 'durationMs' | 'inputAttachmentCount' | 'completion'>>): AgentdRunDetail | undefined;
+    update(id: string, patch: Partial<Pick<StoredRun, 'protocolSessionId' | 'state' | 'progress' | 'output' | 'error' | 'artifacts' | 'artifactCount' | 'updatedAt' | 'endedAt' | 'durationMs' | 'inputAttachmentCount' | 'completion' | 'retryOfRunId'>>): AgentdRunDetail | undefined;
+    /** Queue payload snapshots without blocking the protocol sink. */
+    recordArtifacts(runId: string, artifacts: AgentdArtifact[]): StoredArtifactView[] | undefined;
+    artifactViews(runId: string): StoredArtifactView[] | undefined;
+    readArtifact(runId: string, artifactId: string): Promise<ArtifactReadResult | undefined>;
+    getOwnerKeyId(runId: string): string | undefined;
+    metrics(): {
+        historyBytes: number;
+        retainedRuns: number;
+        pendingWrites: number;
+        lastWriteMs: number;
+        writeFailures: number;
+        artifactStoreStats: ArtifactStoreMetrics;
+    };
+    stats(): {
+        historyBytes: number;
+        retainedRuns: number;
+        pendingWrites: number;
+        lastWriteMs: number;
+        writeFailures: number;
+        artifactStoreStats: ArtifactStoreMetrics;
+    };
+    setRetryOfRunId(runId: string, retryOfRunId?: string): AgentdRunDetail | undefined;
     get(id: string): AgentdRunDetail | undefined;
     list(query?: RunListQuery): {
         runs: AgentdRunView[];
         total: number;
+        stats: {
+            active: number;
+            completed: number;
+            failed: number;
+        };
     };
     flush(): Promise<void>;
     private load;
@@ -44,6 +94,6 @@ export declare class RunStore {
     private prune;
     private persist;
     private assertInitialized;
+    private applyArtifactViews;
 }
 export declare function runStorePathForConfig(configPath: string): string;
-export {};

package/dist/run-store.js

@@ -1,6 +1,8 @@
 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';
 const STATES = new Set([
     'created',
     'running',
@@ -14,17 +16,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 +80,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 +95,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 +113,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 +126,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 +147,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 +163,54 @@ 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);
+    }
+    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 });
+    }
     get(id) {
         this.assertInitialized();
         const run = this.runs.get(id);
@@ -134,8 +220,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)
@@ -144,14 +232,28 @@ export class RunStore {
             run.agentName.toLowerCase().includes(needle) ||
             run.id.toLowerCase().includes(needle));
         const total = matched.length;
-        const runs = matched.slice(0, limit).map(publicView);
-        return { runs, total };
+        const stats = { active: 0, completed: 0, failed: 0 };
+        for (const run of matched) {
+            if (isActive(run.state))
+                stats.active++;
+            if (run.state === 'completed')
+                stats.completed++;
+            if (run.state === 'failed')
+                stats.failed++;
+        }
+        const runs = matched.slice(offset, offset + limit).map(publicView);
+        return { runs, total, stats };
     }
     async flush() {
         this.assertInitialized();
         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;
@@ -165,6 +267,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)
@@ -189,12 +292,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() {
@@ -207,13 +337,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);
@@ -223,6 +362,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);
@@ -254,13 +406,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;