nexus-agentd 0.1.9 → 0.2.0

package/README.md

@@ -62,9 +62,22 @@ Workspace 配置保持不变。
   默认值分别是 24 小时、30 分钟和 60 秒；A2A 请求超时在每个 Agent 的编辑页单独设置，默认 60 秒、
   最大 30 分钟。
 
-## Agent 协议
-
-### ACP
+## Agent 协议
+
+每个任务都会附带协议级完成约束：Agent 在结束 turn 前必须处理完工作，等待用户输入或授权时必须使用
+协议请求，并提供非空最终说明或 Artifact。Gateway 只接受以下完成证明：
+
+- ACP `session/prompt` 返回 `stopReason=end_turn`；`max_tokens`、`max_turn_requests`、拒绝和取消不会被
+  误报为成功。
+- A2A Task 明确进入 `COMPLETED`；如果远端直接返回 Message 而没有创建 Task，则以完整消息流结束作为
+  turn 边界。已经出现 Task 状态但没有终态的流会标记失败。
+- Session 仍有待处理的 permission/input 请求，或者最终文本与 Artifact 都为空时，不允许进入
+  `completed`。
+
+成功的 Session 响应包含 `completion`，其中记录当前 Run ID、协议、完成来源、stop reason、最终文本和
+产物存在性以及完成时间。这个证明验证的是协议边界和结果存在性，不替代业务内容本身的语义验收。
+
+### ACP
 
 | Driver | 默认入口 |
 |---|---|
