nexus-agentd 0.2.5 → 0.3.0

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();
+    }
+}

package/dist/server/diagnostics.d.ts

@@ -0,0 +1,40 @@
+import type { AgentdAgentConfig, AgentdSessionView } from '../types.js';
+type SessionCreator = {
+    create(agentId: string, workspace: string | undefined, ownerKeyId: string): Promise<AgentdSessionView>;
+    close(id: string): Promise<AgentdSessionView>;
+};
+export interface DiagnosticStage {
+    name: 'validate' | 'handshake' | 'close';
+    status: 'passed' | 'failed' | 'skipped';
+    durationMs: number;
+    message?: string;
+}
+export interface DiagnosticResult {
+    ok: boolean;
+    status: 'passed' | 'failed' | 'busy';
+    durationMs: number;
+    stages: DiagnosticStage[];
+    message?: string;
+}
+export declare class DiagnosticConcurrencyError extends Error {
+    readonly status = 429;
+    readonly retryAfterMs = 1000;
+    constructor();
+}
+/**
+ * Run the real SessionManager startup path as a diagnostic.  SessionManager's
+ * `create` performs ACP initialize + session/new (or A2A card/transport
+ * setup), and `close` releases the process and the session slot.  No prompt
+ * is sent here by design.
+ */
+export declare class DiagnosticRunner {
+    private readonly maxConcurrent;
+    private active;
+    constructor(maxConcurrent?: number);
+    run(sessions: SessionCreator, agentId: string, workspace: string | undefined, agentConfig?: AgentdAgentConfig): Promise<DiagnosticResult>;
+    count(): number;
+    private result;
+}
+/** Keep command lines, absolute paths and credential-shaped values out of UI. */
+export declare function safeDiagnosticMessage(error: unknown): string;
+export {};

package/dist/server/diagnostics.js

