@amaster.ai/dsh-a2a 0.1.27 → 0.1.29

package/README.md

@@ -18,9 +18,52 @@ dsh plugin --profile my-agent add @amaster.ai/dsh-a2a
 
 Standard `SendMessage` / `SendStreamingMessage`, task queries, cancellation and subscriptions remain the wire interface. The negotiated [inbox extension](../../docs/protocol/inbox-v1.md) forwards `target` and `wakeup` to DSH. `wakeup: false` leaves an idle driver parked; it does not prevent an active driver from consuming pending input. A later real waking message releases pending input.
 
-The same-process `a2aInbox` service exposes `resolve(contextId)`, `content(message, contextId)`, `enqueue(taskId, message, { target?, wakeup? })`, and `cancel(taskId)`. There is no separate pause, wake-only, resume, or retained-task restart operation. Cancellation is terminal and removes that task's pending input. Other tasks' input is retained according to official DSH cancellation semantics, and may wait for the next waking message. Clearing a context discards all its pending work.
+The same-process `a2aInbox` service exposes `resolve(contextId)`, `content(message, contextId)`, `enqueue(taskId, message, { target?, wakeup? })`, `promote(contextId, nativeMessageId, activeTaskId)`, and `cancel(taskId)`. There is no separate pause, wake-only, resume, or retained-task restart operation. Cancellation is terminal and removes that task's pending input. Other tasks' input is retained according to official DSH cancellation semantics, and may wait for the next waking message. Clearing a context discards all its pending work.
 
-`a2a/before-followup` validates admission; `a2a/before-step` runs at the official pre-step boundary, after system-prompt assembly and before model execution. It cannot change the already assembled system prompt. Original request headers remain process-local. DSH persistence restores its own pending projection; the plugin does not replay splice logs or recover consumed claims. Graceful disposal follows the official runtime's cancellation behavior. Durable A2A task snapshots still require a Redis or GCS TaskStore; an in-memory store is sufficient without restart requirements.
+`a2a/before-followup` validates admission; `a2a/before-step` runs at the official pre-step boundary, after system-prompt assembly and before model execution. It cannot change the already assembled system prompt. Original request headers remain process-local. DSH persistence restores its own pending projection; the plugin does not replay splice logs or recover consumed claims. Graceful disposal cancels tasks by default; `inbox.shutdown: retain-pending` opts into the retention policy below. Durable A2A task snapshots require a filesystem, Redis or GCS TaskStore; an in-memory store is sufficient without restart requirements.
+
+### Goal rounds
+
+When the optional official `@deepseek-ai/dsh-goal` and `dsh-goal-round-driver` plugins are mounted, a Goal created or resumed during an A2A task keeps that task open while the Goal is active and armed. Automatic rounds retain the driver's original native message ID, content and `goal` source. The official driver still validates its reservation, revision and round; the plugin selects the owning task for streaming and `a2a/before-step` billing attribution. Editing the same Goal from another task preserves its original owner. Completing, pausing, blocking or disarming the Goal releases that ownership. A cold restart does not inherit automatic Goal authority: the host must explicitly resume it through a live attributed task.
+
+### Promote a queued input
+
+Queue an ordinary future turn as a new task (omit `taskId`). To steer an active task with that already admitted input, pass its **native DSH message ID**, available from `agent.inbox.nextTurn` or `a2a/inbox` observations:
+
+```ts
+await ctx.a2aInbox.promote(contextId, nativeMessageId, activeTaskId);
+```
+
+Only an unclaimed, single-message independent task in the same context can be promoted. The native ID and A2A `messageId` stay unchanged; the target task owns the next-step input, and `referenceTaskIds` records the original task, which settles canceled after the durable transfer. Claimed input, a finished target, concurrent consumption or task settlement reject a stale request. A failed session checkpoint restores independent ownership; a later storage error can report failure after the transfer committed: inspect the queue and task states before sending new input. Recovery repairs interrupted transfers without replaying an ordinary DSH claim or committed model input.
+
+### Local restart recovery
+
+Select `taskStore: filesystem` with `filesystem.root` pointing at a retained directory, and separately enable durable DSH session persistence. Keep queued file materialization on retained storage as well. Each task snapshot is scoped by tenant and user, written to a private temporary file and atomically renamed; no additional service is needed. Use one host writer per directory. Files have no automatic expiry; context clearing deletes task snapshots.
+
+After a crash, the host discovers sessions, calls `a2aInbox.resolve(contextId)` and supplies a real attributed waking input through the normal API. Restored unclaimed inputs keep their original task ownership. Startup scanning and scheduling remain host responsibilities. Explicit cancellation stays terminal and discards only the canceled task's input. This does not promise exactly-once external side effects, replay of consumed input, or replay of the interrupted active model call.
+
+### Graceful host shutdown
+
+Set `inbox: { enabled: true, shutdown: retain-pending }` on both sides of a restart to retain unclaimed A2A `next-step` and `next-turn` input. Keep durable session persistence, the TaskStore and materialized files on retained storage. This is a host configuration policy, not wire metadata. The default `shutdown: cancel` keeps the existing terminal-on-unload behavior.
+
+Retention tracks normalized native inbox splices, including public edits, reordering, removals and queue moves, then freezes the final pending state when host/plugin unloading begins. It stops the current execution, checkpoints pending input in task snapshot metadata with its order and original native/A2A identities, then closes live request/subscription streams. The extra checkpoint survives the core's later inbox-clearing disposal. A task with pending input stays nonterminal for recovery; an interrupted task with no pending input becomes failed. Reconnect subscriptions after restart: streams are not replayed or carried across processes.
+
+On `a2aInbox.resolve(contextId)`, the plugin restores retained ownership before allowing new input, excludes IDs already committed as `user/message`, and drains the retention checkpoint only after the restored session is durable. Explicit `CancelTask`, `a2aInbox.cancel()` and context clearing remain terminal. Claims already handed to the active execution are not retained, and external tool effects are not exactly-once. The host still owns startup discovery and an attributed waking input; merely resolving a context does not wake it. Persistence/checkpoint errors are reported through the existing shutdown error path; the host must not treat a failed checkpoint as a durable restart barrier.
+
+The dedicated `E2E (dsh-a2a graceful retention)` job covers public plugin disposal, a real SIGTERM child process, repeated restarts, promotion/checkpoint races and terminal cancellation. It also reports recovered tasks to Langfuse and verifies their task/turn/generation ancestry through the real Observations API on same-repository CI.
+
+```sh
+node .github/scripts/check-inbox.mjs -t 'graceful retention'
+DSH_GRACEFUL_RETENTION_LANGFUSE_LIVE=true node .github/scripts/check-inbox.mjs -t 'graceful retention.*reports gracefully recovered'
+```
+
+The dedicated `E2E (dsh-a2a native ownership)` integration job runs these regressions with unmodified npm DSH and scripted model responses. Its Langfuse scenario verifies Goal rounds and promoted input under the original task trace, canceled source ownership, and execution restored after SIGKILL. Same-repository CI also sends the scenario to the configured real Langfuse project and polls its Observations API; fork PRs use the local collector without credentials.
+
+```sh
+node .github/scripts/check-inbox.mjs -t 'native ownership'
+# With LANGFUSE_BASE_URL, LANGFUSE_PUBLIC_KEY and LANGFUSE_SECRET_KEY configured:
+DSH_NATIVE_OWNERSHIP_LANGFUSE_LIVE=true node .github/scripts/check-inbox.mjs -t 'native ownership.*reports Goal continuation'
+```
 
 ## Configuration
 
