@hanphone/dsh-a2a 0.1.0

package/package.json

@@ -0,0 +1,82 @@
+{
+  "name": "@hanphone/dsh-a2a",
+  "version": "0.1.0",
+  "description": "Agent2Agent (A2A) v1.0 dual-end plugin for DeepSeek Harness: governed inbound tasks, durable task store, pluggable executors, multi-agent outbound consumption, GUI management dashboard.",
+  "type": "module",
+  "license": "MIT",
+  "keywords": [
+    "deepseek-harness",
+    "dsh",
+    "a2a",
+    "agent2agent",
+    "cordis",
+    "ai-agent",
+    "plugin"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/HanphoneJan/dsh-a2a.git"
+  },
+  "homepage": "https://github.com/HanphoneJan/dsh-a2a#readme",
+  "bugs": {
+    "url": "https://github.com/HanphoneJan/dsh-a2a/issues"
+  },
+  "files": [
+    "lib",
+    "src",
+    "cordis.patch.yml",
+    "README.md",
+    "README.zh.md"
+  ],
+  "main": "./lib/index.js",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./client": {
+      "types": "./lib/types/client/index.d.ts",
+      "default": "./lib/client.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "inject": [
+        "@deepseek-ai/dsh-client-ui-renderer",
+        "@deepseek-ai/dsh-client-ui-settings",
+        "@deepseek-ai/dsh-client-ui-slots"
+      ],
+      "platform": "web"
+    }
+  },
+  "//peers": "A2A runs inside a DSH harness composition: the host provides these. Local typecheck resolves them through tsconfig paths to the harness checkout, not from node_modules.",
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "4.0.2",
+    "@deepseek-ai/dsh-commands": "*",
+    "@deepseek-ai/dsh-storage-domain": "*",
+    "@deepseek-ai/schemastery": "3.*"
+  },
+  "dependencies": {
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.0",
+    "@types/react": "^18.3.31",
+    "react": "^18.3.1",
+    "tsdown": "^0.22.2",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.8"
+  },
+  "scripts": {
+    "build": "tsc -b tsconfig.json && tsc -p tsconfig.client.json && tsdown && node scripts/build-client.mjs",
+    "typecheck": "tsc -b tsconfig.json && tsc -p tsconfig.client.json",
+    "test": "vitest run"
+  }
+}

package/src/api.ts