@@ -0,0 +1,130 @@
+export class DiagnosticConcurrencyError extends Error {
+    status = 429;
+    retryAfterMs = 1_000;
+    constructor() {
+        super('ACP diagnostic capacity has been reached');
+        this.name = 'DiagnosticConcurrencyError';
+    }
+}
+/**
+ * Run the real SessionManager startup path as a diagnostic.  SessionManager's
+ * `create` performs ACP initialize + session/new (or A2A card/transport
+ * setup), and `close` releases the process and the session slot.  No prompt
+ * is sent here by design.
+ */
+export class DiagnosticRunner {
+    maxConcurrent;
+    active = 0;
+    constructor(maxConcurrent = 2) {
+        this.maxConcurrent = maxConcurrent;
+    }
+    async run(sessions, agentId, workspace, agentConfig) {
+        if (this.active >= this.maxConcurrent)
+            throw new DiagnosticConcurrencyError();
+        this.active++;
+        const startedAt = Date.now();
+        const stages = [];
+        let session;
+        try {
+            const validationStartedAt = Date.now();
+            if (!agentConfig) {
+                stages.push({
+                    name: 'validate',
+                    status: 'failed',
+                    durationMs: elapsed(validationStartedAt),
+                    message: 'Configured agent not found'
+                });
+                return this.result('failed', startedAt, stages, 'Configured agent not found');
+            }
+            if (agentConfig.enabled === false) {
+                stages.push({
+                    name: 'validate',
+                    status: 'failed',
+                    durationMs: elapsed(validationStartedAt),
+                    message: 'Agent is disabled'
+                });
+                return this.result('failed', startedAt, stages, 'Agent is disabled');
+            }
+            stages.push({
+                name: 'validate',
+                status: 'passed',
+                durationMs: elapsed(validationStartedAt),
+                message: 'Agent configuration accepted'
+            });
+            const startupStartedAt = Date.now();
+            try {
+                session = await sessions.create(agentId, workspace, 'console:diagnostic');
+                stages.push({
+                    name: 'handshake',
+                    status: 'passed',
+                    durationMs: elapsed(startupStartedAt),
+                    message: agentConfig.protocol === 'a2a'
+                        ? 'A2A transport and session creation completed'
+                        : 'Process startup, ACP initialize and session/new completed'
+                });
+            }
+            catch (error) {
+                stages.push({
+                    name: 'handshake',
+                    status: 'failed',
+                    durationMs: elapsed(startupStartedAt),
+                    message: safeDiagnosticMessage(error)
+                });
+                return this.result('failed', startedAt, stages, safeDiagnosticMessage(error));
+            }
+            const closeStartedAt = Date.now();
+            try {
+                await sessions.close(session.id);
+                stages.push({
+                    name: 'close',
+                    status: 'passed',
+                    durationMs: elapsed(closeStartedAt),
+                    message: 'Diagnostic session closed'
+                });
+                return this.result('passed', startedAt, stages, 'Agent connection diagnostic completed');
+            }
+            catch (error) {
+                stages.push({
+                    name: 'close',
+                    status: 'failed',
+                    durationMs: elapsed(closeStartedAt),
+                    message: safeDiagnosticMessage(error)
+                });
+                return this.result('failed', startedAt, stages, safeDiagnosticMessage(error));
+            }
+        }
+        finally {
+            // If close itself failed, the SessionManager still owns the
+            // session. Do not issue a second unbounded close here; its normal
+            // shutdown/cleanup path remains authoritative.
+            this.active = Math.max(0, this.active - 1);
+        }
+    }
+    count() {
+        return this.active;
+    }
+    result(status, startedAt, stages, message) {
+        return {
+            ok: status === 'passed',
+            status,
+            durationMs: elapsed(startedAt),
+            stages,
+            ...(message ? { message } : {})
+        };
+    }
+}
+function elapsed(startedAt) {
+    return Math.max(0, Date.now() - startedAt);
+}
+/** Keep command lines, absolute paths and credential-shaped values out of UI. */
+export function safeDiagnosticMessage(error) {
+    let value = error instanceof Error ? error.message : String(error);
+    value = value
+        .replace(/Bearer\s+[^\s]+/gi, 'Bearer [redacted]')
+        .replace(/(token|secret|password|authorization)\s*[:=]\s*[^\s,;]+/gi, '$1=[redacted]')
+        .replace(/(?:[A-Za-z]:[\\/]|\\\\)[^\s"'`]+/g, '[path]')
+        .replace(/(^|[\s(])\/(?!\/)[^\s"'`]+/g, '$1[path]')
+        .replace(/[\r\n\t]+/g, ' ')
+        .trim();
+    return value.length > 500 ? `${value.slice(0, 500)}…` : value;
+}

package/dist/server/metrics.d.ts

@@ -0,0 +1,51 @@
+import type { QuotaManager } from './quota.js';
+import type { RunStore } from '../run-store.js';
+export interface GatewayMetricsSnapshot {
+    rssBytes: number;
+    sessions: number;
+    currentSse: number;
+    activeSse: number;
+    requestCount: number;
+    failures: number;
+    quotaRejections: number;
+    runs: {
+        active: number;
+        completed: number;
+        failed: number;
+        total: number;
+    };
+    recentRuns: unknown[];
+    storage?: {
+        availableBytes: number;
+        totalBytes: number;
+    };
+    storageMetrics?: ReturnType<RunStore['metrics']>;
+    quotas?: ReturnType<QuotaManager['snapshot']>;
+}
+/** Small process-local counters used by the admin metrics endpoint. */
+export declare class GatewayMetrics {
+    private requests;
+    private failures;
+    private quotaRejections;
+    requestStarted(): void;
+    responseFinished(status: number, quotaRejected?: boolean): void;
+    snapshotCounters(): {
+        requestCount: number;
+        failures: number;
+        quotaRejections: number;
+    };
+    snapshot(input: {
+        sessions: number;
+        currentSse: number;
+        runs: {
+            active: number;
+            completed: number;
+            failed: number;
+            total: number;
+        };
+        recentRuns: unknown[];
+        storagePath?: string;
+        storageMetrics?: ReturnType<RunStore['metrics']>;
+        quotas?: QuotaManager;
+    }): Promise<GatewayMetricsSnapshot>;
+}

package/dist/server/metrics.js

@@ -0,0 +1,56 @@
+import { statfs } from 'node:fs/promises';
+import path from 'node:path';
+/** Small process-local counters used by the admin metrics endpoint. */
+export class GatewayMetrics {
+    requests = 0;
+    failures = 0;
+    quotaRejections = 0;
+    requestStarted() {
+        this.requests++;
+    }
+    responseFinished(status, quotaRejected = false) {
+        if (status >= 400)
+            this.failures++;
+        if (quotaRejected)
+            this.quotaRejections++;
+    }
+    snapshotCounters() {
+        return {
+            requestCount: this.requests,
+            failures: this.failures,
+            quotaRejections: this.quotaRejections
+        };
+    }
+    async snapshot(input) {
+        const memory = process.memoryUsage();
+        const counters = this.snapshotCounters();
+        const storage = input.storagePath
+            ? await measureStorage(input.storagePath)
+            : undefined;
+        return {
+            rssBytes: memory.rss,
+            sessions: input.sessions,
+            currentSse: input.currentSse,
+            activeSse: input.currentSse,
+            ...counters,
+            runs: input.runs,
+            recentRuns: input.recentRuns.slice(0, 5),
+            ...(storage ? { storage } : {}),
+            ...(input.storageMetrics ? { storageMetrics: input.storageMetrics } : {}),
+            ...(input.quotas ? { quotas: input.quotas.snapshot() } : {})
+        };
+    }
+}
+async function measureStorage(target) {
+    try {
+        const value = await statfs(path.resolve(target));
+        const blockSize = Number(value.bsize);
+        return {
+            availableBytes: Math.max(0, Number(value.bavail) * blockSize),
+            totalBytes: Math.max(0, Number(value.blocks) * blockSize)
+        };
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/server/quota.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Process-local per API-key resource accounting.
+ *
+ * The gateway still owns the global Session/SSE limits.  This class only
+ * accounts for work admitted through the HTTP data plane, so administrator
+ * operations can keep working while a client key is at its budget.
+ */
+export type QuotaKind = 'sessions' | 'runningRuns' | 'sse' | 'upload';
+export interface QuotaLimits {
+    maxSessionsPerKey: number;
+    maxRunningRunsPerKey: number;
+    maxSsePerKey: number;
+    maxUploadBytesPerKey: number;
+}
+export interface QuotaUsage {
+    sessions: number;
+    runningRuns: number;
+    sse: number;
+    uploadBytes: number;
+}
+export interface QuotaSnapshot {
+    limits: QuotaLimits;
+    keys: number;
+    usage: Record<string, QuotaUsage>;
+}
+export declare class QuotaExceededError extends Error {
+    readonly quota: QuotaKind;
+    readonly limit: number;
+    readonly current: number;
+    readonly status = 429;
+    readonly retryAfterMs: number;
+    constructor(quota: QuotaKind, limit: number, current: number, retryAfterMs?: number);
+}
+type Reservation = () => void;
+/**
+ * Read the canonical `config.quotas` section while retaining bounded defaults
+ * for embedders that construct an in-memory config without loading the file
+ * parser first.
+ */
+export declare function quotaLimitsFromConfig(config: unknown): QuotaLimits;
+export declare class QuotaManager {
+    private readonly buckets;
+    private readonly runOwners;
+    readonly limits: QuotaLimits;
+    constructor(config: unknown);
+    reserveSession(keyId: string): Reservation;
+    reserveRunningRun(keyId: string, sessionId?: string): Reservation;
+    /** Mark a run terminal and release its running slot, if one was tracked. */
+    finishRun(sessionId: string, keyId?: string): void;
+    reserveSse(keyId: string): Reservation;
+    reserveUpload(keyId: string, bytes: number): Reservation;
+    usageFor(keyId: string): QuotaUsage;
+    snapshot(): QuotaSnapshot;
+    private reserveCount;
+    private releaseCount;
+    private bucket;
+    private compact;
+}
+export {};

package/dist/server/quota.js

@@ -0,0 +1,176 @@
+/**
+ * Process-local per API-key resource accounting.
+ *
+ * The gateway still owns the global Session/SSE limits.  This class only
+ * accounts for work admitted through the HTTP data plane, so administrator
+ * operations can keep working while a client key is at its budget.
+ */
+export class QuotaExceededError extends Error {
+    quota;
+    limit;
+    current;
+    status = 429;
+    retryAfterMs;
+    constructor(quota, limit, current, retryAfterMs = 1_000) {
+        super(`Quota exceeded: ${quota}`);
+        this.quota = quota;
+        this.limit = limit;
+        this.current = current;
+        this.name = 'QuotaExceededError';
+        this.retryAfterMs = Math.max(1, Math.floor(retryAfterMs));
+    }
+}
+const ZERO_BUCKET = {
+    sessions: 0,
+    runningRuns: 0,
+    sse: 0,
+    uploadBytes: 0
+};
+/**
+ * Read the canonical `config.quotas` section while retaining bounded defaults
+ * for embedders that construct an in-memory config without loading the file
+ * parser first.
+ */
+export function quotaLimitsFromConfig(config) {
+    const source = asRecord(config) || {};
+    const nested = asRecord(source.quotas) || {};
+    const pick = (name, fallback) => {
+        const value = nested[name];
+        return typeof value === 'number' && Number.isFinite(value) && value > 0
+            ? Math.floor(value)
+            : fallback;
+    };
+    const globalSessions = positiveNumber(source.maxSessions, 64);
+    const globalSse = positiveNumber(source.maxSseConnections, 128);
+    const attachmentBytes = positiveNumber(source.maxAttachmentBytes, 32 * 1024 * 1024);
+    return {
+        maxSessionsPerKey: pick('maxSessionsPerKey', Math.max(1, Math.min(16, globalSessions))),
+        maxRunningRunsPerKey: pick('maxRunningRunsPerKey', Math.max(1, Math.min(4, globalSessions))),
+        maxSsePerKey: pick('maxSsePerKey', Math.max(1, Math.min(8, globalSse))),
+        maxUploadBytesPerKey: pick('maxUploadBytesPerKey', attachmentBytes)
+    };
+}
+export class QuotaManager {
+    buckets = new Map();
+    runOwners = new Map();
+    limits;
+    constructor(config) {
+        this.limits = quotaLimitsFromConfig(config);
+    }
+    reserveSession(keyId) {
+        return this.reserveCount(keyId, 'sessions', this.limits.maxSessionsPerKey, 1_000);
+    }
+    reserveRunningRun(keyId, sessionId) {
+        const release = this.reserveCount(keyId, 'runningRuns', this.limits.maxRunningRunsPerKey, 1_000);
+        if (sessionId)
+            this.runOwners.set(sessionId, keyId);
+        let released = false;
+        return () => {
+            if (released)
+                return;
+            released = true;
+            if (sessionId && this.runOwners.get(sessionId) === keyId) {
+                this.runOwners.delete(sessionId);
+            }
+            release();
+        };
+    }
+    /** Mark a run terminal and release its running slot, if one was tracked. */
+    finishRun(sessionId, keyId) {
+        const owner = this.runOwners.get(sessionId);
+        if (!owner || (keyId && owner !== keyId))
+            return;
+        this.runOwners.delete(sessionId);
+        this.releaseCount(owner, 'runningRuns', 1);
+    }
+    reserveSse(keyId) {
+        return this.reserveCount(keyId, 'sse', this.limits.maxSsePerKey, 1_000);
+    }
+    reserveUpload(keyId, bytes) {
+        const amount = Math.max(0, Math.floor(bytes));
+        if (!amount)
+            return () => { };
+        return this.reserveCount(keyId, 'upload', this.limits.maxUploadBytesPerKey, 60_000, amount);
+    }
+    usageFor(keyId) {
+        const bucket = this.buckets.get(keyId);
+        return {
+            sessions: bucket?.sessions || 0,
+            runningRuns: bucket?.runningRuns || 0,
+            sse: bucket?.sse || 0,
+            uploadBytes: bucket?.uploadBytes || 0
+        };
+    }
+    snapshot() {
+        const usage = {};
+        for (const [keyId, bucket] of this.buckets) {
+            usage[keyId] = {
+                sessions: bucket.sessions,
+                runningRuns: bucket.runningRuns,
+                sse: bucket.sse,
+                uploadBytes: bucket.uploadBytes
+            };
+        }
+        return {
+            limits: { ...this.limits },
+            keys: this.buckets.size,
+            usage
+        };
+    }
+    reserveCount(keyId, quota, limit, retryAfterMs, amount = 1) {
+        const bucket = this.bucket(keyId);
+        const field = quota === 'upload' ? 'uploadBytes' : quota;
+        const current = bucket[field];
+        if (current + amount > limit) {
+            this.compact();
+            throw new QuotaExceededError(quota, limit, current, retryAfterMs);
+        }
+        bucket[field] = current + amount;
+        let released = false;
+        return () => {
+            if (released)
+                return;
+            released = true;
+            this.releaseCount(keyId, quota, amount);
+        };
+    }
+    releaseCount(keyId, quota, amount) {
+        const bucket = this.buckets.get(keyId);
+        if (!bucket)
+            return;
+        const field = quota === 'upload' ? 'uploadBytes' : quota;
+        bucket[field] = Math.max(0, bucket[field] - amount);
+        if (!bucket.sessions && !bucket.runningRuns && !bucket.sse && !bucket.uploadBytes) {
+            this.buckets.delete(keyId);
+        }
+    }
+    bucket(keyId) {
+        let bucket = this.buckets.get(keyId);
+        if (!bucket) {
+            bucket = { ...ZERO_BUCKET };
+            this.buckets.set(keyId, bucket);
+        }
+        return bucket;
+    }
+    compact() {
+        if (this.buckets.size <= 4096)
+            return;
+        for (const [keyId, bucket] of this.buckets) {
+            if (!bucket.sessions && !bucket.runningRuns && !bucket.sse && !bucket.uploadBytes) {
+                this.buckets.delete(keyId);
+            }
+            if (this.buckets.size <= 4096)
+                break;
+        }
+    }
+}
+function asRecord(value) {
+    return value && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+function positiveNumber(value, fallback) {
+    return typeof value === 'number' && Number.isFinite(value) && value > 0
+        ? Math.floor(value)
+        : fallback;
+}

package/dist/server/validation.d.ts

@@ -0,0 +1,29 @@
+import type { IncomingMessage } from 'node:http';
+import type { AgentdPendingResponse, AgentdSessionState } from '../types.js';
+/** HTTP input errors are kept separate from route and domain operations. */
+export declare class RequestError extends Error {
+    readonly status: number;
+    constructor(status: number, message: string);
+}
+export declare function assertJsonContentType(request: IncomingMessage): void;
+export declare function assertEmptyJsonBody(request: IncomingMessage, maxBytes: number): Promise<void>;
+export declare function readJsonBody(request: IncomingMessage, maxBytes: number): Promise<Record<string, unknown>>;
+export declare function readBytesBody(request: IncomingMessage, maxBytes: number): Promise<Buffer<ArrayBuffer>>;
+export declare function assertOnlyKeys(body: Record<string, unknown>, allowed: string[]): void;
+export declare function requiredString(value: unknown, name: string): string;
+export declare function requiredRawString(value: unknown, name: string): string;
+export declare function requiredMessage(value: unknown): string;
+export declare function requiredInteger(value: unknown, name: string): number;
+export declare function optionalAttachmentIds(value: unknown): string[];
+export declare function normalizePublishPaths(body: Record<string, unknown>): string[];
+export declare function normalizedMediaType(value: string | string[] | undefined): string | undefined;
+export declare function decodeHeader(value: string | string[] | undefined): string;
+export declare function cleanQuery(value: string | null): string | undefined;
+export declare function boundedLimit(value: string | null): number | undefined;
+export declare function optionalRunState(value: string | null): AgentdSessionState | undefined;
+export declare function optionalRawString(value: unknown, name: string): string | undefined;
+export declare function optionalString(value: unknown): string | undefined;
+export declare function optionalPendingAction(value: unknown): AgentdPendingResponse['action'] | undefined;
+export declare function optionalBoolean(value: unknown, name: string): boolean | undefined;
+export declare function optionalNumber(value: unknown, name: string): number | undefined;
+export declare function requiredStringArray(value: unknown, name: string, allowEmpty?: boolean): string[];