@amaster.ai/dsh-a2a 0.1.0

package/lib/types/index.d.ts

@@ -0,0 +1,171 @@
+/**
+ * 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 type { Context } from '@deepseek-ai/cordis';
+import Schema from '@deepseek-ai/schemastery';
+export declare const name = "dsh-a2a";
+/** The bridge creates and owns agents through the registry service. */
+export declare const inject: string[];
+export declare const Config: Schema<Schemastery.ObjectS<{
+    enabled: Schema<boolean, boolean>;
+    host: Schema<string, string>;
+    port: Schema<number, number>;
+    basePath: Schema<string, string>;
+    /** Working directory for agents spawned by A2A tasks. Must be absolute. */
+    cwd: Schema<string, string>;
+    agent: Schema<Schemastery.ObjectS<{
+        provider: Schema<string, string>;
+        model: Schema<string, string>;
+        /**
+         * 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, string>;
+    }>, Schemastery.ObjectT<{
+        provider: Schema<string, string>;
+        model: Schema<string, string>;
+        /**
+         * 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, string>;
+    }>>;
+    card: Schema<Schemastery.ObjectS<{
+        name: Schema<string, string>;
+        description: Schema<string, string>;
+        version: Schema<string, string>;
+        publicUrl: Schema<string, string>;
+    }>, Schemastery.ObjectT<{
+        name: Schema<string, string>;
+        description: Schema<string, string>;
+        version: Schema<string, string>;
+        publicUrl: Schema<string, string>;
+    }>>;
+    /**
+     * A2A task state store (task metadata only — conversation history is
+     * dsh-storage's ai_messages, not this). 'memory' loses tasks on restart.
+     */
+    taskStore: Schema<"memory" | "redis" | "gcs", "memory" | "redis" | "gcs">;
+    redis: Schema<Schemastery.ObjectS<{
+        url: Schema<string, string>;
+        keyPrefix: Schema<string, string>;
+        ttlSeconds: Schema<number, number>;
+    }>, Schemastery.ObjectT<{
+        url: Schema<string, string>;
+        keyPrefix: Schema<string, string>;
+        ttlSeconds: Schema<number, number>;
+    }>>;
+    gcs: Schema<Schemastery.ObjectS<{
+        bucket: Schema<string, string>;
+        prefix: Schema<string, string>;
+        keyFilename: Schema<string, string>;
+    }>, Schemastery.ObjectT<{
+        bucket: Schema<string, string>;
+        prefix: Schema<string, string>;
+        keyFilename: Schema<string, string>;
+    }>>;
+}>, Schemastery.ObjectT<{
+    enabled: Schema<boolean, boolean>;
+    host: Schema<string, string>;
+    port: Schema<number, number>;
+    basePath: Schema<string, string>;
+    /** Working directory for agents spawned by A2A tasks. Must be absolute. */
+    cwd: Schema<string, string>;
+    agent: Schema<Schemastery.ObjectS<{
+        provider: Schema<string, string>;
+        model: Schema<string, string>;
+        /**
+         * 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, string>;
+    }>, Schemastery.ObjectT<{
+        provider: Schema<string, string>;
+        model: Schema<string, string>;
+        /**
+         * 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, string>;
+    }>>;
+    card: Schema<Schemastery.ObjectS<{
+        name: Schema<string, string>;
+        description: Schema<string, string>;
+        version: Schema<string, string>;
+        publicUrl: Schema<string, string>;
+    }>, Schemastery.ObjectT<{
+        name: Schema<string, string>;
+        description: Schema<string, string>;
+        version: Schema<string, string>;
+        publicUrl: Schema<string, string>;
+    }>>;
+    /**
+     * A2A task state store (task metadata only — conversation history is
+     * dsh-storage's ai_messages, not this). 'memory' loses tasks on restart.
+     */
+    taskStore: Schema<"memory" | "redis" | "gcs", "memory" | "redis" | "gcs">;
+    redis: Schema<Schemastery.ObjectS<{
+        url: Schema<string, string>;
+        keyPrefix: Schema<string, string>;
+        ttlSeconds: Schema<number, number>;
+    }>, Schemastery.ObjectT<{
+        url: Schema<string, string>;
+        keyPrefix: Schema<string, string>;
+        ttlSeconds: Schema<number, number>;
+    }>>;
+    gcs: Schema<Schemastery.ObjectS<{
+        bucket: Schema<string, string>;
+        prefix: Schema<string, string>;
+        keyFilename: Schema<string, string>;
+    }>, Schemastery.ObjectT<{
+        bucket: Schema<string, string>;
+        prefix: Schema<string, string>;
+        keyFilename: Schema<string, string>;
+    }>>;
+}>>;
+export interface A2aPluginConfig {
+    enabled: boolean;
+    host: string;
+    port: number;
+    basePath: string;
+    cwd: string;
+    agent: {
+        provider: string;
+        model: string;
+        preset: string;
+    };
+    card: {
+        name: string;
+        description: string;
+        version: string;
+        publicUrl: string;
+    };
+    taskStore: 'memory' | 'redis' | 'gcs';
+    redis: {
+        url: string;
+        keyPrefix: string;
+        ttlSeconds: number;
+    };
+    gcs: {
+        bucket: string;
+        prefix: string;
+        keyFilename: string;
+    };
+}
+export declare function apply(ctx: Context, config: A2aPluginConfig): Promise<{
+    port: number;
+}> | undefined;

package/lib/types/server.d.ts

@@ -0,0 +1,34 @@
+/**
+ * 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 { type AgentExecutor, type TaskStore } from '@a2a-js/sdk/server';
+export interface A2aServerOptions {
+    host: string;
+    port: number;
+    basePath: string;
+    card: {
+        name: string;
+        description: string;
+        version: string;
+        /** Public base URL advertised in the card, e.g. https://agent.example.com */
+        publicUrl?: string;
+    };
+    executor: AgentExecutor;
+    taskStore: TaskStore;
+}
+export interface A2aServer {
+    /** The bound port (differs from options.port when 0). */
+    port: number;
+    close(): Promise<void>;
+}
+export declare function startA2aServer(options: A2aServerOptions): Promise<A2aServer>;

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