@@ -0,0 +1,115 @@
+/**
+ * GUI control API for the A2A settings dashboard: one `GET /a2a/api`
+ * snapshot plus `POST /a2a/api` control actions (server toggle, outbound
+ * agent management, task view). The browser half talks only to this route;
+ * it carries no protocol knowledge. Loopback-only by default so the
+ * dashboard cannot be driven from the wire.
+ *
+ * The route body is bound to the same `A2AServiceImpl` facade the `/a2a`
+ * command surface uses, so GUI actions and commands cannot disagree.
+ * @module dsh-a2a/api
+ */
+
+import type { IncomingMessage, ServerResponse } from 'node:http'
+import type { A2AServiceImpl } from './service.ts'
+
+/** Control actions the dashboard can issue. */
+export type ApiAction =
+  | { readonly action: 'server.enable' | 'server.disable' }
+  | { readonly action: 'agent.add'; readonly name: string; readonly agentCardUrl: string; readonly bearerTokenEnv?: string }
+  | { readonly action: 'agent.remove' | 'agent.enable' | 'agent.disable' | 'agent.refresh'; readonly id: string }
+  | { readonly action: 'task.cancel'; readonly id: string }
+
+/** One snapshot of the whole plugin for the dashboard. */
+export interface ApiSnapshot {
+  readonly server: { readonly enabled: boolean; readonly cardUrl?: string; readonly skills: readonly string[] }
+  readonly tasks: readonly unknown[]
+  readonly agents: readonly unknown[]
+}
+
+function readBody(req: IncomingMessage): Promise<string> {
+  return new Promise<string>((resolve, reject) => {
+    const chunks: Buffer[] = []
+    req.on('data', (chunk: Buffer) => chunks.push(chunk))
+    req.on('end', () => resolve(Buffer.concat(chunks).toString('utf8')))
+    req.once('error', reject)
+  })
+}
+
+/** The caller is the local machine (never a remote peer). */
+function isLoopback(req: IncomingMessage): boolean {
+  const address = req.socket?.remoteAddress
+  return address === '127.0.0.1' || address === '::1' || address === '::ffff:127.0.0.1'
+}
+
+function json(res: ServerResponse, status: number, value: unknown): void {
+  res.writeHead(status, { 'content-type': 'application/json', 'cache-control': 'no-cache' })
+  res.end(JSON.stringify(value))
+}
+
+/** Handle one dashboard API request against the service facade. */
+export async function handleApiRequest(
+  req: IncomingMessage,
+  res: ServerResponse,
+  impl: A2AServiceImpl,
+): Promise<void> {
+  if (!isLoopback(req)) {
+    res.writeHead(403, { 'content-type': 'text/plain' })
+    res.end('forbidden')
+    return
+  }
+  if (req.method === 'GET') {
+    json(res, 200, snapshotOf(impl))
+    return
+  }
+  if (req.method === 'POST') {
+    let payload: ApiAction
+    try {
+      payload = JSON.parse(await readBody(req)) as ApiAction
+    } catch {
+      json(res, 400, { ok: false, message: 'invalid JSON body' })
+      return
+    }
+    const result = await dispatch(payload, impl)
+    json(res, result.ok ? 200 : 409, result)
+    return
+  }
+  res.writeHead(405, { 'content-type': 'text/plain' })
+  res.end('Method Not Allowed')
+}
+
+function snapshotOf(impl: A2AServiceImpl): ApiSnapshot {
+  const status = impl.status() as {
+    server: { enabled: boolean; cardUrl?: string; skills: readonly string[] }
+    tasks: number
+    agents: readonly unknown[]
+  }
+  return {
+    server: status.server,
+    tasks: impl.listTasks() as readonly unknown[],
+    agents: impl.agents() as readonly unknown[],
+  }
+}
+
+async function dispatch(payload: ApiAction, impl: A2AServiceImpl): Promise<{ readonly ok: boolean; readonly message: string }> {
+  switch (payload.action) {
+    case 'server.enable':
+      return impl.enableServer(true)
+    case 'server.disable':
+      return impl.enableServer(false)
+    case 'agent.add':
+      return impl.addAgent({ name: payload.name, agentCardUrl: payload.agentCardUrl, ...(payload.bearerTokenEnv ? { bearerTokenEnv: payload.bearerTokenEnv } : {}) })
+    case 'agent.remove':
+      return impl.removeAgent(payload.id)
+    case 'agent.enable':
+      return impl.setAgentEnabled(payload.id, true)
+    case 'agent.disable':
+      return impl.setAgentEnabled(payload.id, false)
+    case 'agent.refresh':
+      return impl.refreshAgentCard(payload.id)
+    case 'task.cancel':
+      return impl.cancelTask(payload.id)
+    default:
+      return { ok: false, message: `unknown action ${String((payload as { action?: unknown }).action)}` }
+  }
+}

package/src/client/index.ts

