nexus-agentd 0.2.6 → 0.3.1

package/dist/drivers/index.js

@@ -4,6 +4,7 @@ import { createHermesDriver } from './hermes.js';
 import { createOpenCodeDriver } from './opencode.js';
 import { createOpenClawDriver } from './openclaw.js';
 import { createPiDriver } from './pi.js';
+import { createStdioAcpDriver } from './stdio.js';
 export function createDriverRegistry(config) {
     const drivers = new Map();
     for (const [id, driver] of Object.entries(config.agents)) {
@@ -12,6 +13,17 @@ export function createDriverRegistry(config) {
         if (driver.enabled === false)
             continue;
         switch (driver.driver) {
+            case 'stdio':
+                if (!driver.command)
+                    break;
+                drivers.set(id, createStdioAcpDriver(id, driver, {
+                    name: driver.name || id,
+                    description: driver.description || 'Custom ACP agent over stdio',
+                    command: driver.command,
+                    args: driver.args || [],
+                    probeArgs: driver.probeArgs
+                }));
+                break;
             case 'opencode':
                 drivers.set(id, createOpenCodeDriver(id, driver));
                 break;

package/dist/drivers/pi.js

@@ -15,7 +15,7 @@ export function createPiDriver(id, config) {
                 return adapter;
             const command = driver.env.PI_ACP_PI_COMMAND || 'pi';
             try {
-                const version = await probeCommand(command, ['--version'], driver.env, 'Pi runtime');
+                const version = await probeCommand(command, ['--version'], driver.env, 'Pi runtime', { ownsProcessGroup: process.platform !== 'win32' });
                 return { ...adapter, version };
             }
             catch (error) {

package/dist/drivers/stdio.d.ts

@@ -10,4 +10,7 @@ export interface StdioAcpDriverDefaults {
 }
 export declare function createStdioAcpDriver(id: string, config: AgentdDriverConfig, defaults: StdioAcpDriverDefaults): AgentDriver;
 export declare function buildEnvironment(config: AgentdDriverConfig, defaults?: Record<string, string>): NodeJS.ProcessEnv;
-export declare function probeCommand(command: string, args: string[], env: NodeJS.ProcessEnv, label: string): Promise<string>;
+export declare function probeCommand(command: string, args: string[], env: NodeJS.ProcessEnv, label: string, options?: {
+    ownsProcessGroup?: boolean;
+    timeoutMs?: number;
+}): Promise<string>;

package/dist/drivers/stdio.js

@@ -1,5 +1,9 @@
 import { spawn } from 'node:child_process';
+import { existsSync, statSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { resolveSecret } from '../config.js';
+import { terminateProcessTree } from '../process-tree.js';
 const BASE_ENV_KEYS = [
     'PATH',
     'HOME',
@@ -11,7 +15,17 @@ const BASE_ENV_KEYS = [
     'TMPDIR',
     'TEMP',
     'LANG',
-    'LC_ALL'
+    'LC_ALL',
+    // Node's Windows process creation and a number of ACP launchers require
+    // these values even when the command itself is an absolute path.
+    'SystemRoot',
+    'ComSpec',
+    'USERPROFILE',
+    'APPDATA',
+    'LOCALAPPDATA',
+    'ProgramFiles',
+    'ProgramFiles(x86)',
+    'PATHEXT'
 ];
 export function createStdioAcpDriver(id, config, defaults) {
     const command = config.command || defaults.command;
@@ -31,7 +45,7 @@ export function createStdioAcpDriver(id, config, defaults) {
         ownsProcessGroup: process.platform !== 'win32',
         async probe() {
             try {
-                const version = await probeCommand(command, defaults.probeArgs || ['--version'], env, name);
+                const version = await probeCommand(command, config.probeArgs || defaults.probeArgs || ['--version'], env, name, { ownsProcessGroup: process.platform !== 'win32' });
                 return {
                     id,
                     name,
@@ -53,7 +67,7 @@ export function createStdioAcpDriver(id, config, defaults) {
             }
         },
         spawn(workspace) {
-            return spawn(command, args, {
+            return spawnCommand(command, args, {
                 cwd: workspace,
                 env,
                 detached: process.platform !== 'win32',
@@ -75,42 +89,144 @@ export function buildEnvironment(config, defaults = {}) {
     }
     return result;
 }
-export function probeCommand(command, args, env, label) {
+export function probeCommand(command, args, env, label, options = {}) {
     return new Promise((resolve, reject) => {
-        const child = spawn(command, args, {
+        const child = spawnCommand(command, args, {
             env,
-            stdio: ['ignore', 'pipe', 'pipe']
+            stdio: ['ignore', 'pipe', 'pipe'],
+            detached: options.ownsProcessGroup ?? process.platform !== 'win32',
+            windowsHide: true
         });
         let output = '';
         let settled = false;
+        let finishing = false;
+        let timedOut = false;
+        let timer;
         const finish = (error) => {
             if (settled)
                 return;
             settled = true;
-            clearTimeout(timer);
+            if (timer)
+                clearTimeout(timer);
             if (error)
                 reject(error);
             else
                 resolve(output.trim().split(/\r?\n/)[0] || 'unknown');
         };
-        const timer = setTimeout(() => {
-            child.kill();
-            finish(new Error(`${label} probe timed out`));
-        }, 5000);
+        const ownsProcessGroup = options.ownsProcessGroup ?? process.platform !== 'win32';
+        const cleanup = () => terminateProcessTree(child, {
+            ownsProcessGroup,
+            graceMs: 250
+        });
+        const cleanupFailure = (error) => error instanceof Error ? error.message : String(error);
+        const settleExit = (code, signal) => {
+            if (settled || finishing || timedOut)
+                return;
+            finishing = true;
+            if (timer)
+                clearTimeout(timer);
+            // A successful wrapper can leave a child in its process group.
+            // Clean the group before exposing probe success/failure.
+            void cleanup().then(() => {
+                if (timedOut || settled)
+                    return;
+                finishing = false;
+                if (code === 0)
+                    finish();
+                else {
+                    finish(new Error(output.trim() ||
+                        `${label} probe exited with ${signal || code || 'unknown'}`));
+                }
+            }, (error) => {
+                if (settled)
+                    return;
+                finishing = false;
+                finish(new Error(`${label} probe cleanup failed: ${cleanupFailure(error)}`));
+            });
+        };
+        timer = setTimeout(() => {
+            if (settled || finishing || timedOut)
+                return;
+            timedOut = true;
+            finishing = true;
+            if (timer)
+                clearTimeout(timer);
+            // Probe commands are allowed to be wrappers that launch another
+            // process. Wait for tree termination before rejecting so a timed
+            // out health check cannot leave an agent running in the background.
+            void cleanup().then(() => finish(new Error(`${label} probe timed out`)), (error) => finish(new Error(`${label} probe timed out; cleanup failed: ${cleanupFailure(error)}`)));
+        }, options.timeoutMs ?? 5000);
+        timer.unref?.();
         child.stdout.on('data', (chunk) => {
             output = `${output}${String(chunk)}`.slice(-8192);
         });
         child.stderr.on('data', (chunk) => {
             output = `${output}${String(chunk)}`.slice(-8192);
         });
-        child.once('error', (error) => finish(error));
-        child.once('exit', (code, signal) => {
-            if (code === 0)
-                finish();
-            else {
-                finish(new Error(output.trim() ||
-                    `${label} probe exited with ${signal || code || 'unknown'}`));
-            }
+        child.once('error', (error) => {
+            if (settled || finishing || timedOut)
+                return;
+            finishing = true;
+            if (timer)
+                clearTimeout(timer);
+            void cleanup().then(() => finish(error), (cleanupError) => finish(new Error(`${label} probe failed (${error.message}); cleanup failed: ${cleanupFailure(cleanupError)}`)));
         });
+        child.once('exit', (code, signal) => settleExit(code, signal));
     });
 }
+function needsWindowsShell(command) {
+    return process.platform === 'win32' && /\.(?:cmd|bat)$/i.test(command);
+}
+function spawnCommand(command, args, options) {
+    const resolvedCommand = resolveWindowsCommand(command, options.env, options.cwd);
+    if (!needsWindowsShell(resolvedCommand)) {
+        return spawn(resolvedCommand, args, options);
+    }
+    // cmd.exe's /S /C parser needs an outer pair around the complete command
+    // when the batch path itself is quoted; otherwise it treats the first
+    // argument as part of the executable path.
+    const commandLine = `"${[quoteWindowsArg(resolvedCommand), ...args.map(quoteWindowsArg)].join(' ')}"`;
+    return spawn(process.env.ComSpec || 'cmd.exe', ['/d', '/s', '/c', commandLine], {
+        ...options,
+        windowsVerbatimArguments: true,
+        shell: false
+    });
+}
+function resolveWindowsCommand(command, env, cwd) {
+    if (process.platform !== 'win32')
+        return command;
+    const pathValue = env?.PATH || process.env.PATH || '';
+    const directory = cwd instanceof URL ? fileURLToPath(cwd) : cwd || process.cwd();
+    const pathEntries = pathValue.split(path.delimiter).filter(Boolean).map((entry) => entry.replace(/^"|"$/g, ''));
+    const pathExtValue = env?.PATHEXT || process.env.PATHEXT || '.COM;.EXE;.BAT;.CMD';
+    const extensions = pathExtValue
+        .split(';')
+        .map((extension) => extension.trim())
+        .filter((extension) => /^\.(?:com|exe|bat|cmd)$/i.test(extension));
+    // npm installs a POSIX shim without an extension beside its .cmd shim.
+    // That file is not a Windows executable; selecting it makes real npm
+    // commands fail even though a runnable .cmd exists in the same directory.
+    const names = /\.(?:com|exe|bat|cmd)$/i.test(command)
+        ? [command] : extensions.map((extension) => `${command}${extension}`);
+    const candidates = commandHasPath(command)
+        ? names.map((name) => path.resolve(directory, name))
+        : [directory, ...pathEntries].flatMap((entry) => names.map((name) => path.resolve(directory, entry, name)));
+    const match = candidates.find(isRegularFile);
+    return match || command;
+}
+function commandHasPath(command) {
+    return command.includes('\\') || command.includes('/') || path.win32.isAbsolute(command);
+}
+function isRegularFile(file) {
+    try {
+        return existsSync(file) && statSync(file).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+function quoteWindowsArg(value) {
+    if (!/[\s"&()^|<>]/.test(value))
+        return value;
+    return `"${value.replace(/(\\*)"/g, '$1$1\\"').replace(/(\\*)$/g, '$1$1')}"`;
+}

package/dist/events.d.ts

@@ -8,6 +8,15 @@ export declare class SessionEventLog {
     constructor(sessionId: string, maxEvents: number);
     append(type: AgentdEventType, data?: unknown): AgentdEvent;
     after(id?: string): AgentdEvent[];
+    replay(id?: string): {
+        earliestId: string;
+        latestId: string;
+        reset: {
+            reason: string;
+            requestedAfter: string | null;
+        } | undefined;
+        events: AgentdEvent[];
+    };
     subscribe(listener: (event: AgentdEvent) => void): () => boolean;
     get lastId(): string | undefined;
 }

package/dist/events.js

@@ -36,10 +36,23 @@ export class SessionEventLog {
         return event;
     }
     after(id) {
-        const sequence = Number(id || 0);
-        return this.events
-            .filter((event) => Number(event.id) > sequence)
-            .map((event) => structuredClone(event));
+        return this.replay(id).events;
+    }
+    replay(id) {
+        const sequence = id === undefined ? 0 : Number(id);
+        const earliest = Number(this.events[0]?.id || this.sequence + 1);
+        const reason = id !== undefined && (!/^\d+$/.test(id) || !Number.isSafeInteger(sequence))
+            ? 'invalid'
+            : sequence > this.sequence ? 'ahead'
+                : sequence < earliest - 1 ? 'expired' : undefined;
+        return {
+            earliestId: this.events[0]?.id ?? null,
+            latestId: String(this.sequence),
+            reset: reason ? { reason, requestedAfter: id ?? null } : undefined,
+            events: reason ? [] : this.events
+                .filter((event) => Number(event.id) > sequence)
+                .map((event) => structuredClone(event))
+        };
     }
     subscribe(listener) {
         this.listeners.add(listener);

package/dist/index.js

@@ -9,7 +9,16 @@ import { WorkspacePolicy } from './workspace.js';
 export async function startAgentd(configPath) {
     const absoluteConfigPath = path.resolve(configPath);
     const config = await loadAgentdConfig(absoluteConfigPath);
-    const runStore = new RunStore(runStorePathForConfig(absoluteConfigPath), 1000, config.maxRequestBytes);
+    const runStore = new RunStore(runStorePathForConfig(absoluteConfigPath), {
+        maxRuns: config.history?.maxRuns ?? 1000,
+        maxTaskChars: config.maxRequestBytes,
+        historyRetentionDays: config.history?.retentionDays ?? 30,
+        historyMaxBytes: config.history?.maxBytes ?? 64 * 1024 * 1024,
+        retentionDays: config.artifacts?.retentionDays ?? 30,
+        maxTotalBytes: config.artifacts?.maxBytes ?? 512 * 1024 * 1024,
+        maxArtifactBytes: config.artifacts?.maxArtifactBytes ?? 12 * 1024 * 1024,
+        maxQueuedBytes: config.artifacts?.maxQueuedBytes ?? 64 * 1024 * 1024
+    });
     await runStore.init();
     const workspacePolicy = await WorkspacePolicy.create(config.workspaceRoots);
     const sessions = new SessionManager(config, workspacePolicy, createDriverRegistry(config), runStore);

package/dist/process-tree.js

@@ -3,30 +3,39 @@ const DEFAULT_GRACE_MS = 2_000;
 const FORCE_KILL_WAIT_MS = 1_000;
 export async function terminateProcessTree(child, options = {}) {
     const pid = child.pid;
-    if (!pid || hasExited(child))
+    if (!pid)
         return;
     const graceMs = Math.max(0, options.graceMs ?? DEFAULT_GRACE_MS);
     if (process.platform === 'win32') {
+        // Once a Windows process has exited taskkill can no longer address its
+        // descendants by the parent's PID. Callers should tear down before
+        // exit when they need Windows tree semantics.
+        if (hasExited(child))
+            return;
         await taskkill(pid, false);
         if (await waitForExit(child, graceMs))
             return;
         await taskkill(pid, true);
-        await waitForExit(child, FORCE_KILL_WAIT_MS);
-        return;
+        if (await waitForExit(child, FORCE_KILL_WAIT_MS))
+            return;
+        throw new Error(`Failed to terminate process ${pid}`);
     }
     if (options.ownsProcessGroup === true) {
         signalUnixGroup(pid, 'SIGTERM');
         if (await waitForUnixGroupExit(pid, graceMs))
             return;
         signalUnixGroup(pid, 'SIGKILL');
-        await waitForUnixGroupExit(pid, FORCE_KILL_WAIT_MS);
-        return;
+        if (await waitForUnixGroupExit(pid, FORCE_KILL_WAIT_MS))
+            return;
+        throw new Error(`Failed to terminate process group ${pid}`);
     }
     signalUnix(child, 'SIGTERM');
     if (await waitForExit(child, graceMs))
         return;
     signalUnix(child, 'SIGKILL');
-    await waitForExit(child, FORCE_KILL_WAIT_MS);
+    if (await waitForExit(child, FORCE_KILL_WAIT_MS))
+        return;
+    throw new Error(`Failed to terminate process ${pid}`);
 }
 function signalUnix(child, signal) {
     try {

package/dist/run-store.d.ts

@@ -1,5 +1,8 @@
-import type { AgentdProtocol, AgentdRunDetail, AgentdRunView, AgentdSessionState } from './types.js';
-interface StoredRun extends AgentdRunDetail {
+import { ArtifactStore, type ArtifactReadResult, type ArtifactStoreMetrics, type ArtifactStoreOptions, type StoredArtifactView } from './artifact-store.js';
+import type { AgentdArtifact, AgentdProtocol, AgentdRunDetail, AgentdRunView, AgentdSessionState } from './types.js';
+export { ArtifactStore, artifactStorePathForRunStore } from './artifact-store.js';
+export type { ArtifactReadResult, ArtifactStorageStatus, ArtifactStoreMetrics, ArtifactStoreIo, ArtifactStoreOptions, StoredArtifactView } from './artifact-store.js';
+interface StoredRun extends Omit<AgentdRunDetail, 'taskPreview'> {
     ownerKeyId: string;
 }
 export interface CreateRunInput {
@@ -12,6 +15,17 @@ export interface CreateRunInput {
     ownerKeyId: string;
     task: string;
     inputAttachmentCount?: number;
+    retryOfRunId?: string;
+}
+export interface RunStoreOptions extends ArtifactStoreOptions {
+    /** History count cap; the positional maxRuns argument takes precedence. */
+    maxRuns?: number;
+    /** Task text cap; the positional maxTaskChars argument takes precedence. */
+    maxTaskChars?: number;
+    /** Terminal run metadata retention duration. Active runs are protected. */
+    historyRetentionDays?: number;
+    /** JSON run-history byte budget, independent from artifact payload bytes. */
+    historyMaxBytes?: number;
 }
 export interface RunListQuery {
     agentId?: string;
@@ -19,20 +33,89 @@ export interface RunListQuery {
     state?: AgentdSessionState;
     query?: string;
     limit?: number;
+    offset?: number;
+}
+export interface RunArtifactQuery {
+    agentId?: string;
+    /** 'all' keeps every kind; otherwise one of artifactKind() values. */
+    kind?: string;
+    query?: string;
+    limit?: number;
+    offset?: number;
+}
+export interface RunArtifactRow {
+    id: string;
+    runId: string;
+    agentId: string;
+    agentName: string;
+    runState: AgentdSessionState;
+    runStartedAt: number;
+    name?: string;
+    filename?: string;
+    mediaType?: string;
+    size?: number;
+    kind: string;
+    downloadable: boolean;
+    storageStatus?: string;
+    createdAt?: number;
 }
+/** Coarse bucket used by the console filter and list grouping. */
+export declare function artifactKind(mediaType: string | undefined): "image" | "audio" | "video" | "file";
 export declare class RunStore {
     readonly filePath: string;
-    private readonly maxRuns;
-    private readonly maxTaskChars;
     private readonly runs;
     private initialized;
     private dirty;
     private persistTimer?;
     private writeQueue;
-    constructor(filePath: string, maxRuns?: number, maxTaskChars?: number);
+    readonly artifactStore: ArtifactStore;
+    private readonly maxRuns;
+    private readonly maxTaskChars;
+    private readonly historyRetentionDays?;
+    private readonly historyMaxBytes?;
+    private readonly now;
+    private lastWriteMs;
+    private writeFailures;
+    private historyBytes;
+    constructor(filePath: string, maxRuns?: number, maxTaskChars?: number | RunStoreOptions, options?: RunStoreOptions);
+    constructor(filePath: string, options?: RunStoreOptions);
     init(): Promise<void>;
     create(input: CreateRunInput): AgentdRunDetail;
-    update(id: string, patch: Partial<Pick<StoredRun, 'protocolSessionId' | 'state' | 'progress' | 'output' | 'error' | 'artifacts' | 'artifactCount' | 'updatedAt' | 'endedAt' | 'durationMs' | 'inputAttachmentCount' | 'completion'>>): AgentdRunDetail | undefined;
+    update(id: string, patch: Partial<Pick<StoredRun, 'protocolSessionId' | 'state' | 'progress' | 'output' | 'error' | 'artifacts' | 'artifactCount' | 'updatedAt' | 'endedAt' | 'durationMs' | 'inputAttachmentCount' | 'completion' | 'retryOfRunId'>>): AgentdRunDetail | undefined;
+    /** Queue payload snapshots without blocking the protocol sink. */
+    recordArtifacts(runId: string, artifacts: AgentdArtifact[]): StoredArtifactView[] | undefined;
+    artifactViews(runId: string): StoredArtifactView[] | undefined;
+    readArtifact(runId: string, artifactId: string): Promise<ArtifactReadResult | undefined>;
+    /** Flat, newest-first artifact index across all retained runs. */
+    listArtifacts(query?: RunArtifactQuery): {
+        artifacts: RunArtifactRow[];
+        total: number;
+    };
+    /** Delete one artifact's payload and record entry; the run record stays. */
+    removeArtifact(runId: string, artifactId: string): Promise<boolean>;
+    getOwnerKeyId(runId: string): string | undefined;
+    metrics(): {
+        historyBytes: number;
+        retainedRuns: number;
+        pendingWrites: number;
+        lastWriteMs: number;
+        writeFailures: number;
+        artifactStoreStats: ArtifactStoreMetrics;
+    };
+    stats(): {
+        historyBytes: number;
+        retainedRuns: number;
+        pendingWrites: number;
+        lastWriteMs: number;
+        writeFailures: number;
+        artifactStoreStats: ArtifactStoreMetrics;
+    };
+    setRetryOfRunId(runId: string, retryOfRunId?: string): AgentdRunDetail | undefined;
+    /**
+     * Remove a terminal run record and its stored artifacts. Active runs are
+     * refused so a live turn cannot lose its progress tracking.
+     */
+    deleteRun(id: string): AgentdRunDetail | undefined;
     get(id: string): AgentdRunDetail | undefined;
     list(query?: RunListQuery): {
         runs: AgentdRunView[];
@@ -49,6 +132,6 @@ export declare class RunStore {
     private prune;
     private persist;
     private assertInitialized;
+    private applyArtifactViews;
 }
 export declare function runStorePathForConfig(configPath: string): string;
-export {};