nexus-agentd 0.2.2 → 0.2.5

package/README.md

@@ -62,22 +62,22 @@ Workspace 配置保持不变。
   默认值分别是 24 小时、30 分钟和 60 秒；A2A 请求超时在每个 Agent 的编辑页单独设置，默认 60 秒、
   最大 30 分钟。
 
-## 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
+## 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 | 默认入口 |
 |---|---|
@@ -97,12 +97,12 @@ npm install -g \
   pi-acp
 ```
 
-`command`、`args`、`inheritEnv` 和 `env` 是仅可在本机配置文件修改的高级字段，WebUI 不接受这些
-字段。Workspace 在启动进程前经过 `realpath` 边界校验。
-
-ACP 权限策略支持 `ask`（询问）、`allow`（始终允许）和 `deny`（拒绝）。`allow` 会优先选择
-Agent 提供的 `allow_once`，不创建待确认请求；它适合管理员明确授权、工作区边界可信的自动化 Agent。
-默认仍为 `ask`。
+`command`、`args`、`inheritEnv` 和 `env` 是仅可在本机配置文件修改的高级字段，WebUI 不接受这些
+字段。Workspace 在启动进程前经过 `realpath` 边界校验。
+
+ACP 权限策略支持 `ask`（询问）、`allow`（始终允许）和 `deny`（拒绝）。`allow` 会优先选择
+Agent 提供的 `allow_once`，不创建待确认请求；它适合管理员明确授权、工作区边界可信的自动化 Agent。
+默认仍为 `ask`。
 
 ### A2A
 
@@ -150,14 +150,15 @@ A2A 使用官方 `@a2a-js/sdk` 客户端，通过完整的 Agent Card URL 发现
 }
 ```
 
-输入附件通过 Session 临时保存，默认单个文件最多 16 MiB、单个 Session 最多 32 MiB、最多 16 个文件；
+输入附件通过 Session 临时保存，默认单个文件最多 16 MiB、单个 Session 最多 32 MiB、最多 16 个文件；
 HTTP 上传总上限由 `maxAttachmentBytes` 控制，默认 32 MiB，允许调整到 64 MiB。Session 释放时附件也会
 一起清理。ACP 会优先使用 Agent 声明支持的 image/audio/embeddedContext 能力，否则为 Agent 提供受限的
-`file://` resource link；A2A 则以带文件名和媒体类型的二进制 Part 发送。
-
-ACP Session 还支持显式发布工作区文件。发布接口只接受 realpath 仍位于该 Session 工作区中的普通文件，
-拒绝目录、路径穿越和符号链接逃逸，单个文件最多 12 MiB。响应将文件作为 Session Artifact 返回；不会
-暴露宿主机绝对路径。
+`file://` resource link；A2A 则以带文件名和媒体类型的二进制 Part 发送。
+
+ACP Session 还支持显式发布工作区文件。发布接口只接受 realpath 仍位于该 Session 工作区中的普通文件，
+拒绝目录、路径穿越和符号链接逃逸，单个文件最多 12 MiB。请求 body 支持单文件 `{ "path": "..." }` 或
+批量 `{ "paths": ["..."] }`（一次最多 32 条），响应在正常 Session 视图上附加
+`publishedArtifacts` 数组，本次发布的文件以 base64 内联返回；不会暴露宿主机绝对路径，也不生成外部 URL。
 
 API Key 与 A2A 认证值支持 `env:VAR`。Console Password 哈希由 WebUI 管理，不要手工生成或把
 旧 `authToken` 复制到该字段。