@@ -0,0 +1,37 @@
+/**
+ * GCS TaskStore for @a2a-js/sdk. `@google-cloud/storage` is an optional peer.
+ *
+ * Ported from the source project's packages/a2a-server/src/persistence/gcs.ts:
+ *   tasks/{taskId}/metadata.json.gz  — gzipped task state (pre-sanitized by
+ *                                      SanitizedTaskStore: no history)
+ *   tasks/{taskId}/workspace.tar.gz  — tar of the task's workspace directory
+ *
+ * The workspace archive is written explicitly via `archiveWorkspace()` (not
+ * wired to any lifecycle event yet — A2A tasks share one configured cwd, so a
+ * per-task snapshot needs a per-task workspace story first).
+ */
+import type { ListTasksRequest, ListTasksResponse, Task } from '@a2a-js/sdk';
+import type { TaskStore } from '@a2a-js/sdk/server';
+export interface GcsTaskStoreConfig {
+    bucket: string;
+    /** Object key prefix, default 'tasks' (matches the source layout). */
+    prefix?: string;
+    /** Path to a service-account key file; omit to use ADC. */
+    keyFilename?: string;
+}
+export declare class GcsTaskStore implements TaskStore {
+    private config;
+    private bucket;
+    private prefix;
+    constructor(config: GcsTaskStoreConfig);
+    init(): Promise<void>;
+    save(task: Task): Promise<void>;
+    load(taskId: string): Promise<Task | undefined>;
+    list(params: ListTasksRequest): Promise<ListTasksResponse>;
+    /**
+     * Tar + gzip the workspace directory to `tasks/{taskId}/workspace.tar.gz`.
+     * TODO: replace the tar subprocess with a streaming tar library (e.g. `tar`)
+     * to control inclusion and avoid shelling out.
+     */
+    archiveWorkspace(taskId: string, cwd: string): Promise<void>;
+}

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

