nexus-agentd 0.2.5 → 0.3.0

package/dist/acp/runtime.js

@@ -1,15 +1,21 @@
 import { randomUUID } from 'node:crypto';
-import { mkdir, readFile, realpath, rm, stat, writeFile } from 'node:fs/promises';
+import { mkdir, rm, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import { Readable, Writable } from 'node:stream';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import * as acp from '@agentclientprotocol/sdk';
 import { terminateProcessTree } from '../process-tree.js';
 import { TURN_COMPLETION_CONTRACT } from '../completion-contract.js';
-const MAX_MEDIA_MARKER_FILE_BYTES = 32 * 1024 * 1024;
+import { readContainedFile } from '../workspace.js';
+// Matches MAX_PUBLISHED_FILE_BYTES in session.ts; larger files are encoded only to be dropped by the base64 budget.
+const MAX_MEDIA_MARKER_FILE_BYTES = 12 * 1024 * 1024;
+// The agent controls how many markers it emits, so bound the reads per turn.
+const MAX_MEDIA_MARKER_ARTIFACTS = 8;
 export class AcpProcessRuntime {
     driver;
     sink;
+    allowedRoots;
+    startupTimeoutMs;
     process;
     connection;
     pending;
@@ -22,9 +28,11 @@ export class AcpProcessRuntime {
     inputDirectory;
     workspace;
     promptOutput = '';
-    constructor(driver, sink, maxStderrChunkChars = 16 * 1024, promptTimeoutMs = 30 * 60 * 1000) {
+    constructor(driver, sink, maxStderrChunkChars = 16 * 1024, promptTimeoutMs = 30 * 60 * 1000, allowedRoots = [], startupTimeoutMs = 30_000) {
         this.driver = driver;
         this.sink = sink;
+        this.allowedRoots = allowedRoots;
+        this.startupTimeoutMs = startupTimeoutMs;
         const limit = Number.isFinite(maxStderrChunkChars)
             ? Math.floor(maxStderrChunkChars)
             : 16 * 1024;
@@ -32,6 +40,21 @@ export class AcpProcessRuntime {
         this.promptTimeoutMs = Math.max(10_000, Math.trunc(promptTimeoutMs));
     }
     async start(workspace) {
+        if (this.disposed)
+            throw new Error('ACP runtime is disposed');
+        if (this.process)
+            throw new Error('ACP runtime is already started');
+        try {
+            await withTimeout(this.connect(workspace), this.startupTimeoutMs, 'ACP startup timed out');
+        }
+        catch (error) {
+            if (this.sink.state !== 'canceled')
+                this.onProcessFailure(error);
+            await this.dispose();
+            throw error;
+        }
+    }
+    async connect(workspace) {
         if (this.process)
             throw new Error('ACP runtime is already started');
         this.workspace = workspace;
@@ -69,6 +92,8 @@ export class AcpProcessRuntime {
                 version: '0.2.2'
             }
         });
+        if (this.disposed)
+            throw new Error('ACP runtime is disposed');
         if (initialize.protocolVersion !== acp.PROTOCOL_VERSION) {
             this.sink.emit('terminal_output', {
                 stream: 'system',
@@ -80,10 +105,14 @@ export class AcpProcessRuntime {
             cwd: workspace,
             mcpServers: []
         });
+        if (this.disposed)
+            throw new Error('ACP runtime is disposed');
         this.sink.setAcpSessionId(String(session.sessionId));
         this.sink.setState('created');
     }
     async prompt(message, attachments = []) {
+        if (this.disposed)
+            throw new Error('ACP runtime is disposed');
         if (!this.connection)
             throw new Error('ACP runtime is not connected');
         if (this.prompting)
@@ -157,11 +186,19 @@ export class AcpProcessRuntime {
             this.finishPermission({ outcome: { outcome: 'cancelled' } });
             return;
         }
-        if (response.action === 'accept') {
-            const option = options.find((item) => item.kind?.startsWith('allow')) ||
-                options.find((item) => !(item.kind?.startsWith('reject') ?? false));
+        // Protocol IDs are opaque: never interpret a numeric ID as an index or
+        // fold its case into a different (possibly permanent) permission.
+        if (response.optionId !== undefined) {
+            const option = options.find((item) => item.id === response.optionId);
+            if (!option)
+                throw new Error('Permission optionId does not match an offered option');
+            this.finishPermission({ outcome: { outcome: 'selected', optionId: option.id } });
+            return;
+        }
+        if (response.action === 'accept' && !response.optionId) {
+            const option = options.find((item) => item.kind === 'allow_once');
             if (!option) {
-                throw new Error('Permission request does not provide an allow option');
+                throw new Error('Permission request requires an explicit optionId; no allow_once option is available');
             }
             this.finishPermission({
                 outcome: { outcome: 'selected', optionId: option.id }
@@ -199,11 +236,12 @@ export class AcpProcessRuntime {
         if (this.pendingInput) {
             this.finishInput('cancel');
         }
-        if (this.connection && this.sink.state !== 'canceled') {
+        this.sink.setState('canceled');
+        if (this.connection) {
             try {
-                await this.connection.agent.notify(acp.methods.agent.session.cancel, {
+                await withTimeout(this.connection.agent.notify(acp.methods.agent.session.cancel, {
                     sessionId: this.requireSessionId()
-                });
+                }), 2_000, 'ACP cancellation notification timed out');
             }
             catch (error) {
                 this.sink.emit('terminal_output', {
@@ -229,8 +267,16 @@ export class AcpProcessRuntime {
             this.pendingInput.resolve({ action: 'cancel' });
             this.pendingInput = undefined;
         }
-        this.connection?.close();
+        const connection = this.connection;
         this.connection = undefined;
+        try {
+            connection?.close();
+        }
+        catch (error) {
+            this.sink.emit('terminal_output', {
+                stream: 'system', text: `ACP connection close failed: ${error instanceof Error ? error.message : String(error)}`
+            });
+        }
         const child = this.process;
         this.process = undefined;
         if (child) {
@@ -243,6 +289,10 @@ export class AcpProcessRuntime {
             this.inputDirectory = undefined;
         }
     }
+    isAvailable() {
+        return !this.disposed && Boolean(this.connection) &&
+            (!this.process || (this.process.exitCode === null && this.process.signalCode === null));
+    }
     requestPermission(params) {
         if (this.driver.permissionPolicy === 'deny') {
             const reject = params.options.find((option) => option.kind.startsWith('reject'));
@@ -256,8 +306,7 @@ export class AcpProcessRuntime {
                 : { outcome: { outcome: 'cancelled' } };
         }
         if (this.driver.permissionPolicy === 'allow') {
-            const allow = params.options.find((option) => option.kind.toLowerCase() === 'allow_once') ||
-                params.options.find((option) => option.kind.toLowerCase().startsWith('allow'));
+            const allow = params.options.find((option) => option.kind.toLowerCase() === 'allow_once');
             return allow
                 ? {
                     outcome: {
@@ -428,13 +477,23 @@ export class AcpProcessRuntime {
         if (!markers.length)
             return;
         this.sink.replaceOutput(withoutMediaMarkers(this.promptOutput));
-        const seen = new Set();
-        for (const marker of markers) {
-            if (seen.has(marker))
-                continue;
-            seen.add(marker);
+        const roots = this.allowedRoots.length
+            ? this.allowedRoots
+            : this.workspace
+                ? [this.workspace]
+                : [];
+        const unique = Array.from(new Set(markers));
+        const accepted = unique.slice(0, MAX_MEDIA_MARKER_ARTIFACTS);
+        const ignored = unique.length - accepted.length;
+        if (ignored > 0) {
+            this.sink.emit('terminal_output', {
+                stream: 'system',
+                text: `Ignored ${ignored} MEDIA marker(s); at most ${MAX_MEDIA_MARKER_ARTIFACTS} artifacts can be attached per turn.`
+            });
+        }
+        for (const marker of accepted) {
             try {
-                const artifact = await artifactFromMediaMarker(marker, `media:${randomUUID()}`, this.workspace);
+                const artifact = await artifactFromMediaMarker(marker, `media:${randomUUID()}`, roots);
                 this.sink.addArtifact(artifact);
                 this.sink.emit('artifact', artifact);
             }
@@ -679,7 +738,7 @@ function withoutMediaMarkers(output) {
         .join('\n')
         .trim();
 }
-async function artifactFromMediaMarker(marker, id, workspace) {
+async function artifactFromMediaMarker(marker, id, roots) {
     if (/^https?:\/\//i.test(marker)) {
         const filename = artifactFilename(marker, undefined, 'resource', undefined);
         return {
@@ -690,29 +749,19 @@ async function artifactFromMediaMarker(marker, id, workspace) {
             metadata: { source: 'acp_media_marker' }
         };
     }
-    const localPath = marker.startsWith('file:')
-        ? fileURLToPath(marker)
-        : marker;
-    const resolved = await realpath(path.isAbsolute(localPath)
-        ? localPath
-        : path.resolve(workspace || process.cwd(), localPath));
-    const details = await stat(resolved);
-    if (!details.isFile()) {
-        throw new Error('declared path is not a regular file');
-    }
-    if (details.size > MAX_MEDIA_MARKER_FILE_BYTES) {
-        throw new Error(`declared file exceeds the ${MAX_MEDIA_MARKER_FILE_BYTES} byte limit`);
-    }
-    const filename = path.basename(resolved);
+    const localPath = marker.startsWith('file:') ? fileURLToPath(marker) : marker;
+    const file = await readContainedFile(roots, localPath, {
+        maxBytes: MAX_MEDIA_MARKER_FILE_BYTES
+    });
     return {
         id,
-        name: filename,
-        filename,
-        mediaType: mediaTypeForPath(filename),
-        bytesBase64: (await readFile(resolved)).toString('base64'),
+        name: file.filename,
+        filename: file.filename,
+        mediaType: mediaTypeForPath(file.filename),
+        bytesBase64: file.bytes.toString('base64'),
         metadata: {
             source: 'acp_media_marker',
-            size: details.size
+            size: file.size
         }
     };
 }

package/dist/artifact-store.d.ts

@@ -0,0 +1,162 @@
+import type { AgentdArtifact, AgentdRunArtifactView } from './types.js';
+/**
+ * The value is persisted with run metadata so callers can distinguish a
+ * downloadable artifact from one for which the gateway only retained
+ * protocol metadata.
+ */
+export type ArtifactStorageStatus = 'pending' | 'available' | 'metadata_only' | 'expired' | 'evicted' | 'failed';
+export interface StoredArtifactView extends AgentdRunArtifactView {
+    id: string;
+    storageStatus: ArtifactStorageStatus;
+    downloadable: boolean;
+    size?: number;
+    sha256?: string;
+    createdAt: number;
+    storedAt?: number;
+    expiresAt?: number;
+    storageError?: string;
+}
+export interface ArtifactReadResult {
+    bytes: Buffer;
+    filename: string;
+    mediaType?: string;
+}
+export interface ArtifactStoreMetrics {
+    totalPayloadBytes: number;
+    /** Short alias useful to metrics consumers. */
+    payloadBytes: number;
+    queuedBytes: number;
+    pendingWrites: number;
+    retainedPayloads: number;
+    retainedRuns: number;
+    lastWriteMs: number;
+    writeFailures: number;
+    maxTotalBytes: number;
+    maxQueuedBytes: number;
+}
+/**
+ * A small, deliberately structural IO seam. Tests can inject failures or
+ * latency without replacing the filesystem globally. Production callers can
+ * leave this unset and the node fs/promises implementation is used.
+ */
+export interface ArtifactStoreIo {
+    mkdir?: (...args: any[]) => Promise<any>;
+    readFile?: (...args: any[]) => Promise<any>;
+    writeFile?: (...args: any[]) => Promise<any>;
+    rename?: (...args: any[]) => Promise<any>;
+    chmod?: (...args: any[]) => Promise<any>;
+    readdir?: (...args: any[]) => Promise<any>;
+    lstat?: (...args: any[]) => Promise<any>;
+    unlink?: (...args: any[]) => Promise<any>;
+    rm?: (...args: any[]) => Promise<any>;
+    open?: (...args: any[]) => Promise<any>;
+}
+export interface ArtifactStoreOptions {
+    /** Directory owned by this store. Defaults to `<run-file>.artifacts`. */
+    rootDir?: string;
+    /** Alias accepted for configuration adapters. */
+    artifactRootDir?: string;
+    /** Maximum payload size for one artifact. Defaults to 12 MiB. */
+    maxArtifactBytes?: number;
+    /** Maximum number of artifact metadata entries retained per run. */
+    maxArtifactsPerRun?: number;
+    /** Maximum aggregate payload bytes owned by this store. */
+    maxTotalBytes?: number;
+    /** Alias accepted for history/disk budget configuration. */
+    maxDiskBytes?: number;
+    /** Maximum bytes awaiting asynchronous persistence. */
+    maxQueuedBytes?: number;
+    /** Payload retention duration. Zero expires payloads immediately. */
+    retentionDays?: number;
+    /** Clock seam used by retention and deterministic tests. */
+    now?: () => number;
+    /** Optional IO seam used by tests. */
+    io?: ArtifactStoreIo;
+    /** Called whenever the public metadata view changes. */
+    onViewsChanged?: (runId: string, views: StoredArtifactView[]) => void;
+    /** Active runs are protected from retention and disk-budget eviction. */
+    isRunActive?: (runId: string) => boolean;
+}
+/**
+ * Durable payload store for run artifacts.
+ *
+ * The store keeps an index in memory and a small manifest per run. Payloads
+ * are written into a hashed run directory with hashed file names; incoming
+ * artifact ids, URLs, and filenames are never used as filesystem paths.
+ */
+export declare class ArtifactStore {
+    readonly rootDir: string;
+    readonly maxArtifactBytes: number;
+    readonly maxArtifactsPerRun: number;
+    readonly maxTotalBytes: number;
+    readonly maxQueuedBytes: number;
+    readonly retentionDays: number;
+    private readonly now;
+    private readonly io;
+    private readonly onViewsChanged?;
+    private readonly isRunActive;
+    private readonly entries;
+    private readonly runIds;
+    private readonly pending;
+    private readonly inFlight;
+    private readonly pendingDeletes;
+    private queuedBytes;
+    private totalBytes;
+    private activeDrain?;
+    private initialized;
+    private lastError?;
+    private lastWriteMs;
+    private writeFailures;
+    constructor(rootDir: string, options?: ArtifactStoreOptions);
+    init(): Promise<void>;
+    /**
+     * Reconcile metadata loaded from the legacy run JSON file with manifests
+     * found on disk. A run JSON file remains the source of truth for metadata;
+     * manifests only make payload bytes durable.
+     */
+    restoreRun(runId: string, views: AgentdRunArtifactView[]): StoredArtifactView[];
+    /**
+     * Record protocol artifacts synchronously. Payload conversion and queue
+     * insertion happen in memory; disk IO is scheduled in the background.
+     */
+    recordArtifacts(runId: string, artifacts: AgentdArtifact[]): StoredArtifactView[];
+    /** Merge display metadata from a RunStore update without dropping storage state. */
+    mergeViews(runId: string, views: AgentdRunArtifactView[], notify?: boolean): StoredArtifactView[];
+    views(runId: string): StoredArtifactView[];
+    readArtifact(runId: string, artifactId: string): Promise<ArtifactReadResult | undefined>;
+    /** Queue removal of one run's own directory. Active runs are protected. */
+    removeRun(runId: string): void;
+    flush(): Promise<void>;
+    get queuedByteCount(): number;
+    get storedByteCount(): number;
+    stats(): ArtifactStoreMetrics;
+    private runDrain;
+    private scheduleDrain;
+    private drainLoop;
+    private writePending;
+    private ensureBudget;
+    private evict;
+    private prune;
+    private expire;
+    private deleteRunDirectory;
+    private writeManifest;
+    private loadManifests;
+    private cleanupTemps;
+    private ensureDirectory;
+    private realDirectory;
+    private realPath;
+    private readRegularFile;
+    private safeUnlink;
+    private runDirectory;
+    private manifestPath;
+    private payloadPath;
+    private viewsForRun;
+    private addPending;
+    private removePending;
+    private requeue;
+    private emit;
+    private assertInitialized;
+}
+export declare class ArtifactBudgetError extends Error {
+}
+export declare function artifactStorePathForRunStore(runStorePath: string): string;