nexus-agentd 0.2.5 → 0.3.0

package/dist/cli.js

@@ -18,22 +18,21 @@ const label = typeof address === 'object' && address
 console.log(`nexus-agentd listening on ${label}`);
 for (const url of displayUrls(address))
     console.log(`WebUI: ${url}`);
-if (bootstrap.created) {
+if (bootstrap.created)
     console.log(`Created config: ${configPath}`);
-    console.log('Setup required: open the WebUI and create the Console Password.');
-    if (runtime.config.listen.host !== '127.0.0.1' && runtime.config.listen.host !== '::1') {
-        console.warn('WARNING: first-run setup is reachable over the network; initialize it immediately on a trusted network.');
-    }
+if (runtime.controlPlane.setupToken) {
+    console.log('Setup required: enter the following one-time setup token in the WebUI, then create the Console Password.');
+    console.log(`Setup token: ${runtime.controlPlane.setupToken}`);
+    console.warn('Keep this token private. It changes on restart. Use a trusted network or HTTPS for remote setup.');
 }
-let closing = false;
-const close = async () => {
-    if (closing)
-        return;
-    closing = true;
-    await runtime.close();
-};
-process.once('SIGINT', () => void close().finally(() => process.exit(0)));
-process.once('SIGTERM', () => void close().finally(() => process.exit(0)));
+let closing;
+const close = () => closing ??= runtime.close();
+const shutdown = () => void close().then(() => process.exit(0), (error) => {
+    console.error(JSON.stringify({ level: 'error', event: 'shutdown_failed', message: error instanceof Error ? error.message : String(error) }));
+    process.exit(1);
+});
+process.once('SIGINT', shutdown);
+process.once('SIGTERM', shutdown);
 function resolveConfigPath(args) {
     const index = args.indexOf('--config');
     const value = index >= 0 ? args[index + 1] : process.env.NEXUS_AGENTD_CONFIG;

package/dist/completion-contract.js

@@ -4,6 +4,6 @@ export const TURN_COMPLETION_CONTRACT = [
     'If you need user input or permission, use the protocol input/permission request and wait for the response.',
     'Before ending the turn, verify the requested work and provide a non-empty final response.',
     'The final response must summarize the outcome, verification performed, and workspace-relative paths for generated files.',
-    'Attach generated resources or artifacts through the protocol when supported. If the runtime only reports a local deliverable path, put each requested file on its own final line as MEDIA:<path>; Agent Nexus will snapshot that explicitly declared file as an artifact before the turn completes.',
+    'Attach generated resources or artifacts through the protocol when supported. If the runtime only reports a local deliverable path, put each requested file on its own final line as MEDIA:<path>, where <path> stays inside the configured workspace roots; Agent Nexus snapshots that declared file as an artifact before the turn completes, refuses paths outside those roots, and attaches at most 8 files per turn.',
     '</agent_nexus_completion_contract>'
 ].join('\n');

package/dist/config.js

@@ -13,7 +13,7 @@ export async function ensureAgentdConfig(filePath, options = {}) {
     }
     const initial = {
         listen: {
-            host: options.host?.trim() || '127.0.0.1',
+            host: options.host?.trim() || '0.0.0.0',
             port: bootstrapNumber(options.port, 8787, 1, 65535)
         },
         initialized: false,
@@ -56,7 +56,7 @@ export async function loadAgentdConfig(filePath) {
     if (!isRecord(value))
         throw new Error('nexus-agentd config root must be an object');
     const listen = optionalRecord(value.listen, 'listen') || {};
-    const host = optionalString(listen.host, 'listen.host') || '127.0.0.1';
+    const host = optionalString(listen.host, 'listen.host') || '0.0.0.0';
     const port = integerValue(listen.port, 'listen.port', 8787, 1, 65535);
     const initialized = optionalBoolean(value.initialized, 'initialized') ?? true;
     const rawAuthToken = optionalString(value.authToken, 'authToken');
@@ -84,17 +84,45 @@ export async function loadAgentdConfig(filePath) {
         throw new Error('nexus-agentd workspaceRoots must contain at least one path');
     }
     const rawAgents = requiredRecord(value.agents, 'agents');
-    const agents = {};
+    const agents = Object.create(null);
     for (const [id, input] of Object.entries(rawAgents)) {
         agents[id] = parseAgent(id, input);
     }
+    const quotas = optionalRecord(value.quotas, 'quotas') || {};
+    const history = optionalRecord(value.history, 'history') || {};
+    const artifacts = optionalRecord(value.artifacts, 'artifacts') || {};
+    const maxSessions = integerValue(value.maxSessions, 'maxSessions', 64, 1, 10_000);
+    const maxSseConnections = integerValue(value.maxSseConnections, 'maxSseConnections', 128, 1, 10_000);
     return {
         listen: { host, port },
+        publicOrigins: value.publicOrigins === undefined ? [] : stringArray(value.publicOrigins, 'publicOrigins').map((origin) => {
+            validateHttpUrl(origin, 'publicOrigins');
+            if (new URL(origin).origin !== origin)
+                throw new Error('publicOrigins must contain exact origins without paths');
+            return origin;
+        }),
         initialized,
         authToken,
         adminPasswordHash,
         apiKeys,
         workspaceRoots,
+        quotas: {
+            maxSessionsPerKey: integerValue(quotas.maxSessionsPerKey, 'quotas.maxSessionsPerKey', Math.min(16, maxSessions), 1, 10_000),
+            maxRunningRunsPerKey: integerValue(quotas.maxRunningRunsPerKey, 'quotas.maxRunningRunsPerKey', Math.min(4, maxSessions), 1, 10_000),
+            maxSsePerKey: integerValue(quotas.maxSsePerKey, 'quotas.maxSsePerKey', Math.min(8, maxSseConnections), 1, 10_000),
+            maxUploadBytesPerKey: integerValue(quotas.maxUploadBytesPerKey, 'quotas.maxUploadBytesPerKey', 32 * 1024 * 1024, 1024, 1024 * 1024 * 1024)
+        },
+        history: {
+            maxRuns: integerValue(history.maxRuns, 'history.maxRuns', 1000, 1, 100_000),
+            retentionDays: integerValue(history.retentionDays, 'history.retentionDays', 30, 1, 3650),
+            maxBytes: integerValue(history.maxBytes, 'history.maxBytes', 64 * 1024 * 1024, 1024, 1024 * 1024 * 1024)
+        },
+        artifacts: {
+            retentionDays: integerValue(artifacts.retentionDays, 'artifacts.retentionDays', 30, 1, 3650),
+            maxBytes: integerValue(artifacts.maxBytes, 'artifacts.maxBytes', 512 * 1024 * 1024, 1024, 1024 ** 4),
+            maxArtifactBytes: integerValue(artifacts.maxArtifactBytes, 'artifacts.maxArtifactBytes', 12 * 1024 * 1024, 1024, 12 * 1024 * 1024),
+            maxQueuedBytes: integerValue(artifacts.maxQueuedBytes, 'artifacts.maxQueuedBytes', 64 * 1024 * 1024, 1024, 512 * 1024 * 1024)
+        },
         maxRequestBytes: integerValue(value.maxRequestBytes, 'maxRequestBytes', 1024 * 1024, 1024, 16 * 1024 * 1024),
         maxAttachmentBytes: integerValue(value.maxAttachmentBytes, 'maxAttachmentBytes', 32 * 1024 * 1024, 1024, 64 * 1024 * 1024),
         maxEventsPerSession: integerValue(value.maxEventsPerSession, 'maxEventsPerSession', 2048, 64, 100_000),
@@ -103,7 +131,7 @@ export async function loadAgentdConfig(filePath) {
         cleanupIntervalMs: integerValue(value.cleanupIntervalMs, 'cleanupIntervalMs', 60_000, 5_000, 60 * 60 * 1000),
         requestTimeoutMs: integerValue(value.requestTimeoutMs, 'requestTimeoutMs', 30_000, 1_000, 5 * 60_000),
         promptTimeoutMs: integerValue(value.promptTimeoutMs, 'promptTimeoutMs', 30 * 60_000, 10_000, 24 * 60 * 60 * 1000),
-        maxSessions: integerValue(value.maxSessions, 'maxSessions', 64, 1, 10_000),
+        maxSessions,
         maxSseConnections: integerValue(value.maxSseConnections, 'maxSseConnections', 128, 1, 10_000),
         maxConnections: integerValue(value.maxConnections, 'maxConnections', 256, 8, 100_000),
         adminSessionTtlMs: integerValue(value.adminSessionTtlMs, 'adminSessionTtlMs', 12 * 60 * 60 * 1000, 5 * 60_000, 7 * 24 * 60 * 60 * 1000),
@@ -150,6 +178,9 @@ function parseAgent(id, value) {
         args: input.args === undefined
             ? undefined
             : stringArray(input.args, `agents.${id}.args`),
+        probeArgs: input.probeArgs === undefined
+            ? undefined
+            : stringArray(input.probeArgs, `agents.${id}.probeArgs`),
         inheritEnv: input.inheritEnv === undefined
             ? undefined
             : stringArray(input.inheritEnv, `agents.${id}.inheritEnv`),
@@ -157,6 +188,9 @@ function parseAgent(id, value) {
         permissionPolicy,
         permissionTimeoutMs: integerValue(input.permissionTimeoutMs, `agents.${id}.permissionTimeoutMs`, 15 * 60 * 1000, 1000, 24 * 60 * 60 * 1000)
     };
+    if (driver === 'stdio' && !result.command) {
+        throw new Error(`nexus-agentd agents.${id}.command is required for the stdio driver`);
+    }
     return result;
 }
 function parseA2AAgent(id, input) {
@@ -204,7 +238,13 @@ function parseA2AAgent(id, input) {
         agentUrl,
         preferredTransport,
         auth,
-        timeoutMs: integerValue(input.timeoutMs, `agents.${id}.timeoutMs`, 60_000, 1_000, 30 * 60_000)
+        timeoutMs: integerValue(input.timeoutMs, `agents.${id}.timeoutMs`, 60_000, 1_000, 30 * 60_000),
+        taskTimeoutMs: input.taskTimeoutMs === undefined
+            ? undefined
+            : integerValue(input.taskTimeoutMs, `agents.${id}.taskTimeoutMs`, 30 * 60_000, 10_000, 24 * 60 * 60 * 1000),
+        streamIdleTimeoutMs: input.streamIdleTimeoutMs === undefined
+            ? undefined
+            : integerValue(input.streamIdleTimeoutMs, `agents.${id}.streamIdleTimeoutMs`, 60_000, 1_000, 30 * 60_000)
     };
 }
 function parseApiKeys(value) {

package/dist/control-plane-validation.d.ts

@@ -0,0 +1,54 @@
+import type { AgentdProtocol, AgentdDriverKind, PermissionPolicy, A2ATransportPreference, A2AAuthType, AgentdApiKeyScope } from './types.js';
+export interface AgentdAgentUpdate {
+    protocol?: AgentdProtocol;
+    driver?: AgentdDriverKind;
+    name?: string;
+    description?: string;
+    enabled?: boolean;
+    workspace?: string;
+    permissionPolicy?: PermissionPolicy;
+    permissionTimeoutMs?: number;
+    agentCardUrl?: string;
+    agentUrl?: string;
+    preferredTransport?: A2ATransportPreference;
+    authType?: A2AAuthType;
+    authValue?: string;
+    authHeaderName?: string;
+    timeoutMs?: number;
+    taskTimeoutMs?: number | null;
+    streamIdleTimeoutMs?: number | null;
+}
+export interface AgentdApiKeyUpdate {
+    name?: string;
+    enabled?: boolean;
+    scope?: AgentdApiKeyScope;
+}
+export interface AgentdRuntimeSettingsUpdate {
+    sessionTtlMs: number;
+    promptTimeoutMs: number;
+    cleanupIntervalMs: number;
+}
+export declare class ControlPlaneError extends Error {
+    readonly status: number;
+    constructor(status: number, message: string);
+}
+export declare function validateRuntimeSettings(update: AgentdRuntimeSettingsUpdate): void;
+export declare function validateIntegerRange(value: number, min: number, max: number, name: string): void;
+export declare function validateUpdate(update: AgentdAgentUpdate): void;
+export declare function validateAgentId(value: string): string;
+export declare function validateOpaqueId(value: string, label: string): string;
+export declare function validatePassword(value: string, confirmation: string): string;
+export declare function validateKeyName(value: string): string;
+export declare function validateApiKeySecret(value: string): string;
+export declare function validateA2ASecret(value: string): string;
+export declare function validateAgentUrl(value: string): string;
+export declare function defaultAgentCardUrl(agentUrl: string | undefined): string | undefined;
+export declare function clampTimeout(value: number | undefined, fallback: number, min: number, max: number): number;
+export declare function preservedAcpAdvanced(previous: Record<string, unknown>): Record<string, unknown>;
+export declare function setOptionalString(target: Record<string, unknown>, key: string, value: string | undefined): void;
+export declare function validHeaderName(value: string): boolean;
+export declare function safeSecretEqual(left: string, right: string): boolean;
+export declare function cleanString(value: unknown): string;
+export declare function recordValue(value: unknown): Record<string, any>;
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+export declare function errorMessage(error: unknown): string;

package/dist/control-plane-validation.js

@@ -0,0 +1,152 @@
+import { timingSafeEqual } from 'node:crypto';
+import { validateAdminPassword } from './auth.js';
+export class ControlPlaneError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+    }
+}
+export function validateRuntimeSettings(update) {
+    validateIntegerRange(update.sessionTtlMs, 60_000, 30 * 24 * 60 * 60 * 1000, 'sessionTtlMs');
+    validateIntegerRange(update.promptTimeoutMs, 10_000, 24 * 60 * 60 * 1000, 'promptTimeoutMs');
+    validateIntegerRange(update.cleanupIntervalMs, 5_000, 60 * 60 * 1000, 'cleanupIntervalMs');
+}
+export function validateIntegerRange(value, min, max, name) {
+    if (!Number.isInteger(value) || value < min || value > max) {
+        throw new ControlPlaneError(400, `${name} must be between ${min} and ${max}`);
+    }
+}
+export function validateUpdate(update) {
+    if (update.protocol !== undefined && update.protocol !== 'acp' && update.protocol !== 'a2a') {
+        throw new ControlPlaneError(400, 'protocol must be acp or a2a');
+    }
+    if (update.permissionPolicy !== undefined &&
+        update.permissionPolicy !== 'ask' &&
+        update.permissionPolicy !== 'allow' &&
+        update.permissionPolicy !== 'deny') {
+        throw new ControlPlaneError(400, 'permissionPolicy must be ask, allow, or deny');
+    }
+    if (update.preferredTransport !== undefined &&
+        !['auto', 'jsonrpc', 'http-json'].includes(update.preferredTransport)) {
+        throw new ControlPlaneError(400, 'preferredTransport must be auto, jsonrpc, or http-json');
+    }
+}
+export function validateAgentId(value) {
+    const id = decodeURIComponent(value).trim().toLowerCase();
+    if (!/^[a-z0-9][a-z0-9._-]{0,63}$/.test(id)) {
+        throw new ControlPlaneError(400, 'Invalid Agent ID');
+    }
+    return id;
+}
+export function validateOpaqueId(value, label) {
+    const id = decodeURIComponent(value).trim();
+    if (!/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}$/.test(id)) {
+        throw new ControlPlaneError(400, `Invalid ${label} ID`);
+    }
+    return id;
+}
+export function validatePassword(value, confirmation) {
+    if (value !== confirmation) {
+        throw new ControlPlaneError(400, 'Console Password confirmation does not match');
+    }
+    try {
+        return validateAdminPassword(value);
+    }
+    catch (error) {
+        throw new ControlPlaneError(400, errorMessage(error));
+    }
+}
+export function validateKeyName(value) {
+    const name = cleanString(value);
+    if (!name)
+        throw new ControlPlaneError(400, 'API Key name is required');
+    if (name.length > 80)
+        throw new ControlPlaneError(400, 'API Key name is too long');
+    return name;
+}
+export function validateApiKeySecret(value) {
+    const secret = cleanString(value);
+    if (secret.length < 16) {
+        throw new ControlPlaneError(400, 'Custom API Key must contain at least 16 characters');
+    }
+    if (Buffer.byteLength(secret, 'utf8') > 512) {
+        throw new ControlPlaneError(400, 'Custom API Key must not exceed 512 bytes');
+    }
+    if (/^env:/i.test(secret) || /[\u0000-\u001f\u007f]/.test(secret)) {
+        throw new ControlPlaneError(400, 'Custom API Key contains an unsupported value');
+    }
+    return secret;
+}
+export function validateA2ASecret(value) {
+    const secret = cleanString(value);
+    if (!secret)
+        return '';
+    if (/^env:/i.test(secret) ||
+        Buffer.byteLength(secret, 'utf8') > 4096 ||
+        /[\u0000\r\n]/.test(secret)) {
+        throw new ControlPlaneError(400, 'A2A authentication value is invalid');
+    }
+    return secret;
+}
+export function validateAgentUrl(value) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw new ControlPlaneError(400, 'A2A Agent Card URL is invalid');
+    }
+    if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password || url.hash) {
+        throw new ControlPlaneError(400, 'A2A Agent Card URL must use http(s) without credentials or a fragment');
+    }
+    return url.toString().replace(/\/$/, '');
+}
+export function defaultAgentCardUrl(agentUrl) {
+    if (!agentUrl)
+        return undefined;
+    return new URL('/.well-known/agent-card.json', agentUrl).toString();
+}
+export function clampTimeout(value, fallback, min, max) {
+    if (value === undefined)
+        return fallback;
+    if (!Number.isInteger(value) || value < min || value > max) {
+        throw new ControlPlaneError(400, `timeout must be between ${min} and ${max}`);
+    }
+    return value;
+}
+export function preservedAcpAdvanced(previous) {
+    const result = {};
+    for (const key of ['command', 'args', 'probeArgs', 'inheritEnv', 'env']) {
+        if (previous[key] !== undefined)
+            result[key] = structuredClone(previous[key]);
+    }
+    return result;
+}
+export function setOptionalString(target, key, value) {
+    const text = cleanString(value);
+    if (text)
+        target[key] = text;
+    else
+        delete target[key];
+}
+export function validHeaderName(value) {
+    return /^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/.test(value);
+}
+export function safeSecretEqual(left, right) {
+    const leftBuffer = Buffer.from(left);
+    const rightBuffer = Buffer.from(right);
+    return leftBuffer.length === rightBuffer.length && timingSafeEqual(leftBuffer, rightBuffer);
+}
+export function cleanString(value) {
+    return typeof value === 'string' ? value.trim() : '';
+}
+export function recordValue(value) {
+    return isRecord(value) ? { ...value } : {};
+}
+export function isRecord(value) {
+    return Boolean(value && typeof value === 'object' && !Array.isArray(value));
+}
+export function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/control-plane.d.ts

@@ -1,39 +1,20 @@
+import { type AgentdAgentUpdate, type AgentdApiKeyUpdate, type AgentdRuntimeSettingsUpdate } from './control-plane-validation.js';
+export { ControlPlaneError, type AgentdAgentUpdate, type AgentdApiKeyUpdate, type AgentdRuntimeSettingsUpdate } from './control-plane-validation.js';
 import type { SessionManager } from './session.js';
-import { type A2AAuthType, type A2ATransportPreference, type AgentdApiKeyPrincipal, type AgentdApiKeyScope, type AgentdApiKeyView, type AgentdConfig, type AgentdControlPlaneView, type AgentdDriverKind, type AgentdProtocol, type PermissionPolicy } from './types.js';
-export interface AgentdAgentUpdate {
-    protocol?: AgentdProtocol;
-    driver?: AgentdDriverKind;
-    name?: string;
-    description?: string;
-    enabled?: boolean;
-    workspace?: string;
-    permissionPolicy?: PermissionPolicy;
-    permissionTimeoutMs?: number;
-    agentCardUrl?: string;
-    agentUrl?: string;
-    preferredTransport?: A2ATransportPreference;
-    authType?: A2AAuthType;
-    authValue?: string;
-    authHeaderName?: string;
-    timeoutMs?: number;
-}
-export interface AgentdApiKeyUpdate {
-    name?: string;
-    enabled?: boolean;
-    scope?: AgentdApiKeyScope;
-}
-export interface AgentdRuntimeSettingsUpdate {
-    sessionTtlMs: number;
-    promptTimeoutMs: number;
-    cleanupIntervalMs: number;
-}
+import { type AgentdApiKeyPrincipal, type AgentdApiKeyScope, type AgentdApiKeyView, type AgentdConfig, type AgentdControlPlaneView } from './types.js';
 export declare class AgentdControlPlane {
     private readonly configPath;
     private config;
     private readonly sessions;
+    /** Process-local proof, delivered only through the local CLI / embedding API. */
+    setupToken?: string;
     private queue;
     private usageTimer?;
+    private readonly keyWatchers;
+    /** Observe authorization without updating last-used time or retaining a stale scope. */
+    watchApiKey(keyId: string, secret: string, agentId: string, revoked: () => void): () => void;
     constructor(configPath: string, config: AgentdConfig, sessions: SessionManager);
+    verifySetupToken(token: string): boolean;
     snapshot(): AgentdControlPlaneView;
     isInitialized(): boolean;
     needsAdminSetup(): boolean;
@@ -85,7 +66,3 @@ export declare class AgentdControlPlane {
     private agentView;
     private exclusive;
 }
-export declare class ControlPlaneError extends Error {
-    readonly status: number;
-    constructor(status: number, message: string);
-}