@hanphone/dsh-a2a 0.1.0

package/src/index.ts

@@ -0,0 +1,353 @@
+/**
+ * @hanphone/dsh-a2a — Cordis plugin entry.
+ *
+ * Mounts the A2A v1.0 dual-end plugin: the inbound server (AgentCard derived
+ * from the live tool registry, JSON-RPC + SSE, durable SQLite task store,
+ * session/subagent executors, the `a2a/inbound-task` policy gate + audit)
+ * and the outbound client (persisted multi-agent registry, skills mapped to
+ * model tools, sync calls with per-agent timeout). Optional services are
+ * probed rather than injected so a composition lacking one half idles just
+ * that half; only the storage domain is required.
+ *
+ * Function-plugin export shape: named `name`/`inject`/`Config`/`apply`, no
+ * default export (mixing forms makes the Loader drop the namespace).
+ * @module dsh-a2a
+ */
+
+import type { Context } from '@deepseek-ai/cordis'
+import z from '@deepseek-ai/schemastery'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+import { mkdirSync } from 'node:fs'
+import { deriveSkills, buildCard, type ToolGetter } from './server/card.ts'
+import { openDomain, DomainTaskStore, type A2aDomain, type TaskStore } from './server/store.ts'
+import { ExecutorSet } from './server/executor.ts'
+import { ContextSessionPool, probeService, type AgentPresetsLike, type AgentRegistryLike } from './server/exec/agent-runtime.ts'
+import { createSessionExecutor } from './server/exec/session.ts'
+import { createSubagentExecutor, type SubagentsLike } from './server/exec/subagent.ts'
+import { A2AServer, type GateInput, type GateResult } from './server/a2a-server.ts'
+import { A2aRoutes } from './server/routes.ts'
+import { handleApiRequest } from './api.ts'
+import { OutboundAgentRegistry, DomainAgentStore, type OutboundAgentSpec } from './outbound/registry.ts'
+import { A2AService, type A2AServiceImpl, type OpResult } from './service.ts'
+import { buildA2aCommand } from './commands.ts'
+import type { InboundTaskDecision } from './events.ts'
+import type { AgentCard, AgentSkill, TaskState } from './protocol.ts'
+
+export const name = 'a2a'
+
+/** Only the storage domain is required; the other halves are probed. */
+export const inject = ['storageDomain'] as const
+
+export interface A2AConfig {
+  server: {
+    enabled: boolean
+    name: string
+    description: string
+    version: string
+    /** Advertised base URL; null/absent lets the host webServer address be used. */
+    baseUrl?: string
+    endpointPath: string
+    /** Environment variable name for the inbound bearer token; absent = anonymous. */
+    authTokenEnv?: string
+    skills: { ids: string[]; exclude: string[] }
+    executors: Record<string, 'session' | 'subagent'>
+    subagentProvider: string
+  }
+  client: {
+    agents: OutboundAgentSpec[]
+    toolPrefix: string
+  }
+}
+
+/** Loader-validated config schema (defaults applied by the Loader). */
+export const Config: z<A2AConfig> = z.object({
+  server: z.object({
+    enabled: z.boolean().default(true),
+    name: z.string().default('My DSH Agent'),
+    description: z.string().default('A DeepSeek Harness agent exposed over A2A v1.0'),
+    version: z.string().default('0.1.0'),
+    baseUrl: z.string(),
+    endpointPath: z.string().default('/a2a'),
+    authTokenEnv: z.string(),
+    skills: z.object({
+      ids: z.array(z.string()).default([]),
+      exclude: z.array(z.string()).default([]),
+    }),
+    executors: z.dict(z.union(['session', 'subagent'] as const)).default({ chat: 'session' }),
+    subagentProvider: z.string().default('in-process'),
+  }),
+  client: z.object({
+    agents: z.array(z.object({
+      name: z.string(),
+      agentCardUrl: z.string(),
+      bearerTokenEnv: z.string(),
+      enabled: z.boolean().default(true),
+      timeoutMs: z.number().default(60000),
+    })).default([]),
+    toolPrefix: z.string().default('a2a'),
+  }),
+})
+
+/** Mutable state shared across the plugin's halves. */
+interface Shared {
+  readonly domain: A2aDomain
+  readonly store: TaskStore
+  registry: OutboundAgentRegistry | undefined
+  server: A2AServer | undefined
+  routes: A2aRoutes | undefined
+  card: AgentCard | undefined
+  executors: ExecutorSet | undefined
+  enabled: boolean
+}
+
+export function apply(ctx: Context, config: A2AConfig) {
+  const logger = ctx.logger('a2a')
+  const serverConfig = { ...config.server }
+  const clientConfig = { ...config.client }
+  const authToken = serverConfig.authTokenEnv !== undefined ? process.env[serverConfig.authTokenEnv] : undefined
+  const toolPrefix = clientConfig.toolPrefix
+  const subagentProvider = serverConfig.subagentProvider
+  const inboundCwd = inboundSessionCwd()
+
+  ctx.inject(['storageDomain'], (ctx) => {
+    ctx.effect(async () => {
+      const domain = await openDomain(ctx.storageDomain)
+      const store = new DomainTaskStore(domain)
+      const holder: Shared = {
+        domain,
+        store,
+        registry: undefined,
+        server: undefined,
+        routes: undefined,
+        card: undefined,
+        executors: undefined,
+        enabled: serverConfig.enabled,
+      }
+
+      // ── inbound server half ────────────────────────────────────────────
+      const webServer = probeService(ctx, 'webServer', 'register') as
+        | { register(route: { kind: 'exact' | 'prefix'; path: string; handler(...args: unknown[]): unknown }): () => void }
+        | undefined
+      if (webServer === undefined) {
+        logger.warn('a2a: webServer not mounted; inbound server idle')
+      } else {
+        try {
+          const skills = deriveSkills(
+            probeService(ctx, 'tools', 'get') as ToolGetter | undefined ?? { get: () => undefined },
+            { ids: serverConfig.skills.ids, exclude: serverConfig.skills.exclude },
+          )
+          const baseUrl = serverConfig.baseUrl ?? `http://127.0.0.1:${process.env['DSH_A2A_PORT'] ?? '3000'}`
+          const endpointPath = serverConfig.endpointPath ?? '/a2a'
+          const card = buildCard({
+            baseUrl,
+            endpointPath,
+            name: serverConfig.name ?? 'My DSH Agent',
+            description: serverConfig.description ?? 'A DeepSeek Harness agent exposed over A2A v1.0',
+            version: serverConfig.version ?? '0.1.0',
+            skills,
+            ...(authToken ? { authToken } : {}),
+          })
+          holder.card = card
+
+          // Executors: probe the agent loop; refuse tasks readably without it.
+          const agents = probeService(ctx, 'agents', 'create') as AgentRegistryLike | undefined
+          const presets = probeService(ctx, 'agentPresets', 'resolve') as AgentPresetsLike | undefined
+          const sessionPool = agents
+            ? new ContextSessionPool(agents, {
+              cwd: inboundCwd,
+              ...(presets ? { agentPresets: presets } : {}),
+              resolveAgentOptions: () => resolveDefaultModel(ctx),
+            })
+            : undefined
+          const sessionExecutor = sessionPool ? createSessionExecutor(sessionPool) : refuseExecutor('no agent loop mounted')
+          const subagents = probeService(ctx, 'subagents', 'start') as SubagentsLike | undefined
+          const subagentExecutor = sessionPool !== undefined && subagents !== undefined
+            ? createSubagentExecutor({ pool: sessionPool, subagents, provider: subagentProvider })
+            : undefined
+          const executors = new ExecutorSet(serverConfig.executors, sessionExecutor, subagentExecutor)
+          holder.executors = executors
+
+          const skillIds = new Set(skills.map((s) => s.id))
+          const gate = async (input: GateInput): Promise<GateResult> => {
+            if (!skillIds.has(input.skill)) {
+              return { ok: false, reason: `unknown skill "${input.skill}"` }
+            }
+            const decision: InboundTaskDecision = {
+              contextId: input.contextId,
+              skill: input.skill,
+              parts: input.parts,
+              remotePeerId: input.remotePeerId,
+            }
+            const decided = await ctx.waterfall('a2a/inbound-task', decision, async (d) => d)
+            // Built-in audit: every task decision is logged with its source.
+            logger.info(`[a2a] inbound skill=${decided.skill} remote=${decided.remotePeerId} rejected=${decided.rejected?.reason ?? 'no'}`)
+            if (decided.rejected !== undefined) return { ok: false, reason: decided.rejected.reason }
+            return { ok: true }
+          }
+
+          const server = new A2AServer({
+            card,
+            store,
+            executors,
+            ...(authToken ? { authToken } : {}),
+            gate,
+            onTaskSettled: (taskId) => logger.info(`[a2a] task settled ${taskId}`),
+          })
+          holder.server = server
+          const routes = new A2aRoutes(webServer as never, server)
+          holder.routes = routes
+          if (holder.enabled) routes.enable()
+        } catch (err) {
+          logger.error(`a2a: server half failed to build: ${(err as Error).message}`)
+        }
+      }
+
+      // ── outbound client half (after the inbound routes exist, so a
+      // loopback agent can fetch this server's own card) ──────────────────
+      const toolsService = probeService(ctx, 'tools', 'get') as
+        | (ToolGetter & { register(def: unknown): (() => void) | void })
+        | undefined
+      if (toolsService === undefined) {
+        logger.warn('a2a: tools service not mounted; outbound client idle')
+      } else {
+        const registry = new OutboundAgentRegistry({
+          registrar: { register: (def) => toolsService.register(def) },
+          store: new DomainAgentStore(domain.agents),
+          toolPrefix,
+          tokenOf: (env) => (env ? process.env[env] : undefined),
+          onError: (message) => logger.warn(message),
+        })
+        holder.registry = registry
+        registry.loadAll()
+        // Declared agents seed the registry: the persisted store stays the
+        // runtime state, so a disabled or removed agent is not reconnected.
+        if (clientConfig.agents.length > 0) await registry.seed(clientConfig.agents)
+      }
+
+      // ── service facade + commands ──────────────────────────────────────
+      const impl: A2AServiceImpl = makeFacade(holder, logger.info.bind(logger))
+      new A2AService(ctx, impl)
+
+      const commands = probeService(ctx, 'commands', 'register') as
+        | { register(def: { name: string; description: string; handler(...args: unknown[]): unknown }): () => void }
+        | undefined
+      if (commands !== undefined) {
+        ctx.effect(() => commands.register(buildA2aCommand(impl) as never), 'a2a: command')
+      }
+
+      // ── GUI dashboard API (loopback-only /a2a/api) ─────────────────────
+      const dashboardWebServer = probeService(ctx, 'webServer', 'register') as
+        | { register(route: { kind: 'exact' | 'prefix'; path: string; handler(...args: unknown[]): unknown }): () => void }
+        | undefined
+      if (dashboardWebServer !== undefined) {
+        ctx.effect(() => dashboardWebServer.register({
+          kind: 'prefix',
+          path: '/a2a/api',
+          handler: (req: unknown, res: unknown) => handleApiRequest(req as never, res as never, impl),
+        }), 'a2a: dashboard api')
+      } else {
+        logger.warn('a2a: webServer not mounted; GUI dashboard API idle')
+      }
+
+      return async () => {
+        holder.routes?.dispose()
+        await holder.executors?.disposeAll()
+        await holder.registry?.disposeAll()
+        await domain.close()
+      }
+    }, 'a2a: domain + halves')
+  })
+}
+
+/** Facade closure over the shared holder (commands and `ctx.a2a` consumers). */
+function makeFacade(holder: Shared, log: (message: string) => void): A2AServiceImpl {
+  const serverEnabled = (): boolean => holder.routes?.active ?? false
+  return {
+    status(): unknown {
+      return {
+        server: {
+          enabled: serverEnabled(),
+          cardUrl: holder.card?.supportedInterfaces?.[0]?.url,
+          skills: holder.card?.skills?.map((s) => s.id) ?? [],
+          executors: holder.executors ? ['session', ...(holder.executors['subagent'] !== undefined ? ['subagent'] : [])] : [],
+        },
+        tasks: holder.store.list().length,
+        agents: holder.registry?.list() ?? [],
+      }
+    },
+    async enableServer(enable: boolean): Promise<OpResult> {
+      if (holder.routes === undefined) return { ok: false, message: 'inbound server is not mounted (no webServer)' }
+      if (enable) holder.routes.enable()
+      else holder.routes.disable()
+      log(`[a2a] server ${enable ? 'enabled' : 'disabled'}`)
+      return { ok: true, message: `server ${enable ? 'enabled' : 'disabled'}` }
+    },
+    getTask(taskId: string): unknown {
+      return holder.store.get(taskId)
+    },
+    listTasks(): unknown {
+      return holder.store.list()
+    },
+    async cancelTask(taskId: string): Promise<OpResult> {
+      const record = holder.store.get(taskId)
+      if (record === undefined) return { ok: false, message: `task ${taskId} not found` }
+      const aborted = holder.server?.abort?.(taskId) ?? false
+      return { ok: true, message: aborted ? `task ${taskId} canceled` : `task ${taskId} already terminal` }
+    },
+    agents(): unknown {
+      return holder.registry?.list() ?? []
+    },
+    async addAgent(spec: { name: string; agentCardUrl: string; bearerTokenEnv?: string }): Promise<OpResult> {
+      const registry = holder.registry
+      if (registry === undefined) return { ok: false, message: 'outbound client not mounted (no tools service)' }
+      const result = await registry.add({ ...spec, enabled: true, timeoutMs: 60000 })
+      return result
+    },
+    async removeAgent(id: string): Promise<OpResult> {
+      return holder.registry?.remove(id) ?? { ok: false, message: 'outbound client not mounted' }
+    },
+    async setAgentEnabled(id: string, enabled: boolean): Promise<OpResult> {
+      return holder.registry?.setEnabled(id, enabled) ?? { ok: false, message: 'outbound client not mounted' }
+    },
+    async refreshAgentCard(id: string): Promise<OpResult> {
+      return holder.registry?.refresh(id) ?? { ok: false, message: 'outbound client not mounted' }
+    },
+  }
+}
+
+/** A task that refuses readably on compositions without an agent loop. */
+function refuseExecutor(reason: string) {
+  return {
+    name: 'refuse',
+    async execute(): Promise<{ parts: { text: string }[] }> {
+      throw new Error(`a2a: ${reason}; refusing inbound task`)
+    },
+  }
+}
+
+function resolveDefaultModel(ctx: Context): { provider?: string; model?: string } | undefined {
+  const service = probeService(ctx, 'agentDefaultModel', 'currentSelection') as
+    | { currentSelection(): { provider?: string; model?: string } }
+    | undefined
+  return service?.currentSelection()
+}
+
+/** Absolute stable cwd for inbound per-context sessions (never profile root). */
+function inboundSessionCwd(): string {
+  const home = join(homedir(), '.dsh')
+  const dshHome = process.env['DSH_HOME'] ?? home
+  const dir = join(dshHome, 'a2a-sessions')
+  try {
+    mkdirSync(dir, { recursive: true })
+  } catch {
+    // cwd fallback below stays valid
+  }
+  return dir
+}
+
+export type { TaskState }
+export type { AgentSkill }
+export { A2AServer } from './server/a2a-server.ts'
+export { A2AClient, A2AError } from './outbound/calls.ts'
+export { A2AService } from './service.ts'