@@ -51,7 +94,9 @@ Disabled by default. Configure via the profile's `cordis.patch.yml`:
           description: My dsh agent over A2A
           version: 0.1.0
           publicUrl: https://agent.example.com
-        taskStore: redis       # memory | redis | gcs
+        taskStore: redis       # memory | filesystem | redis | gcs
+        filesystem:
+          root: /srv/dsh/a2a-tasks # required when taskStore: filesystem
         redis:
           url: redis://127.0.0.1:6379
           keyPrefix: a2a
@@ -128,6 +173,7 @@ Forwarding follows the owning task's active request bus. Background child events
 A2A task snapshots retain protocol history and artifacts; [dsh-storage](../dsh-storage) separately records the full conversation. Backends save on task-state transitions, including the complete reply at `input-required`, so token-rate stream events never reach Redis or GCS. While a task is working, in-process history accumulates text deltas for `GetTask` and resubscription; a restart before the next state change can lose those transient deltas.
 
 - `memory` (default) — in-process, lost on restart
+- `filesystem` — private, atomically replaced JSON snapshots under `filesystem.root`; no additional peer dependency
 - `redis` — task JSON under `<keyPrefix>:tasks:<scope>:<taskId>` with a TTL; requires the `ioredis` peer
 - `gcs` — gzipped task JSON at `<prefix>/<scope>/<taskId>/metadata.json.gz`; requires the `@google-cloud/storage` peer. `archiveWorkspace()` (tar of the workspace) exists but is not wired to the lifecycle yet.
 
@@ -139,7 +185,9 @@ dsh ships **no authentication or authorization**. The server binds `127.0.0.1` b
 
 ## Compatibility
 