@@ -200,27 +201,27 @@ POST   /v1/admin/api-keys/:id/reveal
 POST   /v1/admin/api-keys/:id/regenerate
 ```
 
-Bearer API Key 数据面：
-
-```text
-GET  /v1/meta
-GET  /v1/agents
-POST /v1/sessions
-GET  /v1/sessions/:id
-DELETE /v1/sessions/:id
-POST /v1/sessions/:id/attachments
-POST /v1/sessions/:id/message
-POST /v1/sessions/:id/requests/:requestId/resolve
-POST /v1/sessions/:id/artifacts/publish
-POST /v1/sessions/:id/cancel
-GET  /v1/sessions/:id/events
-```
-
-`/v1/meta` 和 Session 响应包含 Gateway `instanceId`；完成的 Session 还包含与当前 Run 绑定的
-`completion` 证明，客户端可识别进程重启和迟到/伪造的完成状态。授权与输入通过精确的
-`requestId` 解析；过期 ID 返回 `409`，不会误答后续请求。`DELETE /v1/sessions/:id` 会取消活动任务、
-释放 Agent 整个进程组并移除内存 Session。Gateway 停止时会先终止 Session，再在有限宽限期后关闭残留
-HTTP/SSE 连接，避免长连接或 Agent 孙进程阻塞服务重启。
+Bearer API Key 数据面：
+
+```text
+GET  /v1/meta
+GET  /v1/agents
+POST /v1/sessions
+GET  /v1/sessions/:id
+DELETE /v1/sessions/:id
+POST /v1/sessions/:id/attachments
+POST /v1/sessions/:id/message
+POST /v1/sessions/:id/requests/:requestId/resolve
+POST /v1/sessions/:id/artifacts/publish
+POST /v1/sessions/:id/cancel
+GET  /v1/sessions/:id/events
+```
+
+`/v1/meta` 和 Session 响应包含 Gateway `instanceId`；完成的 Session 还包含与当前 Run 绑定的
+`completion` 证明，客户端可识别进程重启和迟到/伪造的完成状态。授权与输入通过精确的
+`requestId` 解析；过期 ID 返回 `409`，不会误答后续请求。`DELETE /v1/sessions/:id` 会取消活动任务、
+释放 Agent 整个进程组并移除内存 Session。Gateway 停止时会先终止 Session，再在有限宽限期后关闭残留
+HTTP/SSE 连接，避免长连接或 Agent 孙进程阻塞服务重启。
 
 API Key 的 Agent scope 在 Agent inventory、Session 创建和后续 Session 操作上都会检查；Session
 还绑定创建它的 Key，其他 Key 即使拥有同一 Agent scope 也不能读取或控制该 Session。

package/dist/a2a/runtime.js

@@ -280,13 +280,16 @@ export class A2AClientRuntime {
                 this.sink.clearPending();
                 this.sink.setState('canceled');
                 break;
-            case TaskState.TASK_STATE_INPUT_REQUIRED:
+            case TaskState.TASK_STATE_INPUT_REQUIRED: {
+                const classification = a2aInputClassification(statusText, status.message);
                 this.sink.setPending({
                     id: this.taskId || randomUUID(),
                     kind: 'input',
-                    prompt: statusText || 'The A2A agent requires additional input.'
+                    prompt: statusText || 'The A2A agent requires additional input.',
+                    ...classification
                 });
                 break;
+            }
             case TaskState.TASK_STATE_FAILED:
             case TaskState.TASK_STATE_REJECTED:
             case TaskState.TASK_STATE_AUTH_REQUIRED:
@@ -450,3 +453,37 @@ function disabledView(id, config) {
 function errorMessage(error) {
     return error instanceof Error ? error.message : String(error);
 }
+/**
+ * Detect payment / confirmation / choice hints in an A2A `input_required`
+ * message so the Gateway can surface them on `pendingRequest.metadata` and
+ * `inputType`. The A2A protocol has no first-class field for these so we
+ * scan text parts for URLs and simple keywords.
+ */
+function a2aInputClassification(statusText, message) {
+    const metadata = {};
+    const haystack = [
+        statusText,
+        ...(message?.parts ? textParts(message.parts) : [])
+    ]
+        .filter(Boolean)
+        .join('\n');
+    const urlMatch = haystack.match(/https?:\/\/\S+/);
+    if (urlMatch)
+        metadata.url = urlMatch[0];
+    let inputType = 'text';
+    if (/pay|支付|invoice|checkout|订单支付/i.test(haystack)) {
+        inputType = 'payment';
+        if (urlMatch)
+            metadata.paymentUrl = urlMatch[0];
+    }
+    else if (/[（(]\s*[yY]\s*\/\s*[nN]\s*[)）]|确认|是否/i.test(haystack)) {
+        inputType = 'confirmation';
+    }
+    else if (/(?:\n|^)\s*(?:\d+[.、]|[-*])\s+\S/.test(haystack)) {
+        inputType = 'choice';
+    }
+    return {
+        inputType,
+        ...(Object.keys(metadata).length ? { metadata } : {})
+    };
+}

package/dist/acp/runtime.d.ts

@@ -14,6 +14,8 @@ export declare class AcpProcessRuntime {
     private readonly promptTimeoutMs;
     private promptCapabilities;
     private inputDirectory?;
+    private workspace?;
+    private promptOutput;
     constructor(driver: AgentDriver, sink: AcpSessionSink, maxStderrChunkChars?: number, promptTimeoutMs?: number);
     start(workspace: string): Promise<void>;
     prompt(message: string, attachments?: AgentdInputAttachment[]): Promise<void>;
@@ -27,6 +29,7 @@ export declare class AcpProcessRuntime {
     private sessionUpdate;
     private captureToolArtifacts;
     private captureArtifact;
+    private captureMediaMarkers;
     private captureStderr;
     private onProcessFailure;
     private requireSessionId;

package/dist/acp/runtime.js

@@ -1,11 +1,12 @@
 import { randomUUID } from 'node:crypto';
-import { mkdir, rm, writeFile } from 'node:fs/promises';
+import { mkdir, readFile, realpath, rm, stat, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import { Readable, Writable } from 'node:stream';
-import { pathToFileURL } from 'node:url';
+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;
 export class AcpProcessRuntime {
     driver;
     sink;
@@ -19,6 +20,8 @@ export class AcpProcessRuntime {
     promptTimeoutMs;
     promptCapabilities = {};
     inputDirectory;
+    workspace;
+    promptOutput = '';
     constructor(driver, sink, maxStderrChunkChars = 16 * 1024, promptTimeoutMs = 30 * 60 * 1000) {
         this.driver = driver;
         this.sink = sink;
@@ -31,6 +34,7 @@ export class AcpProcessRuntime {
     async start(workspace) {
         if (this.process)
             throw new Error('ACP runtime is already started');
+        this.workspace = workspace;
         this.inputDirectory = path.join(workspace, '.nexus-inputs', this.sink.id);
         const child = this.driver.spawn(workspace);
         this.process = child;
@@ -86,6 +90,7 @@ export class AcpProcessRuntime {
             throw new Error('ACP session is already processing a prompt');
         const sessionId = this.requireSessionId();
         this.prompting = true;
+        this.promptOutput = '';
         this.sink.clearPending();
         this.sink.setState('running');
         try {
@@ -98,6 +103,7 @@ export class AcpProcessRuntime {
             }
             switch (response.stopReason) {
                 case 'end_turn':
+                    await this.captureMediaMarkers();
                     this.sink.completeTurn({
                         source: 'acp_prompt_response',
                         stopReason: response.stopReason
@@ -269,11 +275,16 @@ export class AcpProcessRuntime {
             kind: 'permission',
             prompt: params.toolCall.title ||
                 `Permission requested for tool ${params.toolCall.toolCallId}`,
+            inputType: 'confirmation',
+            step: params.toolCall.toolCallId
+                ? `tool:${params.toolCall.toolCallId}`
+                : undefined,
             options: params.options.map((option) => ({
                 id: option.optionId,
                 name: option.name,
                 kind: option.kind
-            }))
+            })),
+            metadata: permissionMetadata(params)
         };
         this.sink.setPending(request);
         return new Promise((resolve, reject) => {
@@ -308,7 +319,8 @@ export class AcpProcessRuntime {
             prompt: params.mode === 'url'
                 ? `${params.message}\n${params.url}`
                 : params.message,
-            options: elicitationOptions(params)
+            options: elicitationOptions(params),
+            ...elicitationClassification(params)
         };
         this.sink.setPending(request);
         return new Promise((resolve) => {
@@ -356,6 +368,7 @@ export class AcpProcessRuntime {
         switch (update.sessionUpdate) {
             case 'agent_message_chunk':
                 if (update.content.type === 'text') {
+                    this.promptOutput += update.content.text;
                     this.sink.appendOutput(update.content.text);
                     this.sink.emit('assistant_chunk', {
                         messageId: update.messageId,
@@ -410,7 +423,35 @@ export class AcpProcessRuntime {
         if (artifact)
             this.sink.addArtifact(artifact);
     }
+    async captureMediaMarkers() {
+        const markers = mediaMarkers(this.promptOutput);
+        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);
+            try {
+                const artifact = await artifactFromMediaMarker(marker, `media:${randomUUID()}`, this.workspace);
+                this.sink.addArtifact(artifact);
+                this.sink.emit('artifact', artifact);
+            }
+            catch (error) {
+                this.sink.emit('terminal_output', {
+                    stream: 'system',
+                    text: `Could not attach MEDIA artifact ${safeMarkerName(marker)}: ${error instanceof Error ? error.message : String(error)}`
+                });
+            }
+        }
+    }
     captureStderr(child) {
+        // Explicit UTF-8 streaming decoder: `String(chunk)` on a Buffer uses the
+        // default binary encoding, which mangles multi-byte characters if a
+        // chunk boundary splits a rune. `TextDecoder` with `stream: true`
+        // preserves the split byte between calls.
+        const decoder = new TextDecoder('utf-8');
         let buffer = '';
         let flushed = false;
         const emit = (text) => {
@@ -441,10 +482,16 @@ export class AcpProcessRuntime {
             if (flushed)
                 return;
             flushed = true;
+            buffer += decoder.decode();
             drain(true);
         };
         child.stderr.on('data', (chunk) => {
-            buffer += String(chunk);
+            const bytes = chunk instanceof Uint8Array
+                ? chunk
+                : Buffer.isBuffer(chunk)
+                    ? chunk
+                    : Buffer.from(String(chunk));
+            buffer += decoder.decode(bytes, { stream: true });
             drain();
         });
         child.stderr.once('end', flush);
@@ -619,6 +666,93 @@ function filenameFromValue(value) {
 function usableUrl(value) {
     return value && /^(?:https?|file):/i.test(value) ? value : undefined;
 }
+function mediaMarkers(output) {
+    return output
+        .split(/\r?\n/)
+        .map((line) => line.match(/^\s*MEDIA:\s*(.+?)\s*$/i)?.[1]?.trim())
+        .filter((value) => Boolean(value));
+}
+function withoutMediaMarkers(output) {
+    return output
+        .split(/\r?\n/)
+        .filter((line) => !/^\s*MEDIA:\s*(.+?)\s*$/i.test(line))
+        .join('\n')
+        .trim();
+}
+async function artifactFromMediaMarker(marker, id, workspace) {
+    if (/^https?:\/\//i.test(marker)) {
+        const filename = artifactFilename(marker, undefined, 'resource', undefined);
+        return {
+            id,
+            name: filename,
+            filename,
+            url: marker,
+            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);
+    return {
+        id,
+        name: filename,
+        filename,
+        mediaType: mediaTypeForPath(filename),
+        bytesBase64: (await readFile(resolved)).toString('base64'),
+        metadata: {
+            source: 'acp_media_marker',
+            size: details.size
+        }
+    };
+}
+function safeMarkerName(marker) {
+    try {
+        return path.basename(marker.startsWith('file:') ? fileURLToPath(marker) : marker);
+    }
+    catch {
+        return 'declared artifact';
+    }
+}
+function mediaTypeForPath(value) {
+    switch (path.extname(value).toLowerCase()) {
+        case '.pptx':
+            return 'application/vnd.openxmlformats-officedocument.presentationml.presentation';
+        case '.docx':
+            return 'application/vnd.openxmlformats-officedocument.wordprocessingml.document';
+        case '.xlsx':
+            return 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet';
+        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 '.mp3':
+            return 'audio/mpeg';
+        case '.wav':
+            return 'audio/wav';
+        case '.mp4':
+            return 'video/mp4';
+        default:
+            return 'application/octet-stream';
+    }
+}
 function artifactIndex(id) {
     return id.split(':').pop() || 'output';
 }
@@ -707,3 +841,88 @@ function isFormElicitation(params) {
             typeof params.requestedSchema ===
                 'object'));
 }
+/**
+ * Derive Agent Nexus semantic classification (inputType / step / metadata) from
+ * an ACP elicitation request. This is a best-effort projection: we look at the
+ * elicitation mode, the requested schema shape and well-known field names to
+ * decide whether the pending request is a plain text prompt, a choice, a
+ * yes/no confirmation, or a payment URL flow.
+ */
+function elicitationClassification(params) {
+    const metadata = {};
+    let inputType = 'unknown';
+    let step;
+    if (params.mode === 'url') {
+        const url = String(params.url || '').trim();
+        if (url) {
+            metadata.paymentUrl = url;
+            metadata.url = url;
+        }
+        inputType = /pay|支付|invoice|order/i.test(`${params.message || ''} ${url}`)
+            ? 'payment'
+            : 'text';
+        step = 'url';
+    }
+    else if (isFormElicitation(params)) {
+        const properties = params.requestedSchema.properties || {};
+        const entries = Object.entries(properties);
+        step = entries.length === 1 ? entries[0][0] : 'form';
+        if (entries.length === 1) {
+            const [, schema] = entries[0];
+            if (schema.type === 'boolean')
+                inputType = 'confirmation';
+            else if (Array.isArray(schema.oneOf) ||
+                Array.isArray(schema.enum)) {
+                inputType = 'choice';
+            }
+            else {
+                inputType = 'text';
+            }
+        }
+        else {
+            inputType = 'text';
+        }
+        const paymentUrl = firstStringFromSchema(properties, [
+            'paymentUrl',
+            'payUrl',
+            'payment_url',
+            'checkoutUrl'
+        ]);
+        if (paymentUrl) {
+            metadata.paymentUrl = paymentUrl;
+            inputType = 'payment';
+        }
+    }
+    else {
+        inputType = 'text';
+    }
+    return {
+        inputType,
+        ...(step ? { step } : {}),
+        ...(Object.keys(metadata).length ? { metadata } : {})
+    };
+}
+function permissionMetadata(params) {
+    const metadata = {};
+    const call = params.toolCall;
+    if (typeof call?.toolCallId === 'string' && call.toolCallId) {
+        metadata.toolCallId = call.toolCallId;
+    }
+    if (typeof call?.name === 'string' && call.name) {
+        metadata.tool = call.name;
+    }
+    return Object.keys(metadata).length ? metadata : undefined;
+}
+function firstStringFromSchema(properties, candidates) {
+    for (const key of candidates) {
+        const schema = properties[key];
+        if (!schema)
+            continue;
+        const value = (typeof schema.const === 'string' && schema.const) ||
+            (typeof schema.default === 'string' && schema.default) ||
+            '';
+        if (value)
+            return value;
+    }
+    return undefined;
+}

package/dist/auth.js

@@ -1,4 +1,4 @@
-import { randomBytes, scrypt as scryptCallback, timingSafeEqual } from 'node:crypto';
+import { createHash, randomBytes, scrypt as scryptCallback, timingSafeEqual } from 'node:crypto';
 import { promisify } from 'node:util';
 const scrypt = promisify(scryptCallback);
 const KEY_LENGTH = 64;
@@ -41,28 +41,46 @@ export function validateAdminPassword(input) {
 }
 export class AdminSessionStore {
     ttlMs;
+    // Stored keys are SHA-256 digests of the raw session id so a timing attack
+    // on Map lookup / string comparison cannot learn a valid prefix. The raw
+    // id never leaves the HttpOnly cookie.
     sessions = new Map();
     constructor(ttlMs) {
         this.ttlMs = ttlMs;
     }
     create() {
         this.cleanup();
-        const id = randomBytes(32).toString('base64url');
-        this.sessions.set(id, Date.now() + this.ttlMs);
-        return id;
+        const raw = randomBytes(32).toString('base64url');
+        this.sessions.set(digest(raw), Date.now() + this.ttlMs);
+        return raw;
     }
     has(id) {
-        const expiresAt = this.sessions.get(id);
-        if (!expiresAt)
+        if (typeof id !== 'string' || !id)
             return false;
+        const key = digest(id);
+        let match;
+        // Walk every stored digest in constant time. `timingSafeEqual` requires
+        // equal-length inputs, which is guaranteed because all digests have the
+        // same byte length.
+        for (const stored of this.sessions.keys()) {
+            const a = Buffer.from(stored, 'hex');
+            const b = Buffer.from(key, 'hex');
+            if (a.length === b.length && timingSafeEqual(a, b))
+                match = stored;
+        }
+        if (!match)
+            return false;
+        const expiresAt = this.sessions.get(match);
         if (expiresAt <= Date.now()) {
-            this.sessions.delete(id);
+            this.sessions.delete(match);
             return false;
         }
         return true;
     }
     delete(id) {
-        this.sessions.delete(id);
+        if (typeof id !== 'string' || !id)
+            return;
+        this.sessions.delete(digest(id));
     }
     clear() {
         this.sessions.clear();
@@ -75,3 +93,6 @@ export class AdminSessionStore {
         }
     }
 }
+function digest(value) {
+    return createHash('sha256').update(value, 'utf8').digest('hex');
+}

package/dist/completion-contract.js

@@ -4,6 +4,6 @@ export const TURN_COMPLETION_CONTRACT = [
     '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.',
+    'Attach generated resources or artifacts through the protocol when supported. If the runtime only reports a local deliverable path, put each requested file on its own final line as MEDIA:<path>; Agent Nexus will snapshot that explicitly declared file as an artifact before the turn completes.',
     '</agent_nexus_completion_contract>'
 ].join('\n');