nexus-agentd 0.3.0 → 0.3.1

package/LICENSE

@@ -1,22 +1,22 @@
-MIT License
-
-Copyright (c) 2026 lumia1998
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
-
+MIT License
+
+Copyright (c) 2026 lumia1998
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/dist/artifact-store.d.ts

@@ -126,6 +126,12 @@ export declare class ArtifactStore {
     readArtifact(runId: string, artifactId: string): Promise<ArtifactReadResult | undefined>;
     /** Queue removal of one run's own directory. Active runs are protected. */
     removeRun(runId: string): void;
+    /**
+     * Delete a single artifact: drop its payload file and record entry. The
+     * run record itself stays; its artifacts list shrinks via the views
+     * callback. Refused while the payload write is still in flight.
+     */
+    removeArtifact(runId: string, artifactId: string): Promise<boolean>;
     flush(): Promise<void>;
     get queuedByteCount(): number;
     get storedByteCount(): number;

package/dist/artifact-store.js

@@ -359,6 +359,36 @@ export class ArtifactStore {
         this.pendingDeletes.add(runId);
         this.scheduleDrain();
     }
+    /**
+     * Delete a single artifact: drop its payload file and record entry. The
+     * run record itself stays; its artifacts list shrinks via the views
+     * callback. Refused while the payload write is still in flight.
+     */
+    async removeArtifact(runId, artifactId) {
+        this.assertInitialized();
+        const key = entryKey(runId, artifactId);
+        const entry = this.entries.get(key);
+        if (!entry)
+            return false;
+        if (this.inFlight.has(key))
+            return false;
+        const batch = this.pending.get(runId);
+        const queued = batch?.get(artifactId);
+        if (queued) {
+            this.queuedBytes -= queued.bytes.length;
+            batch.delete(artifactId);
+            if (!batch.size)
+                this.pending.delete(runId);
+        }
+        if (entry.filePath) {
+            await this.safeUnlink(entry.filePath);
+            this.totalBytes -= entry.bytes || 0;
+        }
+        this.entries.delete(key);
+        await this.writeManifest(runId);
+        this.emit(runId, this.viewsForRun(runId));
+        return true;
+    }
     async flush() {
         this.assertInitialized();
         if (this.activeDrain)

package/dist/run-store.d.ts

@@ -35,6 +35,32 @@ export interface RunListQuery {
     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 runs;
@@ -60,6 +86,13 @@ export declare class RunStore {
     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;
@@ -78,6 +111,11 @@ export declare class RunStore {
         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[];

package/dist/run-store.js

@@ -3,6 +3,17 @@ import { chmod, mkdir, readFile, rename, unlink, writeFile } from 'node:fs/promi
 import path from 'node:path';
 import { ArtifactStore, artifactStorePathForRunStore } from './artifact-store.js';
 export { ArtifactStore, artifactStorePathForRunStore } from './artifact-store.js';
+/** Coarse bucket used by the console filter and list grouping. */
+export function artifactKind(mediaType) {
+    const type = String(mediaType || '').toLowerCase();
+    if (type.startsWith('image/'))
+        return 'image';
+    if (type.startsWith('video/'))
+        return 'video';
+    if (type.startsWith('audio/'))
+        return 'audio';
+    return 'file';
+}
 const STATES = new Set([
     'created',
     'running',
@@ -187,6 +198,55 @@ export class RunStore {
             return undefined;
         return this.artifactStore.readArtifact(runId, artifactId);
     }
+    /** Flat, newest-first artifact index across all retained runs. */
+    listArtifacts(query = {}) {
+        this.assertInitialized();
+        const needle = String(query.query || '').trim().toLowerCase();
+        const limit = Math.min(200, Math.max(1, Number(query.limit) || 50));
+        const offset = Math.max(0, Math.floor(Number(query.offset) || 0));
+        const rows = [];
+        for (const run of this.runs.values()) {
+            for (const view of run.artifacts || []) {
+                if (!view.id)
+                    continue;
+                if (query.agentId && run.agentId !== query.agentId)
+                    continue;
+                const kind = artifactKind(view.mediaType);
+                if (query.kind && query.kind !== 'all' && kind !== query.kind)
+                    continue;
+                if (needle) {
+                    const haystack = `${view.name || ''} ${view.filename || ''}`.toLowerCase();
+                    if (!haystack.includes(needle))
+                        continue;
+                }
+                rows.push({
+                    id: view.id,
+                    runId: run.id,
+                    agentId: run.agentId,
+                    agentName: run.agentName,
+                    runState: run.state,
+                    runStartedAt: run.startedAt,
+                    name: view.name,
+                    filename: view.filename,
+                    mediaType: view.mediaType,
+                    size: view.size,
+                    kind,
+                    downloadable: view.downloadable === true,
+                    storageStatus: view.storageStatus,
+                    createdAt: view.createdAt
+                });
+            }
+        }
+        rows.sort((left, right) => (right.createdAt || 0) - (left.createdAt || 0));
+        return { artifacts: rows.slice(offset, offset + limit), total: rows.length };
+    }
+    /** Delete one artifact's payload and record entry; the run record stays. */
+    async removeArtifact(runId, artifactId) {
+        this.assertInitialized();
+        if (!this.runs.has(runId))
+            return false;
+        return this.artifactStore.removeArtifact(runId, artifactId);
+    }
     getOwnerKeyId(runId) {
         this.assertInitialized();
         return this.runs.get(runId)?.ownerKeyId;
@@ -211,6 +271,22 @@ export class RunStore {
     setRetryOfRunId(runId, retryOfRunId) {
         return this.update(runId, { retryOfRunId });
     }
+    /**
+     * Remove a terminal run record and its stored artifacts. Active runs are
+     * refused so a live turn cannot lose its progress tracking.
+     */
+    deleteRun(id) {
+        this.assertInitialized();
+        const run = this.runs.get(id);
+        if (!run)
+            return undefined;
+        if (isActive(run.state))
+            return undefined;
+        this.runs.delete(id);
+        this.artifactStore.removeRun(id);
+        this.changed();
+        return publicDetail(run);
+    }
     get(id) {
         this.assertInitialized();
         const run = this.runs.get(id);

package/dist/server.js

@@ -505,15 +505,68 @@ async function handleAdminRoute(context, url) {
         await handleAdminRunAction(context, decodeURIComponent(runActionMatch[1]), runActionMatch[2]);
         return;
     }
+    if (url.pathname === '/v1/admin/artifacts' && request.method === 'GET') {
+        writeJson(response, 200, sessions.listArtifacts({
+            agentId: cleanQuery(url.searchParams.get('agentId')),
+            kind: cleanQuery(url.searchParams.get('kind')),
+            query: cleanQuery(url.searchParams.get('q')),
+            offset: boundedOffset(url.searchParams.get('offset')),
+            limit: boundedLimit(url.searchParams.get('limit'))
+        }));
+        return;
+    }
     const adminArtifactMatch = url.pathname.match(/^\/v1\/admin\/runs\/([^/]+)\/artifacts\/([^/]+)$/);
     if (adminArtifactMatch && request.method === 'GET') {
         const run = sessions.getRun(decodeURIComponent(adminArtifactMatch[1]));
         await writeRunArtifact(response, sessions, run, decodeURIComponent(adminArtifactMatch[2]));
         return;
     }
+    if (adminArtifactMatch && request.method === 'DELETE') {
+        await assertEmptyJsonBody(request, config.maxRequestBytes);
+        const runId = decodeURIComponent(adminArtifactMatch[1]);
+        const artifactId = decodeURIComponent(adminArtifactMatch[2]);
+        const run = sessions.getRun(runId);
+        if (!isTerminalState(run.state)) {
+            throw new RequestError(409, 'Artifacts of active runs cannot be deleted; cancel the task first');
+        }
+        const deleted = await sessions.removeRunArtifact(runId, artifactId);
+        if (!deleted)
+            throw new RequestError(404, 'Agent Nexus artifact not found');
+        console.info(JSON.stringify({
+            level: 'info',
+            event: 'admin_artifact_deleted',
+            runId,
+            artifactId,
+            agentId: run.agentId,
+            requestId: String(response.getHeader('X-Request-Id') || '')
+        }));
+        writeJson(response, 200, { deleted: true, runId, artifactId });
+        return;
+    }
     const runMatch = url.pathname.match(/^\/v1\/admin\/runs\/([^/]+)$/);
-    if (runMatch && request.method === 'GET') {
+    if (runMatch && (request.method === 'GET' || request.method === 'DELETE')) {
         const runId = decodeURIComponent(runMatch[1]);
+        if (request.method === 'DELETE') {
+            await assertEmptyJsonBody(request, config.maxRequestBytes);
+            const detail = sessions.getRun(runId);
+            if (!isTerminalState(detail.state)) {
+                throw new RequestError(409, 'Active runs cannot be deleted; cancel the task first');
+            }
+            const deleted = sessions.deleteRun(runId);
+            if (!deleted)
+                throw new RequestError(404, 'Agent Nexus run not found');
+            console.info(JSON.stringify({
+                level: 'info',
+                event: 'admin_run_record_deleted',
+                runId,
+                sessionId: detail.sessionId,
+                agentId: detail.agentId,
+                state: detail.state,
+                requestId: String(response.getHeader('X-Request-Id') || '')
+            }));
+            writeJson(response, 200, { deleted: true, id: runId });
+            return;
+        }
         const detail = sessions.getRun(runId);
         writeJson(response, 200, {
             ...detail,
@@ -778,6 +831,7 @@ function buildRunControls(sessions, detail) {
     return {
         canCancel,
         canRetry,
+        canDelete: !active,
         ...(pendingRequest ? { pendingRequest: structuredClone(pendingRequest) } : {}),
         ...(unavailableReason ? { unavailableReason } : {})
     };

package/dist/session/admin-runs.js

@@ -73,6 +73,7 @@ export class AdminRunManager {
         return {
             canCancel: current && active && Boolean(session?.runtimeAvailable()),
             canRetry,
+            canDelete: isTerminal(run.state),
             ...(pendingRequest ? { pendingRequest } : {}),
             ...(unavailableReason ? { unavailableReason } : {})
         };

package/dist/session.d.ts

@@ -1,6 +1,6 @@
 import type { AgentDriver } from './drivers/index.js';
 import { SessionEventLog } from './events.js';
-import { RunStore, type RunListQuery } from './run-store.js';
+import { RunStore, type RunListQuery, type RunArtifactQuery } from './run-store.js';
 import { type AdminRetryReservationFactory, type AdminRunOperationResult, type AdminRunControls } from './session/admin-runs.js';
 import type { AcpSessionSink, AgentSessionRuntime, AgentSessionSink } from './session-contract.js';
 import type { AgentdAgentView, AgentdArtifact, AgentdConfig, AgentdEvent, AgentdEventType, AgentdInputAttachmentView, AgentdPendingRequest, AgentdPendingResponse, AgentdProtocol, AgentdSessionState, AgentdSessionView, AgentdTurnCompletionProof } from './types.js';
@@ -114,8 +114,14 @@ export declare class SessionManager {
     };
     getRun(id: string): import("./types.js").AgentdRunDetail;
     getRunOwnerKeyId(id: string): string | undefined;
+    deleteRun(id: string): import("./types.js").AgentdRunDetail | undefined;
     ownsRun(id: string, keyId: string): boolean;
     getRunArtifacts(id: string): import("./types.js").AgentdRunArtifactView[];
+    listArtifacts(query?: RunArtifactQuery): {
+        artifacts: import("./run-store.js").RunArtifactRow[];
+        total: number;
+    };
+    removeRunArtifact(runId: string, artifactId: string): Promise<boolean | undefined>;
     getStorageMetrics(): ReturnType<RunStore['metrics']> | undefined;
     readRunArtifact(runId: string, artifactId: string): Promise<import("./artifact-store.js").ArtifactReadResult | undefined>;
     getRunArtifact(runId: string, artifactId: string): Promise<import("./artifact-store.js").ArtifactReadResult | undefined>;

package/dist/session.js

@@ -654,12 +654,24 @@ export class SessionManager {
         const store = this.runStore;
         return store?.getOwnerKeyId?.(id);
     }
+    deleteRun(id) {
+        const store = this.runStore;
+        return store?.deleteRun?.(id);
+    }
     ownsRun(id, keyId) {
         return this.getRunOwnerKeyId(id) === keyId;
     }
     getRunArtifacts(id) {
         return this.getRun(id).artifacts;
     }
+    listArtifacts(query = {}) {
+        const store = this.runStore;
+        return store?.listArtifacts?.(query) || { artifacts: [], total: 0 };
+    }
+    async removeRunArtifact(runId, artifactId) {
+        const store = this.runStore;
+        return store?.removeArtifact?.(runId, artifactId);
+    }
     getStorageMetrics() {
         return this.runStore?.metrics();
     }

package/dist/types.d.ts

@@ -268,6 +268,7 @@ export interface AgentdRunArtifactView {
     size?: number;
     downloadable?: boolean;
     storageStatus?: 'pending' | 'available' | 'metadata_only' | 'expired' | 'evicted' | 'failed';
+    createdAt?: number;
 }
 export interface AgentdRunView {
     id: string;
@@ -301,6 +302,7 @@ export interface AgentdRunDetail extends AgentdRunView {
 export interface AgentdRunControls {
     canCancel: boolean;
     canRetry: boolean;
+    canDelete?: boolean;
     pendingRequest?: AgentdPendingRequest;
     unavailableReason?: string;
 }