nexus-agentd 0.1.1 → 0.1.7

package/dist/acp/runtime.js

@@ -1,6 +1,10 @@
 import { randomUUID } from 'node:crypto';
+import { mkdir, rm, writeFile } from 'node:fs/promises';
+import path from 'node:path';
 import { Readable, Writable } from 'node:stream';
+import { pathToFileURL } from 'node:url';
 import * as acp from '@agentclientprotocol/sdk';
+import { buildAgentInstructions, composeInitialAgentPrompt } from '../agent-instructions.js';
 export class AcpProcessRuntime {
     driver;
     sink;
@@ -10,13 +14,26 @@ export class AcpProcessRuntime {
     pendingInput;
     disposed = false;
     prompting = false;
-    constructor(driver, sink) {
+    maxStderrChunkChars;
+    promptTimeoutMs;
+    instructions;
+    firstPrompt = true;
+    promptCapabilities = {};
+    inputDirectory;
+    constructor(driver, sink, maxStderrChunkChars = 16 * 1024, promptTimeoutMs = 30 * 60 * 1000, customInstructions) {
         this.driver = driver;
         this.sink = sink;
+        const limit = Number.isFinite(maxStderrChunkChars)
+            ? Math.floor(maxStderrChunkChars)
+            : 16 * 1024;
+        this.maxStderrChunkChars = Math.max(1, Math.min(16 * 1024, limit));
+        this.promptTimeoutMs = Math.max(10_000, Math.trunc(promptTimeoutMs));
+        this.instructions = buildAgentInstructions(customInstructions);
     }
     async start(workspace) {
         if (this.process)
             throw new Error('ACP runtime is already started');
+        this.inputDirectory = path.join(workspace, '.nexus-inputs', this.sink.id);
         const child = this.driver.spawn(workspace);
         this.process = child;
         this.captureStderr(child);
@@ -47,7 +64,7 @@ export class AcpProcessRuntime {
             },
             clientInfo: {
                 name: 'nexus-agentd',
-                version: '0.1.1'
+                version: '0.1.4'
             }
         });
         if (initialize.protocolVersion !== acp.PROTOCOL_VERSION) {
@@ -56,6 +73,7 @@ export class AcpProcessRuntime {
                 text: `ACP negotiated protocol ${initialize.protocolVersion}`
             });
         }
+        this.promptCapabilities = initialize.agentCapabilities?.promptCapabilities || {};
         const session = await this.connection.agent.request(acp.methods.agent.session.new, {
             cwd: workspace,
             mcpServers: []
@@ -63,7 +81,7 @@ export class AcpProcessRuntime {
         this.sink.setAcpSessionId(String(session.sessionId));
         this.sink.setState('created');
     }
-    async prompt(message) {
+    async prompt(message, attachments = []) {
         if (!this.connection)
             throw new Error('ACP runtime is not connected');
         if (this.prompting)
@@ -72,13 +90,18 @@ export class AcpProcessRuntime {
         this.prompting = true;
         this.sink.clearPending();
         this.sink.setState('running');
+        const promptMessage = this.firstPrompt
+            ? composeInitialAgentPrompt(this.instructions, message)
+            : message;
+        this.firstPrompt = false;
         try {
-            const response = await this.connection.agent.request(acp.methods.agent.session.prompt, {
+            const response = await withTimeout(this.connection.agent.request(acp.methods.agent.session.prompt, {
                 sessionId,
-                prompt: [{ type: 'text', text: message }]
-            });
-            if (this.sink.state === 'canceled')
+                prompt: await this.promptBlocks(promptMessage, attachments)
+            }), this.promptTimeoutMs, 'ACP prompt timed out');
+            if (this.sink.state === 'canceled' || this.sink.state === 'failed') {
                 return;
+            }
             if (response.stopReason === 'cancelled') {
                 this.sink.setState('canceled');
             }
@@ -93,12 +116,14 @@ export class AcpProcessRuntime {
             if (this.sink.state !== 'canceled') {
                 this.sink.setState('failed', error instanceof Error ? error.message : String(error));
             }
+            if (error instanceof PromptTimeoutError)
+                await this.dispose();
         }
         finally {
             this.prompting = false;
         }
     }
-    async respondPending(message) {
+    async respondPending(message, _attachments = []) {
         if (this.pendingInput) {
             this.finishInput(message);
             return;
@@ -168,6 +193,10 @@ export class AcpProcessRuntime {
         }
         this.connection?.close();
         this.connection = undefined;
+        if (this.inputDirectory) {
+            await rm(this.inputDirectory, { recursive: true, force: true }).catch(() => undefined);
+            this.inputDirectory = undefined;
+        }
         const child = this.process;
         this.process = undefined;
         if (child && child.exitCode === null && child.signalCode === null) {
@@ -286,11 +315,15 @@ export class AcpProcessRuntime {
                         content: update.content
                     });
                 }
+                else {
+                    this.captureArtifact(update.content, `message:${String(update.messageId || 'assistant')}:0`);
+                }
                 break;
             case 'agent_thought_chunk':
                 this.sink.emit('thought_chunk', update);
                 break;
             case 'tool_call':
+                this.captureToolArtifacts(String(update.toolCallId), update.content, update.title);
                 this.sink.emit('tool_call', update);
                 if (update.locations?.length) {
                     this.sink.emit('file_activity', {
@@ -300,6 +333,7 @@ export class AcpProcessRuntime {
                 }
                 break;
             case 'tool_call_update':
+                this.captureToolArtifacts(String(update.toolCallId), update.content, update.title || update.name);
                 this.sink.emit('tool_update', update);
                 if (update.locations?.length) {
                     this.sink.emit('file_activity', {
@@ -317,21 +351,57 @@ export class AcpProcessRuntime {
                 break;
         }
     }
+    captureToolArtifacts(toolCallId, content, hint) {
+        content?.forEach((item, index) => {
+            if (item.type !== 'content')
+                return;
+            this.captureArtifact(item.content, `tool:${toolCallId}:${index}`, hint || undefined);
+        });
+    }
+    captureArtifact(content, id, hint) {
+        const artifact = artifactFromContent(content, id, hint);
+        if (artifact)
+            this.sink.addArtifact(artifact);
+    }
     captureStderr(child) {
         let buffer = '';
-        child.stderr.on('data', (chunk) => {
-            buffer += String(chunk);
+        let flushed = false;
+        const emit = (text) => {
+            if (!text)
+                return;
+            for (let offset = 0; offset < text.length; offset += this.maxStderrChunkChars) {
+                this.sink.emit('terminal_output', {
+                    stream: 'stderr',
+                    text: text.slice(offset, offset + this.maxStderrChunkChars)
+                });
+            }
+        };
+        const drain = (flush = false) => {
             const lines = buffer.split(/\r?\n/);
             buffer = lines.pop() || '';
-            for (const line of lines) {
-                if (line) {
-                    this.sink.emit('terminal_output', {
-                        stream: 'stderr',
-                        text: line
-                    });
-                }
+            for (const line of lines)
+                emit(line);
+            while (buffer.length >= this.maxStderrChunkChars) {
+                emit(buffer.slice(0, this.maxStderrChunkChars));
+                buffer = buffer.slice(this.maxStderrChunkChars);
             }
+            if (flush && buffer) {
+                emit(buffer);
+                buffer = '';
+            }
+        };
+        const flush = () => {
+            if (flushed)
+                return;
+            flushed = true;
+            drain(true);
+        };
+        child.stderr.on('data', (chunk) => {
+            buffer += String(chunk);
+            drain();
         });
+        child.stderr.once('end', flush);
+        child.stderr.once('close', flush);
     }
     onProcessFailure(error) {
         if (this.disposed)
@@ -345,6 +415,175 @@ export class AcpProcessRuntime {
         }
         return value;
     }
+    async promptBlocks(message, attachments) {
+        const blocks = [{ type: 'text', text: message }];
+        for (const attachment of attachments) {
+            const mediaType = attachment.mediaType || 'application/octet-stream';
+            const data = attachment.bytes.toString('base64');
+            if (mediaType.startsWith('image/') && this.promptCapabilities.image) {
+                blocks.push({ type: 'image', data, mimeType: mediaType });
+                continue;
+            }
+            if (mediaType.startsWith('audio/') && this.promptCapabilities.audio) {
+                blocks.push({ type: 'audio', data, mimeType: mediaType });
+                continue;
+            }
+            if (this.promptCapabilities.embeddedContext) {
+                blocks.push({
+                    type: 'resource',
+                    resource: {
+                        uri: `nexus-input://${this.sink.id}/${encodeURIComponent(attachment.name)}`,
+                        blob: data,
+                        mimeType: mediaType
+                    }
+                });
+                continue;
+            }
+            blocks.push(await this.writeResourceLink(attachment, mediaType));
+        }
+        return blocks;
+    }
+    async writeResourceLink(attachment, mediaType) {
+        const directory = this.inputDirectory || path.join(process.cwd(), '.nexus-inputs', this.sink.id);
+        this.inputDirectory = directory;
+        await mkdir(directory, { recursive: true });
+        const filename = `${attachment.id}-${safeFilename(attachment.name) || 'attachment'}`;
+        const filePath = path.join(directory, filename);
+        await writeFile(filePath, attachment.bytes, { mode: 0o600 });
+        return {
+            type: 'resource_link',
+            name: attachment.name,
+            uri: pathToFileURL(filePath).toString(),
+            mimeType: mediaType,
+            size: attachment.bytes.length
+        };
+    }
+}
+class PromptTimeoutError extends Error {
+}
+function safeFilename(value) {
+    return String(value || '')
+        .replace(/[<>:"/\\|?*\u0000-\u001f]/g, '_')
+        .trim()
+        .slice(0, 180);
+}
+function withTimeout(promise, timeoutMs, message) {
+    let timer;
+    const timeout = new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new PromptTimeoutError(message)), timeoutMs);
+        timer.unref?.();
+    });
+    return Promise.race([promise, timeout]).finally(() => {
+        if (timer)
+            clearTimeout(timer);
+    });
+}
+function artifactFromContent(content, id, hint) {
+    switch (content.type) {
+        case 'image': {
+            const filename = artifactFilename(content.uri, hint, `image-${artifactIndex(id)}`, content.mimeType);
+            return {
+                id,
+                name: filename,
+                filename,
+                mediaType: content.mimeType,
+                bytesBase64: content.data,
+                url: usableUrl(content.uri),
+                metadata: artifactMetadata(id, content.uri, content.annotations)
+            };
+        }
+        case 'audio': {
+            const filename = artifactFilename(undefined, hint, `audio-${artifactIndex(id)}`, content.mimeType);
+            return {
+                id,
+                name: filename,
+                filename,
+                mediaType: content.mimeType,
+                bytesBase64: content.data,
+                metadata: artifactMetadata(id, undefined, content.annotations)
+            };
+        }
+        case 'resource_link': {
+            const filename = artifactFilename(content.uri, content.name || hint, `resource-${artifactIndex(id)}`, content.mimeType || undefined);
+            return {
+                id,
+                name: content.title || content.name || filename,
+                description: content.description || undefined,
+                filename,
+                mediaType: content.mimeType || undefined,
+                url: content.uri,
+                metadata: artifactMetadata(id, content.uri, content.annotations, content.size ?? undefined)
+            };
+        }
+        case 'resource': {
+            const resource = content.resource;
+            const filename = artifactFilename(resource.uri, hint, `resource-${artifactIndex(id)}`, resource.mimeType || undefined);
+            return {
+                id,
+                name: filename,
+                filename,
+                mediaType: resource.mimeType || undefined,
+                text: 'text' in resource ? resource.text : undefined,
+                bytesBase64: 'blob' in resource ? resource.blob : undefined,
+                url: usableUrl(resource.uri),
+                metadata: artifactMetadata(id, resource.uri, content.annotations)
+            };
+        }
+        default:
+            return undefined;
+    }
+}
+function artifactMetadata(sourceId, uri, annotations, size) {
+    return {
+        sourceId,
+        ...(uri ? { uri } : {}),
+        ...(size !== undefined ? { size } : {}),
+        ...(annotations ? { annotations } : {})
+    };
+}
+function artifactFilename(uri, hint, fallback, mediaType) {
+    return (filenameFromValue(uri) ||
+        filenameFromValue(hint) ||
+        `${fallback}${extensionForMediaType(mediaType)}`);
+}
+function filenameFromValue(value) {
+    if (!value)
+        return undefined;
+    let candidate = value;
+    try {
+        candidate = new URL(value).pathname;
+    }
+    catch { }
+    candidate = candidate.split(/[\\/]/).pop() || candidate;
+    candidate = candidate.split(/[?#]/, 1)[0].trim();
+    const filename = candidate.match(/([^\s]+\.[A-Za-z0-9]{1,16})$/)?.[1];
+    if (!filename)
+        return undefined;
+    try {
+        return decodeURIComponent(filename);
+    }
+    catch {
+        return filename;
+    }
+}
+function usableUrl(value) {
+    return value && /^(?:https?|file):/i.test(value) ? value : undefined;
+}
+function artifactIndex(id) {
+    return id.split(':').pop() || 'output';
+}
+function extensionForMediaType(mediaType) {
+    const extensions = {
+        'image/png': '.png',
+        'image/jpeg': '.jpg',
+        'image/gif': '.gif',
+        'image/webp': '.webp',
+        'audio/mpeg': '.mp3',
+        'audio/wav': '.wav',
+        'audio/ogg': '.ogg',
+        'application/pdf': '.pdf'
+    };
+    return mediaType ? extensions[mediaType.toLowerCase()] || '' : '';
 }
 function elicitationOptions(params) {
     if (!isFormElicitation(params))

package/dist/agent-instructions.d.ts

@@ -0,0 +1,11 @@
+export declare const MAX_AGENT_INSTRUCTIONS_CHARS: number;
+/**
+ * Baseline guidance for Agents running behind Agent Nexus.
+ *
+ * This is delivered as the first prompt because ACP and A2A do not expose a
+ * portable system-message field across all supported Agent implementations.
+ */
+export declare const DEFAULT_AGENT_INSTRUCTIONS: string;
+export declare function normalizeAgentInstructions(value: unknown, field?: string): string | undefined;
+export declare function buildAgentInstructions(custom?: string): string;
+export declare function composeInitialAgentPrompt(instructions: string, userMessage: string): string;

package/dist/agent-instructions.js

@@ -0,0 +1,44 @@
+export const MAX_AGENT_INSTRUCTIONS_CHARS = 32 * 1024;
+/**
+ * Baseline guidance for Agents running behind Agent Nexus.
+ *
+ * This is delivered as the first prompt because ACP and A2A do not expose a
+ * portable system-message field across all supported Agent implementations.
+ */
+export const DEFAULT_AGENT_INSTRUCTIONS = [
+    'You are running behind the Agent Nexus conversational host.',
+    'When an external tool or operation needs the user to choose, confirm, authorize, pay, or provide more information before it can continue:',
+    '1. Do not present the task as completed.',
+    '2. Use the host\'s native user-input, elicitation, or permission request mechanism when available; do not only print a normal-text question and stop.',
+    '3. Include a concise prompt and structured options when the mechanism supports them. For payment, include the payment URL and stable order metadata.',
+    '4. After the user replies, validate the result with the upstream tool. Never treat a message such as "payment completed" as proof that payment succeeded.',
+    'Only finish the task after the external operation has actually completed.'
+].join('\n');
+export function normalizeAgentInstructions(value, field = 'instructions') {
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value !== 'string')
+        throw new Error(`${field} must be a string`);
+    const text = value.trim();
+    if (text.length > MAX_AGENT_INSTRUCTIONS_CHARS) {
+        throw new Error(`${field} must be at most ${MAX_AGENT_INSTRUCTIONS_CHARS} characters`);
+    }
+    return text || undefined;
+}
+export function buildAgentInstructions(custom) {
+    const extra = normalizeAgentInstructions(custom);
+    return extra
+        ? `${DEFAULT_AGENT_INSTRUCTIONS}\n\nAdditional agent-specific instructions:\n${extra}`
+        : DEFAULT_AGENT_INSTRUCTIONS;
+}
+export function composeInitialAgentPrompt(instructions, userMessage) {
+    return [
+        '<agent-nexus-host-instructions>',
+        instructions,
+        '</agent-nexus-host-instructions>',
+        '',
+        '<user-request>',
+        userMessage,
+        '</user-request>'
+    ].join('\n');
+}

package/dist/artifact-store.d.ts

@@ -0,0 +1,41 @@
+import { type FileHandle } from 'node:fs/promises';
+import { type Readable } from 'node:stream';
+import type { AgentdPublishedFile } from './types.js';
+interface StoredArtifact extends AgentdPublishedFile {
+    filePath: string;
+    handle?: FileHandle;
+}
+export declare class ArtifactStoreError extends Error {
+    readonly status: number;
+    constructor(status: number, message: string);
+}
+export declare class GatewayArtifactStore {
+    private readonly directory;
+    private readonly ttlMs;
+    private readonly maxBytes;
+    private readonly maxStorageBytes;
+    private readonly maxFiles;
+    private readonly maxConcurrentPublishes;
+    private readonly byCacheKey;
+    private cleanupTimer?;
+    private capacityQueue;
+    private activePublishes;
+    private reservedBytes;
+    private reservedFiles;
+    constructor(directory: string, ttlMs: number, maxBytes: number, maxStorageBytes?: number, maxFiles?: number, maxConcurrentPublishes?: number);
+    startCleanup(intervalMs?: number): void;
+    stopCleanup(): void;
+    publishFile(filePath: string, preferredName?: string, mediaType?: string): Promise<AgentdPublishedFile>;
+    publishHandle(handle: FileHandle, preferredName: string, mediaType?: string): Promise<AgentdPublishedFile>;
+    publishBytes(bytes: Uint8Array, preferredName: string, mediaType?: string, cacheKey?: string): Promise<AgentdPublishedFile>;
+    publishStream(input: Readable, preferredName: string, mediaType?: string, declaredSize?: number, cacheKey?: string): Promise<AgentdPublishedFile>;
+    open(id: string, expiresInput: string, requestedName: string): Promise<StoredArtifact>;
+    cleanup(): Promise<void>;
+    private ensureDirectory;
+    private isAvailable;
+    private reserveCapacity;
+    private storageUsage;
+}
+export declare function contentDisposition(name: string): string;
+export declare function mediaTypeForName(name: string): string;
+export {};