nexus-agentd 0.1.8 → 0.2.0

package/dist/session.js

@@ -1,5 +1,7 @@
 import { randomUUID } from 'node:crypto';
-import { AcpProcessRuntime, InvalidPermissionAnswerError } from './acp/runtime.js';
+import { open, realpath } from 'node:fs/promises';
+import { basename, extname, isAbsolute, relative, resolve, sep } from 'node:path';
+import { AcpProcessRuntime } from './acp/runtime.js';
 import { A2AClientRuntime, probeA2AAgent } from './a2a/runtime.js';
 import { SessionEventLog } from './events.js';
 const MAX_SESSION_ARTIFACTS = 64;
@@ -9,6 +11,7 @@ const READINESS_CACHE_MS = 20_000;
 const MAX_INPUT_ATTACHMENTS = 16;
 const MAX_INPUT_ATTACHMENT_BYTES = 16 * 1024 * 1024;
 const MAX_SESSION_INPUT_BYTES = 32 * 1024 * 1024;
+const MAX_PUBLISHED_FILE_BYTES = 12 * 1024 * 1024;
 export class ManagedSession {
     agentId;
     protocol;
@@ -17,6 +20,7 @@ export class ManagedSession {
     maxOutputChars;
     agentName;
     runStore;
+    instanceId;
     id = randomUUID();
     createdAt = Date.now();
     events;
@@ -27,10 +31,11 @@ export class ManagedSession {
     output = '';
     error;
     pendingRequest;
+    completion;
     artifacts = [];
     inputAttachments = new Map();
     runtime;
-    constructor(agentId, protocol, workspace, ownerKeyId, maxEvents, maxOutputChars, agentName, runStore) {
+    constructor(agentId, protocol, workspace, ownerKeyId, maxEvents, maxOutputChars, agentName, runStore, instanceId = randomUUID()) {
         this.agentId = agentId;
         this.protocol = protocol;
         this.workspace = workspace;
@@ -38,6 +43,7 @@ export class ManagedSession {
         this.maxOutputChars = maxOutputChars;
         this.agentName = agentName;
         this.runStore = runStore;
+        this.instanceId = instanceId;
         this.events = new SessionEventLog(this.id, maxEvents);
         this.events.append('session_state', { state: this.state, protocol });
     }
@@ -56,6 +62,8 @@ export class ManagedSession {
     setState(state, error) {
         if (this.state === state && this.error === error)
             return;
+        if (state !== 'completed')
+            this.completion = undefined;
         this.state = state;
         this.error = error;
         this.updatedAt = Date.now();
@@ -66,15 +74,52 @@ export class ManagedSession {
                 : state === 'canceled'
                     ? 'canceled'
                     : 'session_state';
-        this.events.append(type, { state, ...(error ? { error } : {}) });
+        this.events.append(type, {
+            state,
+            ...(error ? { error } : {}),
+            ...(state === 'completed' && this.completion
+                ? { completion: structuredClone(this.completion) }
+                : {})
+        });
         const endedAt = isTerminal(state) ? this.updatedAt : undefined;
         this.syncRun({
             state,
             error,
             progress: progressForState(state, error),
+            completion: state === 'completed' && this.completion
+                ? structuredClone(this.completion)
+                : undefined,
             ...(endedAt ? { endedAt } : {})
         });
     }
+    completeTurn(proof) {
+        if (this.pendingRequest || isInteractive(this.state)) {
+            this.emit('terminal_output', {
+                stream: 'system',
+                text: `Ignored ${proof.source} completion while the session is waiting for ${this.pendingRequest?.kind || 'input'}.`
+            });
+            return false;
+        }
+        if (this.state !== 'running')
+            return false;
+        const outputPresent = this.output.trim().length > 0;
+        const artifactCount = this.artifacts.length;
+        if (!outputPresent && artifactCount < 1) {
+            this.setState('failed', `Agent ended the turn (${proof.stopReason}) without a final response or artifact.`);
+            return false;
+        }
+        this.completion = {
+            ...structuredClone(proof),
+            runId: this.currentRunId,
+            protocol: this.protocol,
+            verified: true,
+            outputPresent,
+            artifactCount,
+            completedAt: Date.now()
+        };
+        this.setState('completed');
+        return true;
+    }
     appendOutput(text) {
         if (!text)
             return;
@@ -116,7 +161,72 @@ export class ManagedSession {
             artifactCount: this.artifacts.length
         });
     }
+    async publishFile(filePath) {
+        const requestedPath = String(filePath || '').trim();
+        if (!requestedPath) {
+            throw new SessionRequestError(400, 'path is required');
+        }
+        if (!this.workspace) {
+            throw new SessionRequestError(400, 'This session does not have a local workspace');
+        }
+        let handle;
+        try {
+            const workspaceRoot = await realpath(this.workspace);
+            const unresolved = resolve(workspaceRoot, requestedPath);
+            const target = await realpath(unresolved);
+            assertWorkspacePath(workspaceRoot, target);
+            handle = await open(target, 'r');
+            // Resolve again after opening so a swapped symlink cannot silently
+            // redirect a publish request outside the configured workspace.
+            const verifiedTarget = await realpath(unresolved);
+            assertWorkspacePath(workspaceRoot, verifiedTarget);
+            if (verifiedTarget !== target) {
+                throw new SessionRequestError(409, 'Published file changed while it was being opened');
+            }
+            const stats = await handle.stat();
+            if (!stats.isFile()) {
+                throw new SessionRequestError(400, 'Only regular files can be published');
+            }
+            if (stats.size > MAX_PUBLISHED_FILE_BYTES) {
+                throw new SessionRequestError(413, `Published file exceeds the ${MAX_PUBLISHED_FILE_BYTES} byte limit`);
+            }
+            const bytes = await handle.readFile();
+            const filename = basename(verifiedTarget);
+            const workspacePath = relative(workspaceRoot, verifiedTarget).split(sep).join('/');
+            const artifact = {
+                id: `published:${randomUUID()}`,
+                name: filename,
+                filename,
+                mediaType: mediaTypeForPath(filename),
+                bytesBase64: bytes.toString('base64'),
+                metadata: {
+                    source: 'workspace_publish',
+                    path: workspacePath,
+                    size: bytes.length
+                }
+            };
+            this.addArtifact(artifact);
+            this.emit('artifact', runArtifact(artifact));
+            return artifact;
+        }
+        catch (error) {
+            if (error instanceof SessionRequestError)
+                throw error;
+            const code = error?.code;
+            if (code === 'ENOENT') {
+                throw new SessionRequestError(404, 'Published file was not found');
+            }
+            if (code === 'EACCES' || code === 'EPERM') {
+                throw new SessionRequestError(403, 'Published file cannot be read');
+            }
+            throw error;
+        }
+        finally {
+            await handle?.close();
+        }
+    }
     setPending(request) {
+        this.completion = undefined;
         this.pendingRequest = structuredClone(request);
         this.state = request.kind === 'permission' ? 'permission_required' : 'input_required';
         this.updatedAt = Date.now();
@@ -167,18 +277,10 @@ export class ManagedSession {
             throw new SessionRequestError(409, 'Agent runtime is unavailable');
         const attachments = this.inputAttachmentsFor(attachmentIds);
         if (this.pendingRequest) {
-            this.syncRun({
-                progress: { phase: '继续执行', message: '已提交补充信息' }
-            });
-            try {
-                await this.runtime.respondPending(message, attachments);
-            }
-            catch (error) {
-                if (error instanceof InvalidPermissionAnswerError) {
-                    throw new SessionRequestError(400, error.message);
-                }
-                throw error;
-            }
+            await this.resolvePending({
+                requestId: this.pendingRequest.id,
+                message
+            }, attachmentIds);
             return;
         }
         if (this.state === 'running') {
@@ -186,6 +288,7 @@ export class ManagedSession {
         }
         this.output = '';
         this.artifacts = [];
+        this.completion = undefined;
         this.error = undefined;
         this.updatedAt = Date.now();
         this.currentRunId = this.runStore?.create({
@@ -204,6 +307,23 @@ export class ManagedSession {
                 this.setState('failed', errorMessage(error));
         });
     }
+    async resolvePending(response, attachmentIds = []) {
+        if (!this.runtime) {
+            throw new SessionRequestError(409, 'Agent runtime is unavailable');
+        }
+        const pending = this.pendingRequest;
+        if (!pending) {
+            throw new SessionRequestError(409, 'Session is not waiting for input');
+        }
+        if (pending.id !== response.requestId) {
+            throw new SessionRequestError(409, `Pending request no longer matches: ${response.requestId}`);
+        }
+        const attachments = this.inputAttachmentsFor(attachmentIds);
+        this.syncRun({
+            progress: { phase: '继续执行', message: '已提交补充信息' }
+        });
+        await this.runtime.respondPending(response, attachments);
+    }
     async cancel() {
         await this.runtime?.cancel();
     }
@@ -214,6 +334,7 @@ export class ManagedSession {
     snapshot() {
         return {
             id: this.id,
+            instanceId: this.instanceId,
             runId: this.currentRunId,
             protocol: this.protocol,
             protocolSessionId: this.protocolSessionId,
@@ -228,6 +349,9 @@ export class ManagedSession {
             pendingRequest: this.pendingRequest
                 ? structuredClone(this.pendingRequest)
                 : undefined,
+            completion: this.completion
+                ? structuredClone(this.completion)
+                : undefined,
             lastEventId: this.events.lastId,
             createdAt: this.createdAt,
             updatedAt: this.updatedAt
@@ -247,6 +371,9 @@ export class ManagedSession {
             output: this.output || undefined,
             artifacts: this.artifacts.map(runArtifact),
             artifactCount: this.artifacts.length,
+            completion: this.completion
+                ? structuredClone(this.completion)
+                : undefined,
             updatedAt: this.updatedAt,
             ...patch
         });
@@ -265,6 +392,7 @@ export class SessionManager {
     workspacePolicy;
     drivers;
     runStore;
+    instanceId = randomUUID();
     sessions = new Map();
     cleanupTimer;
     readinessCache;
@@ -379,10 +507,10 @@ export class SessionManager {
             }
             workspace = await this.workspacePolicy.resolve(requestedWorkspace);
         }
-        const session = new ManagedSession(agentId, config.protocol === 'a2a' ? 'a2a' : 'acp', workspace, ownerKeyId, this.config.maxEventsPerSession, this.config.maxOutputChars, config.name || agentId, this.runStore);
+        const session = new ManagedSession(agentId, config.protocol === 'a2a' ? 'a2a' : 'acp', workspace, ownerKeyId, this.config.maxEventsPerSession, this.config.maxOutputChars, config.name || agentId, this.runStore, this.instanceId);
         const runtime = config.protocol === 'a2a'
             ? new A2AClientRuntime(config, session, this.config.promptTimeoutMs || 30 * 60_000)
-            : new AcpProcessRuntime(driver, session, this.config.maxOutputChars, this.config.promptTimeoutMs || 30 * 60_000, config.instructions);
+            : new AcpProcessRuntime(driver, session, this.config.maxOutputChars, this.config.promptTimeoutMs || 30 * 60_000);
         this.sessions.set(session.id, session);
         session.attach(runtime);
         try {
@@ -422,15 +550,34 @@ export class SessionManager {
         await session.message(text, attachmentIds);
         return session.snapshot();
     }
+    async resolvePending(id, response, attachmentIds = []) {
+        const session = this.require(id);
+        await session.resolvePending(response, attachmentIds);
+        return session.snapshot();
+    }
     addInputAttachment(id, name, mediaType, bytes) {
         const session = this.require(id);
         return session.addInputAttachment(name, mediaType, bytes);
     }
+    async publishFile(id, path) {
+        const session = this.require(id);
+        await session.publishFile(path);
+        return session.snapshot();
+    }
     async cancel(id) {
         const session = this.require(id);
         await session.cancel();
         return session.snapshot();
     }
+    async close(id) {
+        const session = this.require(id);
+        if (isActive(session.state))
+            await session.cancel();
+        const snapshot = session.snapshot();
+        await session.dispose();
+        this.sessions.delete(id);
+        return snapshot;
+    }
     eventsAfter(id, after) {
         return this.require(id).events.after(after);
     }
@@ -542,6 +689,41 @@ function runArtifact(artifact) {
         metadata: artifact.metadata ? structuredClone(artifact.metadata) : undefined
     };
 }
+function assertWorkspacePath(workspaceRoot, target) {
+    const child = relative(workspaceRoot, target);
+    if (child === '..' || child.startsWith(`..${sep}`) || isAbsolute(child)) {
+        throw new SessionRequestError(403, 'Published files must stay inside the session workspace');
+    }
+}
+function mediaTypeForPath(path) {
+    switch (extname(path).toLowerCase()) {
+        case '.txt':
+        case '.log':
+        case '.md':
+            return 'text/plain';
+        case '.json':
+            return 'application/json';
+        case '.pdf':
+            return 'application/pdf';
+        case '.png':
+            return 'image/png';
+        case '.jpg':
+        case '.jpeg':
+            return 'image/jpeg';
+        case '.gif':
+            return 'image/gif';
+        case '.webp':
+            return 'image/webp';
+        case '.svg':
+            return 'image/svg+xml';
+        case '.csv':
+            return 'text/csv';
+        case '.zip':
+            return 'application/zip';
+        default:
+            return 'application/octet-stream';
+    }
+}
 function firstString(...values) {
     for (const value of values) {
         if (typeof value === 'string' && value.trim())
@@ -594,6 +776,9 @@ function isTerminal(state) {
 function isActive(state) {
     return state === 'running' || state === 'input_required' || state === 'permission_required';
 }
+function isInteractive(state) {
+    return state === 'input_required' || state === 'permission_required';
+}
 function errorMessage(error) {
     return error instanceof Error ? error.message : String(error);
 }

package/dist/types.d.ts

@@ -1,6 +1,19 @@
 export type AgentdSessionState = 'created' | 'running' | 'input_required' | 'permission_required' | 'completed' | 'failed' | 'canceled';
 export type AgentdProtocol = 'acp' | 'a2a';
-export type PermissionPolicy = 'ask' | 'allow' | 'deny';
+export type PermissionPolicy = 'ask' | 'deny';
+export type AgentdTurnCompletionSource = 'acp_prompt_response' | 'a2a_task_status' | 'a2a_message_stream';
+export interface AgentdTurnCompletionProof {
+    source: AgentdTurnCompletionSource;
+    stopReason: string;
+}
+export interface AgentdTurnCompletion extends AgentdTurnCompletionProof {
+    runId?: string;
+    protocol: AgentdProtocol;
+    verified: true;
+    outputPresent: boolean;
+    artifactCount: number;
+    completedAt: number;
+}
 export declare const agentdDriverKinds: readonly ["opencode", "claude", "codex", "pi", "openclaw", "hermes"];
 export type AgentdDriverKind = (typeof agentdDriverKinds)[number];
 export interface AgentdDriverConfig {
@@ -14,8 +27,6 @@ export interface AgentdDriverConfig {
     args?: string[];
     inheritEnv?: string[];
     env?: Record<string, string>;
-    /** Optional extra instructions appended to the built-in Agent Nexus guidance. */
-    instructions?: string;
     permissionPolicy?: PermissionPolicy;
     permissionTimeoutMs?: number;
 }
@@ -25,8 +36,6 @@ export interface AgentdA2AConfig {
     protocol: 'a2a';
     name?: string;
     description?: string;
-    /** Optional extra instructions sent with the first A2A user message. */
-    instructions?: string;
     enabled?: boolean;
     /** Full Agent Card JSON URL. Preferred for new configurations. */
     agentCardUrl?: string;
@@ -67,18 +76,6 @@ export interface AgentdConfig {
     workspaceRoots: string[];
     maxRequestBytes: number;
     maxAttachmentBytes?: number;
-    /** Gateway-owned directory for temporary, anonymously downloadable artifacts. */
-    artifactStoragePath?: string;
-    /** Maximum size of one published artifact. */
-    maxArtifactBytes?: number;
-    /** Maximum combined size of all retained published artifacts. */
-    maxArtifactStorageBytes?: number;
-    /** Maximum number of retained published artifacts. */
-    maxPublishedArtifacts?: number;
-    /** Maximum number of simultaneous artifact copies. */
-    maxConcurrentArtifactPublishes?: number;
-    /** Lifetime of a published artifact URL. */
-    artifactTtlMs?: number;
     maxEventsPerSession: number;
     maxOutputChars: number;
     sessionTtlMs: number;
@@ -92,27 +89,6 @@ export interface AgentdConfig {
     secureAdminCookies?: boolean;
     agents: Record<string, AgentdAgentConfig>;
 }
-export interface AgentdFileRootView {
-    id: string;
-    name: string;
-    path: string;
-}
-export interface AgentdFileEntryView {
-    name: string;
-    path: string;
-    type: 'file' | 'directory' | 'symlink' | 'other';
-    size?: number;
-    modifiedAt: number;
-}
-export interface AgentdPublishedFile {
-    id: string;
-    name: string;
-    url: string;
-    size: number;
-    mediaType: string;
-    sha256: string;
-    expiresAt: number;
-}
 export interface AgentdAgentView {
     id: string;
     name: string;
@@ -132,7 +108,6 @@ export interface AgentdAgentConfigView {
     protocol: AgentdProtocol;
     name: string;
     description?: string;
-    instructions?: string;
     enabled: boolean;
     driver?: AgentdDriverKind;
     workspace?: string;
@@ -186,17 +161,17 @@ export interface AgentdPendingRequest {
     id: string;
     kind: 'permission' | 'input';
     prompt: string;
-    /** Optional business-facing step, for example `payment` or `pickup_time`. */
-    step?: string;
-    /** Optional hint for clients rendering the pending interaction. */
-    inputType?: 'text' | 'choice' | 'confirmation' | 'payment' | 'unknown';
     options?: Array<{
         id: string;
         name: string;
         kind?: string;
     }>;
-    /** JSON-safe metadata for the owning integration. Never put secrets here. */
-    metadata?: Record<string, unknown>;
+}
+export interface AgentdPendingResponse {
+    requestId: string;
+    message?: string;
+    optionId?: string;
+    action?: 'accept' | 'decline' | 'cancel';
 }
 export interface AgentdArtifact {
     id?: string;
@@ -212,6 +187,8 @@ export interface AgentdArtifact {
 }
 export interface AgentdSessionView {
     id: string;
+    /** Identifies the Gateway process that owns this in-memory session. */
+    instanceId?: string;
     runId?: string;
     protocol: AgentdProtocol;
     protocolSessionId?: string;
@@ -225,6 +202,8 @@ export interface AgentdSessionView {
     artifacts: AgentdArtifact[];
     inputAttachments?: AgentdInputAttachmentView[];
     pendingRequest?: AgentdPendingRequest;
+    /** Structural proof that the current protocol turn reached a valid terminal boundary. */
+    completion?: AgentdTurnCompletion;
     lastEventId?: string;
     createdAt: number;
     updatedAt: number;
@@ -259,6 +238,7 @@ export interface AgentdRunView {
     error?: string;
     artifactCount: number;
     inputAttachmentCount?: number;
+    completion?: AgentdTurnCompletion;
     startedAt: number;
     updatedAt: number;
     endedAt?: number;