@@ -0,0 +1,28 @@
+/**
+ * Redis TaskStore for @a2a-js/sdk. `ioredis` is an optional peer dependency.
+ *
+ * Ported from the source project's packages/a2a-server/src/persistence/redis.ts:
+ * task state JSON under `a2a:tasks:{taskId}` with a TTL. Tasks arrive
+ * pre-sanitized (metadata shell, no history) from SanitizedTaskStore —
+ * conversation history is dsh-storage's job (ai_messages), not this store's.
+ */
+import type { ListTasksRequest, ListTasksResponse, Task } from '@a2a-js/sdk';
+import type { TaskStore } from '@a2a-js/sdk/server';
+export interface RedisTaskStoreConfig {
+    url: string;
+    keyPrefix?: string;
+    ttlSeconds?: number;
+}
+export declare class RedisTaskStore implements TaskStore {
+    private readonly config;
+    private redis;
+    private readonly prefix;
+    private readonly ttl;
+    constructor(config: RedisTaskStoreConfig);
+    init(): Promise<void>;
+    private taskKey;
+    save(task: Task): Promise<void>;
+    load(taskId: string): Promise<Task | undefined>;
+    list(params: ListTasksRequest): Promise<ListTasksResponse>;
+    close(): Promise<void>;
+}

package/lib/types/task-store.d.ts

@@ -0,0 +1,45 @@
+/**
+ * TaskStore boundary for the SDK's DefaultRequestHandler.
+ *
+ * The SDK's ResultManager calls `taskStore.save()` on EVERY task/statusUpdate
+ * event — including each streamed text delta — and folds status messages into
+ * `task.history`. Two constraints follow from this plugin's design:
+ *
+ * 1. A2A stores carry task STATE only (task metadata ≠ conversation history —
+ *    history is dsh-storage's `ai_messages`). {@link sanitizeTask} strips
+ *    `history`/`artifacts` before anything reaches a backend.
+ * 2. Token-rate saves would hammer Redis and put a GCS upload in the hot path
+ *    of the SSE stream (ResultManager awaits every save). {@link
+ *    SanitizedTaskStore} collapses saves to task-state CHANGES, which are the
+ *    only transitions a `tasks/get` reader can act on anyway.
+ *
+ * A2A 1.0 added `list()` to the TaskStore contract; {@link listShells} holds
+ * the shared filter/sort/paginate logic so the backends only enumerate shells.
+ */
+import type { ListTasksRequest, ListTasksResponse, Task } from '@a2a-js/sdk';
+import type { ServerCallContext, TaskStore } from '@a2a-js/sdk/server';
+/** The persistent shape: a metadata shell with empty history/artifacts. */
+export declare function sanitizeTask(task: Task): Task;
+/** TaskStore with the optional lifecycle our backends add. */
+export interface ManagedTaskStore extends TaskStore {
+    init?(): Promise<void>;
+    close?(): Promise<void>;
+}
+/** Strips history/artifacts and saves only on task-state transitions. */
+export declare class SanitizedTaskStore implements ManagedTaskStore {
+    private readonly inner;
+    private readonly lastState;
+    constructor(inner: ManagedTaskStore);
+    init(): Promise<void>;
+    close(): Promise<void>;
+    save(task: Task, context: ServerCallContext): Promise<void>;
+    load(taskId: string, context: ServerCallContext): Promise<Task | undefined>;
+    list(params: ListTasksRequest, context: ServerCallContext): Promise<ListTasksResponse>;
+}
+/**
+ * Shared `listTasks` semantics for the backends: filter by contextId / status /
+ * statusTimestampAfter (strictly greater), newest status first, cursor-paginated
+ * (base64 "timestamp|id"; a well-formed but unknown cursor yields an empty page,
+ * a malformed token throws). Follows the SDK's InMemoryTaskStore.
+ */
+export declare function listShells(shells: Task[], params: ListTasksRequest): ListTasksResponse;