-Pinned dsh/cordis versions live in the [root compat matrix](../../README.md#compatibility). Event payloads ride pre-release dsh APIs (`@deepseek-ai/dsh-{agent,session,llm,attachment,tools}@0.2.0-rc.2` — the attachment store is an optional peer) — the session peer floor is `>=0.2.0-rc.1` because child attribution uses `firstLifecycleSeq` to reject restored sessions; check the `TODO(verify)` markers in `src/` before upgrading dsh.
+Optional Goal integration requires `@deepseek-ai/dsh-goal >=0.2.0-rc.2 || >=0.2.1-alpha.1` and the official Goal round driver (both tested at `0.2.1-rc.2`).
+
+Pinned dsh/cordis versions live in the [root compat matrix](../../README.md#compatibility). Event payloads ride pre-release dsh APIs (`@deepseek-ai/dsh-{agent,session,llm,attachment,tools}@0.2.1-rc.2` — the attachment store is an optional peer) — the session peer floor is `>=0.2.0-rc.1` because child attribution uses `firstLifecycleSeq` to reject restored sessions; check the `TODO(verify)` markers in `src/` before upgrading dsh.
 
 ## License
 

package/lib/inbox.js

@@ -5,30 +5,80 @@ import { AgentEvent, ServerCallContext, STATE_HEADERS_KEY, } from '@a2a-js/sdk/s
 import { createUserMessage } from '@deepseek-ai/dsh-llm/message';
 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';
+const RETAINED_INPUTS = `${INBOX_EXTENSION}#retained-inputs`;
 export class NativeInbox {
     ctx;
     bridge;
     store;
+    retainPending;
     contexts = new Map();
     resolving = new Map();
     stopping = false;
     shutdownPromise;
     preadmitted = new WeakMap();
     server;
-    constructor(ctx, bridge, store) {
+    persistence;
+    constructor(ctx, bridge, store, retainPending = false) {
         this.ctx = ctx;
         this.bridge = bridge;
         this.store = store;
+        this.retainPending = retainPending;
         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())
+                    return;
+                try {
+                    const splice = event.data;
+                    run.retained[splice.target].splice(splice.start, splice.removedCount ?? 0, ...structuredClone(splice.inserted));
+                }
+                catch (error) {
+                    console.error('[dsh-a2a] failed to track pending inbox:', error);
+                }
+            });
         ctx.on('agent/pre-step', async (detail, next) => {
             await this.prepare(detail);
             return next();
         });
+        ctx.on('goal/changed', ({ agent, change }) => {
+            const run = this.contexts.get(agent.session.id);
+            if (!run)
+                return;
+            const previous = run.goalOwner;
+            if (change.goal?.phase === 'active' && change.goal.activation === 'armed') {
+                const task = previous?.goalId === change.ref.id ? previous.task : run.active;
+                if (task && !task.settled)
+                    run.goalOwner = { goalId: change.ref.id, task };
+            }
+            else
+                run.goalOwner = undefined;
+            if (previous)
+                this.settle(run, previous.task);
+        });
+        ctx.on('agent/status', ({ agent, status }) => {
+            const run = this.contexts.get(agent.session.id);
+            if (status !== 'idle' || !run?.goalOwner)
+                return;
+            const { task } = run.goalOwner;
+            try {
+                const goal = ctx.get('goals')?.get(agent);
+                if (goal?.phase === 'active' && goal.activation === 'armed')
+                    return;
+                run.goalOwner = undefined;
+                this.settle(run, task);
+            }
+            catch (error) {
+                run.goalOwner = undefined;
+                this.fail(task, agent.session.id, error);
+            }
+        });
         ctx.on('agent/inbox/claimed', ({ agent, message, turn }) => {
             const run = this.contexts.get(agent.session.id);
-            if (!run || message.source.kind !== 'a2a')
+            if (!run)
                 return;
-            const task = run.tasks.get(message.source.taskId);
+            const task = this.owner(run, message);
             if (task && !task.settled) {
                 run.claimed.add(task);
                 if (!run.active)
@@ -41,6 +91,18 @@ export class NativeInbox {
             }
         });
     }
+    unloading() {
+        // Cordis publishes FiberState as a const enum, without a runtime export.
+        const unloading = 5;
+        for (let fiber = this.ctx.fiber;;) {
+            if (fiber.uid === null || fiber.state === unloading)
+                return true;
+            const parent = fiber.parent.fiber;
+            if (parent === fiber)
+                return false;
+            fiber = parent;
+        }
+    }
     content(message, contextId) {
         return this.bridge.buildContent(message, contextId);
     }
@@ -69,6 +131,243 @@ export class NativeInbox {
         }
         throw new Error('Host input must address a live A2A task.');
     }
+    // A non-canceled removal keeps an interrupted move distinguishable from explicit cancellation.
+    moveInput(agent, message, target) {
+        const from = target === 'next-step' ? 'next-turn' : 'next-step';
+        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.');
+        agent.session.append('agent/inbox/spliced', {
+            target: from,
+            start: index,
+            removedCount: 1,
+            inserted: [],
+        });
+        agent.inbox.append(target, message);
+    }
+    async promote(contextId, messageId, taskId) {
+        const run = await this.context(contextId);
+        const operation = run.admissionTail.then(() => this.promoteInput(run, messageId, taskId));
+        run.admissionTail = operation.catch(() => { });
+        run.promotions.set(messageId, operation);
+        const clear = () => {
+            if (run.promotions.get(messageId) === operation)
+                run.promotions.delete(messageId);
+        };
+        void operation.then(clear, clear);
+        return operation;
+    }
+    async promoteInput(run, messageId, taskId) {
+        const agent = run.entry.handle.agent;
+        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.');
+        const source = run.tasks.get(message.source.taskId);
+        if (!target || !source)
+            throw new Error('Promotion requires live source and target tasks.');
+        const valid = () => !this.stopping &&
+            !this.bridge.isClearing(run.entry.sessionId) &&
+            !target.settled &&
+            !target.controller.signal.aborted &&
+            run.active === target &&
+            source !== target &&
+            !source.settled &&
+            !source.controller.signal.aborted &&
+            source.task.history.length === 1 &&
+            !source.pendingRequests &&
+            !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.');
+        const original = Message.fromJSON(JSON.parse(message.source.message));
+        original.taskId = taskId;
+        original.referenceTaskIds = [...new Set([...original.referenceTaskIds, source.task.id])];
+        const promotionId = randomUUID();
+        const promoted = {
+            ...message,
+            source: {
+                ...message.source,
+                taskId,
+                target: 'next-step',
+                promotedFrom: source.task.id,
+                promotionId,
+                message: JSON.stringify(Message.toJSON(original)),
+            },
+        };
+        target.pendingRequests++;
+        try {
+            await this.checkpoint(target.task, target.context);
+            if (!valid())
+                throw new Error('Promotion raced input consumption or task settlement.');
+            target.task.history = [...target.task.history, 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.');
+            this.moveInput(agent, promoted, 'next-step');
+            try {
+                await this.flush(agent.session);
+            }
+            catch (error) {
+                // Until the session checkpoint succeeds, the independent task still owns this input.
+                const rollback = {
+                    ...message,
+                    source: { ...message.source, promotedFrom: source.task.id },
+                };
+                run.rolledBack.add(promotionId);
+                const live = this.contexts.get(run.entry.sessionId) === run &&
+                    !this.stopping &&
+                    !this.bridge.isClearing(run.entry.sessionId);
+                if (live && !source.settled && !source.controller.signal.aborted) {
+                    if (this.pending(run).some((item) => item.id === message.id)) {
+                        agent.inbox.replace(message.id, rollback);
+                        this.moveInput(agent, rollback, 'next-turn');
+                    }
+                    else
+                        agent.inbox.append('next-turn', rollback);
+                }
+                else if (live)
+                    agent.inbox.remove(message.id);
+                target.task.history = target.task.history.filter((item) => item.messageId !== original.messageId);
+                target.headers.delete(message.id);
+                try {
+                    if (live)
+                        await this.flush(agent.session);
+                }
+                catch (rollbackError) {
+                    console.error('[dsh-a2a] promotion rollback checkpoint failed:', rollbackError);
+                }
+                throw error;
+            }
+            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.');
+            source.controller.abort();
+            try {
+                await this.checkpoint(target.task, target.context);
+            }
+            finally {
+                await this.cancel(source.task.id);
+            }
+            this.observeInput('promoted', run, promoted);
+        }
+        finally {
+            target.pendingRequests--;
+            this.settle(run, target);
+        }
+    }
+    /** Repair only an incomplete ownership move, never an ordinary DSH claim. */
+    async recoverPromotions(run, context) {
+        const agent = run.entry.handle.agent;
+        const transfers = new Map();
+        for (const event of agent.session.snapshotEvents()) {
+            if (event.type !== 'agent/inbox/spliced')
+                continue;
+            for (const message of event.data.inserted) {
+                if (message.source.kind !== 'a2a' || !message.source.promotedFrom)
+                    continue;
+                const previous = transfers.get(message.id);
+                transfers.set(message.id, {
+                    message: message,
+                    // A completed transfer stays complete after later public queue edits.
+                    placed: event.data.target === message.source.target ||
+                        !!(previous?.placed &&
+                            previous.message.source.taskId === message.source.taskId &&
+                            previous.message.source.promotionId === message.source.promotionId),
+                });
+            }
+        }
+        for (const { message, placed } of transfers.values()) {
+            if (!placed) {
+                const queued = this.pending(run).find((item) => item.id === message.id);
+                if (queued)
+                    this.moveInput(agent, message, message.source.target);
+                else
+                    agent.inbox.append(message.source.target, message);
+            }
+            if (this.pending(run).some((item) => item.id === message.id)) {
+                const recipient = await this.store.load(message.source.taskId, context);
+                if (!recipient || recipient.contextId !== agent.session.id)
+                    throw new Error('Promoted A2A task is not accessible.');
+                const original = Message.fromJSON(JSON.parse(message.source.message));
+                if (!recipient.history.some((item) => item.messageId === original.messageId)) {
+                    recipient.history.push(original);
+                    await this.checkpoint(recipient, context);
+                }
+            }
+            if (message.source.promotedFrom === message.source.taskId)
+                continue;
+            const former = await this.store.load(message.source.promotedFrom, context);
+            if (!former || this.terminal(former))
+                continue;
+            former.status = {
+                state: TaskState.TASK_STATE_CANCELED,
+                message: undefined,
+                timestamp: new Date().toISOString(),
+            };
+            await this.flush(agent.session);
+            await this.checkpoint(former, context);
+        }
+    }
+    async recoverRetained(run, context) {
+        if (!this.retainPending)
+            return;
+        const agent = run.entry.handle.agent;
+        const committed = new Set(agent.session
+            .snapshotEvents()
+            .flatMap((event) => (event.type === 'user/message' ? [event.data.id] : [])));
+        const snapshots = [];
+        const inputs = [];
+        let pageToken = '';
+        do {
+            const page = await this.store.list({
+                tenant: '',
+                contextId: agent.session.id,
+                pageSize: 100,
+                pageToken,
+                status: TaskState.TASK_STATE_UNSPECIFIED,
+                statusTimestampAfter: undefined,
+            }, context);
+            for (const task of page.tasks) {
+                const retained = task.metadata?.[RETAINED_INPUTS];
+                if (typeof retained !== 'string')
+                    continue;
+                snapshots.push(task);
+                if (this.terminal(task))
+                    continue;
+                for (const input of JSON.parse(retained)) {
+                    const { message } = input;
+                    if (message.source.kind !== 'a2a' || message.source.taskId !== task.id)
+                        throw new Error('Retained input has invalid task ownership.');
+                    if (!committed.has(message.id))
+                        inputs.push(input);
+                }
+            }
+            pageToken = page.nextPageToken;
+        } while (pageToken);
+        for (const { message, target } of inputs.sort((a, b) => a.position - b.position)) {
+            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))
+                    this.moveInput(agent, message, target);
+            }
+            else
+                agent.inbox.append(target, message);
+        }
+        if (!snapshots.length)
+            return;
+        await this.flush(agent.session);
+        for (const task of snapshots) {
+            delete task.metadata[RETAINED_INPUTS];
+            await this.checkpoint(task, context);
+        }
+    }
     context(contextId, context = new ServerCallContext()) {
         if (this.stopping)
             return Promise.reject(new Error('Native inbox is unloading.'));
@@ -85,7 +384,12 @@ export class NativeInbox {
                     claimed: new Set(),
                     admissions: new Set(),
                     admissionTail: Promise.resolve(),
+                    promotions: new Map(),
+                    rolledBack: new Set(),
+                    retained: { 'next-step': [], 'next-turn': [] },
                 };
+                await this.recoverRetained(run, context);
+                await this.recoverPromotions(run, context);
                 const snapshots = new Map();
                 for (const message of this.pending(run)) {
                     if (message.source.kind !== 'a2a' || snapshots.has(message.source.taskId))
@@ -101,6 +405,10 @@ export class NativeInbox {
                 await this.flush(entry.handle.agent.session);
                 for (const snapshot of snapshots.values())
                     this.restoreTask(run, snapshot, context);
+                run.retained = structuredClone({
+                    'next-step': [...entry.handle.agent.inbox.nextStep],
+                    'next-turn': [...entry.handle.agent.inbox.nextTurn],
+                });
                 this.contexts.set(contextId, run);
                 this.observe('resolved', run);
                 for (const message of this.pending(run))
@@ -113,7 +421,9 @@ export class NativeInbox {
     }
     observe(phase, run, fields = {}) {
         try {
-            const pending = this.pending(run);
+            const pending = this.stopping && this.retainPending
+                ? [...run.retained['next-step'], ...run.retained['next-turn']]
+                : this.pending(run);
             void this.ctx
                 .parallel('a2a/inbox', {
                 phase,
@@ -137,21 +447,22 @@ export class NativeInbox {
     }
     observeInput(phase, run, message, fields = {}) {
         try {
-            if (message.source.kind !== 'a2a')
+            const task = this.owner(run, message);
+            if (!task)
                 return;
-            const original = Message.fromJSON(JSON.parse(message.source.message));
+            const original = this.protocolMessage(run, task, message);
             const position = this.pending(run).findIndex((input) => input.id === message.id);
             this.observe(phase, run, {
-                target: message.source.target,
+                target: message.source.kind === 'a2a' ? message.source.target : 'next-turn',
                 input: original.parts
                     .flatMap((part) => (part.content?.$case === 'text' ? [part.content.value] : []))
                     .join('\n'),
                 position: position < 0 ? undefined : position + 1,
-                taskId: message.source.taskId,
+                taskId: task.task.id,
                 messageId: original.messageId,
                 referenceTaskIds: original.referenceTaskIds,
                 nativeMessageId: message.id,
-                queuedAt: message.source.queuedAt,
+                queuedAt: message.source.kind === 'a2a' ? message.source.queuedAt : undefined,
                 ...fields,
             });
         }
@@ -416,7 +727,7 @@ export class NativeInbox {
                 bus.publish(task.final);
         }
         catch (error) {
-            if (task?.settled)
+            if (task?.settled || (this.stopping && this.retainPending))
                 return;
             if (task && !ownsTask) {
                 bus.publish(AgentEvent.task(structuredClone(task.task)));
@@ -468,13 +779,67 @@ export class NativeInbox {
             run.turnStart = undefined;
         }
     }
+    protocolMessage(run, task, message) {
+        if (message.source.kind === 'a2a')
+            return Message.fromJSON(JSON.parse(message.source.message));
+        return Message.fromJSON({
+            messageId: message.id,
+            taskId: task.task.id,
+            contextId: run.entry.sessionId,
+            role: 'ROLE_USER',
+            parts: message.content
+                .filter((block) => block.type === 'text')
+                .map((block) => ({ text: block.text })),
+        });
+    }
+    owner(run, message) {
+        if (message.source.kind === 'a2a')
+            return run.tasks.get(message.source.taskId);
+        if (message.source.kind !== 'goal' || message.source.round <= 0)
+            return;
+        const goal = this.ctx.get('goals')?.get(run.entry.handle.agent);
+        if (run.goalOwner &&
+            goal &&
+            run.goalOwner.goalId === message.source.goalId &&
+            goal.id === message.source.goalId &&
+            goal.revision === message.source.revision &&
+            goal.phase === 'active' &&
+            goal.activation === 'armed')
+            return run.goalOwner.task;
+    }
     async prepare(detail) {
         const run = this.contexts.get(detail.agent.session.id);
         if (!run)
             return;
         if (this.stopping)
             throw new Error('Inbox is unloading.');
-        if (!run.active && detail.messages.some((message) => message.source.kind !== 'a2a'))
+        for (let index = detail.messages.length - 1; index >= 0; index--) {
+            const message = detail.messages[index];
+            if (message.source.kind !== 'a2a' || !message.source.promotionId)
+                continue;
+            const promotion = run.promotions.get(message.id);
+            if (promotion) {
+                let onAbort;
+                try {
+                    await Promise.race([
+                        promotion.catch(() => { }),
+                        new Promise((_resolve, reject) => {
+                            onAbort = () => reject(detail.signal.reason);
+                            detail.signal.addEventListener('abort', onAbort, { once: true });
+                            if (detail.signal.aborted)
+                                onAbort();
+                        }),
+                    ]);
+                    detail.signal.throwIfAborted();
+                }
+                finally {
+                    detail.signal.removeEventListener('abort', onAbort);
+                }
+            }
+            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.
@@ -495,9 +860,9 @@ export class NativeInbox {
                     detail.messages.splice(index, 1);
         }
         for (const message of detail.messages) {
-            if (message.source.kind !== 'a2a')
+            const task = this.owner(run, message);
+            if (!task && message.source.kind !== 'a2a')
                 continue;
-            const task = run.tasks.get(message.source.taskId);
             if (!task || task.settled)
                 throw new Error('Queued input has no live A2A task; restore it before waking.');
             if (run.active && run.active !== task)
@@ -511,7 +876,7 @@ export class NativeInbox {
                     agent: detail.agent,
                     contextId: detail.agent.session.id,
                     taskId: task.task.id,
-                    a2aMessage: Message.fromJSON(JSON.parse(message.source.message)),
+                    a2aMessage: this.protocolMessage(run, task, message),
                     dshMessageId: message.id,
                     requestHeaders: task.headers.get(message.id),
                     signal: detail.signal,
@@ -607,6 +972,7 @@ export class NativeInbox {
         }
         else if (!task.settlementReady ||
             task.pendingRequests ||
+            run.goalOwner?.task === task ||
             run.active === task ||
             this.pending(run).some((message) => message.source.kind === 'a2a' && message.source.taskId === task.task.id))
             return;
@@ -738,6 +1104,7 @@ export class NativeInbox {
         ];
         for (const admission of run.admissions)
             admission.abort();
+        run.retained = { 'next-step': [], 'next-turn': [] };
         run.entry.handle.agent.inbox.clear();
         run.entry.handle.agent.cancel({ kind: 'user' });
         await run.entry.handle.agent.whenIdle();
@@ -754,7 +1121,7 @@ export class NativeInbox {
     }
     onDisposed(session) {
         const run = this.contexts.get(session.id);
-        if (!run)
+        if (!run || (this.retainPending && this.stopping))
             return;
         for (const admission of run.admissions)
             admission.abort();
@@ -787,7 +1154,7 @@ export class NativeInbox {
                 for (const admission of run.admissions)
                     admission.abort();
                 try {
-                    run.entry.handle.agent.cancel({ kind: 'disposed' });
+                    run.entry.handle.agent.cancel({ kind: 'disposed' }, { keepInbox: this.retainPending });
                 }
                 catch (error) {
                     failures.push(error);
@@ -799,7 +1166,11 @@ export class NativeInbox {
                     failures.push(error);
                 }
                 try {
-                    await this.flush(run.entry.handle.agent.session);
+                    // The persistence barrier tolerates writers already closed by parallel core teardown.
+                    if (this.retainPending && this.persistence)
+                        await this.persistence.flush();
+                    else
+                        await this.flush(run.entry.handle.agent.session);
                 }
                 catch (error) {
                     failures.push(error);
@@ -807,8 +1178,40 @@ export class NativeInbox {
                 finally {
                     for (const task of run.tasks.values()) {
                         try {
-                            if (!task.settled)
-                                await this.cancelTask(run, task);
+                            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]
+                                            : [];
+                                    }));
+                                    if (pending.length) {
+                                        task.task.metadata = {
+                                            ...task.task.metadata,
+                                            [RETAINED_INPUTS]: JSON.stringify(pending),
+                                        };
+                                        await this.checkpoint(structuredClone(task.task), task.context);
+                                    }
+                                    else {
+                                        task.final = terminalStatusUpdate(task.task.id, run.entry.sessionId, 'failed', 'Host stopped; active input will not be replayed.');
+                                        if (task.final.kind === 'statusUpdate')
+                                            task.task.status = task.final.data.status;
+                                        await this.checkpoint(structuredClone(task.task), task.context);
+                                        task.bus.publish(task.final);
+                                    }
+                                    task.settled = true;
+                                    task.controller.abort();
+                                }
+                                else
+                                    await this.cancelTask(run, task);
+                            }
                         }
                         catch (error) {
                             failures.push(error);

package/lib/index.js

@@ -18,6 +18,7 @@ import { A2aBridge } from './bridge.js';
 import { DshAgentExecutor } from './executor.js';
 import { INBOX_EXTENSION, NativeInbox } from './inbox.js';
 import { startA2aServer } from './server.js';
+import { FilesystemTaskStore } from './stores/filesystem.js';
 import { GcsTaskStore } from './stores/gcs.js';
 import { RedisTaskStore } from './stores/redis.js';
 import { MemoryTaskStore, SanitizedTaskStore } from './task-store.js';
@@ -29,7 +30,10 @@ export const name = 'dsh-a2a';
 /** The bridge creates and owns agents through the registry service. */
 export const inject = ['agents'];
 export const Config = Schema.object({
-    inbox: Schema.object({ enabled: Schema.boolean().default(false) }).description('Use the official DSH inbox for queued turns and steering.'),
+    inbox: Schema.object({
+        enabled: Schema.boolean().default(false),
+        shutdown: Schema.union([Schema.const('cancel'), Schema.const('retain-pending')]).default('cancel'),
+    }).description('Use the official DSH inbox for queued turns and steering.'),
     enabled: Schema.boolean().default(false),
     host: Schema.string().default('127.0.0.1'),
     port: Schema.natural().default(41241),
@@ -70,9 +74,11 @@ export const Config = Schema.object({
      */
     taskStore: Schema.union([
         Schema.const('memory'),
+        Schema.const('filesystem'),
         Schema.const('redis'),
         Schema.const('gcs'),
     ]).default('memory'),
+    filesystem: Schema.object({ root: Schema.string().default('') }),
     redis: Schema.object({
         url: Schema.string().role('secret').default('redis://127.0.0.1:6379'),
         keyPrefix: Schema.string().default('a2a'),
@@ -111,7 +117,9 @@ export function apply(ctx, config) {
             subagentTools: config.subagentTools,
         });
         const store = createTaskStore(config);
-        const inbox = config.inbox?.enabled ? new NativeInbox(ctx, bridge, store) : undefined;
+        const inbox = config.inbox?.enabled
+            ? new NativeInbox(ctx, bridge, store, config.inbox.shutdown === 'retain-pending')
+            : undefined;
         await store.init?.();
         if (inbox)
             ctx.provide('a2aInbox', inbox);
@@ -198,6 +206,8 @@ export function apply(ctx, config) {
 }
 function createTaskStore(config) {
     switch (config.taskStore) {
+        case 'filesystem':
+            return new SanitizedTaskStore(new FilesystemTaskStore({ root: config.filesystem?.root ?? '' }));
         case 'redis':
             return new SanitizedTaskStore(new RedisTaskStore(config.redis));
         case 'gcs':

package/lib/stores/filesystem.js

@@ -0,0 +1,86 @@
+/** Local task snapshots, retained alongside the DSH session log. */
+import { createHash, randomUUID } from 'node:crypto';
+import { mkdir, open, readdir, readFile, rename, rm } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { Task } from '@a2a-js/sdk';
+import { listShells, taskScopeKey } from '../task-store.js';
+export class FilesystemTaskStore {
+    root;
+    constructor(config) {
+        if (!config.root)
+            throw new Error('[dsh-a2a] filesystem.root is required.');
+        this.root = resolve(config.root);
+    }
+    directory(context) {
+        return join(this.root, taskScopeKey(context));
+    }
+    path(id, context) {
+        return join(this.directory(context), `${createHash('sha256').update(id).digest('hex')}.json`);
+    }
+    async save(task, context) {
+        const directory = this.directory(context);
+        await mkdir(directory, { recursive: true, mode: 0o700 });
+        const temporary = join(directory, `${randomUUID()}.tmp`);
+        try {
+            const file = await open(temporary, 'wx', 0o600);
+            try {
+                await file.writeFile(JSON.stringify(Task.toJSON(task)));
+                await file.sync();
+            }
+            finally {
+                await file.close();
+            }
+            await rename(temporary, this.path(task.id, context));
+            // Windows cannot open directory handles through fs.open.
+            if (process.platform !== 'win32') {
+                const dir = await open(directory, 'r');
+                try {
+                    await dir.sync();
+                }
+                finally {
+                    await dir.close();
+                }
+            }
+        }
+        finally {
+            await rm(temporary, { force: true });
+        }
+    }
+    async load(id, context) {
+        try {
+            return Task.fromJSON(JSON.parse(await readFile(this.path(id, context), 'utf8')));
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return;
+            throw error;
+        }
+    }
+    async delete(id, context) {
+        await rm(this.path(id, context), { force: true });
+    }
+    async list(params, context) {
+        let files;
+        try {
+            files = await readdir(this.directory(context));
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+            files = [];
+        }
+        const tasks = [];
+        for (const file of files) {
+            if (!/^[a-f0-9]{64}\.json$/.test(file))
+                continue;
+            try {
+                tasks.push(Task.fromJSON(JSON.parse(await readFile(join(this.directory(context), file), 'utf8'))));
+            }
+            catch (error) {
+                if (error.code !== 'ENOENT')
+                    throw error;
+            }
+        }
+        return listShells(tasks, params);
+    }
+}

package/lib/types/inbox.d.ts

@@ -2,6 +2,7 @@ import { Message } from '@a2a-js/sdk';
 import { type ExecutionEventBus, type RequestContext, ServerCallContext } from '@a2a-js/sdk/server';
 import type { Context } from '@deepseek-ai/cordis';
 import type { Agent, AssistantStreamFrame, InboxTarget } from '@deepseek-ai/dsh-agent';
+import type { GoalMessageSource } from '@deepseek-ai/dsh-goal';
 import type { ContentBlock } from '@deepseek-ai/dsh-llm/types';
 import type { Session, SessionEvent } from '@deepseek-ai/dsh-session';
 import type { A2aBridge } from './bridge.js';
@@ -35,10 +36,13 @@ interface InboxSource {
     message: string;
     target: InboxTarget;
     queuedAt?: number;
+    promotedFrom?: string;
+    promotionId?: string;
 }
 declare module '@deepseek-ai/dsh-llm/types' {
     interface MessageSourceMap {
         a2a: InboxSource;
+        goal: GoalMessageSource;
     }
 }
 declare module '@deepseek-ai/cordis' {
@@ -58,6 +62,8 @@ export interface A2aInbox {
         target?: InboxTarget;
         wakeup?: boolean;
     }): Promise<void>;
+    /** Transfer one unclaimed independent input into the active task. */
+    promote(contextId: string, messageId: string, taskId: string): Promise<void>;
     /** Standard cancellation is terminal and removes only this task's pending input. */
     cancel(taskId: string): Promise<string | undefined>;
 }
@@ -65,19 +71,28 @@ export declare class NativeInbox implements A2aInbox {
     private readonly ctx;
     private readonly bridge;
     private readonly store;
+    private readonly retainPending;
     private readonly contexts;
     private readonly resolving;
     private stopping;
     private shutdownPromise?;
     private readonly preadmitted;
     server?: A2aServer;
-    constructor(ctx: Context, bridge: A2aBridge, store: ManagedTaskStore);
+    private readonly persistence?;
+    constructor(ctx: Context, bridge: A2aBridge, store: ManagedTaskStore, retainPending?: boolean);
+    private unloading;
     content(message: Message, contextId: string): Promise<ContentBlock[]>;
     resolve(contextId: string): Promise<Agent>;
     enqueue(taskId: string, message: Message, options?: {
         target?: InboxTarget;
         wakeup?: boolean;
     }): Promise<void>;
+    private moveInput;
+    promote(contextId: string, messageId: string, taskId: string): Promise<void>;
+    private promoteInput;
+    /** Repair only an incomplete ownership move, never an ordinary DSH claim. */
+    private recoverPromotions;
+    private recoverRetained;
     private context;
     private observe;
     private observeInput;
@@ -96,6 +111,8 @@ export declare class NativeInbox implements A2aInbox {
     execute(request: RequestContext, bus: ExecutionEventBus): Promise<void>;
     private restoreTask;
     private select;
+    private protocolMessage;
+    private owner;
     private prepare;
     private publish;
     onSessionEvent(session: Session, event: SessionEvent): boolean;

package/lib/types/index.d.ts

@@ -71,8 +71,10 @@ export declare const inject: string[];
 export declare const Config: Schema<Schemastery.ObjectS<{
     inbox: Schema<Schemastery.ObjectS<{
         enabled: Schema<boolean, boolean>;
+        shutdown: Schema<"cancel" | "retain-pending", "cancel" | "retain-pending">;
     }>, Schemastery.ObjectT<{
         enabled: Schema<boolean, boolean>;
+        shutdown: Schema<"cancel" | "retain-pending", "cancel" | "retain-pending">;
     }>>;
     enabled: Schema<boolean, boolean>;
     host: Schema<string, string>;
@@ -131,7 +133,12 @@ export declare const Config: Schema<Schemastery.ObjectS<{
      * A2A task snapshots, including protocol history. dsh-storage separately
      * owns the full conversation log. 'memory' loses tasks on restart.
      */
-    taskStore: Schema<"memory" | "redis" | "gcs", "memory" | "redis" | "gcs">;
+    taskStore: Schema<"memory" | "filesystem" | "redis" | "gcs", "memory" | "filesystem" | "redis" | "gcs">;
+    filesystem: Schema<Schemastery.ObjectS<{
+        root: Schema<string, string>;
+    }>, Schemastery.ObjectT<{
+        root: Schema<string, string>;
+    }>>;
     redis: Schema<Schemastery.ObjectS<{
         url: Schema<string, string>;
         keyPrefix: Schema<string, string>;
@@ -153,8 +160,10 @@ export declare const Config: Schema<Schemastery.ObjectS<{
 }>, Schemastery.ObjectT<{
     inbox: Schema<Schemastery.ObjectS<{
         enabled: Schema<boolean, boolean>;
+        shutdown: Schema<"cancel" | "retain-pending", "cancel" | "retain-pending">;
     }>, Schemastery.ObjectT<{
         enabled: Schema<boolean, boolean>;
+        shutdown: Schema<"cancel" | "retain-pending", "cancel" | "retain-pending">;
     }>>;
     enabled: Schema<boolean, boolean>;
     host: Schema<string, string>;
@@ -213,7 +222,12 @@ export declare const Config: Schema<Schemastery.ObjectS<{
      * A2A task snapshots, including protocol history. dsh-storage separately
      * owns the full conversation log. 'memory' loses tasks on restart.
      */
-    taskStore: Schema<"memory" | "redis" | "gcs", "memory" | "redis" | "gcs">;
+    taskStore: Schema<"memory" | "filesystem" | "redis" | "gcs", "memory" | "filesystem" | "redis" | "gcs">;
+    filesystem: Schema<Schemastery.ObjectS<{
+        root: Schema<string, string>;
+    }>, Schemastery.ObjectT<{
+        root: Schema<string, string>;
+    }>>;
     redis: Schema<Schemastery.ObjectS<{
         url: Schema<string, string>;
         keyPrefix: Schema<string, string>;
@@ -236,6 +250,7 @@ export declare const Config: Schema<Schemastery.ObjectS<{
 export interface A2aPluginConfig {
     inbox?: {
         enabled: boolean;
+        shutdown?: 'cancel' | 'retain-pending';
     };
     enabled: boolean;
     host: string;
@@ -261,7 +276,10 @@ export interface A2aPluginConfig {
         version: string;
         publicUrl: string;
     };
-    taskStore: 'memory' | 'redis' | 'gcs';
+    taskStore: 'memory' | 'filesystem' | 'redis' | 'gcs';
+    filesystem?: {
+        root: string;
+    };
     redis: {
         url: string;
         keyPrefix: string;

package/lib/types/stores/filesystem.d.ts

@@ -0,0 +1,15 @@
+import { type ListTasksRequest, type ListTasksResponse, Task } from '@a2a-js/sdk';
+import type { ServerCallContext } from '@a2a-js/sdk/server';
+import { type ManagedTaskStore } from '../task-store.js';
+export declare class FilesystemTaskStore implements ManagedTaskStore {
+    private readonly root;
+    constructor(config: {
+        root: string;
+    });
+    private directory;
+    private path;
+    save(task: Task, context: ServerCallContext): Promise<void>;
+    load(id: string, context: ServerCallContext): Promise<Task | undefined>;
+    delete(id: string, context: ServerCallContext): Promise<void>;
+    list(params: ListTasksRequest, context: ServerCallContext): Promise<ListTasksResponse>;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amaster.ai/dsh-a2a",
-  "version": "0.1.27",
+  "version": "0.1.29",
   "description": "A2A protocol (JSON-RPC + SSE) server plugin for DeepSeek Harness: expose dsh agents as A2A agents.",
   "type": "module",
   "main": "lib/index.js",
@@ -39,13 +39,15 @@
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",
     "@deepseek-ai/dsh-agent": ">=0.2.0-rc.2 || >=0.2.1-alpha.1",
-    "@deepseek-ai/dsh-attachment": ">=0.1.5-rc.1 || >=0.1.6-alpha.1 || >=0.1.7-alpha.1 || >=0.2.0-rc.1",
-    "@deepseek-ai/dsh-llm": ">=0.1.5-rc.1 || >=0.1.6-alpha.1 || >=0.1.7-alpha.1 || >=0.2.0-rc.1",
-    "@deepseek-ai/dsh-session": ">=0.2.0-rc.1",
-    "@deepseek-ai/dsh-tools": ">=0.1.5-rc.1 || >=0.1.6-alpha.1 || >=0.1.7-alpha.1 || >=0.2.0-rc.1",
-    "@deepseek-ai/dsh-user-approval": ">=0.1.6-alpha.2 || >=0.1.7-alpha.1 || >=0.2.0-rc.1",
+    "@deepseek-ai/dsh-attachment": ">=0.1.5-rc.1 || >=0.1.6-alpha.1 || >=0.1.7-alpha.1 || >=0.2.0-rc.1 || >=0.2.1-rc.1",
+    "@deepseek-ai/dsh-llm": ">=0.1.5-rc.1 || >=0.1.6-alpha.1 || >=0.1.7-alpha.1 || >=0.2.0-rc.1 || >=0.2.1-rc.1",
+    "@deepseek-ai/dsh-session": ">=0.2.0-rc.1 || >=0.2.1-rc.1",
+    "@deepseek-ai/dsh-tools": ">=0.1.5-rc.1 || >=0.1.6-alpha.1 || >=0.1.7-alpha.1 || >=0.2.0-rc.1 || >=0.2.1-rc.1",
+    "@deepseek-ai/dsh-user-approval": ">=0.1.6-alpha.2 || >=0.1.7-alpha.1 || >=0.2.0-rc.1 || >=0.2.1-rc.1",
     "@google-cloud/storage": "^7.0.0",
-    "ioredis": "^5.0.0"
+    "ioredis": "^5.0.0",
+    "@deepseek-ai/dsh-goal": ">=0.2.0-rc.2 || >=0.2.1-alpha.1",
+    "@deepseek-ai/dsh-session-persistence": ">=0.2.0-rc.2 || >=0.2.1-alpha.1"
   },
   "peerDependenciesMeta": {
     "@deepseek-ai/dsh-attachment": {
@@ -59,6 +61,12 @@
     },
     "ioredis": {
       "optional": true
+    },
+    "@deepseek-ai/dsh-goal": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-session-persistence": {
+      "optional": true
     }
   },
   "devDependencies": {
@@ -76,7 +84,9 @@
     "@types/node": "^22.0.0",
     "ioredis": "^5.0.0",
     "typescript": "^5.6.3",
-    "vitest": "^4.1.11"
+    "vitest": "^4.1.11",
+    "@deepseek-ai/dsh-goal": "0.2.1-rc.2",
+    "@deepseek-ai/dsh-session-persistence": "0.2.1-rc.2"
   },
   "engines": {
     "node": "^20.19 || ^22.12 || >=24.0"