@amaster.ai/dsh-a2a 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dsh-plugins contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,82 @@
+# @amaster.ai/dsh-a2a
+
+![dsh-a2a preview](preview.png)
+
+A2A protocol server plugin for [DeepSeek Harness (dsh)](https://github.com/deepseek-ai/deepseek-harness): expose dsh agents as [A2A](https://github.com/a2aproject) agents — streaming turns, task cancel, agent card, and pluggable task-state stores. Speaks **A2A 1.0** (JSON-RPC + SSE) on [`@a2a-js/sdk`](https://github.com/a2aproject/a2a-js) 1.x, with the SDK's opt-in **v0.3 compatibility layer** kept on so pre-1.0 clients keep working. Ported from the source project's `packages/a2a-server`.
+
+`dsh-a2a` is the network boundary for a dsh agent. It gives A2A clients a stable task-oriented interface while the agent continues to use the profile's models, presets, tools, and workspace rules.
+
+## Install
+
+```sh
+dsh plugin --profile my-agent add @amaster.ai/dsh-a2a
+```
+
+## Configuration
+
+Disabled by default. Configure via the profile's `cordis.patch.yml`:
+
+```yaml
+- insert:
+    - id: a2a
+      name: '@amaster.ai/dsh-a2a'
+      config:
+        enabled: true
+        host: 127.0.0.1        # no auth built in — keep loopback or front with a proxy
+        port: 41241
+        basePath: /a2a
+        cwd: /srv/agent-workspaces
+        agent:
+          provider: ''       # dsh provider/model for A2A sessions; empty = profile default
+          model: ''
+          preset: ''         # agent preset mounted per task; empty = deployment default
+        card:
+          name: my-agent
+          description: My dsh agent over A2A
+          version: 0.1.0
+          publicUrl: https://agent.example.com
+        taskStore: redis       # memory | redis | gcs
+        redis:
+          url: redis://127.0.0.1:6379
+          keyPrefix: a2a
+          ttlSeconds: 86400
+        gcs:
+          bucket: my-agent-archives
+          prefix: tasks
+          keyFilename: ''      # GOOGLE_APPLICATION_CREDENTIALS path; empty = ADC
+```
+
+## Endpoints
+
+- `GET /.well-known/agent-card.json` — agent card: A2A 1.0 shape for `A2A-Version: 1.0` clients, the 0.3 shape for headerless clients (the legacy `/.well-known/agent.json` path is served as an alias)
+- `POST <basePath>/` — JSON-RPC. v1 methods: `SendMessage` (blocking by default, `configuration.returnImmediately: true` returns after the first event), `SendStreamingMessage` (SSE), `GetTask`, `ListTasks` (filter + cursor pagination), `CancelTask`, `SubscribeToTask` (the current task is the first event; the bus stays alive while the task is interrupted, so interrupted tasks can be re-followed live). v0.3 spellings (`message/send`, `message/stream`, `tasks/get`, `tasks/cancel`, `tasks/resubscribe`) keep working through the compat layer.
+
+## Behavior notes
+
+- **One task = one dsh session.** The A2A `contextId` IS the dsh session id. A completed turn ends `input-required`, not `completed` — the task is a conversation and stays continuable; `CancelTask` and turn errors are terminal (`canceled` / `failed`), and the SDK rejects follow-ups addressed at a terminal `taskId` (send with only the `contextId` to continue the session under a fresh task id).
+- **Agents are full preset citizens.** Each task's agent is created with the deployment's default model selection (`agentDefaultModel`) and mounts its agent preset (the web profile keeps all tools inside presets — without one the agent would see an empty tool catalog). `agent.preset` pins a specific preset.
+- **Streaming aggregation.** Text deltas of a turn share one `messageId`, so clients accumulate them into a single message; reasoning deltas ride a separate `messageId` and are marked `metadata.dshAgent.kind: 'thought'`. The turn-final event's message carries the full assembled text, so blocking `SendMessage` clients read the answer from `result.task.status.message`. Tool calls/results are data parts marked `tool-call` / `tool-result`; token usage lands in `metadata.usage` of the final event. A2A 1.0 has no `final` flag — terminal and interrupted states close the stream.
+- **Text-only boundary** for now: `SendMessage` rejects messages with non-text parts (file/url/data) with a failed task.
+- **No approval bridge**: dsh rc.7 has no mid-turn approval seam, so tools that would ask are governed by the profile's own approval setup; the A2A side never enters a mid-turn `input-required`.
+- **One in-flight message per task** is the supported flow (send the next message after the turn-final event). dsh serializes queued follow-ups into successive turns, but concurrent requests share one event bus — a second in-flight request may resolve with the first turn's final event.
+- **Restart**: persisted task shells survive in Redis/GCS, but live agents do not — continuing after a restart starts a fresh session (a client-supplied `contextId` names it).
+
+## Task stores
+
+A2A **task state** (status + metadata) is separate from conversation history — use [dsh-storage](../dsh-storage) for the latter. Every backend persists a sanitized metadata shell (history/artifacts stripped) and saves only on task-state transitions, so token-rate stream events never reach the backend.
+
+- `memory` (default) — in-process, lost on restart
+- `redis` — task JSON under `<keyPrefix>:tasks:<taskId>` with a TTL; requires the `ioredis` peer
+- `gcs` — gzipped task JSON at `<prefix>/<taskId>/metadata.json.gz` (same layout as the source project's `GCSTaskStore`); requires the `@google-cloud/storage` peer. `archiveWorkspace()` (tar of the workspace) exists but is not wired to the lifecycle yet.
+
+## Security
+
+dsh ships **no authentication or authorization**. The server binds `127.0.0.1` by default; if you expose it, put an authenticated reverse proxy in front and treat every agent as running with the host process's OS privileges.
+
+## 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}@0.1.0-rc.7`) — check the `TODO(verify)` markers in `src/` before upgrading dsh.
+
+## License
+
+MIT

package/cordis.patch.yml

@@ -0,0 +1,3 @@
+- insert:
+    - id: a2a
+      name: '@amaster.ai/dsh-a2a'

package/lib/bridge.js

@@ -0,0 +1,229 @@
+/**
+ * Bridges A2A tasks to dsh agents.
+ *
+ * One A2A task maps to one dsh session/agent; the A2A `contextId` IS the dsh
+ * sessionId. The bridge owns every agent it creates (the consumer-handle
+ * pattern dsh's own ACP bridge uses) and routes the durable `session/event`
+ * stream through a per-task {@link SessionTranslator} onto the executing
+ * request's {@link ExecutionEventBus}.
+ *
+ * Turn settlement: `agent.followup()` is fire-and-forget, so callers await a
+ * FIFO waiter resolved by the session's next `turn/end` event (dsh's inbox
+ * serializes queued follow-ups into successive turns, so waiter order matches
+ * turn order). The final status-update is published before the waiter
+ * resolves, so an execute() that returns always landed its events first.
+ */
+// installModelSelection is a root-module runtime import: the dsh-agent index
+// pulls workspace-internal packages (dsh-scope) that are absent from the
+// plugin's dev install, so unit tests vi.mock this module.
+import { installModelSelection } from '@deepseek-ai/dsh-agent';
+// Runtime helpers ride the clean subpaths: the dsh-llm/dsh-session index
+// modules import packages that are not on npm yet (dsh-timeout, dsh-scope).
+import { createUserMessage } from '@deepseek-ai/dsh-llm/message';
+import { SessionId } from '@deepseek-ai/dsh-session/types';
+import { SessionTranslator, terminalStatusUpdate } from './translator.js';
+export class A2aBridge {
+    ctx;
+    options;
+    tasks = new Map(); // taskId → entry
+    bySession = new Map(); // sessionId (== contextId) → entry
+    constructor(ctx, options) {
+        this.ctx = ctx;
+        this.options = options;
+        ctx.on('session/event', (session, event) => this.onSessionEvent(session, event));
+        ctx.on('session/disposed', (session) => this.onSessionDisposed(session));
+    }
+    /**
+     * Resolve the live task entry, creating the session/agent when needed.
+     * `freshTask` tells the executor to anchor the SDK's ResultManager with an
+     * initial Task event (status-updates for a task id the store never saw are
+     * dropped by it). Rebinding by bare contextId counts as fresh: the SDK mints
+     * a new task id for `message/send` calls that omit `taskId`.
+     */
+    async ensureTask(taskId, contextId) {
+        const existing = this.tasks.get(taskId);
+        if (existing)
+            return { entry: existing, freshTask: false };
+        const forContext = this.bySession.get(contextId);
+        if (forContext) {
+            this.tasks.delete(forContext.taskId);
+            forContext.taskId = taskId;
+            forContext.translator = new SessionTranslator(taskId, contextId, this.options.agentOptions?.model);
+            this.tasks.set(taskId, forContext);
+            return { entry: forContext, freshTask: true };
+        }
+        // TODO(verify): resuming a persisted session (agents.resume) after a
+        // restart — needs dsh's sessionPersistence service composed. For now a
+        // client-supplied contextId simply names the fresh session.
+        const sessionId = SessionId(contextId);
+        const selection = this.resolveSelection();
+        // The web profile disables the host-plane tool plugins — agents get tools
+        // only through a mounted agent preset (dsh-host-apiproxy's composeAgent is
+        // the reference: resolve the id up front so it lands on the session header,
+        // mount inside setup). Profiles without a preset roster (headless) keep
+        // host-plane tools and skip this entirely.
+        const presets = this.ctx.get('agentPresets');
+        let agentPreset;
+        if (presets) {
+            agentPreset = (await presets.resolve(this.options.preset || undefined)).id;
+        }
+        const handle = await this.ctx.agents.create({
+            sessionId,
+            meta: { cwd: this.options.cwd, ...(agentPreset ? { agentPreset } : {}) },
+            agentOptions: selection
+                ? { provider: selection.provider, model: selection.model }
+                : undefined,
+            // The loop's `{{model}}` prompt variable and request routing resolve from
+            // the agent's installed model selection (dsh-agent-loop's variables read
+            // agent.options; the scoped waterfalls wire provider/model into prompt
+            // assembly and the request config). Verified against
+            // @deepseek-ai/dsh-headless@0.1.0-rc.7's run() — entry points are
+            // expected to resolve the deployment default themselves.
+            setup: selection || agentPreset
+                ? async (agentCtx) => {
+                    if (selection) {
+                        // Statement, deliberately not returned: a returned disposer would
+                        // be invoked as the setup commit and immediately unwired. Likewise
+                        // the mount result must not escape — setup's return value is
+                        // commit()-shaped to the factory.
+                        installModelSelection(agentCtx, { current: selection, assembled: undefined });
+                    }
+                    if (agentPreset)
+                        await presets.mount(agentCtx, agentPreset);
+                }
+                : undefined,
+        });
+        const entry = {
+            taskId,
+            sessionId,
+            handle,
+            translator: new SessionTranslator(taskId, contextId, this.options.agentOptions?.model),
+            bus: null,
+            turnActive: false,
+            settled: [],
+        };
+        this.tasks.set(taskId, entry);
+        this.bySession.set(contextId, entry);
+        return { entry, freshTask: true };
+    }
+    /** Queue one user-message turn on the task's agent and await its `turn/end`. */
+    async runTurn(entry, text, bus) {
+        let resolveSettled;
+        const settled = new Promise((resolve) => {
+            resolveSettled = resolve;
+        });
+        entry.settled.push(resolveSettled);
+        entry.bus = bus;
+        try {
+            const result = entry.handle.agent.followup(createUserMessage({
+                content: [{ type: 'text', text }],
+                source: { kind: 'user' },
+            }));
+            // followup() is typed void; guard a mistyped async impl anyway — an
+            // unhandled rejection would crash the host process, and no turn/end
+            // would ever settle this waiter.
+            void Promise.resolve(result).catch((error) => {
+                const message = error instanceof Error ? error.message : String(error);
+                console.error('[dsh-a2a] followup failed:', error);
+                if (entry.bus === bus) {
+                    entry.bus.publish(terminalStatusUpdate(entry.taskId, entry.sessionId, 'failed', message));
+                }
+                resolveSettled();
+            });
+            // Never rejects: waiters only resolve. A synchronous followup() throw is
+            // the one failure path — it means no turn ever started, so pull this
+            // waiter back out of the FIFO before it can be settled by the NEXT
+            // turn's turn/end (which would resolve one execute() too early).
+            await settled;
+        }
+        catch (error) {
+            const index = entry.settled.indexOf(resolveSettled);
+            if (index >= 0)
+                entry.settled.splice(index, 1);
+            throw error;
+        }
+        finally {
+            if (entry.bus === bus)
+                entry.bus = null;
+        }
+    }
+    /** Abort the task's active turn; returns the contextId when the task is live. */
+    cancel(taskId) {
+        const entry = this.tasks.get(taskId);
+        if (!entry)
+            return undefined;
+        // cancel() is typed void; the guard keeps a mistyped async impl from
+        // crashing the host (the caller already published its canceled final).
+        void Promise.resolve(entry.handle.agent.cancel({ kind: 'user' })).catch((error) => console.error('[dsh-a2a] cancel failed:', error));
+        return entry.sessionId;
+    }
+    /** Dispose every owned agent (plugin unload / server shutdown). */
+    async dispose() {
+        const entries = [...this.tasks.values()];
+        this.tasks.clear();
+        this.bySession.clear();
+        for (const entry of entries) {
+            this.settleEntry(entry, 'Plugin unloaded.');
+            try {
+                await entry.handle.dispose();
+            }
+            catch (error) {
+                console.error('[dsh-a2a] failed to dispose agent:', error);
+            }
+        }
+    }
+    onSessionEvent(session, event) {
+        const entry = this.bySession.get(session.id);
+        if (!entry)
+            return;
+        if (event.type === 'turn/start')
+            entry.turnActive = true;
+        // No-throw seam: translation errors must never reach the agent loop. The
+        // turn/end waiter still resolves below, so a poisoned event cannot hang
+        // an in-flight execute() either.
+        try {
+            for (const out of entry.translator.handle(event))
+                entry.bus?.publish(out);
+        }
+        catch (error) {
+            console.error('[dsh-a2a] failed to translate session event:', error);
+        }
+        if (event.type === 'turn/end') {
+            entry.turnActive = false;
+            entry.settled.shift()?.();
+        }
+    }
+    onSessionDisposed(session) {
+        const entry = this.bySession.get(session.id);
+        if (!entry)
+            return;
+        this.tasks.delete(entry.taskId);
+        this.bySession.delete(session.id);
+        // A mid-turn disposal never emits turn/end — settle instead of hanging
+        // the in-flight execute() calls.
+        this.settleEntry(entry, 'Session disposed.');
+    }
+    /** Close an in-flight stream honestly and release every turn waiter. */
+    settleEntry(entry, message) {
+        if (entry.turnActive && entry.bus) {
+            entry.bus.publish(terminalStatusUpdate(entry.taskId, entry.sessionId, 'canceled', message));
+        }
+        entry.turnActive = false;
+        for (const resolve of entry.settled.splice(0))
+            resolve();
+    }
+    /**
+     * Config override wins per field; otherwise the deployment default read from
+     * the `agentDefaultModel` service (the entry-point contract — the loop
+     * itself does not apply it). Undefined when neither source has a pair
+     * (persona-less minimal compositions stay valid).
+     */
+    resolveSelection() {
+        const defaults = this.ctx.get('agentDefaultModel')?.currentSelection?.();
+        const provider = this.options.agentOptions?.provider || defaults?.provider;
+        const model = this.options.agentOptions?.model || defaults?.model;
+        if (!provider || !model)
+            return undefined;
+        return { provider, model, reasoningEffort: defaults?.reasoningEffort };
+    }
+}

package/lib/executor.js

@@ -0,0 +1,97 @@
+/**
+ * The @a2a-js/sdk {@link AgentExecutor} that drives dsh agents through the
+ * bridge. One `execute()` = one user-message turn:
+ *
+ *   1. extract the text prompt (v1 is text-only)
+ *   2. ensure the task's session/agent exists (creating it on first contact)
+ *   3. publish a `task` event first — A2A 1.0 stream ordering REQUIRES the
+ *      first event of every execute to be a task or message, including
+ *      follow-up turns on a known task (the ResultManager merges it with the
+ *      stored task; fresh tasks get the submitted anchor carrying the user
+ *      message, continuing tasks get a working snapshot)
+ *   4. run the turn; session events stream onto the bus via the bridge
+ *   5. on failure publish a failed statusUpdate (plus a failed task anchor if
+ *      none went out yet) instead of rethrowing — clients get the terminal
+ *      state in band on both blocking and streaming paths
+ *
+ * `cancelTask` is an arrow property because the SDK destructures it.
+ */
+import { TaskState } from '@a2a-js/sdk';
+import { AgentEvent } from '@a2a-js/sdk/server';
+import { agentTextMessage, terminalStatusUpdate } from './translator.js';
+export class DshAgentExecutor {
+    bridge;
+    constructor(bridge) {
+        this.bridge = bridge;
+    }
+    async execute(requestContext, eventBus) {
+        const { userMessage, taskId, contextId } = requestContext;
+        let anchored = false;
+        try {
+            const text = extractText(userMessage);
+            const { entry, freshTask } = await this.bridge.ensureTask(taskId, contextId);
+            eventBus.publish(freshTask
+                ? // First contact: the submitted anchor carries the user message
+                    // into the task history the ResultManager persists.
+                    taskEvent(taskId, contextId, TaskState.TASK_STATE_SUBMITTED, { history: [userMessage] })
+                : // Follow-up turn: a working snapshot satisfies the 1.0
+                    // stream-ordering rule; the ResultManager merges it with the
+                    // stored task (history/artifacts preserved).
+                    taskEvent(taskId, contextId, TaskState.TASK_STATE_WORKING));
+            anchored = true;
+            await this.bridge.runTurn(entry, text, eventBus);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            if (!anchored) {
+                eventBus.publish(taskEvent(taskId, contextId, TaskState.TASK_STATE_FAILED, {
+                    message: agentTextMessage(taskId, contextId, message),
+                }));
+            }
+            eventBus.publish(terminalStatusUpdate(taskId, contextId, 'failed', message));
+        }
+        finally {
+            eventBus.finished();
+        }
+    }
+    cancelTask = async (taskId, eventBus) => {
+        // The SDK only calls cancelTask while a bus for the task is live. The live
+        // path aborts the dsh turn (its turn/end also lands on the bus as a
+        // canceled statusUpdate via the translator — a harmless duplicate); the
+        // published event moves the persisted shell to canceled through the
+        // handler's ResultManager either way.
+        const contextId = this.bridge.cancel(taskId) ?? '';
+        eventBus.publish(terminalStatusUpdate(taskId, contextId, 'canceled', 'Task canceled by request.'));
+    };
+}
+/** One task event in the 1.0 model: the proto-required fields live here exactly once. */
+function taskEvent(taskId, contextId, state, extra = {}) {
+    const task = {
+        id: taskId,
+        contextId,
+        status: {
+            state,
+            message: extra.message,
+            timestamp: new Date().toISOString(),
+        },
+        history: extra.history ?? [],
+        artifacts: [],
+        metadata: undefined,
+    };
+    return AgentEvent.task(task);
+}
+// TODO(verify): non-text parts (file/raw/url/data) — dsh supports image
+// content blocks; map them when a client needs it. The confirmation data-part
+// protocol ({callId, outcome}) has no dsh rc.7 counterpart to bridge to.
+function extractText(message) {
+    const nonText = message.parts.filter((part) => part.content?.$case !== 'text');
+    if (nonText.length > 0) {
+        throw new Error(`dsh-a2a: unsupported part kind(s): ${nonText.map((part) => part.content?.$case ?? 'unknown').join(', ')} (text-only)`);
+    }
+    const text = message.parts
+        .map((part) => (part.content?.$case === 'text' ? part.content.value : ''))
+        .join('');
+    if (!text.trim())
+        throw new Error('dsh-a2a: message must contain at least one text part');
+    return text;
+}

package/lib/index.js

@@ -0,0 +1,130 @@
+/**
+ * dsh-a2a — exposes DeepSeek Harness agents over the A2A protocol.
+ *
+ * Plugin shape mirrors dsh's own ACP bridge (packages/acp/acp in the dsh
+ * repo): the plugin owns the agents it creates, serves a protocol endpoint
+ * for the process lifetime, and disposes everything on unload.
+ *
+ * Security note: dsh ships no authn/authz. This plugin binds 127.0.0.1 by
+ * default; put a real authentication layer in front before exposing it
+ * beyond loopback.
+ *
+ * @module dsh-a2a
+ */
+import { InMemoryTaskStore } from '@a2a-js/sdk/server';
+import Schema from '@deepseek-ai/schemastery';
+import { A2aBridge } from './bridge.js';
+import { DshAgentExecutor } from './executor.js';
+import { startA2aServer } from './server.js';
+import { GcsTaskStore } from './stores/gcs.js';
+import { RedisTaskStore } from './stores/redis.js';
+import { SanitizedTaskStore } from './task-store.js';
+export const name = 'dsh-a2a';
+/** The bridge creates and owns agents through the registry service. */
+export const inject = ['agents'];
+export const Config = Schema.object({
+    enabled: Schema.boolean().default(false),
+    host: Schema.string().default('127.0.0.1'),
+    port: Schema.natural().default(41241),
+    basePath: Schema.string().default('/a2a'),
+    /** Working directory for agents spawned by A2A tasks. Must be absolute. */
+    cwd: Schema.string().default(process.cwd()),
+    agent: Schema.object({
+        provider: Schema.string().default(''),
+        model: Schema.string().default(''),
+        /**
+         * Agent preset to mount per task (empty = the deployment default when the
+         * profile composes a preset roster). The web profile keeps tools inside
+         * presets — without one the agent sees an empty tool catalog.
+         */
+        preset: Schema.string().default(''),
+    }),
+    card: Schema.object({
+        name: Schema.string().default('dsh-a2a-agent'),
+        description: Schema.string().default('DeepSeek Harness agent over A2A'),
+        version: Schema.string().default('0.1.0'),
+        publicUrl: Schema.string().default(''),
+    }),
+    /**
+     * A2A task state store (task metadata only — conversation history is
+     * dsh-storage's ai_messages, not this). 'memory' loses tasks on restart.
+     */
+    taskStore: Schema.union([
+        Schema.const('memory'),
+        Schema.const('redis'),
+        Schema.const('gcs'),
+    ]).default('memory'),
+    redis: Schema.object({
+        url: Schema.string().role('secret').default('redis://127.0.0.1:6379'),
+        keyPrefix: Schema.string().default('a2a'),
+        ttlSeconds: Schema.natural().default(86400),
+    }),
+    gcs: Schema.object({
+        bucket: Schema.string().default(''),
+        prefix: Schema.string().default('tasks'),
+        keyFilename: Schema.string().default(''),
+    }),
+});
+export function apply(ctx, config) {
+    if (!config.enabled)
+        return;
+    // This cordis fork has no ready/dispose events: startup runs inside
+    // ctx.effect() (executed at fiber load) and its returned disposer runs on
+    // fiber unload. apply() returns the startup promise so fiber readiness
+    // covers the bind.
+    let ready;
+    let serverPort = 0;
+    ctx.effect(() => {
+        const startup = start();
+        ready = startup.then(() => ({ port: serverPort }));
+        return startup;
+    });
+    return ready;
+    async function start() {
+        const bridge = new A2aBridge(ctx, {
+            cwd: config.cwd,
+            agentOptions: {
+                provider: config.agent.provider || undefined,
+                model: config.agent.model || undefined,
+            },
+            preset: config.agent.preset || undefined,
+        });
+        const store = createTaskStore(config);
+        await store.init?.();
+        const executor = new DshAgentExecutor(bridge);
+        const server = await startA2aServer({
+            host: config.host,
+            port: config.port,
+            basePath: config.basePath,
+            card: {
+                name: config.card.name,
+                description: config.card.description,
+                version: config.card.version,
+                publicUrl: config.card.publicUrl || undefined,
+            },
+            executor,
+            taskStore: store,
+        });
+        serverPort = server.port;
+        console.log(`[dsh-a2a] A2A endpoint: http://${config.host}:${server.port}${config.basePath}/ ` +
+            `(agent card: /.well-known/agent-card.json)`);
+        return async () => {
+            await server.close();
+            await bridge.dispose();
+            await store.close?.();
+        };
+    }
+}
+function createTaskStore(config) {
+    switch (config.taskStore) {
+        case 'redis':
+            return new SanitizedTaskStore(new RedisTaskStore(config.redis));
+        case 'gcs':
+            if (!config.gcs.bucket) {
+                throw new Error("[dsh-a2a] taskStore 'gcs' requires gcs.bucket");
+            }
+            return new SanitizedTaskStore(new GcsTaskStore(config.gcs));
+        default:
+            return new SanitizedTaskStore(new InMemoryTaskStore());
+    }
+}

package/lib/server.js

@@ -0,0 +1,82 @@
+/**
+ * HTTP layer: the @a2a-js/sdk Express middlewares on a plain Express app.
+ *
+ * - `GET /.well-known/agent-card.json` (and the legacy `agent.json` alias) —
+ *   agent card, via the SDK's `agentCardHandler`
+ * - `POST <basePath>/` — JSON-RPC: A2A 1.0 methods (`SendMessage`,
+ *   `SendStreamingMessage`, `GetTask`, `ListTasks`, `CancelTask`,
+ *   `SubscribeToTask`, ...) plus the v0.3 spellings (`message/send`, ...)
+ *   through the SDK's opt-in legacyCompat layer
+ *
+ * The SSE framing and error envelopes are the SDK's; this layer only binds
+ * the server and builds the card.
+ */
+import { createServer } from 'node:http';
+import { A2A_PROTOCOL_VERSION, AGENT_CARD_PATH, } from '@a2a-js/sdk';
+import { duplicateInterfacesForLegacy } from '@a2a-js/sdk/compat/v0_3';
+import { DefaultRequestHandler } from '@a2a-js/sdk/server';
+import { agentCardHandler, jsonRpcHandler, UserBuilder } from '@a2a-js/sdk/server/express';
+import express from 'express';
+export async function startA2aServer(options) {
+    const base = options.basePath.replace(/\/$/, '');
+    const publicUrl = (options.card.publicUrl ?? `http://${options.host}:${options.port}`).replace(/\/$/, '');
+    const interfaces = [
+        {
+            url: `${publicUrl}${base}/`,
+            protocolBinding: 'JSONRPC',
+            tenant: '',
+            protocolVersion: A2A_PROTOCOL_VERSION,
+        },
+    ];
+    const card = {
+        name: options.card.name,
+        description: options.card.description,
+        version: options.card.version,
+        // The v0.3 mirror entries let pre-1.0 clients keep working through the
+        // legacyCompat layer (they discover the card without an A2A-Version header).
+        supportedInterfaces: duplicateInterfacesForLegacy(interfaces, ['JSONRPC']),
+        provider: undefined,
+        capabilities: {
+            streaming: true,
+            pushNotifications: false,
+            extensions: [],
+            extendedAgentCard: false,
+        },
+        securitySchemes: {},
+        securityRequirements: [],
+        defaultInputModes: ['text'],
+        defaultOutputModes: ['text'],
+        skills: [],
+        signatures: [],
+    };
+    const requestHandler = new DefaultRequestHandler(card, options.taskStore, options.executor);
+    const app = express();
+    // The SDK's jsonRpcHandler parses bodies with express.json()'s 100kb default;
+    // raise the ceiling here — body-parser skips re-parsing an already-read body.
+    app.use(express.json({ limit: '16mb' }));
+    const cardHandler = agentCardHandler({
+        agentCardProvider: requestHandler,
+        legacyCompat: { enabled: true },
+    });
+    app.use(`/${AGENT_CARD_PATH}`, cardHandler);
+    // Pre-1.0 discovery path, kept as a convenience alias.
+    app.use('/.well-known/agent.json', cardHandler);
+    // dsh ships no authn/authz — the loopback default binding is the boundary.
+    app.use(base, jsonRpcHandler({
+        requestHandler,
+        userBuilder: UserBuilder.noAuthentication,
+        legacyCompat: { enabled: true },
+    }));
+    const server = createServer(app);
+    await new Promise((resolve, reject) => {
+        server.once('error', reject);
+        server.listen(options.port, options.host, () => resolve());
+    });
+    return {
+        port: server.address().port,
+        close: () => new Promise((resolve) => {
+            server.closeAllConnections?.();
+            server.close(() => resolve());
+        }),
+    };
+}