@amaster.ai/dsh-a2a 0.1.34 → 0.1.35

package/lib/content.js

@@ -16,13 +16,17 @@
  * used: they take base64 wire uploads and throw on refusal — this path holds
  * raw bytes and must degrade, never fail.
  */
+import { lookup as dnsLookup } from 'node:dns/promises';
 import { mkdir, writeFile } from 'node:fs/promises';
+import { request as httpRequest } from 'node:http';
+import { request as httpsRequest } from 'node:https';
+import { BlockList, isIP } from 'node:net';
 import os from 'node:os';
 import path from 'node:path';
 /** Cap on one url part download. */
 const MAX_DOWNLOAD_BYTES = 64 * 1024 * 1024;
 const DOWNLOAD_TIMEOUT_MS = 30_000;
-export async function buildMessageContent(parts, attachments, dir, materialization) {
+export async function buildMessageContent(parts, attachments, dir, materialization, downloads = {}) {
     const content = [];
     for (const part of parts) {
         const c = part.content;
@@ -38,7 +42,7 @@ export async function buildMessageContent(parts, attachments, dir, materializati
                 break;
             case 'raw':
             case 'url':
-                content.push(await fileContent(c, part, attachments, dir, materialization));
+                content.push(await fileContent(c, part, attachments, dir, materialization, downloads));
                 break;
             default:
                 // A part kind this SDK version predates: keep it visible, never drop.
@@ -59,17 +63,18 @@ export function uploadsDir(root) {
 /** Log and degrade one file-part failure to a metadata note. */
 function failNote(part, mediaType, uri, label, error) {
     console.error(`[dsh-a2a] ${label}:`, error);
-    return note(part, mediaType, uri, error instanceof Error ? error.message : String(error));
+    const text = error instanceof Error ? error.message : String(error);
+    return note(part, mediaType, uri, uri ? text.replaceAll(uri, redactedUri(uri) ?? '[redacted URL]') : text);
 }
 /** Resolve one file part to an attachment block or a workspace file. */
-async function fileContent(c, part, attachments, dir, materialization) {
+async function fileContent(c, part, attachments, dir, materialization, downloads) {
     let bytes;
     let mediaType = part.mediaType;
     let uri;
     try {
         if (c.$case === 'url') {
             uri = c.value;
-            const got = await download(uri);
+            const got = await download(uri, downloads);
             bytes = got.bytes;
             mediaType ||= got.mediaType ?? '';
         }
@@ -171,6 +176,7 @@ function sanitizeUploadFileName(name) {
 }
 /** Tool-readable path stand-in for a file part. */
 function documentBlock(uri, mediaType, bytes, filePath, originalName) {
+    const displayUri = uri ? redactedUri(uri) : undefined;
     const attrs = [
         // The basename of the final path, so name= always matches the file on
         // disk — including collision suffixes.
@@ -178,7 +184,7 @@ function documentBlock(uri, mediaType, bytes, filePath, originalName) {
         originalName &&
             originalName !== path.win32.basename(filePath) &&
             `originalName="${attr(originalName)}"`,
-        uri && `uri="${attr(uri)}"`,
+        displayUri && `uri="${attr(displayUri)}"`,
         mediaType && `type="${attr(mediaType)}"`,
         `size="${bytes}"`,
         `path="${attr(filePath)}"`,
@@ -191,10 +197,11 @@ function documentBlock(uri, mediaType, bytes, filePath, originalName) {
     };
 }
 function note(part, mediaType, uri, reason) {
+    const displayUri = uri ? redactedUri(uri) : undefined;
     const desc = [
         part.filename && `"${part.filename}"`,
         mediaType && `(${mediaType})`,
-        uri && `at ${uri}`,
+        displayUri && `at ${displayUri}`,
     ]
         .filter(Boolean)
         .join(' ');
@@ -213,31 +220,157 @@ function dataText(value) {
 function attr(value) {
     return value.replace(/["\r\n<>]/g, ' ');
 }
-/** Fetch one url part's bytes over http(s), bounded in size and time. */
-async function download(uri) {
-    const scheme = new URL(uri).protocol;
-    if (scheme !== 'http:' && scheme !== 'https:') {
-        throw new Error(`unsupported scheme "${scheme}"`);
-    }
-    const response = await fetch(uri, { signal: AbortSignal.timeout(DOWNLOAD_TIMEOUT_MS) });
-    if (!response.ok)
-        throw new Error(`HTTP ${response.status}`);
-    const declared = Number(response.headers.get('content-length'));
-    if (declared > MAX_DOWNLOAD_BYTES) {
-        throw new Error(`exceeds the ${MAX_DOWNLOAD_BYTES}-byte download limit`);
-    }
-    const chunks = [];
-    let total = 0;
-    if (response.body) {
-        // Throwing out of the loop cancels the stream via the iterator's return.
-        for await (const chunk of response.body) {
-            total += chunk.byteLength;
-            if (total > MAX_DOWNLOAD_BYTES) {
+/** Display-only URL: credentials, query and fragment never enter prompts or notes. */
+function redactedUri(uri) {
+    try {
+        const parsed = new URL(uri);
+        parsed.username = '';
+        parsed.password = '';
+        parsed.search = '';
+        parsed.hash = '';
+        return parsed.toString();
+    }
+    catch {
+        return undefined;
+    }
+}
+const nonPublic = new BlockList();
+for (const [subnet, prefix] of [
+    ['0.0.0.0', 8],
+    ['10.0.0.0', 8],
+    ['100.64.0.0', 10],
+    ['127.0.0.0', 8],
+    ['169.254.0.0', 16],
+    ['172.16.0.0', 12],
+    ['192.0.0.0', 24],
+    ['192.0.2.0', 24],
+    ['192.168.0.0', 16],
+    ['198.18.0.0', 15],
+    ['198.51.100.0', 24],
+    ['203.0.113.0', 24],
+    ['224.0.0.0', 4],
+    ['240.0.0.0', 4],
+])
+    nonPublic.addSubnet(subnet, prefix, 'ipv4');
+for (const [subnet, prefix] of [
+    ['::', 128],
+    ['::1', 128],
+    ['fc00::', 7],
+    ['fe80::', 10],
+    ['ff00::', 8],
+    ['2001:db8::', 32],
+])
+    nonPublic.addSubnet(subnet, prefix, 'ipv6');
+function assertPublicAddress(address) {
+    const mapped = /^::ffff:(\d+\.\d+\.\d+\.\d+)$/i.exec(address)?.[1];
+    const value = mapped ?? address;
+    const family = isIP(value);
+    if (!family || nonPublic.check(value, family === 6 ? 'ipv6' : 'ipv4')) {
+        throw new Error(`download targets a private or non-public address: ${address}`);
+    }
+}
+async function safeAddresses(hostname, allowedHosts, allowPrivate) {
+    const host = hostname.replace(/^\[|\]$/g, '').toLowerCase();
+    if (allowPrivate || allowedHosts.has(host))
+        return [];
+    const addresses = isIP(host)
+        ? [{ address: host, family: isIP(host) }]
+        : await dnsLookup(host, { all: true, verbatim: true });
+    if (!addresses.length)
+        throw new Error(`download host has no address: ${host}`);
+    for (const { address } of addresses)
+        assertPublicAddress(address);
+    return addresses;
+}
+/** Fetch one url part's bytes over http(s), bounded in size, redirects, address and time. */
+async function download(uri, options) {
+    const allowedHosts = new Set((options.allowedHosts ?? []).map((host) => host.replace(/^\[|\]$/g, '').toLowerCase()));
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(new Error('download timed out')), DOWNLOAD_TIMEOUT_MS);
+    timeout.unref();
+    try {
+        let current = new URL(uri);
+        for (let redirect = 0;; redirect++) {
+            if (current.protocol !== 'http:' && current.protocol !== 'https:') {
+                throw new Error(`unsupported scheme "${current.protocol}"`);
+            }
+            await safeAddresses(current.hostname, allowedHosts, options.allowPrivate === true);
+            const response = await new Promise((resolve, reject) => {
+                const request = (current.protocol === 'http:' ? httpRequest : httpsRequest)(current, {
+                    signal: controller.signal,
+                    lookup: (hostname, lookupOptions, callback) => {
+                        const allowed = options.allowPrivate === true ||
+                            allowedHosts.has(hostname.replace(/^\[|\]$/g, '').toLowerCase());
+                        const resolving = allowed
+                            ? dnsLookup(hostname, { all: lookupOptions.all ?? false }).then((entry) => Array.isArray(entry) ? entry : [entry])
+                            : safeAddresses(hostname, allowedHosts, false);
+                        void resolving.then((addresses) => {
+                            if (lookupOptions.all)
+                                return callback(null, addresses);
+                            const { address, family } = addresses[0];
+                            callback(null, address, family);
+                            return addresses;
+                        }, (error) => callback(error, '', 0));
+                    },
+                }, resolve);
+                request.on('socket', (socket) => {
+                    socket.once('connect', () => {
+                        if (options.allowPrivate === true)
+                            return;
+                        if (allowedHosts.has(current.hostname.replace(/^\[|\]$/g, '').toLowerCase()))
+                            return;
+                        try {
+                            assertPublicAddress(socket.remoteAddress ?? '');
+                        }
+                        catch (error) {
+                            request.destroy(error);
+                        }
+                    });
+                });
+                request.on('error', reject);
+                request.end();
+            });
+            const status = response.statusCode ?? 0;
+            const location = response.headers.location;
+            if ([301, 302, 303, 307, 308].includes(status) && location) {
+                response.resume();
+                if (redirect >= 5)
+                    throw new Error('too many download redirects');
+                current = new URL(location, current);
+                continue;
+            }
+            if (status < 200 || status >= 300) {
+                response.resume();
+                throw new Error(`HTTP ${status}`);
+            }
+            const declared = Number(response.headers['content-length']);
+            if (declared > MAX_DOWNLOAD_BYTES) {
+                response.destroy();
                 throw new Error(`exceeds the ${MAX_DOWNLOAD_BYTES}-byte download limit`);
             }
-            chunks.push(chunk);
+            const chunks = [];
+            let total = 0;
+            try {
+                for await (const chunk of response) {
+                    total += chunk.byteLength;
+                    if (total > MAX_DOWNLOAD_BYTES) {
+                        throw new Error(`exceeds the ${MAX_DOWNLOAD_BYTES}-byte download limit`);
+                    }
+                    chunks.push(chunk);
+                }
+            }
+            catch (error) {
+                response.destroy();
+                throw error;
+            }
+            const contentType = response.headers['content-type'];
+            const mediaType = (Array.isArray(contentType) ? contentType[0] : contentType)
+                ?.split(';')[0]
+                .trim();
+            return { bytes: Buffer.concat(chunks, total), mediaType: mediaType || undefined };
         }
     }
-    const mediaType = response.headers.get('content-type')?.split(';')[0].trim() || undefined;
-    return { bytes: Buffer.concat(chunks, total), mediaType };
+    finally {
+        clearTimeout(timeout);
+    }
 }

package/lib/executor.js

@@ -19,11 +19,14 @@
  */
 import { TaskState } from '@a2a-js/sdk';
 import { AgentEvent, STATE_HEADERS_KEY } from '@a2a-js/sdk/server';
+import { AdmissionGate } from './admission.js';
 import { ApprovalReplyError } from './approval.js';
 import { agentTextMessage, terminalStatusUpdate } from './translator.js';
 export class DshAgentExecutor {
     bridge;
     suppressTask;
+    admissions = new AdmissionGate();
+    admissionFailures = new Map();
     constructor(bridge, suppressTask) {
         this.bridge = bridge;
         this.suppressTask = suppressTask;
@@ -35,9 +38,35 @@ export class DshAgentExecutor {
         if (this.bridge.isClearing(requestContext.contextId)) {
             this.suppressTask?.(requestContext.taskId);
         }
-        return this.bridge.trackExecution(requestContext.contextId, () => this.executeInner(requestContext, eventBus));
+        const contextId = requestContext.contextId;
+        const failureVersion = this.admissionFailures.get(contextId) ?? 0;
+        const admission = this.admissions.acquire(contextId);
+        let accepted = false;
+        const accept = () => {
+            if (accepted)
+                return;
+            accepted = true;
+            admission.release(() => this.admissionFailures.delete(contextId));
+        };
+        try {
+            return await this.bridge.trackExecution(contextId, async () => {
+                await admission.ready;
+                if ((this.admissionFailures.get(contextId) ?? 0) !== failureVersion) {
+                    eventBus.publish(taskEvent(requestContext.taskId, contextId, TaskState.TASK_STATE_FAILED));
+                    eventBus.publish(terminalStatusUpdate(requestContext.taskId, contextId, 'failed', 'Preceding queued turn failed.'));
+                    eventBus.finished();
+                    return;
+                }
+                await this.executeInner(requestContext, eventBus, accept, () => {
+                    this.admissionFailures.set(contextId, (this.admissionFailures.get(contextId) ?? 0) + 1);
+                });
+            });
+        }
+        finally {
+            accept();
+        }
     }
-    async executeInner(requestContext, eventBus) {
+    async executeInner(requestContext, eventBus, accept, fail) {
         const { userMessage, taskId, contextId } = requestContext;
         let anchored = false;
         try {
@@ -49,6 +78,7 @@ export class DshAgentExecutor {
                 }
                 finally {
                     approval.resume();
+                    accept();
                 }
                 await this.bridge.waitForTurn(approval.entry);
                 return;
@@ -65,11 +95,16 @@ export class DshAgentExecutor {
                     taskEvent(taskId, contextId, TaskState.TASK_STATE_WORKING));
             anchored = true;
             const requestHeaders = requestContext.context.state.get(STATE_HEADERS_KEY);
-            await this.bridge.runTurn(entry, content, eventBus, taskId, userMessage, requestHeaders);
+            const turn = this.bridge.runTurn(entry, content, eventBus, taskId, userMessage, requestHeaders);
+            // runTurn registers synchronously before its first await. The next
+            // request may prepare now; the bridge FIFO still executes turns in order.
+            accept();
+            await turn;
         }
         catch (error) {
             if (error instanceof ApprovalReplyError)
                 return;
+            fail();
             if (this.bridge.isClearing(contextId))
                 this.suppressTask?.(taskId);
             const message = error instanceof Error ? error.message : String(error);

package/lib/inbox-api.js

@@ -0,0 +1,117 @@
+/** JSON-RPC method extension; standard task methods stay with the official SDK. */
+import { A2A_PROTOCOL_VERSION, A2A_VERSION_HEADER, Extensions, HTTP_EXTENSION_HEADER, Message, } from '@a2a-js/sdk';
+import { ExtensionSupportRequiredError, RequestMalformedError, toJsonRpcError, } from '@a2a-js/sdk/errors';
+import { validateVersion } from '@a2a-js/sdk/server';
+import { INBOX_EXTENSION, validateInboxPage } from './inbox.js';
+export function inboxRpcHandler(inbox, card) {
+    return async (req, res, next) => {
+        const body = req.body;
+        if (typeof body?.method !== 'string' || !body.method.startsWith('dsh/inbox/'))
+            return next();
+        try {
+            if (body.jsonrpc !== '2.0' || !['string', 'number'].includes(typeof body.id))
+                throw new RequestMalformedError('A JSON-RPC 2.0 request id is required.');
+            validateVersion(req.get(A2A_VERSION_HEADER) || A2A_PROTOCOL_VERSION, card, 'JSONRPC');
+            if (!Extensions.parseServiceParameter(req.get(HTTP_EXTENSION_HEADER)).includes(INBOX_EXTENSION))
+                throw new ExtensionSupportRequiredError('Activate the native inbox extension.');
+            res.setHeader(HTTP_EXTENSION_HEADER, INBOX_EXTENSION);
+            const params = body.params;
+            if (!params ||
+                typeof params !== 'object' ||
+                Array.isArray(params) ||
+                typeof params.contextId !== 'string' ||
+                !params.contextId.trim() ||
+                (params.tenant !== undefined && params.tenant !== ''))
+                throw new RequestMalformedError('A contextId and the default tenant are required.');
+            const method = body.method.slice('dsh/inbox/'.length);
+            const page = { pageSize: params.pageSize, pageToken: params.pageToken };
+            validateInboxPage(page);
+            if (method !== 'get' && page.pageToken)
+                throw new RequestMalformedError('pageToken is only supported by inbox get.');
+            if (['update', 'move', 'remove', 'steer'].includes(method) &&
+                (typeof params.id !== 'string' || !params.id))
+                throw new RequestMalformedError('A native inbox id is required.');
+            let result;
+            switch (method) {
+                case 'get':
+                    result = await inbox.get(params.contextId, page);
+                    break;
+                case 'update': {
+                    if (!params.message ||
+                        typeof params.message !== 'object' ||
+                        Array.isArray(params.message))
+                        throw new RequestMalformedError('A user Message is required.');
+                    let message;
+                    try {
+                        message = Message.fromJSON(params.message);
+                    }
+                    catch {
+                        throw new RequestMalformedError('Invalid A2A Message.');
+                    }
+                    result = await inbox.update(params.contextId, params.id, message, page);
+                    break;
+                }
+                case 'move':
+                    result = await inbox.move(params.contextId, params.id, params.index, page);
+                    break;
+                case 'remove':
+                    result = await inbox.remove(params.contextId, params.id, page);
+                    break;
+                case 'clear':
+                    result = await inbox.clearPending(params.contextId, page);
+                    break;
+                case 'execute': {
+                    if (params.id !== undefined && (typeof params.id !== 'string' || !params.id))
+                        throw new RequestMalformedError('id must be a native inbox id.');
+                    result = await inbox.executePending(params.contextId, params.id, page);
+                    break;
+                }
+                case 'steer': {
+                    if (typeof params.taskId !== 'string' || !params.taskId)
+                        throw new RequestMalformedError('An active taskId is required.');
+                    await inbox.promote(params.contextId, params.id, params.taskId);
+                    result = await inbox.get(params.contextId, page);
+                    break;
+                }
+                case 'subscribe': {
+                    const agent = await inbox.resolve(params.contextId);
+                    if (res.destroyed)
+                        return;
+                    res.setHeader('Content-Type', 'text/event-stream');
+                    res.setHeader('Cache-Control', 'no-cache');
+                    const dispose = inbox.changes.watch(agent.session, (change) => {
+                        if (res.destroyed || res.writableEnded)
+                            return;
+                        res.flushHeaders();
+                        if (!res.write(`data: ${JSON.stringify({ jsonrpc: '2.0', id: body.id, result: change })}\n\n`))
+                            res.destroy();
+                    }, () => res.end());
+                    res.once('close', dispose);
+                    try {
+                        await inbox.changes.checkpoint(agent.session);
+                    }
+                    catch (error) {
+                        res.off('close', dispose);
+                        dispose();
+                        throw error;
+                    }
+                    return;
+                }
+                default:
+                    return next();
+            }
+            res.json({ jsonrpc: '2.0', id: body.id, result });
+        }
+        catch (error) {
+            if (res.destroyed || res.writableEnded)
+                return;
+            const response = { jsonrpc: '2.0', id: body?.id ?? null, error: toJsonRpcError(error) };
+            if (res.headersSent)
+                res.end(`data: ${JSON.stringify(response)}\n\n`);
+            else {
+                res.setHeader('Content-Type', 'application/json');
+                res.json(response);
+            }
+        }
+    };
+}

package/lib/inbox-changes.js

@@ -0,0 +1,116 @@
+import { UnsupportedOperationError } from '@a2a-js/sdk/errors';
+/** Invalidation only: DSH owns the queue, sequence and durability barrier. */
+export class InboxChanges {
+    ctx;
+    states = new WeakMap();
+    listeners = new Map();
+    disposed = new WeakSet();
+    detach;
+    stopped = false;
+    constructor(ctx, managed, enabled = false) {
+        this.ctx = ctx;
+        this.detach = [
+            ctx.on('session/event', (session, event) => {
+                if (this.stopped ||
+                    this.disposed.has(session) ||
+                    event.type !== 'agent/inbox/spliced' ||
+                    !managed(session.id) ||
+                    (!enabled && !this.listeners.has(session)))
+                    return;
+                const pending = this.states.get(session);
+                if (pending?.job) {
+                    pending.requested = Math.max(pending.requested, session.seq - 1);
+                    return;
+                }
+                void this.checkpoint(session).catch((error) => {
+                    if (!this.stopped)
+                        console.error('[dsh-a2a] inbox checkpoint notification failed:', error);
+                });
+            }),
+            ctx.on('session/disposed', (session) => this.closeSession(session)),
+        ];
+        ctx.effect(() => () => this.close());
+    }
+    watch(session, listener, closed) {
+        if (this.stopped || this.disposed.has(session))
+            throw new UnsupportedOperationError('Inbox notifications are closed.');
+        let listeners = this.listeners.get(session);
+        if (!listeners) {
+            listeners = new Map();
+            this.listeners.set(session, listeners);
+        }
+        listeners.set(listener, closed);
+        const dispose = () => {
+            listeners.delete(listener);
+            if (!listeners.size && this.listeners.get(session) === listeners)
+                this.listeners.delete(session);
+        };
+        return dispose;
+    }
+    checkpoint(session) {
+        if (this.stopped || this.disposed.has(session))
+            return Promise.reject(new UnsupportedOperationError('Inbox notifications are closed.'));
+        let state = this.states.get(session);
+        if (!state) {
+            state = { requested: -1 };
+            this.states.set(session, state);
+        }
+        state.requested = Math.max(state.requested, session.seq - 1);
+        const pending = state;
+        if (!pending.job)
+            pending.job = Promise.resolve().then(async () => {
+                try {
+                    let version;
+                    do {
+                        if (this.stopped || this.disposed.has(session))
+                            throw new UnsupportedOperationError('Inbox notifications are closed.');
+                        version = pending.requested;
+                        const sessions = this.ctx.get('sessions');
+                        if (!sessions || !(await sessions.flush(session)))
+                            throw new UnsupportedOperationError('Inbox notifications require a successful DSH durability checkpoint.');
+                        if (this.stopped || this.disposed.has(session))
+                            throw new UnsupportedOperationError('Inbox notifications are closed.');
+                        const change = { contextId: session.id, version };
+                        for (const listener of this.listeners.get(session)?.keys() ?? []) {
+                            try {
+                                listener(change);
+                            }
+                            catch (error) {
+                                console.error('[dsh-a2a] inbox notification listener failed:', error);
+                            }
+                        }
+                        await this.ctx.parallel('a2a/inbox-checkpointed', change).catch((error) => {
+                            console.error('[dsh-a2a] inbox checkpoint observer failed:', error);
+                        });
+                    } while (pending.requested > version);
+                    return { contextId: session.id, version };
+                }
+                finally {
+                    pending.job = undefined;
+                }
+            });
+        return pending.job;
+    }
+    close() {
+        if (this.stopped)
+            return;
+        this.stopped = true;
+        for (const detach of this.detach)
+            detach();
+        for (const session of this.listeners.keys())
+            this.closeSession(session);
+    }
+    closeSession(session) {
+        this.disposed.add(session);
+        const listeners = this.listeners.get(session);
+        this.listeners.delete(session);
+        for (const close of listeners?.values() ?? []) {
+            try {
+                close();
+            }
+            catch (error) {
+                console.error('[dsh-a2a] inbox subscription cleanup failed:', error);
+            }
+        }
+    }
+}