@amaster.ai/dsh-a2a 0.1.34 → 0.1.36

package/lib/inbox.js

@@ -1,17 +1,31 @@
 /** Native DSH input ownership with standard A2A task delivery. */
 import { randomUUID } from 'node:crypto';
-import { Message, TaskState } from '@a2a-js/sdk';
+import { Message, Role, TaskState } from '@a2a-js/sdk';
+import { RequestMalformedError } from '@a2a-js/sdk/errors';
 import { AgentEvent, ServerCallContext, STATE_HEADERS_KEY, } from '@a2a-js/sdk/server';
 import { createUserMessage } from '@deepseek-ai/dsh-llm/message';
+import { InboxChanges } from './inbox-changes.js';
 import { commitInboxInput, markInboxInputPending } from './task-store.js';
 import { agentTextMessage, SessionTranslator, terminalStatusUpdate } from './translator.js';
-export const INBOX_EXTENSION = 'https://github.com/TGYD-helige/dsh-plugins/blob/main/docs/protocol/inbox-v1.md';
+export const INBOX_EXTENSION = 'https://github.com/TGYD-helige/dsh-plugins/blob/main/packages/dsh-a2a/README.md';
 const RETAINED_INPUTS = `${INBOX_EXTENSION}#retained-inputs`;
+export function validateInboxPage(page) {
+    if (page === undefined)
+        return;
+    if (!page ||
+        typeof page !== 'object' ||
+        Array.isArray(page) ||
+        (page.pageSize !== undefined &&
+            (!Number.isInteger(page.pageSize) || page.pageSize < 1 || page.pageSize > 100)) ||
+        (page.pageToken !== undefined && typeof page.pageToken !== 'string'))
+        throw new RequestMalformedError('pageSize must be an integer from 1 to 100 and pageToken must be a string.');
+}
 export class NativeInbox {
     ctx;
     bridge;
     store;
     retainPending;
+    changes;
     contexts = new Map();
     resolving = new Map();
     stopping = false;
@@ -19,17 +33,20 @@ export class NativeInbox {
     preadmitted = new WeakMap();
     server;
     persistence;
-    constructor(ctx, bridge, store, retainPending = false) {
+    constructor(ctx, bridge, store, retainPending = false, notifications = false) {
         this.ctx = ctx;
         this.bridge = bridge;
         this.store = store;
         this.retainPending = retainPending;
+        this.changes = new InboxChanges(ctx, (contextId) => this.contexts.has(contextId), notifications);
         bridge.inbox = this;
         this.persistence = ctx.get('sessionPersistence');
         if (retainPending)
             ctx.on('session/event', (session, event) => {
                 const run = this.contexts.get(session.id);
-                if (!run || event.type !== 'agent/inbox/spliced' || this.stopping || this.unloading())
+                // Shutdown drains in-flight commits before disposal; those splices must
+                // still update retained input or recovery would see history without a task.
+                if (!run || event.type !== 'agent/inbox/spliced' || this.unloading())
                     return;
                 try {
                     const splice = event.data;
@@ -110,6 +127,236 @@ export class NativeInbox {
     async resolve(contextId) {
         return (await this.context(contextId)).entry.handle.agent;
     }
+    async get(contextId, page) {
+        validateInboxPage(page);
+        let offset = 0;
+        let cursorVersion;
+        if (page?.pageToken) {
+            try {
+                const cursor = JSON.parse(Buffer.from(page.pageToken, 'base64url').toString('utf8'));
+                if (!Array.isArray(cursor) ||
+                    cursor.length !== 3 ||
+                    cursor[0] !== contextId ||
+                    !Number.isSafeInteger(cursor[1]) ||
+                    !Number.isSafeInteger(cursor[2]) ||
+                    cursor[2] < 0)
+                    throw new Error();
+                [, cursorVersion, offset] = cursor;
+            }
+            catch {
+                throw new RequestMalformedError('Invalid inbox page token.');
+            }
+        }
+        const run = await this.context(contextId);
+        const agent = run.entry.handle.agent;
+        const version = agent.session.seq - 1;
+        const steps = agent.inbox.nextStep;
+        const turns = agent.inbox.nextTurn;
+        const totalSize = steps.length + turns.length;
+        if ((cursorVersion !== undefined && cursorVersion !== version) || offset > totalSize)
+            throw new RequestMalformedError('Inbox page is stale; read again without pageToken.');
+        const limit = page === undefined ? totalSize : (page.pageSize ?? 50);
+        const entry = (message) => {
+            const task = this.owner(run, message);
+            const protocol = task
+                ? this.protocolMessage(run, task, message)
+                : Message.fromJSON({
+                    messageId: message.id,
+                    contextId,
+                    role: 'ROLE_USER',
+                    parts: message.content
+                        .filter((block) => block.type === 'text')
+                        .map((block) => ({ text: block.text })),
+                });
+            return {
+                id: message.id,
+                message: Message.toJSON(protocol),
+                editable: message.source.kind === 'a2a',
+            };
+        };
+        const nextStep = [];
+        const nextTurn = [];
+        let count = 0;
+        let bytes = 2;
+        for (let index = offset; index < totalSize && count < limit; index++) {
+            if (page !== undefined && count && bytes >= 1024 * 1024)
+                break;
+            const step = index < steps.length;
+            const item = entry(step ? steps[index] : turns[index - steps.length]);
+            if (page !== undefined) {
+                const size = Buffer.byteLength(JSON.stringify(item)) + (count ? 1 : 0);
+                // Keep each A2A Message intact, allowing one oversized item to make progress.
+                if (count && bytes + size > 1024 * 1024)
+                    break;
+                bytes += size;
+            }
+            (step ? nextStep : nextTurn).push(item);
+            count++;
+        }
+        return {
+            contextId,
+            version,
+            nextTurn,
+            nextStep,
+            totalSize,
+            nextPageToken: offset + count < totalSize
+                ? Buffer.from(JSON.stringify([contextId, version, offset + count])).toString('base64url')
+                : '',
+        };
+    }
+    async editQueue(contextId, edit, page) {
+        validateInboxPage(page);
+        if (page?.pageToken)
+            throw new RequestMalformedError('pageToken is only supported by inbox get.');
+        const run = await this.context(contextId);
+        const operation = run.admissionTail.then(async () => {
+            if (this.stopping || this.bridge.isClearing(contextId))
+                throw new RequestMalformedError('Inbox is unloading or clearing.');
+            await edit(run);
+            await this.flush(run.entry.handle.agent.session);
+        });
+        run.admissionTail = operation.catch(() => { });
+        await operation;
+        return this.get(contextId, page);
+    }
+    queued(run, id) {
+        const agent = run.entry.handle.agent;
+        const target = agent.inbox.nextTurn.some((message) => message.id === id)
+            ? 'next-turn'
+            : 'next-step';
+        const items = target === 'next-turn' ? agent.inbox.nextTurn : agent.inbox.nextStep;
+        const index = items.findIndex((message) => message.id === id);
+        const message = items[index];
+        if (!message)
+            throw new RequestMalformedError('Input is no longer pending.');
+        return { agent, target, items, index, message };
+    }
+    async update(contextId, id, message, page) {
+        return this.editQueue(contextId, async (run) => {
+            const queued = this.queued(run, id);
+            const task = this.owner(run, queued.message);
+            if (queued.message.source.kind !== 'a2a' || !task)
+                throw new RequestMalformedError('Only task-attributed A2A input can be edited.');
+            const original = this.protocolMessage(run, task, queued.message);
+            if (message.messageId !== original.messageId ||
+                message.taskId !== original.taskId ||
+                message.contextId !== contextId ||
+                message.role !== Role.ROLE_USER ||
+                !message.parts.length ||
+                message.parts.some((part) => !part.content))
+                throw new RequestMalformedError('A user Message with unchanged messageId, taskId and contextId is required.');
+            const content = await this.content(message, contextId);
+            if (this.stopping ||
+                this.bridge.isClearing(contextId) ||
+                this.queued(run, id).message !== queued.message)
+                throw new RequestMalformedError('Input changed while editing.');
+            await this.ctx.serial('a2a/before-followup', {
+                agent: queued.agent,
+                contextId,
+                taskId: task.task.id,
+                a2aMessage: message,
+                dshMessageId: id,
+                requestHeaders: task.headers.get(id),
+                signal: task.controller.signal,
+            });
+            if (this.stopping ||
+                this.bridge.isClearing(contextId) ||
+                this.queued(run, id).message !== queued.message)
+                throw new RequestMalformedError('Input changed while editing.');
+            const replacement = {
+                ...queued.message,
+                content,
+                source: {
+                    ...queued.message.source,
+                    message: JSON.stringify(Message.toJSON(message)),
+                },
+            };
+            if (!queued.agent.inbox.replace(queued.message.id, replacement))
+                throw new RequestMalformedError('Input has already been claimed.');
+            task.task.history = task.task.history.map((item) => item.messageId === original.messageId
+                ? markInboxInputPending(structuredClone(message))
+                : item);
+            await this.checkpoint(task.task, task.context);
+        }, page);
+    }
+    async move(contextId, id, index, page) {
+        return this.editQueue(contextId, (run) => this.reorder(this.queued(run, id), index), page);
+    }
+    reorder(queued, index) {
+        if (!Number.isInteger(index) || index < 0 || index >= queued.items.length)
+            throw new RequestMalformedError('index must address the same pending list.');
+        if (index === queued.index)
+            return;
+        const start = Math.min(queued.index, index);
+        const items = queued.items.slice(start, Math.max(queued.index, index) + 1);
+        items.splice(queued.index - start, 1);
+        items.splice(index - start, 0, queued.message);
+        // One atomic native splice records only the affected interval.
+        queued.agent.inbox.splice(queued.target, start, items.length, items);
+    }
+    async removed(run, messages) {
+        const removed = new Map();
+        for (const message of messages) {
+            const task = this.owner(run, message);
+            if (!task || message.source.kind !== 'a2a')
+                continue;
+            let ids = removed.get(task);
+            if (!ids) {
+                ids = new Set();
+                removed.set(task, ids);
+            }
+            ids.add(Message.fromJSON(JSON.parse(message.source.message)).messageId);
+        }
+        // One queue durability barrier precedes all terminal task publications.
+        await this.flush(run.entry.handle.agent.session);
+        const pending = new Set(this.pending(run).map((message) => this.owner(run, message)));
+        const entries = removed.entries();
+        const errors = [];
+        await Promise.all(Array.from({ length: Math.min(4, removed.size) }, async () => {
+            for (const [task, ids] of entries) {
+                if (task.settled)
+                    continue;
+                try {
+                    task.task.history = task.task.history.filter((message) => !ids.has(message.messageId));
+                    if (run.active !== task && !run.claimed.has(task) && !pending.has(task))
+                        await this.cancelTask(run, task, false);
+                    else
+                        await this.checkpoint(task.task, task.context);
+                }
+                catch (error) {
+                    if (!errors.length)
+                        errors.push(error);
+                }
+            }
+        }));
+        if (errors.length)
+            throw errors[0];
+    }
+    async remove(contextId, id, page) {
+        return this.editQueue(contextId, async (run) => {
+            const { agent, message } = this.queued(run, id);
+            agent.inbox.remove(message.id);
+            await this.removed(run, [message]);
+        }, page);
+    }
+    async clearPending(contextId, page) {
+        return this.editQueue(contextId, async (run) => {
+            const messages = this.pending(run);
+            run.entry.handle.agent.inbox.clear();
+            await this.removed(run, messages);
+        }, page);
+    }
+    async executePending(contextId, id, page) {
+        return this.editQueue(contextId, async (run) => {
+            if (id !== undefined) {
+                const queued = this.queued(run, id);
+                if (queued.target !== 'next-turn')
+                    throw new RequestMalformedError('Execute selects next-turn input; use steer for next-step input.');
+                this.reorder(queued, 0);
+            }
+            await this.wake(contextId);
+        }, page);
+    }
     async enqueue(taskId, message, options = {}) {
         if (this.stopping)
             throw new Error('Native inbox is unloading.');
@@ -138,7 +385,7 @@ export class NativeInbox {
         const items = from === 'next-turn' ? agent.inbox.nextTurn : agent.inbox.nextStep;
         const index = items.findIndex((item) => item.id === message.id);
         if (index < 0)
-            throw new Error('Queued input has already been claimed.');
+            throw new RequestMalformedError('Queued input has already been claimed.');
         agent.session.append('agent/inbox/spliced', {
             target: from,
             start: index,
@@ -164,10 +411,10 @@ export class NativeInbox {
         const target = run.tasks.get(taskId);
         const message = agent.inbox.nextTurn.find((item) => item.id === messageId);
         if (message?.source.kind !== 'a2a')
-            throw new Error('Queued input has already been claimed.');
+            throw new RequestMalformedError('Queued input has already been claimed.');
         const source = run.tasks.get(message.source.taskId);
         if (!target || !source)
-            throw new Error('Promotion requires live source and target tasks.');
+            throw new RequestMalformedError('Promotion requires live source and target tasks.');
         const valid = () => !this.stopping &&
             !this.bridge.isClearing(run.entry.sessionId) &&
             !target.settled &&
@@ -181,7 +428,7 @@ export class NativeInbox {
             !run.claimed.has(source) &&
             agent.inbox.nextTurn.some((item) => item === message);
         if (!valid())
-            throw new Error('Promotion requires an unclaimed independent input and an active target.');
+            throw new RequestMalformedError('Promotion requires an unclaimed independent input and an active target.');
         const original = Message.fromJSON(JSON.parse(message.source.message));
         original.taskId = taskId;
         original.referenceTaskIds = [...new Set([...original.referenceTaskIds, source.task.id])];
@@ -201,11 +448,11 @@ export class NativeInbox {
         try {
             await this.checkpoint(target.task, target.context);
             if (!valid())
-                throw new Error('Promotion raced input consumption or task settlement.');
+                throw new RequestMalformedError('Promotion raced input consumption or task settlement.');
             target.task.history = [...target.task.history, markInboxInputPending(original)];
             target.headers.set(message.id, source.headers.get(message.id));
             if (!agent.inbox.replace(message.id, promoted))
-                throw new Error('Queued input has already been claimed.');
+                throw new RequestMalformedError('Queued input has already been claimed.');
             this.moveInput(agent, promoted, 'next-step');
             try {
                 await this.flush(agent.session);
@@ -244,7 +491,7 @@ export class NativeInbox {
             if (this.stopping ||
                 this.contexts.get(run.entry.sessionId) !== run ||
                 this.bridge.isClearing(run.entry.sessionId))
-                throw new Error('Promotion was interrupted by context disposal.');
+                throw new RequestMalformedError('Promotion was interrupted by context disposal.');
             source.controller.abort();
             try {
                 await this.checkpoint(target.task, target.context);
@@ -259,6 +506,59 @@ export class NativeInbox {
             this.settle(run, target);
         }
     }
+    async resume(contextId, taskId) {
+        const context = new ServerCallContext();
+        const previous = await this.store.load(taskId, context);
+        if (!previous || previous.contextId !== contextId || !this.terminal(previous))
+            throw new Error('Resume requires a terminal retained task.');
+        const retained = previous.metadata?.[RETAINED_INPUTS];
+        if (typeof retained !== 'string')
+            throw new Error('Task has no retained input to resume.');
+        const inputs = JSON.parse(retained);
+        if (!inputs.length)
+            throw new Error('Task has no retained input to resume.');
+        const run = await this.context(contextId, context);
+        const id = randomUUID();
+        const replacement = {
+            ...previous,
+            id,
+            status: {
+                state: TaskState.TASK_STATE_SUBMITTED,
+                timestamp: new Date().toISOString(),
+                message: undefined,
+            },
+            history: [],
+            metadata: { ...previous.metadata },
+        };
+        delete replacement.metadata[RETAINED_INPUTS];
+        const retainedInputs = inputs.map((input) => {
+            if (input.message.source.kind !== 'a2a')
+                throw new Error('Retained input has invalid task ownership.');
+            const original = Message.fromJSON(JSON.parse(input.message.source.message));
+            original.taskId = id;
+            original.referenceTaskIds = [...new Set([...original.referenceTaskIds, taskId])];
+            replacement.history.push(markInboxInputPending(original));
+            return {
+                ...input,
+                message: {
+                    ...input.message,
+                    source: {
+                        ...input.message.source,
+                        taskId: id,
+                        message: JSON.stringify(Message.toJSON(original)),
+                    },
+                },
+            };
+        });
+        await this.checkpoint(replacement, context);
+        for (const [index, input] of retainedInputs.entries()) {
+            if (this.pending(run).some((pending) => pending.id === input.message.id))
+                run.entry.handle.agent.inbox.remove(input.message.id);
+            run.entry.handle.agent.send(input.message, input.target, index === retainedInputs.length - 1);
+        }
+        this.restoreTask(run, replacement, context);
+        return id;
+    }
     /** Repair only an incomplete ownership move, never an ordinary DSH claim. */
     async recoverPromotions(run, context) {
         const agent = run.entry.handle.agent;
@@ -335,9 +635,11 @@ export class NativeInbox {
                 const retained = task.metadata?.[RETAINED_INPUTS];
                 if (typeof retained !== 'string')
                     continue;
-                snapshots.push(task);
+                // Terminal snapshots belong to explicit resume(); do not consume their
+                // retained metadata during ordinary context recovery.
                 if (this.terminal(task))
                     continue;
+                snapshots.push(task);
                 for (const input of JSON.parse(retained)) {
                     const { message } = input;
                     if (message.source.kind !== 'a2a' || message.source.taskId !== task.id)
@@ -348,18 +650,87 @@ export class NativeInbox {
             }
             pageToken = page.nextPageToken;
         } while (pageToken);
-        for (const { message, target } of inputs.sort((a, b) => a.position - b.position)) {
+        const queuedAtOf = (input) => input.message.source.kind === 'a2a' ? (input.message.source.queuedAt ?? 0) : 0;
+        // Equal per-task positions must not inherit the store's timestamp ordering.
+        const ordered = inputs.sort((a, b) => a.position - b.position || queuedAtOf(a) - queuedAtOf(b));
+        const destinationIds = {
+            'next-step': new Set(agent.inbox.nextStep.map((message) => message.id)),
+            'next-turn': new Set(agent.inbox.nextTurn.map((message) => message.id)),
+        };
+        const existingIds = new Set([...destinationIds['next-step'], ...destinationIds['next-turn']]);
+        const byPosition = new Map();
+        for (const input of ordered) {
+            const positions = byPosition.get(input.target) ?? new Map();
+            const group = positions.get(input.position) ?? [];
+            group.push(input);
+            positions.set(input.position, group);
+            byPosition.set(input.target, positions);
+        }
+        const nextInGroup = new Map();
+        const nextPosition = new Map();
+        for (const [target, positions] of byPosition) {
+            nextInGroup.set(target, new Map());
+            nextPosition.set(target, new Map());
+            const orderedPositions = [...positions.keys()].sort((a, b) => a - b);
+            for (const position of orderedPositions) {
+                const group = positions.get(position);
+                const stack = [];
+                for (let index = 0; index < group.length; index++) {
+                    while (stack.length && queuedAtOf(group[stack.at(-1)]) <= queuedAtOf(group[index]))
+                        stack.pop();
+                    if (stack.length)
+                        nextInGroup.get(target).set(group[index].message.id, group[stack.at(-1)]);
+                    stack.push(index);
+                }
+            }
+            for (let index = orderedPositions.length - 1; index >= 0; index--) {
+                const position = orderedPositions[index];
+                const next = orderedPositions[index + 1];
+                nextPosition.get(target).set(position, next);
+            }
+        }
+        const laterFor = (input) => {
+            let candidate = nextInGroup.get(input.target)?.get(input.message.id);
+            while (candidate && !destinationIds[input.target].has(candidate.message.id))
+                candidate = nextInGroup.get(input.target)?.get(candidate.message.id);
+            if (candidate)
+                return candidate;
+            let position = nextPosition.get(input.target)?.get(input.position);
+            const queuedAt = queuedAtOf(input);
+            while (position !== undefined) {
+                const candidate = byPosition
+                    .get(input.target)
+                    ?.get(position)
+                    ?.find((item) => queuedAtOf(item) > queuedAt && destinationIds[input.target].has(item.message.id));
+                if (candidate)
+                    return candidate;
+                position = nextPosition.get(input.target)?.get(position);
+            }
+            return undefined;
+        };
+        for (const input of ordered) {
+            const { message, target } = input;
             if (message.source.kind !== 'a2a')
                 continue;
-            const existing = this.pending(run).find((pending) => pending.id === message.id);
-            if (existing) {
-                agent.inbox.replace(message.id, message);
-                const destination = target === 'next-step' ? agent.inbox.nextStep : agent.inbox.nextTurn;
-                if (!destination.some((pending) => pending.id === message.id))
+            const destination = target === 'next-step' ? agent.inbox.nextStep : agent.inbox.nextTurn;
+            if (existingIds.has(message.id)) {
+                if (!destinationIds[target].has(message.id)) {
                     this.moveInput(agent, message, target);
+                    const from = target === 'next-step' ? 'next-turn' : 'next-step';
+                    destinationIds[from].delete(message.id);
+                    destinationIds[target].add(message.id);
+                }
+                continue;
             }
-            else
-                agent.inbox.append(target, message);
+            // Keep the recovered public order; only an interrupted earlier input is
+            // inserted before the first retained message queued after it.
+            const later = laterFor(input);
+            const insertAt = later
+                ? destination.findIndex((pending) => pending.id === later.message.id)
+                : destination.length;
+            agent.inbox.splice(target, Math.min(insertAt, destination.length), 0, [message]);
+            existingIds.add(message.id);
+            destinationIds[target].add(message.id);
         }
         if (!snapshots.length)
             return;
@@ -381,14 +752,21 @@ export class NativeInbox {
                 const { entry } = await this.bridge.ensureTask(randomUUID(), contextId);
                 const run = {
                     entry,
+                    paused: false,
                     tasks: new Map(),
                     claimed: new Set(),
                     admissions: new Set(),
+                    commits: new Set(),
                     admissionTail: Promise.resolve(),
                     promotions: new Map(),
                     rolledBack: new Set(),
                     retained: { 'next-step': [], 'next-turn': [] },
                 };
+                const pause = [...run.entry.handle.agent.session.snapshotEvents()]
+                    .reverse()
+                    .find((event) => event.type === 'agent/inbox/paused');
+                if (pause)
+                    run.paused = pause.data.paused;
                 await this.recoverRetained(run, context);
                 await this.recoverPromotions(run, context);
                 const snapshots = new Map();
@@ -471,8 +849,15 @@ export class NativeInbox {
             console.error('[dsh-a2a] inbox observer failed:', error);
         }
     }
-    flush(session) {
-        return this.ctx.parallel('session/flush', session);
+    async flush(session) {
+        // Core teardown closes handles concurrently; the service-wide barrier drains only live writers.
+        if (this.stopping && this.persistence)
+            return this.persistence.flush();
+        const sessions = this.ctx.get('sessions');
+        if (sessions)
+            await sessions.flush(session);
+        else
+            await this.ctx.parallel('session/flush', session);
     }
     checkpoint(task, context) {
         return this.store.checkpoint
@@ -607,6 +992,8 @@ export class NativeInbox {
             ].includes(task.status.state));
     }
     async admit(run, task, a2aMessage, context, target, wakeup, accepted) {
+        if (run.paused)
+            throw new Error('Inbox is paused.');
         if (target === 'next-step' && run.active !== task)
             throw new Error('Steering must address an active task.');
         const duplicate = () => [...run.tasks.values()].some((owned) => owned.task.history.some((message) => message.messageId === a2aMessage.messageId));
@@ -654,11 +1041,21 @@ export class NativeInbox {
                 ? history
                 : [...history, markInboxInputPending(a2aMessage)];
             await this.checkpoint({ ...task.task, history: acceptedHistory }, context);
-            abort.signal.throwIfAborted();
+            // The durable checkpoint is the admission commit point. A later abort may
+            // reject the caller, but must not strand history without its native input.
             task.task.history = acceptedHistory;
             task.headers.set(message.id, headers);
             accepted?.();
+            if (this.stopping && run.entry.borrowed) {
+                if (this.retainPending && !task.discardInput && !run.discardInput)
+                    run.retained[target].push(structuredClone(message));
+                return;
+            }
             run.entry.handle.agent.send(message, target, wakeup);
+            // Explicit discard markers survive cancel/clear state resets. Disposal
+            // and retain-pending shutdown deliberately leave them unset.
+            if (task.discardInput || run.discardInput)
+                run.entry.handle.agent.inbox.remove(message.id);
             this.observeInput('admitted', run, message);
             await this.flush(run.entry.handle.agent.session);
             void this.ctx
@@ -681,6 +1078,10 @@ export class NativeInbox {
                     onAbort();
             }),
         ]);
+        // Admission order follows the abortable wait, but shutdown separately drains
+        // every full commit so an interrupted caller cannot strand durable input.
+        run.commits.add(work);
+        void work.finally(() => run.commits.delete(work)).catch(() => { });
         run.admissionTail = admitted.catch(() => { });
         try {
             await admitted;
@@ -818,6 +1219,8 @@ export class NativeInbox {
         const run = this.contexts.get(detail.agent.session.id);
         if (!run)
             return;
+        if (run.paused)
+            throw new Error('Inbox is paused.');
         if (this.stopping)
             throw new Error('Inbox is unloading.');
         for (let index = detail.messages.length - 1; index >= 0; index--) {
@@ -846,8 +1249,6 @@ export class NativeInbox {
             if (run.rolledBack.delete(message.source.promotionId))
                 detail.messages.splice(index, 1);
         }
-        if (!run.active && detail.messages.some((message) => !this.owner(run, message)))
-            throw new Error('Native host input requires task-attributed a2aInbox.enqueue().');
         // Restarted steering and an ordinary queued turn may be claimed together by the core.
         // Requeue other owners before committing any user message, keeping task lifecycles separate.
         const owner = detail.messages.find((message) => message.source.kind === 'a2a');
@@ -875,6 +1276,7 @@ export class NativeInbox {
             if (run.active && run.active !== task)
                 throw new Error('A model step cannot consume inputs from different A2A tasks.');
             this.select(run, task);
+            task.claimedInputs = detail.messages.filter((candidate) => this.owner(run, candidate) === task);
             const selectedAt = task.selectedAt.get(message.id) ?? Date.now();
             const timing = { selectedAt, turn: detail.turn, step: detail.step };
             try {
@@ -914,6 +1316,12 @@ export class NativeInbox {
             return true;
         }
         const task = run.active;
+        if (event.type === 'turn/end' && run.paused) {
+            // Paused turns must never discard retained input, including a driver
+            // started accidentally before wake(). Requeue before any failure cleanup.
+            this.requeueClaimed(run);
+            return true;
+        }
         if (event.type === 'turn/end') {
             if (!this.stopping && ['error', 'blocked', 'aborted'].includes(event.data.reason.kind))
                 for (const owner of run.claimed)
@@ -923,6 +1331,8 @@ export class NativeInbox {
         }
         if (!task)
             return true;
+        if (event.type === 'turn/end')
+            task.claimedInputs = undefined;
         if (task.settled) {
             if (event.type === 'turn/end')
                 run.active = undefined;
@@ -1091,9 +1501,10 @@ export class NativeInbox {
         }
         return undefined;
     }
-    async cancelTask(run, task) {
+    async cancelTask(run, task, flush = true) {
         const contextId = run.entry.sessionId;
         const taskId = task.task.id;
+        task.discardInput = true;
         this.discard(run, taskId);
         task.controller.abort();
         task.settled = true;
@@ -1105,7 +1516,8 @@ export class NativeInbox {
         }
         try {
             try {
-                await this.flush(run.entry.handle.agent.session);
+                if (flush)
+                    await this.flush(run.entry.handle.agent.session);
             }
             finally {
                 await this.checkpoint(structuredClone(task.task), task.context);
@@ -1116,11 +1528,64 @@ export class NativeInbox {
             task.finish();
         }
     }
+    requeueClaimed(run) {
+        const task = run.active;
+        if (!task?.claimedInputs)
+            return;
+        const committed = new Set(run.entry.handle.agent.session
+            .snapshotEvents()
+            .flatMap((event) => (event.type === 'user/message' ? [event.data.id] : [])));
+        for (const message of [...task.claimedInputs].reverse()) {
+            if (message.source.kind !== 'a2a' || committed.has(message.id))
+                continue;
+            if (!this.pending(run).some((pending) => pending.id === message.id))
+                run.entry.handle.agent.inbox.prepend(message.source.target, message);
+        }
+        task.claimedInputs = undefined;
+    }
+    async pause(contextId) {
+        const run = await this.context(contextId);
+        if (run.paused)
+            return;
+        run.paused = true;
+        run.entry.handle.agent.session.append('agent/inbox/paused', { paused: true });
+        for (const admission of run.admissions)
+            admission.abort();
+        run.entry.handle.agent.cancel({ kind: 'user' }, { keepInbox: true });
+        await run.entry.handle.agent.whenIdle();
+        this.requeueClaimed(run);
+    }
+    async wake(contextId) {
+        const run = await this.context(contextId);
+        const agent = run.entry.handle.agent;
+        const pending = this.pending(run);
+        run.paused = false;
+        agent.session.append('agent/inbox/paused', { paused: false });
+        const target = agent.inbox.nextTurn.length ? 'next-turn' : 'next-step';
+        const items = target === 'next-turn' ? agent.inbox.nextTurn : agent.inbox.nextStep;
+        const input = items.at(-1);
+        if (input) {
+            // Agent.send is the public wake seam; reinsert only the tail, without canceling it.
+            agent.session.append('agent/inbox/spliced', {
+                target,
+                start: items.length - 1,
+                removedCount: 1,
+                inserted: [],
+            });
+            agent.send(input, target, true);
+        }
+        const taskIds = [
+            ...new Set(pending.flatMap((input) => (input.source.kind === 'a2a' ? [input.source.taskId] : []))),
+        ];
+        this.observe('woken', run, { taskIds });
+        return taskIds;
+    }
     async clear(contextId) {
         await this.resolving.get(contextId);
         const run = this.contexts.get(contextId);
         if (!run)
             return;
+        run.discardInput = true;
         const taskIds = [
             ...new Set([...run.tasks.values()]
                 .filter((task) => !task.settled)
@@ -1165,27 +1630,69 @@ export class NativeInbox {
         this.contexts.delete(session.id);
     }
     shutdown() {
+        this.changes.close();
         if (this.shutdownPromise)
             return this.shutdownPromise;
         this.stopping = true;
+        const failures = [];
+        const borrowed = new Set();
+        const detachBorrowed = () => {
+            for (const run of this.contexts.values()) {
+                if (!run.entry.borrowed)
+                    continue;
+                borrowed.add(run);
+                this.contexts.delete(run.entry.sessionId);
+                // Freeze retention before detaching owned input from a still-live native driver.
+                try {
+                    const agent = run.entry.handle.agent;
+                    if (run.active) {
+                        agent.cancel({ kind: 'disposed' }, { keepInbox: true });
+                        run.active = undefined;
+                    }
+                    for (const target of ['next-step', 'next-turn']) {
+                        const items = target === 'next-step' ? agent.inbox.nextStep : agent.inbox.nextTurn;
+                        if (!items.some((message) => message.source.kind === 'a2a'))
+                            continue;
+                        agent.session.append('agent/inbox/spliced', {
+                            target,
+                            start: 0,
+                            removedCount: items.length,
+                            inserted: items.filter((message) => message.source.kind !== 'a2a'),
+                        });
+                    }
+                }
+                catch (error) {
+                    failures.push(error);
+                }
+            }
+        };
+        detachBorrowed();
         this.shutdownPromise = (async () => {
-            const failures = [];
             await Promise.allSettled([...this.resolving.values()]);
-            const cancellations = [...this.contexts.values()].flatMap((run) => [...run.tasks.values()].flatMap((task) => (task.cancellation ? [task.cancellation] : [])));
+            detachBorrowed();
+            const runs = [...borrowed, ...this.contexts.values()];
+            const cancellations = runs.flatMap((run) => [...run.tasks.values()].flatMap((task) => (task.cancellation ? [task.cancellation] : [])));
             for (const outcome of await Promise.allSettled(cancellations))
                 if (outcome.status === 'rejected')
                     failures.push(outcome.reason);
-            for (const run of this.contexts.values()) {
+            for (const run of runs) {
                 for (const admission of run.admissions)
                     admission.abort();
+                // An aborted caller may already have settled, but its durable commit can
+                // still be in flight. Finish that work before agent/session disposal.
+                for (const outcome of await Promise.allSettled([...run.commits]))
+                    if (outcome.status === 'rejected')
+                        failures.push(outcome.reason);
                 try {
-                    run.entry.handle.agent.cancel({ kind: 'disposed' }, { keepInbox: this.retainPending });
+                    if (!run.entry.borrowed)
+                        run.entry.handle.agent.cancel({ kind: 'disposed' }, { keepInbox: this.retainPending });
                 }
                 catch (error) {
                     failures.push(error);
                 }
                 try {
-                    await run.entry.handle.agent.whenIdle();
+                    if (!run.entry.borrowed)
+                        await run.entry.handle.agent.whenIdle();
                 }
                 catch (error) {
                     failures.push(error);
@@ -1201,22 +1708,29 @@ export class NativeInbox {
                     failures.push(error);
                 }
                 finally {
+                    const targets = ['next-step', 'next-turn'];
+                    const committed = this.retainPending
+                        ? new Set(run.entry.handle.agent.session
+                            .snapshotEvents()
+                            .flatMap((event) => (event.type === 'user/message' ? [event.data.id] : [])))
+                        : new Set();
+                    const retainedByTask = new Map();
+                    let position = 0;
+                    for (const target of targets) {
+                        for (const message of run.retained[target]) {
+                            const input = { message, target, position: position++ };
+                            if (message.source.kind !== 'a2a' || committed.has(message.id))
+                                continue;
+                            const group = retainedByTask.get(message.source.taskId) ?? [];
+                            group.push(input);
+                            retainedByTask.set(message.source.taskId, group);
+                        }
+                    }
                     for (const task of run.tasks.values()) {
                         try {
                             if (!task.settled) {
                                 if (this.retainPending) {
-                                    const committed = new Set(run.entry.handle.agent.session
-                                        .snapshotEvents()
-                                        .flatMap((event) => (event.type === 'user/message' ? [event.data.id] : [])));
-                                    let position = 0;
-                                    const pending = ['next-step', 'next-turn'].flatMap((target) => run.retained[target].flatMap((message) => {
-                                        const input = { message, target, position: position++ };
-                                        return message.source.kind === 'a2a' &&
-                                            message.source.taskId === task.task.id &&
-                                            !committed.has(message.id)
-                                            ? [input]
-                                            : [];
-                                    }));
+                                    const pending = retainedByTask.get(task.task.id) ?? [];
                                     if (pending.length) {
                                         task.task.metadata = {
                                             ...task.task.metadata,