package/src/jsonrpc.ts

@@ -0,0 +1,61 @@
+/**
+ * JSON-RPC 2.0 helpers and SSE framing for the A2A binding. Transport-agnostic:
+ * the A2AServer consumes these, and the HTTP route layer only maps requests to
+ * `handle` / `handleStream` and bytes back.
+ * @module dsh-a2a/jsonrpc
+ */
+
+import {
+  A2A_ERROR_CODES,
+  type JsonRpcError,
+  type JsonRpcRequest,
+  type JsonRpcSuccess,
+} from './protocol.ts'
+
+/** Parse a request body into a JSON-RPC request, or undefined on malformed input. */
+export function parseRpc(body: string): JsonRpcRequest | undefined {
+  let value: unknown
+  try {
+    value = JSON.parse(body)
+  } catch {
+    return undefined
+  }
+  if (typeof value !== 'object' || value === null) return undefined
+  const rpc = value as Partial<JsonRpcRequest>
+  if (rpc.jsonrpc !== '2.0' || typeof rpc.method !== 'string') return undefined
+  return rpc as JsonRpcRequest
+}
+
+/** Build a JSON-RPC error response object. */
+export function rpcError(
+  id: string | number | null | undefined,
+  code: number,
+  message: string,
+  data?: unknown,
+): JsonRpcError {
+  return {
+    jsonrpc: '2.0',
+    id: id ?? null,
+    error: { code, message, ...(data === undefined ? {} : { data }) },
+  }
+}
+
+/** Build a JSON-RPC success response object. */
+export function rpcSuccess(id: string | number | null | undefined, result: unknown): JsonRpcSuccess {
+  return { jsonrpc: '2.0', id: id ?? null, result }
+}
+
+/** Invalid-method error for the SSE path (no request id on the wire). */
+export function methodNotFound(method: string): JsonRpcError {
+  return rpcError(null, A2A_ERROR_CODES.METHOD_NOT_FOUND, `Unknown method ${method}`)
+}
+
+/** One data frame of an SSE stream. */
+export function sseData(payload: unknown): string {
+  return `data: ${JSON.stringify(payload)}\n\n`
+}
+
+/** One named event frame of an SSE stream (e.g. `event: error`). */
+export function sseEvent(name: string, payload: unknown): string {
+  return `event: ${name}\ndata: ${JSON.stringify(payload)}\n\n`
+}