@@ -199,7 +212,8 @@ POST /v1/sessions/:id/cancel
 GET  /v1/sessions/:id/events
 ```
 
-`/v1/meta` 和 Session 响应包含 Gateway `instanceId`，客户端可识别进程重启。授权与输入通过精确的
+`/v1/meta` 和 Session 响应包含 Gateway `instanceId`；完成的 Session 还包含与当前 Run 绑定的
+`completion` 证明，客户端可识别进程重启和迟到/伪造的完成状态。授权与输入通过精确的
 `requestId` 解析；过期 ID 返回 `409`，不会误答后续请求。`DELETE /v1/sessions/:id` 会取消活动任务、
 释放 Agent 进程并移除内存 Session。
 

package/dist/a2a/runtime.d.ts

@@ -14,6 +14,9 @@ export declare class A2AClientRuntime implements AgentSessionRuntime {
     private activeController?;
     private readonly artifactCache;
     private readonly emittedMessages;
+    private sawTaskStatus;
+    private sawAgentMessage;
+    private completionProof?;
     constructor(config: AgentdA2AConfig, sink: AgentSessionSink, promptTimeoutMs: number);
     start(): Promise<void>;
     prompt(message: string, attachments?: AgentdInputAttachment[]): Promise<void>;

package/dist/a2a/runtime.js

@@ -1,6 +1,7 @@
 import { randomUUID } from 'node:crypto';
 import { Role, TaskState } from '@a2a-js/sdk';
 import { ClientFactory, DefaultAgentCardResolver, JsonRpcTransportFactory, RestTransportFactory } from '@a2a-js/sdk/client';
+import { TURN_COMPLETION_CONTRACT } from '../completion-contract.js';
 export async function probeA2AAgent(id, config) {
     const startedAt = Date.now();
     if (config.enabled === false)
@@ -47,6 +48,9 @@ export class A2AClientRuntime {
     activeController;
     artifactCache = new Map();
     emittedMessages = new Set();
+    sawTaskStatus = false;
+    sawAgentMessage = false;
+    completionProof;
     constructor(config, sink, promptTimeoutMs) {
         this.config = config;
         this.sink = sink;
@@ -76,6 +80,9 @@ export class A2AClientRuntime {
         if (this.disposed)
             throw new Error('A2A runtime is disposed');
         this.prompting = true;
+        this.sawTaskStatus = false;
+        this.sawAgentMessage = false;
+        this.completionProof = undefined;
         this.sink.clearPending();
         this.sink.setState('running');
         const controller = new AbortController();
@@ -89,8 +96,22 @@ export class A2AClientRuntime {
             })) {
                 this.processResponse(response);
             }
-            if (this.sink.state === 'running')
-                this.sink.setState('completed');
+            if (this.sink.state === 'running') {
+                if (this.completionProof) {
+                    this.sink.completeTurn(this.completionProof);
+                }
+                else if (!this.sawTaskStatus && this.sawAgentMessage) {
+                    this.sink.completeTurn({
+                        source: 'a2a_message_stream',
+                        stopReason: 'message_stream_end'
+                    });
+                }
+                else {
+                    this.sink.setState('failed', this.sawTaskStatus
+                        ? 'A2A stream ended without a terminal task status.'
+                        : 'A2A stream ended without an agent result.');
+                }
+            }
         }
         catch (error) {
             if (this.sink.state !== 'canceled') {
@@ -156,6 +177,12 @@ export class A2AClientRuntime {
                         filename: '',
                         mediaType: 'text/plain'
                     },
+                    {
+                        content: { $case: 'text', value: TURN_COMPLETION_CONTRACT },
+                        metadata: undefined,
+                        filename: '',
+                        mediaType: 'text/plain'
+                    },
                     ...attachments.map((attachment) => ({
                         content: {
                             $case: 'raw',
@@ -210,6 +237,7 @@ export class A2AClientRuntime {
     processMessage(message) {
         if (!message || message.role !== Role.ROLE_AGENT)
             return;
+        this.sawAgentMessage = true;
         this.captureIds(message.taskId, message.contextId);
         if (message.messageId && this.emittedMessages.has(message.messageId))
             return;
@@ -222,10 +250,18 @@ export class A2AClientRuntime {
                 content: { type: 'text', text }
             });
         }
+        message.parts.forEach((part, index) => {
+            const artifact = artifactFromPart(part, `message:${message.messageId || 'agent'}:${index}`);
+            if (!artifact)
+                return;
+            this.sink.addArtifact(artifact);
+            this.sink.emit('artifact', artifact);
+        });
     }
     processStatus(status) {
         if (!status)
             return;
+        this.sawTaskStatus = true;
         this.processMessage(status.message);
         const statusText = textParts(status.message?.parts || []).join('\n').trim();
         switch (status.state) {
@@ -235,7 +271,10 @@ export class A2AClientRuntime {
                 break;
             case TaskState.TASK_STATE_COMPLETED:
                 this.sink.clearPending();
-                this.sink.setState('completed');
+                this.completionProof = {
+                    source: 'a2a_task_status',
+                    stopReason: 'completed'
+                };
                 break;
             case TaskState.TASK_STATE_CANCELED:
                 this.sink.clearPending();
@@ -349,6 +388,36 @@ function artifactFromA2A(artifact) {
         metadata: artifact.metadata || undefined
     };
 }
+function artifactFromPart(part, id) {
+    switch (part.content?.$case) {
+        case 'raw':
+            return {
+                id,
+                name: part.filename || id,
+                filename: part.filename || undefined,
+                mediaType: part.mediaType || undefined,
+                bytesBase64: Buffer.from(part.content.value).toString('base64')
+            };
+        case 'url':
+            return {
+                id,
+                name: part.filename || part.content.value || id,
+                filename: part.filename || undefined,
+                mediaType: part.mediaType || undefined,
+                url: part.content.value || undefined
+            };
+        case 'data':
+            return {
+                id,
+                name: part.filename || id,
+                filename: part.filename || undefined,
+                mediaType: part.mediaType || undefined,
+                data: part.content.value
+            };
+        default:
+            return undefined;
+    }
+}
 function textParts(parts) {
     return parts.flatMap((part) => part.content?.$case === 'text' && part.content.value ? [part.content.value] : []);
 }

package/dist/acp/runtime.js

@@ -4,6 +4,7 @@ import path from 'node:path';
 import { Readable, Writable } from 'node:stream';
 import { pathToFileURL } from 'node:url';
 import * as acp from '@agentclientprotocol/sdk';
+import { TURN_COMPLETION_CONTRACT } from '../completion-contract.js';
 export class AcpProcessRuntime {
     driver;
     sink;
@@ -60,7 +61,7 @@ export class AcpProcessRuntime {
             },
             clientInfo: {
                 name: 'nexus-agentd',
-                version: '0.1.4'
+                version: '0.2.0'
             }
         });
         if (initialize.protocolVersion !== acp.PROTOCOL_VERSION) {
@@ -94,14 +95,21 @@ export class AcpProcessRuntime {
             if (this.sink.state === 'canceled' || this.sink.state === 'failed') {
                 return;
             }
-            if (response.stopReason === 'cancelled') {
-                this.sink.setState('canceled');
-            }
-            else if (response.stopReason === 'refusal') {
-                this.sink.setState('failed', 'ACP agent refused the prompt');
-            }
-            else {
-                this.sink.setState('completed');
+            switch (response.stopReason) {
+                case 'end_turn':
+                    this.sink.completeTurn({
+                        source: 'acp_prompt_response',
+                        stopReason: response.stopReason
+                    });
+                    break;
+                case 'cancelled':
+                    this.sink.setState('canceled');
+                    break;
+                case 'refusal':
+                    this.sink.setState('failed', 'ACP agent refused the prompt');
+                    break;
+                default:
+                    this.sink.setState('failed', `ACP turn stopped before completion: ${response.stopReason}`);
             }
         }
         catch (error) {
@@ -440,7 +448,10 @@ export class AcpProcessRuntime {
         return value;
     }
     async promptBlocks(message, attachments) {
-        const blocks = [{ type: 'text', text: message }];
+        const blocks = [
+            { type: 'text', text: message },
+            { type: 'text', text: TURN_COMPLETION_CONTRACT }
+        ];
         for (const attachment of attachments) {
             const mediaType = attachment.mediaType || 'application/octet-stream';
             const data = attachment.bytes.toString('base64');

package/dist/completion-contract.d.ts

@@ -0,0 +1 @@
+export declare const TURN_COMPLETION_CONTRACT: string;

package/dist/completion-contract.js

@@ -0,0 +1,9 @@
+export const TURN_COMPLETION_CONTRACT = [
+    '<agent_nexus_completion_contract>',
+    'Do not end this turn while requested work is still running or incomplete.',
+    'If you need user input or permission, use the protocol input/permission request and wait for the response.',
+    'Before ending the turn, verify the requested work and provide a non-empty final response.',
+    'The final response must summarize the outcome, verification performed, and workspace-relative paths for generated files.',
+    'Attach generated resources or artifacts through the protocol when supported.',
+    '</agent_nexus_completion_contract>'
+].join('\n');

package/dist/run-store.d.ts

@@ -32,7 +32,7 @@ export declare class RunStore {
     constructor(filePath: string, maxRuns?: number, maxTaskChars?: number);
     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'>>): AgentdRunDetail | undefined;
+    update(id: string, patch: Partial<Pick<StoredRun, 'protocolSessionId' | 'state' | 'progress' | 'output' | 'error' | 'artifacts' | 'artifactCount' | 'updatedAt' | 'endedAt' | 'durationMs' | 'inputAttachmentCount' | 'completion'>>): AgentdRunDetail | undefined;
     get(id: string): AgentdRunDetail | undefined;
     list(query?: RunListQuery): {
         runs: AgentdRunView[];

package/dist/session-contract.d.ts

@@ -1,10 +1,11 @@
-import type { AgentdArtifact, AgentdEventType, AgentdInputAttachment, AgentdPendingRequest, AgentdPendingResponse, AgentdSessionState } from './types.js';
+import type { AgentdArtifact, AgentdEventType, AgentdInputAttachment, AgentdPendingRequest, AgentdPendingResponse, AgentdSessionState, AgentdTurnCompletionProof } from './types.js';
 export interface AgentSessionSink {
     readonly id: string;
     readonly state: AgentdSessionState;
     readonly protocolSessionId?: string;
     setProtocolSessionId(id: string): void;
     setState(state: AgentdSessionState, error?: string): void;
+    completeTurn(proof: AgentdTurnCompletionProof): boolean;
     appendOutput(text: string): void;
     addArtifact(artifact: AgentdArtifact): void;
     setPending(request: AgentdPendingRequest): void;

package/dist/session.d.ts

@@ -2,7 +2,7 @@ import type { AgentDriver } from './drivers/index.js';
 import { SessionEventLog } from './events.js';
 import { RunStore, type RunListQuery } from './run-store.js';
 import type { AcpSessionSink, AgentSessionRuntime, AgentSessionSink } from './session-contract.js';
-import type { AgentdAgentView, AgentdArtifact, AgentdConfig, AgentdEvent, AgentdEventType, AgentdInputAttachmentView, AgentdPendingRequest, AgentdPendingResponse, AgentdProtocol, AgentdSessionState, AgentdSessionView } from './types.js';
+import type { AgentdAgentView, AgentdArtifact, AgentdConfig, AgentdEvent, AgentdEventType, AgentdInputAttachmentView, AgentdPendingRequest, AgentdPendingResponse, AgentdProtocol, AgentdSessionState, AgentdSessionView, AgentdTurnCompletionProof } from './types.js';
 import type { WorkspacePolicy } from './workspace.js';
 export declare class ManagedSession implements AgentSessionSink, AcpSessionSink {
     readonly agentId: string;
@@ -23,6 +23,7 @@ export declare class ManagedSession implements AgentSessionSink, AcpSessionSink
     output: string;
     error?: string;
     pendingRequest?: AgentdPendingRequest;
+    private completion?;
     private artifacts;
     private inputAttachments;
     private runtime?;
@@ -31,6 +32,7 @@ export declare class ManagedSession implements AgentSessionSink, AcpSessionSink
     setProtocolSessionId(id: string): void;
     setAcpSessionId(id: string): void;
     setState(state: AgentdSessionState, error?: string): void;
+    completeTurn(proof: AgentdTurnCompletionProof): boolean;
     appendOutput(text: string): void;
     addArtifact(artifact: AgentdArtifact): void;
     publishFile(filePath: string): Promise<AgentdArtifact>;

package/dist/session.js

@@ -31,6 +31,7 @@ export class ManagedSession {
     output = '';
     error;
     pendingRequest;
+    completion;
     artifacts = [];
     inputAttachments = new Map();
     runtime;
@@ -61,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();
@@ -71,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;
@@ -186,6 +226,7 @@ export class ManagedSession {
         }
     }
     setPending(request) {
+        this.completion = undefined;
         this.pendingRequest = structuredClone(request);
         this.state = request.kind === 'permission' ? 'permission_required' : 'input_required';
         this.updatedAt = Date.now();
@@ -247,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({
@@ -307,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
@@ -326,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
         });
@@ -728,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' | '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 {
@@ -189,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;
@@ -223,6 +238,7 @@ export interface AgentdRunView {
     error?: string;
     artifactCount: number;
     inputAttachmentCount?: number;
+    completion?: AgentdTurnCompletion;
     startedAt: number;
     updatedAt: number;
     endedAt?: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nexus-agentd",
-  "version": "0.1.9",
+  "version": "0.2.0",
   "description": "Local Nexus Gateway daemon that exposes allowlisted Coding Agents through HTTP/SSE and ACP",
   "type": "module",
   "main": "dist/index.js",