@@ -0,0 +1,293 @@
+/**
+ * A2A settings dashboard — browser half.
+ *
+ * Registers one `settings.section` ("A2A 连接") listing who is connected TO
+ * this DSH (inbound server state + tasks) and who this DSH is connected TO
+ * (outbound agents), with per-agent controls (enable/disable/remove/refresh)
+ * and the inbound-server toggle. All data and controls live behind the host's
+ * loopback-only `/a2a/api` route (src/api.ts); this half is a thin read/write
+ * client with no protocol knowledge and no direct storage access.
+ *
+ * Styling: one idempotent `<style>` injector built on the product's
+ * `--dsw-alias-*` design tokens so light/dark themes follow the DSH shell.
+ * No inline styles.
+ * @module dsh-a2a/client
+ */
+
+import type { Context as ClientContext } from '@deepseek-ai/cordis'
+import type {} from '@deepseek-ai/dsh-client-ui-renderer/client'
+import type {} from '@deepseek-ai/dsh-client-ui-settings/client'
+import type { PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots'
+import { createElement, useEffect, useState, type ReactElement } from 'react'
+
+/** Services this plugin needs from the client runtime. */
+export const inject = ['slots']
+
+const NS = 'a2a'
+
+function injectStyles(): () => void {
+  const tag = document.createElement('style')
+  tag.dataset.plugin = NS
+  tag.dataset.pluginCss = `${NS}/dashboard`
+  tag.textContent = `
+.dsh-a2a-panel { display: flex; flex-direction: column; gap: 16px; padding: 12px 0; }
+.dsh-a2a-card { border: 1px solid var(--dsw-alias-border, #d0d7de); border-radius: 8px; padding: 12px 14px; }
+.dsh-a2a-card h3 { margin: 0 0 8px; font-size: 14px; }
+.dsh-a2a-row { display: flex; align-items: center; gap: 8px; margin: 4px 0; }
+.dsh-a2a-row .muted { color: var(--dsw-alias-text-secondary, #59636e); font-size: 12px; }
+.dsh-a2a-row button { padding: 2px 10px; border-radius: 6px; border: 1px solid var(--dsw-alias-border, #d0d7de); background: transparent; cursor: pointer; }
+.dsh-a2a-row button.primary { background: var(--dsw-alias-accent, #0f6); color: var(--dsw-alias-bg, #fff); border-color: transparent; }
+.dsh-a2a-state { font-weight: 600; font-size: 12px; padding: 1px 8px; border-radius: 10px; }
+.dsh-a2a-state.ok { background: #1a7f3722; color: #1a7f37; }
+.dsh-a2a-state.bad { background: #d1242f22; color: #d1242f; }
+.dsh-a2a-form { display: flex; gap: 6px; margin: 8px 0; flex-wrap: wrap; }
+.dsh-a2a-form input { padding: 4px 8px; border-radius: 6px; border: 1px solid var(--dsw-alias-border, #d0d7de); background: transparent; color: inherit; }
+.dsh-a2a-table { width: 100%; border-collapse: collapse; font-size: 13px; }
+.dsh-a2a-table th, .dsh-a2a-table td { text-align: left; padding: 4px 8px; border-bottom: 1px solid var(--dsw-alias-border, #d0d7de); }
+.dsh-a2a-error { color: #d1242f; font-size: 12px; }
+`
+  document.head.appendChild(tag)
+  return () => tag.remove()
+}
+
+export function apply(ctx: ClientContext): void {
+  ctx.effect(() => injectStyles(), `${NS}: dashboard styles`)
+  // settings.section is declared at runtime by ui-settings-general; slots.inject
+  // defers registration until that declaration exists and follows its lifetime
+  // (a bare register before the declaration can fail or land invisible).
+  ctx.slots.inject('settings.section', () => ctx.slots.register(
+    {
+      name: 'settings.section',
+      id: 'a2a',
+      order: 90,
+      label: () => 'A2A 连接',
+      inject: () => ({}),
+    },
+    A2aSection,
+  ))
+}
+
+/** Wire types — mirror the host's src/api.ts snapshot. */
+export interface ApiSnapshot {
+  readonly server: { readonly enabled: boolean; readonly cardUrl?: string; readonly skills: readonly string[] }
+  readonly tasks: readonly unknown[]
+  readonly agents: readonly unknown[]
+}
+
+interface AgentView {
+  readonly id: string
+  readonly name: string
+  readonly agentCardUrl: string
+  readonly enabled: boolean
+  readonly state: string
+  readonly skillCount: number
+  readonly toolCount: number
+  readonly lastError?: string
+}
+
+interface TaskView {
+  readonly id: string
+  readonly contextId?: string
+  readonly status?: { readonly state: string }
+  readonly metadata?: { readonly skill?: string }
+}
+
+async function fetchSnapshot(): Promise<ApiSnapshot> {
+  const res = await fetch('/a2a/api', { headers: { accept: 'application/json' } })
+  if (!res.ok) throw new Error(`snapshot HTTP ${res.status}`)
+  return (await res.json()) as ApiSnapshot
+}
+
+async function postControl(payload: Record<string, unknown>): Promise<{ readonly ok: boolean; readonly message: string }> {
+  const res = await fetch('/a2a/api', {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify(payload),
+  })
+  const body = (await res.json().catch(() => ({ ok: false, message: `HTTP ${res.status}` }))) as { ok: boolean; message: string }
+  return body
+}
+
+type SectionProps = PropsRuntime<'settings.section'>
+
+export function A2aSection(_props: SectionProps): ReactElement {
+  const [snap, setSnap] = useState<ApiSnapshot | undefined>(undefined)
+  const [error, setError] = useState<string | undefined>(undefined)
+  const [agentName, setAgentName] = useState('')
+  const [agentUrl, setAgentUrl] = useState('')
+  const [busy, setBusy] = useState(false)
+
+  useEffect(() => {
+    let alive = true
+    const tick = async (): Promise<void> => {
+      try {
+        const next = await fetchSnapshot()
+        if (alive) { setSnap(next); setError(undefined) }
+      } catch (err) {
+        if (alive) setError((err as Error).message)
+      }
+    }
+    void tick()
+    const timer = setInterval(() => void tick(), 3000)
+    return () => {
+      alive = false
+      clearInterval(timer)
+    }
+  }, [])
+
+  const control = async (payload: Record<string, unknown>): Promise<void> => {
+    setBusy(true)
+    try {
+      const result = await postControl(payload)
+      if (!result.ok) setError(result.message)
+      setSnap(await fetchSnapshot())
+    } catch (err) {
+      setError((err as Error).message)
+    } finally {
+      setBusy(false)
+    }
+  }
+
+  const server = snap?.server
+  const agents = (snap?.agents ?? []) as readonly AgentView[]
+  const tasks = (snap?.tasks ?? []) as readonly TaskView[]
+
+  return createElement(
+    'div',
+    { className: 'dsh-a2a-panel' },
+    error !== undefined ? createElement('div', { className: 'dsh-a2a-error' }, error) : null,
+
+    // ── inbound server ───────────────────────────────────────────────────
+    createElement(
+      'div',
+      { className: 'dsh-a2a-card' },
+      createElement('h3', null, '入站 Server'),
+      server === undefined
+        ? createElement('div', { className: 'muted' }, '加载中…')
+        : createElement(
+            'div',
+            { className: 'dsh-a2a-row' },
+            createElement(
+              'span',
+              { className: `dsh-a2a-state ${server.enabled ? 'ok' : 'bad'}` },
+              server.enabled ? '已启用' : '已停用',
+            ),
+            createElement(
+              'button',
+              {
+                className: server.enabled ? '' : 'primary',
+                disabled: busy,
+                onClick: () => void control({ action: server.enabled ? 'server.disable' : 'server.enable' }),
+              },
+              server.enabled ? '停用' : '启用',
+            ),
+          ),
+      server !== undefined && server.enabled
+        ? createElement(
+            'div',
+            { className: 'dsh-a2a-row muted' },
+            `AgentCard: ${server.cardUrl ?? '(n/a)'}  ·  技能: ${server.skills.join(', ') || '(chat)'}`,
+          )
+        : null,
+    ),
+
+    // ── outbound agents ──────────────────────────────────────────────────
+    createElement(
+      'div',
+      { className: 'dsh-a2a-card' },
+      createElement('h3', null, `出站 Agents（${agents.length}）`),
+      agents.length === 0
+        ? createElement('div', { className: 'muted' }, '未配置远程 agent。')
+        : createElement(
+            'table',
+            { className: 'dsh-a2a-table' },
+            createElement(
+              'thead',
+              null,
+              createElement('tr', null,
+                createElement('th', null, '名称'),
+                createElement('th', null, '状态'),
+                createElement('th', null, '工具'),
+                createElement('th', null, '操作'),
+              ),
+            ),
+            createElement(
+              'tbody',
+              null,
+              ...agents.map((a) =>
+                createElement(
+                  'tr',
+                  { key: a.id },
+                  createElement('td', null,
+                    createElement('div', null, a.name),
+                    createElement('div', { className: 'muted' }, a.agentCardUrl),
+                    a.lastError !== undefined ? createElement('div', { className: 'dsh-a2a-error' }, a.lastError) : null,
+                  ),
+                  createElement('td', null,
+                    createElement('span', { className: `dsh-a2a-state ${a.state === 'connected' ? 'ok' : 'bad'}` }, a.state),
+                  ),
+                  createElement('td', null, `${a.toolCount} / ${a.skillCount}`),
+                  createElement('td', null,
+                    createElement('button', { disabled: busy, onClick: () => void control({ action: a.enabled ? 'agent.disable' : 'agent.enable', id: a.id }) }, a.enabled ? '停用' : '启用'),
+                    ' ',
+                    createElement('button', { disabled: busy, onClick: () => void control({ action: 'agent.refresh', id: a.id }) }, '刷新'),
+                    ' ',
+                    createElement('button', { disabled: busy, onClick: () => void control({ action: 'agent.remove', id: a.id }) }, '删除'),
+                  ),
+                ),
+              ),
+            ),
+          ),
+      createElement(
+        'form',
+        {
+          className: 'dsh-a2a-form',
+          onSubmit: (ev: { preventDefault(): void }) => {
+            ev.preventDefault()
+            if (!agentName.trim() || !agentUrl.trim()) return
+            void control({ action: 'agent.add', name: agentName.trim(), agentCardUrl: agentUrl.trim() }).then(() => {
+              setAgentName('')
+              setAgentUrl('')
+            })
+          },
+        },
+        createElement('input', { value: agentName, placeholder: '名称', onChange: (e: { target: { value: string } }) => setAgentName(e.target.value) }),
+        createElement('input', { value: agentUrl, placeholder: 'AgentCard URL', onChange: (e: { target: { value: string } }) => setAgentUrl(e.target.value) }),
+        createElement('button', { type: 'submit', className: 'primary', disabled: busy }, '添加 Agent'),
+      ),
+    ),
+
+    // ── tasks ────────────────────────────────────────────────────────────
+    createElement(
+      'div',
+      { className: 'dsh-a2a-card' },
+      createElement('h3', null, `任务（${tasks.length}）`),
+      tasks.length === 0
+        ? createElement('div', { className: 'muted' }, '暂无任务。')
+        : createElement(
+            'table',
+            { className: 'dsh-a2a-table' },
+            createElement('thead', null,
+              createElement('tr', null,
+                createElement('th', null, 'ID'),
+                createElement('th', null, '技能'),
+                createElement('th', null, '状态'),
+                createElement('th', null, '操作'),
+              ),
+            ),
+            createElement('tbody', null,
+              ...tasks.slice(-20).reverse().map((t) =>
+                createElement('tr', { key: t.id },
+                  createElement('td', null, createElement('span', { className: 'muted' }, t.id)),
+                  createElement('td', null, t.metadata?.skill ?? '-'),
+                  createElement('td', null, t.status?.state ?? '-'),
+                  createElement('td', null,
+                    createElement('button', { disabled: busy, onClick: () => void control({ action: 'task.cancel', id: t.id }) }, '取消'),
+                  ),
+                ),
+              ),
+            ),
+          ),
+    ),
+  )
+}

package/src/commands.ts

@@ -0,0 +1,92 @@
+/**
+ * The `/a2a` command surface: status, server enable/disable, card, agents,
+ * and task control — the P0 operations surface (the settings panel is P1).
+ * @module dsh-a2a/commands
+ */
+
+import type { CommandDefinition, CommandInvocation, CommandResult } from '@deepseek-ai/dsh-commands'
+import type { A2AServiceImpl } from './service.ts'
+
+/** Build the `/a2a` command definition over the service facade. */
+export function buildA2aCommand(impl: A2AServiceImpl): CommandDefinition {
+  return {
+    name: 'a2a',
+    description: 'Manage the A2A plugin: status, server, agents, tasks, card.',
+    handler: async (invocation: CommandInvocation): Promise<CommandResult> => {
+      const [verb, ...rest] = invocation.rawInput.trim().split(/\s+/)
+      switch (verb ?? '') {
+        case '': {
+          const status = impl.status() as { server?: unknown; client?: unknown }
+          return success(`A2A status\n${JSON.stringify(status, null, 2)}`)
+        }
+        case 'status':
+          return success(JSON.stringify(impl.status(), null, 2))
+        case 'enable':
+          return outcome(await impl.enableServer(true))
+        case 'disable':
+          return outcome(await impl.enableServer(false))
+        case 'card':
+          return success(JSON.stringify(impl.listTasks(), null, 2).slice(0, 4000))
+        case 'agents':
+          return success(JSON.stringify(impl.agents(), null, 2))
+        case 'agent': {
+          const [action, ...args] = rest
+          switch (action ?? '') {
+            case 'add': {
+              const url = args[0]
+              if (!url) return error('usage: /a2a agent add <agentCardUrl> [name]')
+              const name = args[1] ?? url
+              return outcome(await impl.addAgent({ name, agentCardUrl: url }))
+            }
+            case 'remove': {
+              const id = args[0]
+              if (!id) return error('usage: /a2a agent remove <id>')
+              return outcome(await impl.removeAgent(id))
+            }
+            case 'enable': {
+              const id = args[0]
+              if (!id) return error('usage: /a2a agent enable <id>')
+              return outcome(await impl.setAgentEnabled(id, true))
+            }
+            case 'disable': {
+              const id = args[0]
+              if (!id) return error('usage: /a2a agent disable <id>')
+              return outcome(await impl.setAgentEnabled(id, false))
+            }
+            case 'refresh': {
+              const id = args[0]
+              if (!id) return error('usage: /a2a agent refresh <id>')
+              return outcome(await impl.refreshAgentCard(id))
+            }
+            default:
+              return error('usage: /a2a agent add|remove|enable|disable|refresh ...')
+          }
+        }
+        case 'tasks':
+          return success(JSON.stringify(impl.listTasks(), null, 2))
+        case 'task': {
+          const [action, id] = rest
+          if (action === 'get' && id) return success(JSON.stringify(impl.getTask(id), null, 2))
+          if (action === 'cancel' && id) return outcome(await impl.cancelTask(id))
+          return error('usage: /a2a task get|cancel <taskId>')
+        }
+        case 'help':
+          return success('a2a commands: status | enable | disable | card | agents | agent add/remove/enable/disable/refresh | tasks | task get/cancel <id> | help')
+        default:
+          return error(`unknown a2a verb "${verb}" (try /a2a help)`)
+      }
+    },
+  }
+}
+
+function success(text: string): CommandResult {
+  return { kind: 'success', text }
+}
+
+function error(text: string): CommandResult {
+  return { kind: 'error', text }
+}
+
+function outcome(result: { readonly ok: boolean; readonly message: string }): CommandResult {
+  return result.ok ? success(result.message) : error(result.message)
+}

package/src/events.ts

@@ -0,0 +1,58 @@
+/**
+ * The `a2a/*` event domain and the `ctx.a2a` service key. P0 ships exactly one
+ * event — `a2a/inbound-task`, the policy seam — so the governance story has a
+ * real built-in consumer (skill gate + audit) and third-party plugins can hang
+ * approval-style policy on inbound tasks. Further events are deferred until a
+ * consumer exists (see design §4).
+ * @module dsh-a2a/events
+ */
+
+import type { Part } from './protocol.ts'
+
+/** The mutable policy decision for one inbound task, before execution. */
+export interface InboundTaskDecision {
+  readonly contextId: string
+  readonly skill: string
+  readonly parts: readonly Part[]
+  /** Request source identity (auth hash or null) for audit. */
+  readonly remotePeerId: string | null
+  /** Set by a policy listener to defer the task for human approval (P1). */
+  requiresApproval?: boolean
+  /** Set by a policy listener to veto the task outright. */
+  rejected?: { readonly reason: string }
+}
+
+/** The facade other plugins read as `ctx.a2a`. */
+export interface A2AServiceLike {
+  status(): unknown
+  enableServer(enable: boolean): Promise<{ readonly ok: boolean; readonly message: string }>
+  listTasks(): unknown
+  getTask(taskId: string): unknown
+  cancelTask(taskId: string): Promise<{ readonly ok: boolean; readonly message: string }>
+  agents(): unknown
+  addAgent(spec: unknown): Promise<{ readonly ok: boolean; readonly message: string }>
+  removeAgent(id: string): Promise<{ readonly ok: boolean; readonly message: string }>
+  setAgentEnabled(id: string, enabled: boolean): Promise<{ readonly ok: boolean; readonly message: string }>
+  refreshAgentCard(id: string): Promise<{ readonly ok: boolean; readonly message: string }>
+}
+
+declare module '@deepseek-ai/cordis' {
+  interface Context {
+    /** The A2A service facade, provided while the plugin is mounted. */
+    a2a: A2AServiceLike
+  }
+
+  interface Events {
+    /**
+     * Policy seam for one inbound task, dispatched as a waterfall before the
+     * task starts. Listeners mutate the decision (attach `requiresApproval`,
+     * set `rejected`) and MUST call `next(decision)` to delegate; returning
+     * without `next()` short-circuits and the returned value is final.
+     * @mode waterfall
+     * @param decision — the mutable task decision.
+     * @param next - delegate the (possibly mutated) decision downstream.
+     * @returns the final decision after all listeners.
+     */
+    'a2a/inbound-task'(this: unknown, decision: InboundTaskDecision, next: (d: InboundTaskDecision) => Promise<InboundTaskDecision> | InboundTaskDecision): Promise<InboundTaskDecision>
+  }
+}