nexus-agentd 0.2.3 → 0.2.6

package/dist/a2a/runtime.js

@@ -44,6 +44,8 @@ export class A2AClientRuntime {
     taskId = '';
     contextId = '';
     prompting = false;
+    promptFinished;
+    queuedResponse = false;
     disposed = false;
     activeController;
     artifactCache = new Map();
@@ -57,6 +59,8 @@ export class A2AClientRuntime {
         this.promptTimeoutMs = promptTimeoutMs;
     }
     async start() {
+        if (this.disposed)
+            throw new Error('A2A runtime is disposed');
         const resolver = createResolver(this.config);
         this.card = await resolveAgentCard(resolver, this.config);
         const fetchImpl = authenticatedFetch(this.config);
@@ -70,6 +74,8 @@ export class A2AClientRuntime {
             ]
         });
         this.client = await factory.createFromAgentCard(this.card);
+        if (this.disposed)
+            throw new Error('A2A runtime is disposed');
         this.sink.setState('created');
     }
     async prompt(message, attachments = []) {
@@ -80,6 +86,8 @@ export class A2AClientRuntime {
         if (this.disposed)
             throw new Error('A2A runtime is disposed');
         this.prompting = true;
+        let finish;
+        this.promptFinished = new Promise((resolve) => { finish = resolve; });
         this.sawTaskStatus = false;
         this.sawAgentMessage = false;
         this.completionProof = undefined;
@@ -94,9 +102,15 @@ export class A2AClientRuntime {
             for await (const response of this.client.sendMessageStream(request, {
                 signal: controller.signal
             })) {
+                if (controller.signal.aborted || this.disposed)
+                    break;
+                // An accepted answer supersedes the old input-required stream.
+                // Its trailing status must not reopen the answered request.
+                if (this.queuedResponse)
+                    continue;
                 this.processResponse(response);
             }
-            if (this.sink.state === 'running') {
+            if (this.sink.state === 'running' && !this.queuedResponse) {
                 if (this.completionProof) {
                     this.sink.completeTurn(this.completionProof);
                 }
@@ -114,7 +128,7 @@ export class A2AClientRuntime {
             }
         }
         catch (error) {
-            if (this.sink.state !== 'canceled') {
+            if (this.sink.state !== 'canceled' && !this.queuedResponse) {
                 this.sink.setState('failed', abortMessage(error, controller.signal));
             }
         }
@@ -123,9 +137,13 @@ export class A2AClientRuntime {
             if (this.activeController === controller)
                 this.activeController = undefined;
             this.prompting = false;
+            finish();
+            this.promptFinished = undefined;
         }
     }
     async respondPending(response, attachments = []) {
+        if (!this.isAvailable())
+            throw new Error('A2A runtime is unavailable');
         if (this.sink.state !== 'input_required') {
             throw new Error('A2A session is not waiting for input');
         }
@@ -138,10 +156,23 @@ export class A2AClientRuntime {
                     : response.message ?? response.optionId ?? '';
         if (!message.trim())
             throw new Error('A2A pending response is empty');
+        const previous = this.promptFinished || Promise.resolve();
+        this.queuedResponse = true;
         this.sink.clearPending();
-        await this.prompt(message, attachments);
+        this.sink.setState('running');
+        void previous.then(async () => {
+            this.queuedResponse = false;
+            if (this.disposed || this.sink.state === 'canceled')
+                return;
+            await this.prompt(message, attachments);
+        }).catch((error) => {
+            if (!this.disposed && this.sink.state !== 'canceled')
+                this.sink.setState('failed', errorMessage(error));
+        });
     }
     async cancel() {
+        this.sink.clearPending();
+        this.sink.setState('canceled');
         this.activeController?.abort(new Error('A2A session canceled'));
         if (this.client && this.taskId) {
             try {
@@ -162,6 +193,9 @@ export class A2AClientRuntime {
         this.activeController?.abort(new Error('A2A runtime disposed'));
         this.activeController = undefined;
     }
+    isAvailable() {
+        return !this.disposed && Boolean(this.client && this.card);
+    }
     messageRequest(text, attachments) {
         return {
             tenant: '',
@@ -280,13 +314,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:
@@ -335,12 +372,43 @@ function createResolver(config) {
         legacyCompat: { enabled: true }
     });
 }
-function resolveAgentCard(resolver, config) {
-    if (config.agentCardUrl)
-        return resolver.resolve(config.agentCardUrl, '');
-    if (config.agentUrl)
-        return resolver.resolve(config.agentUrl);
-    throw new Error('A2A Agent Card URL is required');
+async function resolveAgentCard(resolver, config) {
+    const origin = configuredOrigin(config);
+    const card = config.agentCardUrl
+        ? await resolver.resolve(config.agentCardUrl, '')
+        : await resolver.resolve(config.agentUrl);
+    // The resolver normalizes v0.3 url/additionalInterfaces into this array.
+    // Validate every advertised endpoint before transport selection or probing.
+    if (!Array.isArray(card.supportedInterfaces) || !card.supportedInterfaces.length) {
+        throw new Error('A2A Agent Card must declare at least one interface URL');
+    }
+    for (const endpoint of card.supportedInterfaces)
+        assertSameOrigin(endpoint?.url, origin);
+    return card;
+}
+function a2aUrl(value) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw new Error('A2A URL is invalid');
+    }
+    if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password || url.hash) {
+        throw new Error('A2A URL must use http(s) without credentials or a fragment');
+    }
+    return url;
+}
+function configuredOrigin(config) {
+    const value = config.agentCardUrl || config.agentUrl;
+    if (!value)
+        throw new Error('A2A Agent Card URL is required');
+    return a2aUrl(value).origin;
+}
+function assertSameOrigin(value, origin) {
+    if (a2aUrl(value).origin !== origin) {
+        throw new Error('A2A URL must have the same origin as the configured Agent Card URL');
+    }
 }
 function preferredTransports(config) {
     if (config.preferredTransport === 'jsonrpc')
@@ -350,8 +418,12 @@ function preferredTransports(config) {
     return undefined;
 }
 function authenticatedFetch(config) {
+    const origin = configuredOrigin(config);
     return async (input, init = {}) => {
-        const headers = new Headers(init.headers);
+        // The final guard also covers SDK-derived paths and future card flows.
+        // Check before attaching credentials; never let fetch follow redirects.
+        assertSameOrigin(input instanceof Request ? input.url : String(input), origin);
+        const headers = new Headers(init.headers ?? (input instanceof Request ? input.headers : undefined));
         if (config.auth?.type === 'bearer' && config.auth.value) {
             headers.set('Authorization', `Bearer ${config.auth.value}`);
         }
@@ -363,6 +435,7 @@ function authenticatedFetch(config) {
         return fetch(input, {
             ...init,
             headers,
+            redirect: 'error',
             signal: init.signal || AbortSignal.timeout(config.timeoutMs || 60_000)
         });
     };
@@ -450,3 +523,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

@@ -4,6 +4,8 @@ import type { AgentdInputAttachment, AgentdPendingResponse } from '../types.js';
 export declare class AcpProcessRuntime {
     private readonly driver;
     private readonly sink;
+    private readonly allowedRoots;
+    private readonly startupTimeoutMs;
     private process?;
     private connection?;
     private pending?;
@@ -16,12 +18,14 @@ export declare class AcpProcessRuntime {
     private inputDirectory?;
     private workspace?;
     private promptOutput;
-    constructor(driver: AgentDriver, sink: AcpSessionSink, maxStderrChunkChars?: number, promptTimeoutMs?: number);
+    constructor(driver: AgentDriver, sink: AcpSessionSink, maxStderrChunkChars?: number, promptTimeoutMs?: number, allowedRoots?: readonly string[], startupTimeoutMs?: number);
     start(workspace: string): Promise<void>;
+    private connect;
     prompt(message: string, attachments?: AgentdInputAttachment[]): Promise<void>;
     respondPending(input: AgentdPendingResponse | string, _attachments?: AgentdInputAttachment[]): Promise<void>;
     cancel(): Promise<void>;
     dispose(): Promise<void>;
+    isAvailable(): boolean;
     private requestPermission;
     private finishPermission;
     private requestInput;

package/dist/acp/runtime.js

@@ -1,15 +1,21 @@
 import { randomUUID } from 'node:crypto';
-import { mkdir, readFile, realpath, rm, stat, writeFile } from 'node:fs/promises';
+import { mkdir, rm, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import { Readable, Writable } from 'node:stream';
 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;
+import { readContainedFile } from '../workspace.js';
+// Matches MAX_PUBLISHED_FILE_BYTES in session.ts; larger files are encoded only to be dropped by the base64 budget.
+const MAX_MEDIA_MARKER_FILE_BYTES = 12 * 1024 * 1024;
+// The agent controls how many markers it emits, so bound the reads per turn.
+const MAX_MEDIA_MARKER_ARTIFACTS = 8;
 export class AcpProcessRuntime {
     driver;
     sink;
+    allowedRoots;
+    startupTimeoutMs;
     process;
     connection;
     pending;
@@ -22,9 +28,11 @@ export class AcpProcessRuntime {
     inputDirectory;
     workspace;
     promptOutput = '';
-    constructor(driver, sink, maxStderrChunkChars = 16 * 1024, promptTimeoutMs = 30 * 60 * 1000) {
+    constructor(driver, sink, maxStderrChunkChars = 16 * 1024, promptTimeoutMs = 30 * 60 * 1000, allowedRoots = [], startupTimeoutMs = 30_000) {
         this.driver = driver;
         this.sink = sink;
+        this.allowedRoots = allowedRoots;
+        this.startupTimeoutMs = startupTimeoutMs;
         const limit = Number.isFinite(maxStderrChunkChars)
             ? Math.floor(maxStderrChunkChars)
             : 16 * 1024;
@@ -32,6 +40,21 @@ export class AcpProcessRuntime {
         this.promptTimeoutMs = Math.max(10_000, Math.trunc(promptTimeoutMs));
     }
     async start(workspace) {
+        if (this.disposed)
+            throw new Error('ACP runtime is disposed');
+        if (this.process)
+            throw new Error('ACP runtime is already started');
+        try {
+            await withTimeout(this.connect(workspace), this.startupTimeoutMs, 'ACP startup timed out');
+        }
+        catch (error) {
+            if (this.sink.state !== 'canceled')
+                this.onProcessFailure(error);
+            await this.dispose();
+            throw error;
+        }
+    }
+    async connect(workspace) {
         if (this.process)
             throw new Error('ACP runtime is already started');
         this.workspace = workspace;
@@ -69,6 +92,8 @@ export class AcpProcessRuntime {
                 version: '0.2.2'
             }
         });
+        if (this.disposed)
+            throw new Error('ACP runtime is disposed');
         if (initialize.protocolVersion !== acp.PROTOCOL_VERSION) {
             this.sink.emit('terminal_output', {
                 stream: 'system',
@@ -80,10 +105,14 @@ export class AcpProcessRuntime {
             cwd: workspace,
             mcpServers: []
         });
+        if (this.disposed)
+            throw new Error('ACP runtime is disposed');
         this.sink.setAcpSessionId(String(session.sessionId));
         this.sink.setState('created');
     }
     async prompt(message, attachments = []) {
+        if (this.disposed)
+            throw new Error('ACP runtime is disposed');
         if (!this.connection)
             throw new Error('ACP runtime is not connected');
         if (this.prompting)
@@ -199,11 +228,12 @@ export class AcpProcessRuntime {
         if (this.pendingInput) {
             this.finishInput('cancel');
         }
-        if (this.connection && this.sink.state !== 'canceled') {
+        this.sink.setState('canceled');
+        if (this.connection) {
             try {
-                await this.connection.agent.notify(acp.methods.agent.session.cancel, {
+                await withTimeout(this.connection.agent.notify(acp.methods.agent.session.cancel, {
                     sessionId: this.requireSessionId()
-                });
+                }), 2_000, 'ACP cancellation notification timed out');
             }
             catch (error) {
                 this.sink.emit('terminal_output', {
@@ -229,8 +259,16 @@ export class AcpProcessRuntime {
             this.pendingInput.resolve({ action: 'cancel' });
             this.pendingInput = undefined;
         }
-        this.connection?.close();
+        const connection = this.connection;
         this.connection = undefined;
+        try {
+            connection?.close();
+        }
+        catch (error) {
+            this.sink.emit('terminal_output', {
+                stream: 'system', text: `ACP connection close failed: ${error instanceof Error ? error.message : String(error)}`
+            });
+        }
         const child = this.process;
         this.process = undefined;
         if (child) {
@@ -243,6 +281,10 @@ export class AcpProcessRuntime {
             this.inputDirectory = undefined;
         }
     }
+    isAvailable() {
+        return !this.disposed && Boolean(this.connection) &&
+            (!this.process || (this.process.exitCode === null && this.process.signalCode === null));
+    }
     requestPermission(params) {
         if (this.driver.permissionPolicy === 'deny') {
             const reject = params.options.find((option) => option.kind.startsWith('reject'));
@@ -275,11 +317,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) => {
@@ -314,7 +361,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) => {
@@ -422,13 +470,23 @@ export class AcpProcessRuntime {
         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);
+        const roots = this.allowedRoots.length
+            ? this.allowedRoots
+            : this.workspace
+                ? [this.workspace]
+                : [];
+        const unique = Array.from(new Set(markers));
+        const accepted = unique.slice(0, MAX_MEDIA_MARKER_ARTIFACTS);
+        const ignored = unique.length - accepted.length;
+        if (ignored > 0) {
+            this.sink.emit('terminal_output', {
+                stream: 'system',
+                text: `Ignored ${ignored} MEDIA marker(s); at most ${MAX_MEDIA_MARKER_ARTIFACTS} artifacts can be attached per turn.`
+            });
+        }
+        for (const marker of accepted) {
             try {
-                const artifact = await artifactFromMediaMarker(marker, `media:${randomUUID()}`, this.workspace);
+                const artifact = await artifactFromMediaMarker(marker, `media:${randomUUID()}`, roots);
                 this.sink.addArtifact(artifact);
                 this.sink.emit('artifact', artifact);
             }
@@ -441,6 +499,11 @@ export class AcpProcessRuntime {
         }
     }
     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) => {
@@ -471,10 +534,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);
@@ -662,7 +731,7 @@ function withoutMediaMarkers(output) {
         .join('\n')
         .trim();
 }
-async function artifactFromMediaMarker(marker, id, workspace) {
+async function artifactFromMediaMarker(marker, id, roots) {
     if (/^https?:\/\//i.test(marker)) {
         const filename = artifactFilename(marker, undefined, 'resource', undefined);
         return {
@@ -673,29 +742,19 @@ async function artifactFromMediaMarker(marker, id, workspace) {
             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);
+    const localPath = marker.startsWith('file:') ? fileURLToPath(marker) : marker;
+    const file = await readContainedFile(roots, localPath, {
+        maxBytes: MAX_MEDIA_MARKER_FILE_BYTES
+    });
     return {
         id,
-        name: filename,
-        filename,
-        mediaType: mediaTypeForPath(filename),
-        bytesBase64: (await readFile(resolved)).toString('base64'),
+        name: file.filename,
+        filename: file.filename,
+        mediaType: mediaTypeForPath(file.filename),
+        bytesBase64: file.bytes.toString('base64'),
         metadata: {
             source: 'acp_media_marker',
-            size: details.size
+            size: file.size
         }
     };
 }
@@ -824,3 +883,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. 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.',
+    '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>, where <path> stays inside the configured workspace roots; Agent Nexus snapshots that declared file as an artifact before the turn completes, refuses paths outside those roots, and attaches at most 8 files per turn.',
     '</agent_nexus_completion_contract>'
 ].join('\n');