package/src/outbound/calls.ts

@@ -0,0 +1,145 @@
+/**
+ * Outbound A2A client: AgentCard discovery plus the JSON-RPC methods the
+ * tools layer needs. Sync-by-polling for P0 (each tool call waits for the
+ * task to settle up to a timeout); passive result injection replaces this in
+ * P1 without changing the transport.
+ * @module dsh-a2a/client/calls
+ */
+
+import {
+  A2A_ERROR_CODES,
+  A2A_METHODS,
+  isTerminal,
+  type AgentCard,
+  type JsonRpcResponse,
+  type Message,
+  type Task,
+} from '../protocol.ts'
+
+/** Error carrying the remote JSON-RPC error code. */
+export class A2AError extends Error {
+  constructor(
+    readonly code: number,
+    message: string,
+  ) {
+    super(message)
+    this.name = 'A2AError'
+  }
+}
+
+export interface ClientOptions {
+  readonly bearerToken?: string
+  /** Per-call timeout in ms. Default 60000. */
+  readonly timeoutMs?: number
+  readonly fetchImpl?: typeof fetch
+}
+
+/** A connected remote A2A agent (one AgentCard endpoint). */
+export class A2AClient {
+  readonly card: AgentCard
+  private readonly endpoint: string
+
+  private constructor(
+    card: AgentCard,
+    endpoint: string,
+    private readonly opts: ClientOptions,
+  ) {
+    this.card = card
+    this.endpoint = endpoint
+  }
+
+  /** Fetch and validate an AgentCard, then connect to its JSON-RPC endpoint. */
+  static async connect(agentCardUrl: string, opts: ClientOptions = {}): Promise<A2AClient> {
+    const timeoutMs = opts.timeoutMs ?? 60_000
+    const fetchImpl = opts.fetchImpl ?? fetch
+    const response = await fetchImpl(agentCardUrl, {
+      headers: {
+        accept: 'application/json',
+        ...(opts.bearerToken ? { authorization: `Bearer ${opts.bearerToken}` } : {}),
+      },
+      signal: AbortSignal.timeout(timeoutMs),
+    })
+    if (!response.ok) {
+      throw new A2AError(A2A_ERROR_CODES.AGENT_CARD_NOT_FOUND, `agent card fetch failed: HTTP ${response.status}`)
+    }
+    const card = (await response.json()) as AgentCard
+    if (typeof card.name !== 'string' || typeof card.description !== 'string') {
+      throw new A2AError(A2A_ERROR_CODES.AGENT_CARD_SIGNATURE_INVALID, `invalid agent card at ${agentCardUrl}`)
+    }
+    const iface = card.supportedInterfaces?.find((i) => (i.protocolBinding ?? 'JSONRPC') === 'JSONRPC')
+      ?? card.supportedInterfaces?.[0]
+    const endpoint = iface?.url ?? card.url
+    if (!endpoint) {
+      throw new A2AError(A2A_ERROR_CODES.AGENT_CARD_NOT_FOUND, `agent card at ${agentCardUrl} advertises no JSON-RPC interface`)
+    }
+    return new A2AClient(card, endpoint, opts)
+  }
+
+  /** Send a message and wait (or poll) until the task settles. */
+  async sendMessage(message: Message): Promise<Task> {
+    const task = await this.call<Task>(A2A_METHODS.sendMessage, { message })
+    if (isTerminal(task.status.state)) return task
+    return this.pollTask(task.id)
+  }
+
+  async getTask(taskId: string): Promise<Task> {
+    return this.call<Task>(A2A_METHODS.getTask, { id: taskId })
+  }
+
+  async listTasks(): Promise<Task[]> {
+    return this.call<Task[]>(A2A_METHODS.listTasks, {})
+  }
+
+  async cancelTask(taskId: string): Promise<Task> {
+    return this.call<Task>(A2A_METHODS.cancelTask, { id: taskId })
+  }
+
+  /** Poll a task until terminal or the overall timeout elapses. */
+  private async pollTask(taskId: string): Promise<Task> {
+    const budget = this.opts.timeoutMs ?? 60_000
+    const deadline = Date.now() + budget
+    for (;;) {
+      const task = await this.getTask(taskId)
+      if (isTerminal(task.status.state)) return task
+      if (Date.now() >= deadline) {
+        throw new A2AError(-32000, `task ${taskId} did not settle within ${budget}ms`)
+      }
+      await new Promise((resolve) => setTimeout(resolve, 250))
+    }
+  }
+
+  private async call<T>(method: string, params: unknown): Promise<T> {
+    const timeoutMs = this.opts.timeoutMs ?? 60_000
+    const fetchImpl = this.opts.fetchImpl ?? fetch
+    let response: Response
+    try {
+      response = await fetchImpl(this.endpoint, {
+        method: 'POST',
+        headers: {
+          'content-type': 'application/json',
+          accept: 'application/json',
+          ...(this.opts.bearerToken ? { authorization: `Bearer ${this.opts.bearerToken}` } : {}),
+        },
+        body: JSON.stringify({ jsonrpc: '2.0', id: crypto.randomUUID(), method, params }),
+        signal: AbortSignal.timeout(timeoutMs),
+      })
+    } catch (err) {
+      if (err instanceof Error && err.name === 'TimeoutError') {
+        throw new A2AError(-32000, `A2A call ${method} timed out after ${timeoutMs}ms`)
+      }
+      throw err
+    }
+    if (response.status === 401) {
+      throw new A2AError(A2A_ERROR_CODES.UNAUTHORIZED, 'remote agent rejected credentials (401)')
+    }
+    if (!response.ok) {
+      throw new A2AError(A2A_ERROR_CODES.INTERNAL_ERROR, `A2A call ${method} failed: HTTP ${response.status}`)
+    }
+    const payload = (await response.json()) as JsonRpcResponse
+    if ('error' in payload) {
+      const error = payload.error
+      throw new A2AError(error.code, error.message)
+    }
+    return payload.result as T
+  }
+}