nexus-agentd 0.1.0 → 0.1.6

package/dist/config.js

@@ -1,6 +1,48 @@
-import { readFile } from 'node:fs/promises';
+import { mkdir, open, readFile } from 'node:fs/promises';
 import path from 'node:path';
 import { agentdDriverKinds } from './types.js';
+export async function ensureAgentdConfig(filePath, options = {}) {
+    const absolute = path.resolve(filePath);
+    try {
+        await readFile(absolute, 'utf8');
+        return { created: false };
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+    const initial = {
+        listen: {
+            host: options.host?.trim() || '127.0.0.1',
+            port: bootstrapNumber(options.port, 8787, 1, 65535)
+        },
+        initialized: false,
+        workspaceRoots: [path.resolve(options.workspace || process.cwd())],
+        sessionTtlMs: 24 * 60 * 60 * 1000,
+        promptTimeoutMs: 30 * 60 * 1000,
+        cleanupIntervalMs: 60_000,
+        apiKeys: [],
+        agents: {}
+    };
+    await mkdir(path.dirname(absolute), { recursive: true });
+    try {
+        const handle = await open(absolute, 'wx', 0o600);
+        try {
+            await handle.writeFile(`${JSON.stringify(initial, null, 2)}\n`, 'utf8');
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+        return { created: true };
+    }
+    catch (error) {
+        if (error.code === 'EEXIST') {
+            return { created: false };
+        }
+        throw error;
+    }
+}
 export async function loadAgentdConfig(filePath) {
     const absolute = path.resolve(filePath);
     const raw = await readFile(absolute, 'utf8');
@@ -13,54 +55,65 @@ export async function loadAgentdConfig(filePath) {
     }
     if (!isRecord(value))
         throw new Error('nexus-agentd config root must be an object');
-    const listen = isRecord(value.listen) ? value.listen : {};
-    const host = stringValue(listen.host) || '127.0.0.1';
-    const port = numberValue(listen.port, 8787, 1, 65535);
-    const authToken = resolveSecret(stringValue(value.authToken));
-    if (!authToken)
-        throw new Error('nexus-agentd authToken is required');
-    const workspaceRoots = arrayOfStrings(value.workspaceRoots);
+    const listen = optionalRecord(value.listen, 'listen') || {};
+    const host = optionalString(listen.host, 'listen.host') || '127.0.0.1';
+    const port = integerValue(listen.port, 'listen.port', 8787, 1, 65535);
+    const initialized = optionalBoolean(value.initialized, 'initialized') ?? true;
+    const rawAuthToken = optionalString(value.authToken, 'authToken');
+    const authToken = rawAuthToken ? resolveSecret(rawAuthToken) : undefined;
+    const adminPasswordHash = optionalString(value.adminPasswordHash, 'adminPasswordHash');
+    const apiKeys = parseApiKeys(value.apiKeys);
+    if (!initialized && (rawAuthToken || adminPasswordHash || apiKeys.length)) {
+        throw new Error('nexus-agentd pending setup must not contain authToken, credentials, or API keys');
+    }
+    if (initialized && !authToken && !adminPasswordHash && !apiKeys.length) {
+        throw new Error('nexus-agentd requires an adminPasswordHash, authToken, or API key after initialization');
+    }
+    if (authToken && !apiKeys.some((key) => secretsEqual(key.secret, authToken))) {
+        apiKeys.unshift({
+            id: 'legacy',
+            name: 'Legacy Access Key',
+            secret: authToken,
+            enabled: true,
+            scope: { allAgents: true, agentIds: [] },
+            createdAt: 0
+        });
+    }
+    const workspaceRoots = stringArray(value.workspaceRoots, 'workspaceRoots');
     if (!workspaceRoots.length) {
         throw new Error('nexus-agentd workspaceRoots must contain at least one path');
     }
-    if (!isRecord(value.agents)) {
-        throw new Error('nexus-agentd agents must be an object');
-    }
+    const rawAgents = requiredRecord(value.agents, 'agents');
     const agents = {};
-    for (const [id, input] of Object.entries(value.agents)) {
-        if (!isRecord(input))
-            throw new Error(`Agent config must be an object: ${id}`);
-        const driver = stringValue(input.driver) || inferDriver(id);
-        if (!isAgentdDriverKind(driver)) {
-            throw new Error(`Unsupported nexus-agentd driver: ${driver || id}`);
-        }
-        const permissionPolicy = stringValue(input.permissionPolicy) || 'ask';
-        if (permissionPolicy !== 'ask' && permissionPolicy !== 'deny') {
-            throw new Error(`Invalid permissionPolicy for ${id}`);
-        }
-        agents[id] = {
-            driver,
-            name: optionalString(input.name),
-            description: optionalString(input.description),
-            enabled: input.enabled !== false,
-            command: optionalString(input.command),
-            args: input.args === undefined ? undefined : arrayOfStrings(input.args),
-            inheritEnv: input.inheritEnv === undefined
-                ? undefined
-                : arrayOfStrings(input.inheritEnv),
-            env: recordOfStrings(input.env),
-            permissionPolicy,
-            permissionTimeoutMs: numberValue(input.permissionTimeoutMs, 15 * 60 * 1000, 1000, 24 * 60 * 60 * 1000)
-        };
+    for (const [id, input] of Object.entries(rawAgents)) {
+        agents[id] = parseAgent(id, input);
     }
     return {
         listen: { host, port },
+        initialized,
         authToken,
+        adminPasswordHash,
+        apiKeys,
         workspaceRoots,
-        maxRequestBytes: numberValue(value.maxRequestBytes, 1024 * 1024, 1024, 16 * 1024 * 1024),
-        maxEventsPerSession: numberValue(value.maxEventsPerSession, 2048, 64, 100_000),
-        maxOutputChars: numberValue(value.maxOutputChars, 512 * 1024, 16 * 1024, 16 * 1024 * 1024),
-        sessionTtlMs: numberValue(value.sessionTtlMs, 24 * 60 * 60 * 1000, 60_000, 30 * 24 * 60 * 60 * 1000),
+        maxRequestBytes: integerValue(value.maxRequestBytes, 'maxRequestBytes', 1024 * 1024, 1024, 16 * 1024 * 1024),
+        maxAttachmentBytes: integerValue(value.maxAttachmentBytes, 'maxAttachmentBytes', 32 * 1024 * 1024, 1024, 64 * 1024 * 1024),
+        artifactStoragePath: resolveConfigPath(absolute, optionalString(value.artifactStoragePath, 'artifactStoragePath') || './artifacts'),
+        maxArtifactBytes: integerValue(value.maxArtifactBytes, 'maxArtifactBytes', 512 * 1024 * 1024, 1024, 16 * 1024 * 1024 * 1024),
+        maxArtifactStorageBytes: integerValue(value.maxArtifactStorageBytes, 'maxArtifactStorageBytes', 4 * 1024 * 1024 * 1024, 1024 * 1024, Number.MAX_SAFE_INTEGER),
+        maxPublishedArtifacts: integerValue(value.maxPublishedArtifacts, 'maxPublishedArtifacts', 4096, 1, 1_000_000),
+        maxConcurrentArtifactPublishes: integerValue(value.maxConcurrentArtifactPublishes, 'maxConcurrentArtifactPublishes', 4, 1, 128),
+        artifactTtlMs: integerValue(value.artifactTtlMs, 'artifactTtlMs', 24 * 60 * 60 * 1000, 60_000, 30 * 24 * 60 * 60 * 1000),
+        maxEventsPerSession: integerValue(value.maxEventsPerSession, 'maxEventsPerSession', 2048, 64, 100_000),
+        maxOutputChars: integerValue(value.maxOutputChars, 'maxOutputChars', 512 * 1024, 16 * 1024, 16 * 1024 * 1024),
+        sessionTtlMs: integerValue(value.sessionTtlMs, 'sessionTtlMs', 24 * 60 * 60 * 1000, 60_000, 30 * 24 * 60 * 60 * 1000),
+        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),
+        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),
+        secureAdminCookies: optionalBoolean(value.secureAdminCookies, 'secureAdminCookies') ?? false,
         agents
     };
 }
@@ -75,6 +128,126 @@ export function resolveSecret(value) {
         throw new Error(`Secret environment variable is missing: ${name}`);
     return secret;
 }
+function parseAgent(id, value) {
+    const input = requiredRecord(value, `agents.${id}`);
+    const protocol = optionalString(input.protocol, `agents.${id}.protocol`) || 'acp';
+    if (protocol === 'a2a')
+        return parseA2AAgent(id, input);
+    if (protocol !== 'acp')
+        throw new Error(`Unsupported protocol for ${id}: ${protocol}`);
+    const driver = optionalString(input.driver, `agents.${id}.driver`) || inferDriver(id);
+    if (!isAgentdDriverKind(driver)) {
+        throw new Error(`Unsupported nexus-agentd driver: ${driver || id}`);
+    }
+    const permissionPolicy = optionalString(input.permissionPolicy, `agents.${id}.permissionPolicy`) || 'ask';
+    if (permissionPolicy !== 'ask' && permissionPolicy !== 'deny') {
+        throw new Error(`Invalid permissionPolicy for ${id}`);
+    }
+    const result = {
+        protocol: 'acp',
+        driver,
+        name: optionalString(input.name, `agents.${id}.name`),
+        description: optionalString(input.description, `agents.${id}.description`),
+        enabled: optionalBoolean(input.enabled, `agents.${id}.enabled`) ?? true,
+        workspace: optionalString(input.workspace, `agents.${id}.workspace`),
+        command: optionalString(input.command, `agents.${id}.command`),
+        args: input.args === undefined
+            ? undefined
+            : stringArray(input.args, `agents.${id}.args`),
+        inheritEnv: input.inheritEnv === undefined
+            ? undefined
+            : stringArray(input.inheritEnv, `agents.${id}.inheritEnv`),
+        env: optionalStringRecord(input.env, `agents.${id}.env`),
+        permissionPolicy,
+        permissionTimeoutMs: integerValue(input.permissionTimeoutMs, `agents.${id}.permissionTimeoutMs`, 15 * 60 * 1000, 1000, 24 * 60 * 60 * 1000)
+    };
+    return result;
+}
+function parseA2AAgent(id, input) {
+    const agentCardUrl = optionalString(input.agentCardUrl, `agents.${id}.agentCardUrl`);
+    const agentUrl = optionalString(input.agentUrl, `agents.${id}.agentUrl`);
+    if (!agentCardUrl && !agentUrl) {
+        throw new Error(`nexus-agentd agents.${id}.agentCardUrl is required`);
+    }
+    if (agentCardUrl)
+        validateHttpUrl(agentCardUrl, `agents.${id}.agentCardUrl`);
+    if (agentUrl)
+        validateHttpUrl(agentUrl, `agents.${id}.agentUrl`);
+    const preferredTransport = (optionalString(input.preferredTransport, `agents.${id}.preferredTransport`) || 'auto');
+    if (!['auto', 'jsonrpc', 'http-json'].includes(preferredTransport)) {
+        throw new Error(`Invalid A2A preferredTransport for ${id}`);
+    }
+    const rawAuth = optionalRecord(input.auth, `agents.${id}.auth`);
+    let auth;
+    if (rawAuth) {
+        const type = (optionalString(rawAuth.type, `agents.${id}.auth.type`) ||
+            'none');
+        if (!['none', 'bearer', 'header'].includes(type)) {
+            throw new Error(`Invalid A2A auth type for ${id}`);
+        }
+        const rawValue = optionalString(rawAuth.value, `agents.${id}.auth.value`);
+        const headerName = optionalString(rawAuth.headerName, `agents.${id}.auth.headerName`);
+        if (type !== 'none' && !rawValue) {
+            throw new Error(`A2A auth value is required for ${id}`);
+        }
+        if (type === 'header' && !validHeaderName(headerName || '')) {
+            throw new Error(`A valid A2A auth headerName is required for ${id}`);
+        }
+        auth = {
+            type,
+            value: rawValue ? resolveSecret(rawValue) : undefined,
+            headerName: type === 'header' ? headerName : undefined
+        };
+    }
+    return {
+        protocol: 'a2a',
+        name: optionalString(input.name, `agents.${id}.name`),
+        description: optionalString(input.description, `agents.${id}.description`),
+        enabled: optionalBoolean(input.enabled, `agents.${id}.enabled`) ?? true,
+        agentCardUrl,
+        agentUrl,
+        preferredTransport,
+        auth,
+        timeoutMs: integerValue(input.timeoutMs, `agents.${id}.timeoutMs`, 60_000, 1_000, 30 * 60_000)
+    };
+}
+function parseApiKeys(value) {
+    if (value === undefined)
+        return [];
+    if (!Array.isArray(value))
+        throw new Error('nexus-agentd apiKeys must be an array');
+    const ids = new Set();
+    return value.map((entry, index) => {
+        const item = requiredRecord(entry, `apiKeys[${index}]`);
+        const id = requiredString(item.id, `apiKeys[${index}].id`);
+        if (!/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}$/.test(id)) {
+            throw new Error(`Invalid API key id: ${id}`);
+        }
+        if (ids.has(id))
+            throw new Error(`Duplicate API key id: ${id}`);
+        ids.add(id);
+        const rawSecret = requiredString(item.secret, `apiKeys[${index}].secret`);
+        const scope = requiredRecord(item.scope, `apiKeys[${index}].scope`);
+        const allAgents = optionalBoolean(scope.allAgents, `apiKeys[${index}].scope.allAgents`);
+        if (allAgents === undefined) {
+            throw new Error(`apiKeys[${index}].scope.allAgents is required`);
+        }
+        return {
+            id,
+            name: requiredString(item.name, `apiKeys[${index}].name`),
+            secret: resolveSecret(rawSecret),
+            enabled: optionalBoolean(item.enabled, `apiKeys[${index}].enabled`) ?? true,
+            scope: {
+                allAgents,
+                agentIds: stringArray(scope.agentIds ?? [], `apiKeys[${index}].scope.agentIds`)
+            },
+            createdAt: integerValue(item.createdAt, `apiKeys[${index}].createdAt`, 0, 0, Number.MAX_SAFE_INTEGER),
+            lastUsedAt: item.lastUsedAt === undefined
+                ? undefined
+                : integerValue(item.lastUsedAt, `apiKeys[${index}].lastUsedAt`, 0, 0, Number.MAX_SAFE_INTEGER)
+        };
+    });
+}
 function inferDriver(id) {
     const value = id.trim().toLowerCase();
     return isAgentdDriverKind(value) ? value : '';
@@ -82,34 +255,89 @@ function inferDriver(id) {
 function isAgentdDriverKind(value) {
     return agentdDriverKinds.includes(value);
 }
+function requiredRecord(value, name) {
+    if (!isRecord(value))
+        throw new Error(`nexus-agentd ${name} must be an object`);
+    return value;
+}
+function optionalRecord(value, name) {
+    if (value === undefined)
+        return undefined;
+    return requiredRecord(value, name);
+}
 function isRecord(value) {
     return Boolean(value && typeof value === 'object' && !Array.isArray(value));
 }
-function stringValue(value) {
-    return typeof value === 'string' ? value.trim() : '';
+function requiredString(value, name) {
+    const result = optionalString(value, name);
+    if (!result)
+        throw new Error(`nexus-agentd ${name} is required`);
+    return result;
 }
-function optionalString(value) {
-    return stringValue(value) || undefined;
+function optionalString(value, name) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value !== 'string')
+        throw new Error(`nexus-agentd ${name} must be a string`);
+    return value.trim() || undefined;
 }
-function arrayOfStrings(value) {
+function optionalBoolean(value, name) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== 'boolean')
+        throw new Error(`nexus-agentd ${name} must be a boolean`);
+    return value;
+}
+function stringArray(value, name) {
     if (!Array.isArray(value))
-        return [];
-    return value.map(stringValue).filter(Boolean);
+        throw new Error(`nexus-agentd ${name} must be an array`);
+    return value.map((entry, index) => requiredString(entry, `${name}[${index}]`));
 }
-function recordOfStrings(value) {
-    if (!isRecord(value))
+function optionalStringRecord(value, name) {
+    if (value === undefined)
         return undefined;
+    const input = requiredRecord(value, name);
     const result = {};
-    for (const [key, item] of Object.entries(value)) {
-        if (typeof item !== 'string')
-            continue;
+    for (const [key, item] of Object.entries(input)) {
+        if (typeof item !== 'string') {
+            throw new Error(`nexus-agentd ${name}.${key} must be a string`);
+        }
         result[key] = item;
     }
     return result;
 }
-function numberValue(value, fallback, min, max) {
+function integerValue(value, name, fallback, min, max) {
+    if (value === undefined)
+        return fallback;
+    if (typeof value !== 'number' || !Number.isInteger(value) || value < min || value > max) {
+        throw new Error(`nexus-agentd ${name} must be an integer between ${min} and ${max}`);
+    }
+    return value;
+}
+function bootstrapNumber(value, fallback, min, max) {
     const number = Number(value);
     if (!Number.isFinite(number))
         return fallback;
     return Math.min(max, Math.max(min, Math.trunc(number)));
 }
+function validHeaderName(value) {
+    return /^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/.test(value);
+}
+function validateHttpUrl(value, name) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw new Error(`nexus-agentd ${name} must be a valid URL`);
+    }
+    if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password || url.hash) {
+        throw new Error(`nexus-agentd ${name} must be an http(s) URL without credentials or a fragment`);
+    }
+}
+function resolveConfigPath(configPath, value) {
+    return path.resolve(path.dirname(configPath), value);
+}
+function secretsEqual(left, right) {
+    return left.length === right.length && left === right;
+}

package/dist/control-plane.d.ts

@@ -0,0 +1,91 @@
+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;
+}
+export declare class AgentdControlPlane {
+    private readonly configPath;
+    private config;
+    private readonly sessions;
+    private queue;
+    private usageTimer?;
+    constructor(configPath: string, config: AgentdConfig, sessions: SessionManager);
+    snapshot(): AgentdControlPlaneView;
+    isInitialized(): boolean;
+    needsAdminSetup(): boolean;
+    /** @deprecated Legacy data-plane key accessor. */
+    accessKey(): string | undefined;
+    initializeAdminPassword(passwordInput: string, confirmationInput: string): Promise<{
+        initialized: true;
+        adminSetupRequired: false;
+    }>;
+    /** @deprecated Kept as a clear error for integrations using the old bootstrap API. */
+    initializeAccessKey(): void;
+    verifyAdminPassword(password: string): Promise<boolean>;
+    changeAdminPassword(current: string, next: string, confirmation: string): Promise<{
+        changed: true;
+    }>;
+    authenticateApiKey(secret: string): AgentdApiKeyPrincipal | undefined;
+    listApiKeys(): AgentdApiKeyView[];
+    createApiKey(nameInput: string, scopeInput: AgentdApiKeyScope, customSecret?: string): Promise<{
+        key: AgentdApiKeyView;
+        secret: string;
+    }>;
+    updateApiKey(idInput: string, update: AgentdApiKeyUpdate): Promise<AgentdApiKeyView>;
+    deleteApiKey(idInput: string): Promise<{
+        deleted: true;
+    }>;
+    revealApiKey(idInput: string): {
+        secret: string;
+    };
+    regenerateApiKey(idInput: string): Promise<{
+        key: AgentdApiKeyView;
+        secret: string;
+    }>;
+    /** @deprecated Rotates the migrated legacy key when present. */
+    rotateAccessKey(): Promise<{
+        accessKey: string;
+    }>;
+    putWorkspaceRoots(values: string[]): Promise<AgentdControlPlaneView>;
+    putRuntimeSettings(update: AgentdRuntimeSettingsUpdate): Promise<AgentdControlPlaneView>;
+    putAgent(idInput: string, update: AgentdAgentUpdate): Promise<AgentdControlPlaneView>;
+    deleteAgent(idInput: string): Promise<AgentdControlPlaneView>;
+    private updateAgents;
+    private validateScope;
+    private requireApiKey;
+    private apiKeyView;
+    private markApiKeyUsed;
+    private rawApiKeys;
+    private readRawConfig;
+    private persist;
+    private agentView;
+    private exclusive;
+}
+export declare class ControlPlaneError extends Error {
+    readonly status: number;
+    constructor(status: number, message: string);
+}