@dev-mainsequence/codex-plugin 0.3.0 → 0.7.9

package/dist/vendor/devtools/shared/agentDelivery.js

@@ -0,0 +1,477 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgentDelivery = void 0;
+const node_fs_1 = require("node:fs");
+const fs = __importStar(require("node:fs/promises"));
+const path = __importStar(require("node:path"));
+const os = __importStar(require("node:os"));
+const node_crypto_1 = require("node:crypto");
+const models_1 = require("./models.js");
+const session_1 = require("./session.js");
+const hash = (value) => (0, node_crypto_1.createHash)('sha256').update(JSON.stringify(value)).digest('hex');
+const uuid = (value) => {
+    if (typeof value !== 'string' || !/^[a-f\d]{8}(?:-[a-f\d]{4}){3}-[a-f\d]{12}$/i.test(value))
+        throw new models_1.ToolingError('INVALID_REQUEST', 'A valid saved request or agent identifier is required.');
+    return value.toLowerCase();
+};
+const failStore = () => new models_1.ToolingError('STORE_ERROR', 'Saved agent requests could not be read safely. Existing requests were kept; no message was resent.');
+const live = (pid) => { try {
+    process.kill(pid, 0);
+    return true;
+}
+catch (e) {
+    return e.code !== 'ESRCH';
+} };
+const view = (r) => { const { owner: _, ...publicRequest } = r; return structuredClone(publicRequest); };
+const finished = (r) => !['pending', 'preparing', 'sending'].includes(r.state);
+const sleep = (ms) => new Promise(resolve => setTimeout(resolve, ms));
+const defaultDirectory = () => path.join(process.platform === 'darwin' ? path.join(os.homedir(), 'Library', 'Application Support', 'MainSequenceCLI')
+    : process.platform === 'win32' ? path.join(process.env.APPDATA || os.homedir(), 'MainSequenceCLI') : path.join(os.homedir(), '.config', 'mainsequence'), 'agent-delivery-v1');
+/**
+ * Durable, account/chat-scoped delivery. A receipt can be read repeatedly; a send is never replayed.
+ * Native turn cancellation only cancels the caller's wait. Accepted work has its own bounded lifetime.
+ * Process loss during a send is uncertain, not evidence of failure or permission to send again.
+ */
+class AgentDelivery {
+    options;
+    directory;
+    jobs = new Map();
+    constructor(options) {
+        this.options = options;
+        this.directory = path.resolve(options.directory || defaultDirectory());
+    }
+    scope(input) {
+        if (!input || typeof input.host !== 'string' || !/^[a-z][a-z0-9-]{0,63}$/.test(input.host)
+            || typeof input.conversationId !== 'string' || !input.conversationId.trim() || input.conversationId.length > 512
+            || typeof input.account !== 'string' || !input.account.trim() || input.account.length > 300)
+            throw new models_1.ToolingError('INVALID_REQUEST', 'A verified account and host conversation are required.');
+        const scope = { ...input, backend: (0, session_1.requireBackend)(input.backend) };
+        return { scope, key: hash([scope.host, scope.conversationId, scope.backend, scope.account]) };
+    }
+    async verify(scope, signal) {
+        signal?.throwIfAborted();
+        const result = await this.options.createDispatch(signal)({ action: 'auth-status', backend: scope.backend, check: true });
+        const data = result.data;
+        if (result.status !== 'success')
+            throw new models_1.ToolingError(result.error?.code || 'AUTH_REJECTED', result.summary);
+        if (!data?.authenticated || data.username !== scope.account)
+            throw new models_1.ToolingError('AUTH_REJECTED', 'The MainSequence account changed. Refresh before accessing saved agent requests.');
+        signal?.throwIfAborted();
+    }
+    async secureDirectory() {
+        await fs.mkdir(this.directory, { recursive: true, mode: 0o700 });
+        const stat = await fs.lstat(this.directory);
+        if (!stat.isDirectory() || stat.isSymbolicLink() || (process.getuid && stat.uid !== process.getuid()))
+            throw failStore();
+        await fs.chmod(this.directory, 0o700);
+    }
+    async readFile(file, lockRead = false) {
+        const handle = await fs.open(file, node_fs_1.constants.O_RDONLY | (node_fs_1.constants.O_NOFOLLOW || 0));
+        try {
+            const stat = await handle.stat();
+            if (lockRead && stat.nlink === 0)
+                throw Object.assign(new Error('The lock was released while opening it.'), { code: 'ENOENT' });
+            if (!stat.isFile() || stat.nlink !== 1 || stat.size > 36_000_000 || (process.getuid && stat.uid !== process.getuid()))
+                throw failStore();
+            return await handle.readFile('utf8');
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    async locked(key, run) {
+        await this.secureDirectory();
+        const file = path.join(this.directory, key + '.json'), lock = file + '.lock';
+        const owner = { pid: process.pid, token: (0, node_crypto_1.randomUUID)() };
+        let guard;
+        const deadline = Date.now() + 3000;
+        while (!guard) {
+            try {
+                guard = await fs.open(lock, 'wx', 0o600);
+            }
+            catch (error) {
+                if (error.code !== 'EEXIST')
+                    throw failStore();
+                let previous;
+                try {
+                    previous = JSON.parse(await this.readFile(lock, true));
+                }
+                catch (e) {
+                    // A new exclusive file can briefly precede its owner record. Never reclaim it.
+                    if (Date.now() >= deadline)
+                        throw failStore();
+                    if (e instanceof SyntaxError || e.code === 'ENOENT') {
+                        await sleep(25);
+                        continue;
+                    }
+                    throw failStore();
+                }
+                if (!Number.isSafeInteger(previous.pid) || previous.pid <= 0 || typeof previous.token !== 'string')
+                    throw failStore();
+                if (!live(previous.pid)) {
+                    // One durable reclamation claim per dead owner prevents deleting a replacement lock.
+                    const claim = lock + '.reclaim-' + uuid(previous.token);
+                    try {
+                        const handle = await fs.open(claim, 'wx', 0o600);
+                        await handle.close();
+                    }
+                    catch {
+                        throw new models_1.ToolingError('PROJECT_BUSY', 'Agent storage recovery is already running. Try reading status again.');
+                    }
+                    if (await this.readFile(lock) !== JSON.stringify(previous))
+                        throw failStore();
+                    await fs.unlink(lock);
+                    continue;
+                }
+                if (Date.now() >= deadline)
+                    throw new models_1.ToolingError('PROJECT_BUSY', 'Another agent request is updating local storage. Try reading status again.');
+                await sleep(25);
+            }
+        }
+        try {
+            await guard.writeFile(JSON.stringify(owner));
+            await guard.sync();
+            let state;
+            try {
+                state = JSON.parse(await this.readFile(file));
+            }
+            catch (e) {
+                if (e.code !== 'ENOENT')
+                    throw failStore();
+                state = { version: 1, scope: key, requests: {} };
+            }
+            if (state?.version !== 1 || state.scope !== key || !state.requests || Array.isArray(state.requests) || typeof state.requests !== 'object' || Object.keys(state.requests).length > 256)
+                throw failStore();
+            for (const [id, r] of Object.entries(state.requests)) {
+                if (!r || uuid(id) !== id || r.requestId !== id || r.messageId !== id || typeof r.message !== 'string' || r.message.length > 64000
+                    || typeof r.agentName !== 'string' || !['pending', 'preparing', 'sending', 'delivered', 'failed', 'uncertain', 'cancelled', 'expired'].includes(r.state)
+                    || !/^host_[a-f0-9]{64}$/.test(r.handleId) || !Number.isFinite(Date.parse(r.createdAt))
+                    || !r.submission || !Number.isSafeInteger(r.submission.attempts) || r.submission.attempts < 0
+                    || !['not-submitted', 'attempted', 'acknowledged', 'unknown'].includes(r.submission.outcome)
+                    || !Number.isSafeInteger(r.sendAttempts) || r.sendAttempts < 0 || r.sendAttempts > 1 || !Number.isFinite(Date.parse(r.expiresAt)))
+                    throw failStore();
+                // 'failed' is reserved for a completed devtools result proving no remote mutation.
+                // Early development records counted entry into agent-send before its preflight.
+                if (r.state === 'failed')
+                    r.sendAttempts = 0;
+                uuid(r.agentUid);
+                uuid(r.environmentUid);
+                if (r.sessionUid)
+                    uuid(r.sessionUid);
+                if (r.conversationKey)
+                    uuid(r.conversationKey);
+                if (r.continuationTaskUid)
+                    uuid(r.continuationTaskUid);
+                if (r.taskRequestId)
+                    uuid(r.taskRequestId);
+                if (r.state === 'delivered' && (!r.receipt || typeof r.receipt.message !== 'string' || !r.receipt.message || r.receipt.sessionUid !== r.sessionUid))
+                    throw failStore();
+                if (['preparing', 'sending'].includes(r.state)) {
+                    if (!r.owner || !Number.isSafeInteger(r.owner.pid) || r.owner.pid <= 0 || typeof r.owner.token !== 'string')
+                        throw failStore();
+                    if (!live(r.owner.pid)) {
+                        r.state = r.state === 'sending' ? 'uncertain' : 'pending';
+                        r.reason = r.state === 'uncertain' ? 'The process ended during dispatch. Delivery is unknown; resend is blocked.' : 'Preparation was interrupted before sending. Recover this same request.';
+                        delete r.owner;
+                    }
+                }
+                if ((r.state === 'pending' || (r.state === 'failed' && r.sendAttempts === 0)) && Date.parse(r.expiresAt) <= Date.now()) {
+                    r.state = 'expired';
+                    r.reason = 'This request expired without being sent.';
+                }
+            }
+            const save = async () => {
+                const serialized = JSON.stringify(state);
+                if (Buffer.byteLength(serialized) > 36_000_000)
+                    throw failStore();
+                const temporary = file + '.' + (0, node_crypto_1.randomUUID)() + '.tmp', handle = await fs.open(temporary, 'wx', 0o600);
+                try {
+                    await handle.writeFile(serialized);
+                    await handle.sync();
+                }
+                finally {
+                    await handle.close();
+                }
+                try {
+                    await fs.rename(temporary, file);
+                    const directory = await fs.open(this.directory, 'r');
+                    try {
+                        await directory.sync();
+                    }
+                    finally {
+                        await directory.close();
+                    }
+                }
+                finally {
+                    await fs.unlink(temporary).catch(() => { });
+                }
+            };
+            const result = await run(state, save);
+            await save();
+            return result;
+        }
+        finally {
+            await guard.close();
+            await fs.unlink(lock);
+        }
+    }
+    /** Prepare a stable conversation without sending an introductory message. */
+    async prepare(input, selection, signal) {
+        const { scope, key } = this.scope(input), environmentUid = uuid(selection.environmentUid), agentUid = uuid(selection.agentUid);
+        const conversationKey = selection.conversationKey === undefined ? undefined : uuid(selection.conversationKey);
+        await this.verify(scope, signal);
+        const dispatch = this.options.createDispatch(signal), target = { backend: scope.backend, expectedAccount: scope.account, environmentUid, agentUid };
+        const handleId = 'host_' + hash(conversationKey ? [key, environmentUid, agentUid, conversationKey] : [key, environmentUid, agentUid]);
+        const session = await dispatch({ action: 'agent-session', ...target, handleId });
+        if (session.status !== 'success')
+            throw new models_1.ToolingError(session.error?.code || 'API_ERROR', session.summary);
+        const sessionUid = uuid(session.data?.sessionUid);
+        const ready = await dispatch({ action: 'agent-readiness', ...target, sessionUid, timeoutMs: 90000 });
+        if (ready.status !== 'success')
+            throw new models_1.ToolingError(ready.error?.code || 'API_ERROR', ready.summary);
+        return { sessionUid, handleId, ready: true };
+    }
+    async stage(input, draft, signal) {
+        const { scope, key } = this.scope(input), requestId = uuid(draft.requestId), agentUid = uuid(draft.agentUid), environmentUid = uuid(draft.environmentUid);
+        if (typeof draft.message !== 'string' || !draft.message.trim() || draft.message.length > 64000)
+            throw new models_1.ToolingError('INVALID_REQUEST', 'Enter a message of 1–64000 characters.');
+        const conversationKey = draft.conversationKey === undefined ? undefined : uuid(draft.conversationKey);
+        const responseKind = draft.responseKind ?? 'message';
+        if (!['message', 'task'].includes(responseKind))
+            throw new models_1.ToolingError('INVALID_REQUEST', 'Choose message or task response mode.');
+        await this.verify(scope, signal);
+        const detail = await this.options.createDispatch(signal)({ action: 'agent-get', backend: scope.backend, expectedAccount: scope.account, environmentUid, agentUid });
+        const agent = detail.data?.agent;
+        if (detail.status !== 'success')
+            throw new models_1.ToolingError(detail.error?.code || 'API_ERROR', detail.summary);
+        if (!agent || agent.uid !== agentUid || !agent.responseKinds.includes(responseKind))
+            throw new models_1.ToolingError('UNSUPPORTED_ACTION', 'This agent does not support the selected response mode.');
+        const previousTask = draft.taskRequestId ? await this.get(scope, uuid(draft.taskRequestId), signal) : undefined;
+        if (previousTask && (responseKind !== 'task' || previousTask.agentUid !== agentUid || previousTask.environmentUid !== environmentUid || !previousTask.task))
+            throw new models_1.ToolingError('INVALID_REQUEST', 'Continue only a saved task belonging to this agent and environment.');
+        signal?.throwIfAborted();
+        return this.locked(key, async (state) => {
+            const same = (r) => r.agentUid === agentUid && r.environmentUid === environmentUid && r.message === draft.message && (r.responseKind ?? 'message') === responseKind && r.conversationKey === conversationKey && r.taskRequestId === draft.taskRequestId;
+            const previous = state.requests[requestId];
+            if (previous) {
+                if (!same(previous))
+                    throw new models_1.ToolingError('INVALID_REQUEST', 'This request ID already belongs to different immutable content.');
+                return view(previous);
+            }
+            const duplicate = Object.values(state.requests).find(r => same(r) && ['pending', 'preparing', 'sending', 'uncertain'].includes(r.state));
+            if (duplicate)
+                return view(duplicate);
+            if (Object.keys(state.requests).length >= 256)
+                throw new models_1.ToolingError('STORE_ERROR', 'This conversation reached its saved request limit. Existing receipts are retained.');
+            const request = { requestId, messageId: requestId, agentUid, environmentUid, agentName: agent.name.slice(0, 300), message: draft.message, responseKind, ...(previousTask ? { taskRequestId: previousTask.requestId, continuationTaskUid: uuid(previousTask.task.taskUid) } : {}), ...(conversationKey ? { conversationKey } : {}),
+                handleId: previousTask?.handleId ?? 'host_' + hash(conversationKey ? [key, environmentUid, agentUid, conversationKey] : [key, environmentUid, agentUid]), createdAt: new Date().toISOString(), expiresAt: new Date(Date.now() + 86400000).toISOString(),
+                state: 'pending', sendAttempts: 0, submission: { attempts: 0, outcome: 'not-submitted' } };
+            state.requests[requestId] = request;
+            return view(request);
+        });
+    }
+    async list(input, signal) {
+        const { scope, key } = this.scope(input);
+        await this.verify(scope, signal);
+        return this.locked(key, async (state) => Object.values(state.requests).map(view));
+    }
+    async get(input, id, signal) {
+        const requestId = uuid(id);
+        const requests = await this.list(input, signal), request = requests.find(r => r.requestId === requestId);
+        if (!request)
+            throw new models_1.ToolingError('INVALID_REQUEST', 'No saved request with this ID belongs to this account and conversation.');
+        return request;
+    }
+    async submission(input, id, outcome, signal) {
+        if (!['attempted', 'acknowledged', 'unknown'].includes(outcome))
+            throw new models_1.ToolingError('INVALID_REQUEST', 'Invalid submission outcome.');
+        const { scope, key } = this.scope(input), requestId = uuid(id);
+        await this.verify(scope, signal);
+        return this.locked(key, async (state) => {
+            const r = state.requests[requestId];
+            if (!r)
+                throw new models_1.ToolingError('INVALID_REQUEST', 'Unknown saved request.');
+            r.submission.outcome = outcome;
+            if (outcome === 'attempted')
+                r.submission.attempts++;
+            return view(r);
+        });
+    }
+    async cancel(input, id, signal) {
+        const { scope, key } = this.scope(input), requestId = uuid(id);
+        await this.verify(scope, signal);
+        return this.locked(key, async (state) => {
+            const r = state.requests[requestId];
+            if (!r)
+                throw new models_1.ToolingError('INVALID_REQUEST', 'Unknown saved request.');
+            if (r.state !== 'pending' && r.state !== 'cancelled')
+                throw new models_1.ToolingError('INVALID_REQUEST', 'An accepted or completed message cannot be unsent. Read its saved status.');
+            r.state = 'cancelled';
+            r.reason = 'Cancelled before dispatch.';
+            return view(r);
+        });
+    }
+    async deliver(input, id, signal) {
+        const { scope, key } = this.scope(input), requestId = uuid(id);
+        await this.verify(scope, signal);
+        const owner = { pid: process.pid, token: (0, node_crypto_1.randomUUID)() };
+        const claimed = await this.locked(key, async (state) => {
+            signal?.throwIfAborted();
+            const r = state.requests[requestId];
+            if (!r)
+                throw new models_1.ToolingError('INVALID_REQUEST', 'Unknown saved request in this conversation.');
+            // Explicit recovery may repeat preparation when the durable marker proves no send began.
+            // Ambiguous transport failures remain uncertain and are never eligible.
+            if (r.state !== 'pending' && !(r.state === 'failed' && r.sendAttempts === 0))
+                return false;
+            if (Object.values(state.requests).some(other => other.requestId !== requestId && other.agentUid === r.agentUid && other.environmentUid === r.environmentUid && ['preparing', 'sending', 'uncertain'].includes(other.state))) {
+                throw new models_1.ToolingError('PROJECT_BUSY', 'This agent conversation has a running or uncertain delivery. Recover its existing request before sending another.');
+            }
+            r.state = 'preparing';
+            r.owner = owner;
+            delete r.reason;
+            return true;
+        });
+        if (claimed) {
+            const jobKey = key + requestId;
+            const job = this.run(scope, key, requestId, owner).catch(() => { });
+            this.jobs.set(jobKey, job);
+            void job.finally(() => { if (this.jobs.get(jobKey) === job)
+                this.jobs.delete(jobKey); });
+        }
+        return this.wait(scope, requestId, signal);
+    }
+    async wait(input, id, signal, waitMs = 25000) {
+        if (!Number.isInteger(waitMs) || waitMs < 0 || waitMs > 30000)
+            throw new models_1.ToolingError('INVALID_REQUEST', 'Wait must be between zero and 30 seconds.');
+        const { scope, key } = this.scope(input), requestId = uuid(id);
+        await this.verify(scope, signal);
+        const deadline = Date.now() + waitMs;
+        while (true) {
+            signal?.throwIfAborted();
+            const r = await this.locked(key, async (state) => { const value = state.requests[requestId]; if (!value)
+                throw new models_1.ToolingError('INVALID_REQUEST', 'Unknown saved request.'); return view(value); });
+            if (finished(r) || r.state === 'pending' || Date.now() >= deadline) {
+                await this.verify(scope, signal);
+                return r;
+            }
+            await sleep(Math.min(250, Math.max(1, deadline - Date.now())));
+        }
+    }
+    /** Reads/cancels only a task obtained from this chat's durable receipt; never sends a message. */
+    async task(input, id, action, signal) {
+        if (!['get', 'wait', 'cancel'].includes(action))
+            throw new models_1.ToolingError('INVALID_REQUEST', 'Choose get, wait or cancel.');
+        const { scope, key } = this.scope(input), r = await this.get(input, id, signal);
+        if (!r.task || !r.sessionUid)
+            throw new models_1.ToolingError('INVALID_REQUEST', 'This request has no accepted agent task.');
+        const taskUid = uuid(r.task.taskUid);
+        const result = await this.options.createDispatch(signal)({ action: action === 'cancel' ? 'agent-task-cancel' : action === 'wait' ? 'agent-task-wait' : 'agent-task-get',
+            backend: scope.backend, expectedAccount: scope.account, environmentUid: r.environmentUid, agentUid: r.agentUid, taskUid });
+        if (result.status !== 'success')
+            throw new models_1.ToolingError(result.error?.code || 'API_ERROR', result.summary);
+        const task = result.data;
+        if (task.taskUid !== taskUid || task.sessionUid !== r.sessionUid)
+            throw new models_1.ToolingError('API_ERROR', 'The task response does not match this saved request.');
+        return this.locked(key, async (state) => {
+            const record = state.requests[r.requestId];
+            // Older responses from concurrent reads must not overwrite newer task progress.
+            if (Number(task.eventCursor ?? 0) >= Number(record.task?.eventCursor ?? 0)) {
+                record.task = task;
+                record.receipt = { completedAt: new Date().toISOString(), sessionUid: r.sessionUid, message: JSON.stringify(task) };
+            }
+            return view(record);
+        });
+    }
+    async run(scope, key, id, owner) {
+        const controller = new AbortController(), timer = setTimeout(() => controller.abort(), 12 * 60_000);
+        const dispatch = this.options.createDispatch(controller.signal);
+        const update = async (fn) => this.locked(key, async (state) => {
+            const r = state.requests[id];
+            if (r?.owner?.token !== owner.token)
+                throw failStore();
+            fn(r);
+            return view(r);
+        });
+        let sending = false;
+        try {
+            const r = await update(() => { }), selection = { backend: scope.backend, environmentUid: r.environmentUid, agentUid: r.agentUid, expectedAccount: scope.account };
+            const prepared = await dispatch({ action: 'agent-session', ...selection, handleId: r.handleId });
+            if (prepared.status !== 'success')
+                throw new models_1.ToolingError(prepared.error?.code || 'API_ERROR', prepared.summary);
+            const sessionUid = uuid(prepared.data?.sessionUid);
+            await update(record => { record.sessionUid = sessionUid; });
+            const ready = await dispatch({ action: 'agent-readiness', ...selection, sessionUid, timeoutMs: this.options.readinessTimeoutMs ?? 300000 });
+            if (ready.status !== 'success')
+                throw new models_1.ToolingError(ready.error?.code || 'API_ERROR', ready.summary);
+            controller.signal.throwIfAborted();
+            await update(record => { record.state = 'sending'; record.sendAttempts = 1; });
+            sending = true;
+            const result = await dispatch({ action: 'agent-send', ...selection, ...(r.continuationTaskUid ? { taskUid: r.continuationTaskUid } : { sessionUid }), message: r.message, messageId: r.messageId, responseKind: r.responseKind ?? 'message' });
+            const reply = result.data;
+            await update(record => {
+                if (result.status === 'success' && reply?.responseKind === 'task' && r.responseKind === 'task' && reply.sessionUid === sessionUid && reply.taskUid) {
+                    uuid(reply.taskUid);
+                    record.state = 'delivered';
+                    record.task = reply;
+                    record.receipt = { completedAt: new Date().toISOString(), sessionUid, message: JSON.stringify(reply) };
+                }
+                else if (result.status === 'success' && reply?.responseKind === 'message' && typeof reply.message === 'string' && reply.message.trim() && reply.sessionUid === sessionUid) {
+                    record.state = 'delivered';
+                    record.receipt = { completedAt: new Date().toISOString(), sessionUid, message: reply.message };
+                }
+                else {
+                    record.state = result.effects || result.status === 'success' ? 'uncertain' : 'failed';
+                    if (record.state === 'failed')
+                        record.sendAttempts = 0; // AgentClient proved its preflight failed before a2a.send_message.
+                    record.reason = record.state === 'uncertain' ? 'The agent may have received this message. Resend is blocked.' : result.summary.slice(0, 2000);
+                }
+                delete record.owner;
+            });
+        }
+        catch (error) {
+            await update(record => {
+                record.state = sending ? 'uncertain' : 'failed';
+                record.reason = sending ? 'Dispatch did not produce a durable reply. Resend is blocked.' : error instanceof models_1.ToolingError ? error.message.slice(0, 2000) : 'Preparation failed before sending. No agent message was sent.';
+                delete record.owner;
+            }).catch(() => { });
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+}
+exports.AgentDelivery = AgentDelivery;

package/dist/vendor/devtools/shared/agentIcon.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.stillAgentPng = stillAgentPng;
+exports.inlineAgentAsset = inlineAgentAsset;
+/** APNG's default image is frame zero. Hosts choose it when reduced motion is enabled. */
+function stillAgentPng(bytes) {
+    if (!bytes.subarray(0, 8).equals(Buffer.from([137, 80, 78, 71, 13, 10, 26, 10])))
+        return bytes;
+    const parts = [bytes.subarray(0, 8)];
+    let offset = 8;
+    while (offset + 12 <= bytes.length) {
+        const end = offset + 12 + bytes.readUInt32BE(offset), type = bytes.toString('ascii', offset + 4, offset + 8);
+        if (end > bytes.length)
+            break;
+        if (!['acTL', 'fcTL', 'fdAT'].includes(type))
+            parts.push(bytes.subarray(offset, end));
+        offset = end;
+        if (type === 'IEND' && end === bytes.length)
+            return Buffer.concat(parts);
+    }
+    throw new Error('The agent icon is incomplete.');
+}
+/** Only bounded inline bytes cross into the host. Never fetch the icon URL. */
+function inlineAgentAsset(value) {
+    if (!value || typeof value !== 'object')
+        return null;
+    const icon = value, idle = icon.idle;
+    if (!['mask', 'color'].includes(icon.rendering) || !idle || !['image/png', 'image/svg+xml'].includes(idle.mime)
+        || typeof idle.bytes !== 'string' || !idle.bytes.length || idle.bytes.length > 699052
+        || idle.bytes.length % 4 !== 0 || !/^[A-Za-z0-9+/]*={0,2}$/.test(idle.bytes))
+        return null;
+    try {
+        const bytes = Buffer.from(idle.bytes, 'base64');
+        if (!bytes.length || bytes.length > 524288 || bytes.toString('base64') !== idle.bytes)
+            return null;
+        const uri = (data) => `data:${idle.mime};base64,${data.toString('base64')}`;
+        return { source: uri(bytes), stillSource: uri(idle.mime === 'image/png' ? stillAgentPng(bytes) : bytes),
+            rendering: icon.rendering, imageRendering: icon.imageRendering === 'pixelated' ? 'pixelated' : 'auto' };
+    }
+    catch {
+        return null;
+    }
+}

package/dist/vendor/devtools/shared/agents.js

@@ -7,6 +7,7 @@ const models_1 = require("./models.js");
 const session_1 = require("./session.js");
 const mcpTransport_1 = require("./mcpTransport.js");
 const agentReadiness_1 = require("./agentReadiness.js");
+const agentIcon_1 = require("./agentIcon.js");
 function isAgentAction(action) {
     return ['agents-list', 'agent-get', 'agent-session', 'agent-readiness', 'agent-send', 'agent-task-get', 'agent-task-wait', 'agent-task-cancel'].includes(action);
 }
@@ -17,12 +18,13 @@ function uuid(value) {
     return value.toLowerCase();
 }
 function text(value, limit = 16000) { return typeof value === 'string' ? value.replace(/[\u0000-\u0008\u000b\u000c\u000e-\u001f]/g, '').slice(0, limit) : ''; }
-function agent(row, environmentUid) {
+function agent(row, environmentUid, includeIcons = false) {
     if (!row || uuid(row.organization_environment_uid) !== environmentUid)
         throw new models_1.ToolingError('INVALID_REQUEST', 'This agent belongs to a different environment. Refresh the directory.');
     if (!text(row.name).trim())
         throw new models_1.ToolingError('API_ERROR', 'The agent directory returned an unnamed agent.');
     return { uid: uuid(row.uid), name: text(row.name, 300), description: text(row.description), environmentUid,
+        ...(includeIcons ? { icon: (0, agentIcon_1.inlineAgentAsset)(row.command_center_icon) } : {}),
         environmentName: text(row.organization_environment_name, 300), repositoryBranch: text(row.repository_branch, 300),
         runtimeReleaseUid: row.runtime_release_uid ? uuid(row.runtime_release_uid) : null,
         runtimeState: text(row.runtime_update?.state, 50) || 'unknown',
@@ -46,6 +48,8 @@ class AgentClient {
             this.options.signal?.throwIfAborted();
             if (!isAgentAction(input.action))
                 throw new models_1.ToolingError('INVALID_REQUEST', 'Unknown agent action.');
+            if ('includeIcons' in input && input.includeIcons !== undefined && typeof input.includeIcons !== 'boolean')
+                throw new models_1.ToolingError('INVALID_REQUEST', 'includeIcons must be a boolean.');
             const identity = await this.session.status(backend, true);
             if (!identity.authenticated || !identity.username)
                 throw new models_1.ToolingError('NOT_AUTHENTICATED', 'Sign in to MainSequence to use agents.');
@@ -54,12 +58,16 @@ class AgentClient {
             if (['agent-session', 'agent-readiness', 'agent-send', 'agent-task-get', 'agent-task-wait', 'agent-task-cancel'].includes(input.action) && !input.expectedAccount) {
                 throw new models_1.ToolingError('INVALID_REQUEST', 'Agent conversations must be bound to the account returned by discovery.');
             }
+            // The built-in session binds every request/retry to the selected account. Legacy
+            // custom agent transports retain their existing account-check contract.
+            const session = input.expectedAccount !== undefined && this.session.withAccount
+                ? await this.session.withAccount(backend, input.expectedAccount) : this.session;
             const timeouts = new Map();
             const client = new mcpTransport_1.McpTransport(message => {
                 const remaining = readinessDeadline === undefined ? undefined : Math.ceil(readinessDeadline - performance.now());
                 if (remaining !== undefined && remaining <= 0)
                     throw new models_1.ToolingError('PROCESS_TIMEOUT', 'The agent did not become ready in time. No message was sent. Try again.');
-                return this.session.request(backend, 'POST', '/mcp', message, message.method !== 'tools/call' || !['a2a.send_message', 'a2a.cancel_task'].includes(message.params?.name), remaining !== undefined ? { timeoutMs: Math.min(30000, remaining) }
+                return session.request(backend, 'POST', '/mcp', message, message.method !== 'tools/call' || !['a2a.send_message', 'a2a.cancel_task'].includes(message.params?.name), remaining !== undefined ? { timeoutMs: Math.min(30000, remaining) }
                     : message.method === 'tools/call' && timeouts.has(message.params?.name) ? { timeoutMs: timeouts.get(message.params.name) } : undefined);
             });
             await client.initialize();
@@ -96,15 +104,17 @@ class AgentClient {
                     || (input.search !== undefined && (typeof input.search !== 'string' || input.search.length > 2000)))
                     throw new models_1.ToolingError('INVALID_REQUEST', 'Search requires text, a limit of 1–100, and a nonnegative offset.');
                 const search = input.search?.trim();
-                const page = search ? await call('agent.search', { organization_environment_uid: environmentUid, q: search, limit })
-                    : await call('agent.list', { organization_environment_uid: environmentUid, limit, offset });
+                const icons = input.includeIcons ? { include_icons: true } : {};
+                const page = search ? await call('agent.search', { organization_environment_uid: environmentUid, q: search, limit, ...icons })
+                    : await call('agent.list', { organization_environment_uid: environmentUid, limit, offset, ...icons });
                 if (!Array.isArray(page.results) || (!search && (!Number.isInteger(page.count) || page.count < 0)))
                     throw new models_1.ToolingError('API_ERROR', 'The platform returned invalid agent pagination.');
-                data = { account: identity.username, results: page.results.map((row) => agent(row, environmentUid)), count: search ? page.results.length : page.count, offset: search ? 0 : offset, semantic: !!search };
+                data = { account: identity.username, results: page.results.map((row) => agent(row, environmentUid, input.includeIcons)), count: search ? page.results.length : page.count, offset: search ? 0 : offset, semantic: !!search };
             }
             else {
                 const agentUid = uuid(input.agentUid);
-                const selected = agent(await call('agent.get', { agent_uid: agentUid }), environmentUid);
+                const includeIcons = input.action === 'agent-get' && input.includeIcons === true;
+                const selected = agent(await call('agent.get', { agent_uid: agentUid, ...(includeIcons ? { include_icons: true } : {}) }), environmentUid, includeIcons);
                 if (selected.uid !== agentUid)
                     throw new models_1.ToolingError('API_ERROR', 'The platform returned another agent.');
                 const task = async (taskUid) => {
@@ -164,6 +174,7 @@ class AgentClient {
                         ...(resolved.bound_handle?.handle_unique_id ? { handleId: text(resolved.bound_handle.handle_unique_id, 255) } : {}) };
                 }
                 else if (input.action === 'agent-send') {
+                    const messageId = input.messageId === undefined ? (0, node_crypto_1.randomUUID)() : uuid(input.messageId);
                     if (typeof input.message !== 'string' || !input.message.trim() || input.message.length > 64000)
                         throw new models_1.ToolingError('INVALID_REQUEST', 'Enter a message of 1–64000 characters.');
                     if (!['message', 'task'].includes(input.responseKind) || !selected.responseKinds.includes(input.responseKind))
@@ -194,7 +205,7 @@ class AgentClient {
                             : input.sessionUid ? { session_uid: uuid(input.sessionUid) } : { handle_unique_id: input.handleId });
                         await ready(uuid(resolved.uid));
                     }
-                    const reply = await call('a2a.send_message', { ...target, message: input.message, message_id: (0, node_crypto_1.randomUUID)(), response_kind: input.responseKind,
+                    const reply = await call('a2a.send_message', { ...target, message: input.message, message_id: messageId, response_kind: input.responseKind,
                         ...(input.responseKind === 'task' ? { completion_policy: 'poll' } : {}) }, true);
                     if (uuid(reply.agent_uid) !== agentUid || reply.response_kind !== input.responseKind || (input.sessionUid && uuid(reply.agent_session_uid) !== uuid(input.sessionUid)))
                         throw new models_1.ToolingError('API_ERROR', 'The agent response does not match this conversation.');