package/lib/types/translator.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Pure translation layer: dsh session events → A2A protocol events.
+ *
+ * One {@link SessionTranslator} serves one A2A task (one dsh session). It is
+ * deliberately free of cordis/HTTP concerns so the mapping is unit-testable
+ * without a harness. The mapping ports the source project's
+ * `packages/a2a-server/src/agent/task.ts` event switch onto dsh's
+ * `SessionEventMap` (verified against @deepseek-ai/dsh-session@0.1.0-rc.7),
+ * emitting the A2A 1.0 data model (@a2a-js/sdk 1.1.0):
+ *
+ *   turn/start                         → statusUpdate(WORKING), ids rotate
+ *   assistant/chunk (text-delta)       → statusUpdate(WORKING, text part),
+ *                                        reusing the turn's messageId so
+ *                                        clients aggregate deltas into one message
+ *   assistant/chunk (reasoning-delta)  → statusUpdate(WORKING, thought metadata)
+ *   assistant/message                  → no event; text + usage captured for the
+ *                                        turn-final message (blocking `SendMessage`
+ *                                        clients read the answer from the final
+ *                                        task status, not from streamed deltas)
+ *   tool/call                          → statusUpdate(WORKING, data part)
+ *   tool/result                        → statusUpdate(WORKING, data part)
+ *   turn/end completed | max-tokens    → statusUpdate(INPUT_REQUIRED) — the task
+ *                                        is a conversation and stays continuable
+ *                                        (COMPLETED is terminal in A2A and the SDK
+ *                                        refuses follow-ups to terminal tasks)
+ *   turn/end aborted                   → statusUpdate(CANCELED)
+ *   turn/end blocked | error           → statusUpdate(FAILED)
+ *   everything else                    → no event
+ *
+ * A2A 1.0 removed the `final` flag: the SDK's event queue stops on terminal
+ * and interrupted (input-required) states, which is exactly the set above.
+ *
+ * dsh rc.7 has no approval/`input-required` mid-turn seam (the unpublished
+ * dsh-user-approval package is not installed anywhere; `tools/pre-execute`'s
+ * `ask` degrades to deny without an approval service), so no approval bridge
+ * exists here. TODO(verify) when dsh ships one.
+ */
+import { type Message } from '@a2a-js/sdk';
+import { type AgentExecutionEvent } from '@a2a-js/sdk/server';
+import type { SessionEvent } from '@deepseek-ai/dsh-session';
+/** One agent-role text message — the single construction site for the plugin's message payloads. */
+export declare function agentTextMessage(taskId: string, contextId: string, text: string, messageId?: string): Message;
+/** A terminal (stream-closing) statusUpdate — shared by the bridge's settle path and the executor's failure/cancel paths. */
+export declare function terminalStatusUpdate(taskId: string, contextId: string, state: 'canceled' | 'failed', text: string): AgentExecutionEvent;
+export declare class SessionTranslator {
+    private readonly taskId;
+    private readonly contextId;
+    private readonly model?;
+    /** messageId shared by this turn's streamed text deltas (client-side aggregation key). */
+    private textMessageId;
+    private thoughtMessageId;
+    /** Authoritative turn text, assembled from `assistant/message` events. */
+    private turnText;
+    /** Fallback turn text, accumulated from `text-delta` chunks. */
+    private deltaText;
+    private sawAssistantMessage;
+    private usage;
+    /** callId → tool name, for naming `tool/result` payloads. */
+    private readonly toolNames;
+    constructor(taskId: string, contextId: string, model?: string | undefined);
+    /** Translate one session event into zero or more A2A events. Never throws on unknown types. */
+    handle(event: SessionEvent): AgentExecutionEvent[];
+    private turnEnd;
+    private status;
+    private dataMessage;
+}

package/package.json

@@ -0,0 +1,75 @@
+{
+  "name": "@amaster.ai/dsh-a2a",
+  "version": "0.1.0",
+  "description": "A2A protocol (JSON-RPC + SSE) server plugin for DeepSeek Harness: expose dsh agents as A2A agents.",
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "cordis.patch.yml",
+    "preview.png"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/TGYD-helige/dsh-plugins.git",
+    "directory": "packages/dsh-a2a"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "dependencies": {
+    "@a2a-js/sdk": "^1.1.0",
+    "@deepseek-ai/schemastery": "^3.18.1",
+    "express": "^4.21.0"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-agent": "0.1.0-rc.7",
+    "@deepseek-ai/dsh-llm": "0.1.0-rc.7",
+    "@deepseek-ai/dsh-session": "0.1.0-rc.7",
+    "@google-cloud/storage": "^7.0.0",
+    "ioredis": "^5.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@google-cloud/storage": {
+      "optional": true
+    },
+    "ioredis": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-agent": "0.1.0-rc.7",
+    "@deepseek-ai/dsh-llm": "0.1.0-rc.7",
+    "@deepseek-ai/dsh-session": "0.1.0-rc.7",
+    "@google-cloud/storage": "^7.0.0",
+    "@types/express": "^4.17.21",
+    "@types/node": "^22.0.0",
+    "ioredis": "^5.0.0",
+    "typescript": "^5.6.3",
+    "vitest": "^4.1.11"
+  },
+  "engines": {
+    "node": "^20.19 || ^22.12 || >=24.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  }
+}