@hanphone/dsh-a2a 0.1.0

package/src/outbound/registry.ts

@@ -0,0 +1,290 @@
+/**
+ * Outbound agent registry: the persisted list of connected remote agents,
+ * their connection state, and the tool-registration disposers for each live
+ * connection. Loaded at boot, mutations persist through the agent store.
+ * @module dsh-a2a/client/registry
+ */
+
+import { A2AClient } from './calls.ts'
+import { registerAgentTools, type ToolRegistrar } from './tools.ts'
+import { type OutboundAgentRecord } from '../server/store.ts'
+
+/** User-supplied agent spec (from config or the /a2a command). */
+export interface OutboundAgentSpec {
+  readonly name: string
+  readonly agentCardUrl: string
+  readonly bearerTokenEnv?: string
+  readonly enabled?: boolean
+  readonly timeoutMs?: number
+}
+
+export interface OutboundAgentView {
+  readonly id: string
+  readonly name: string
+  readonly agentCardUrl: string
+  readonly enabled: boolean
+  readonly state: 'connected' | 'disconnected' | 'failed'
+  readonly skillCount: number
+  readonly toolCount: number
+  readonly lastError?: string
+}
+
+/** Durable store for the registry records. */
+export interface AgentStore {
+  list(): OutboundAgentRecord[]
+  save(records: readonly OutboundAgentRecord[]): Promise<void>
+}
+
+/** In-memory agent store (tests and minimal embeddings). */
+export class MemoryAgentStore implements AgentStore {
+  private records: OutboundAgentRecord[] = []
+
+  constructor(initial: readonly OutboundAgentRecord[] = []) {
+    this.records = [...initial]
+  }
+
+  list(): OutboundAgentRecord[] {
+    return [...this.records]
+  }
+
+  async save(records: readonly OutboundAgentRecord[]): Promise<void> {
+    this.records = [...records]
+  }
+}
+
+/** Domain-backed agent store: one JSON array under the `agents` table key. */
+export class DomainAgentStore implements AgentStore {
+  private static readonly KEY = 'records'
+
+  constructor(private readonly table: { get(key: string): string | undefined; put(key: string, value: string): Promise<void> }) {}
+
+  list(): OutboundAgentRecord[] {
+    const raw = this.table.get(DomainAgentStore.KEY)
+    if (raw === undefined) return []
+    try {
+      const parsed = JSON.parse(raw) as unknown
+      return Array.isArray(parsed) ? (parsed as OutboundAgentRecord[]) : []
+    } catch {
+      return []
+    }
+  }
+
+  async save(records: readonly OutboundAgentRecord[]): Promise<void> {
+    await this.table.put(DomainAgentStore.KEY, JSON.stringify(records))
+  }
+}
+
+export interface RegistryOptions {
+  readonly registrar: ToolRegistrar
+  readonly store: AgentStore
+  readonly toolPrefix?: string
+  readonly defaultTimeoutMs?: number
+  /** Resolve a bearer token from an env-var name; undefined when unset. */
+  readonly tokenOf: (env: string | undefined) => string | undefined
+  readonly onError?: (message: string) => void
+}
+
+interface LiveConnection {
+  readonly record: OutboundAgentRecord
+  readonly client: A2AClient
+  readonly disposers: readonly { dispose(): void }[]
+  readonly skillCount: number
+}
+
+/** A list of remote agents, each with live tool registrations when enabled. */
+export class OutboundAgentRegistry {
+  private readonly live = new Map<string, LiveConnection>()
+  private readonly views = new Map<string, OutboundAgentView>()
+  private seedRecords: OutboundAgentRecord[] | undefined
+
+  constructor(private readonly opts: RegistryOptions) {}
+
+  /** Load persisted records and connect every enabled agent (background). */
+  loadAll(): void {
+    const records = this.opts.store.list()
+    this.seedRecords = records
+    for (const record of records) {
+      if (record.enabled) void this.connectRecord(record).catch((err: unknown) => {
+        this.opts.onError?.(`[a2a] failed to connect "${record.name}": ${(err as Error).message}`)
+      })
+    }
+  }
+
+  /**
+   * Seed configured agents that the persisted store does not know yet. The
+   * store is the runtime state: an existing record (enabled or disabled,
+   * present or removed) keeps its state — a disabled agent stays
+   * disconnected and a removed one is not resurrected. Only specs with a name
+   * absent from the store (and not already live this boot) connect and
+   * persist.
+   * @param specs - declared agents from the profile config.
+   */
+  async seed(specs: readonly OutboundAgentSpec[]): Promise<void> {
+    const known = new Set(this.opts.store.list().map((r) => r.name))
+    for (const connection of this.live.values()) known.add(connection.record.name)
+    for (const spec of specs) {
+      if (known.has(spec.name)) continue
+      const result = await this.add(spec)
+      if (result.ok) known.add(spec.name)
+      else this.opts.onError?.(`[a2a] seed agent "${spec.name}": ${result.message}`)
+    }
+  }
+
+  list(): OutboundAgentView[] {
+    return [...this.views.values()]
+  }
+
+  /** Add and connect an agent, persisting the record on success. */
+  async add(spec: OutboundAgentSpec): Promise<{ ok: boolean; message: string }> {
+    const record: OutboundAgentRecord = {
+      id: `agent-${crypto.randomUUID()}`,
+      name: spec.name,
+      agentCardUrl: spec.agentCardUrl,
+      ...(spec.bearerTokenEnv ? { bearerTokenEnv: spec.bearerTokenEnv } : {}),
+      enabled: spec.enabled ?? true,
+      timeoutMs: spec.timeoutMs ?? this.opts.defaultTimeoutMs ?? 60_000,
+      lastCardAt: null,
+    }
+    try {
+      await this.connectRecord(record)
+    } catch (err) {
+      this.views.set(record.id, {
+        id: record.id,
+        name: record.name,
+        agentCardUrl: record.agentCardUrl,
+        enabled: record.enabled,
+        state: 'failed',
+        skillCount: 0,
+        toolCount: 0,
+        lastError: (err as Error).message,
+      })
+      return { ok: false, message: `failed to connect to ${record.agentCardUrl}: ${(err as Error).message}` }
+    }
+    this.persist(record)
+    return { ok: true, message: `agent "${record.name}" connected` }
+  }
+
+  async remove(id: string): Promise<{ ok: boolean; message: string }> {
+    const live = this.live.get(id)
+    const view = this.views.get(id)
+    if (live === undefined && view === undefined) return { ok: false, message: `agent ${id} not found` }
+    for (const disposer of live?.disposers ?? []) disposer.dispose()
+    this.live.delete(id)
+    this.views.delete(id)
+    await this.persistAll()
+    return { ok: true, message: `agent ${id} removed` }
+  }
+
+  async setEnabled(id: string, enabled: boolean): Promise<{ ok: boolean; message: string }> {
+    const live = this.live.get(id)
+    const view = this.views.get(id)
+    if (live === undefined && view === undefined) return { ok: false, message: `agent ${id} not found` }
+    if (enabled && live === undefined) {
+      const record = this.findRecord(id)
+      if (record === undefined) return { ok: false, message: `agent ${id} has no persisted record` }
+      try {
+        await this.connectRecord(record)
+      } catch (err) {
+        return { ok: false, message: `failed to connect: ${(err as Error).message}` }
+      }
+      await this.persistAll()
+      return { ok: true, message: `agent ${id} enabled` }
+    }
+    if (!enabled && live !== undefined) {
+      for (const disposer of live.disposers) disposer.dispose()
+      this.live.delete(id)
+      const current = this.views.get(id)
+      if (current !== undefined) {
+        this.views.set(id, { ...current, enabled: false, state: 'disconnected', toolCount: 0, skillCount: 0 })
+      }
+      await this.persistAll()
+      return { ok: true, message: `agent ${id} disabled` }
+    }
+    return { ok: true, message: `agent ${id} already ${enabled ? 'enabled' : 'disabled'}` }
+  }
+
+  async refresh(id: string): Promise<{ ok: boolean; message: string }> {
+    const record = this.findRecord(id) ?? this.live.get(id)?.record
+    if (record === undefined) return { ok: false, message: `agent ${id} not found` }
+    const live = this.live.get(id)
+    for (const disposer of live?.disposers ?? []) disposer.dispose()
+    this.live.delete(id)
+    try {
+      await this.connectRecord(record)
+    } catch (err) {
+      return { ok: false, message: `refresh failed: ${(err as Error).message}` }
+    }
+    await this.persistAll()
+    return { ok: true, message: `agent "${record.name}" reconnected` }
+  }
+
+  async disposeAll(): Promise<void> {
+    for (const connection of this.live.values()) {
+      for (const disposer of connection.disposers) disposer.dispose()
+    }
+    this.live.clear()
+    this.views.clear()
+  }
+
+  private async connectRecord(record: OutboundAgentRecord): Promise<void> {
+    const token = this.opts.tokenOf(record.bearerTokenEnv)
+    const client = await A2AClient.connect(record.agentCardUrl, {
+      ...(token ? { bearerToken: token } : {}),
+      timeoutMs: record.timeoutMs,
+    })
+    const contextByAgent = new Map<string, string>()
+    const fallback = `a2a-out-${crypto.randomUUID()}`
+    const contextFor = (agentId: string | undefined): string => {
+      const key = agentId ?? '\0fallback'
+      const existing = contextByAgent.get(key)
+      if (existing !== undefined) return existing
+      const id = agentId ? `a2a-out-${crypto.randomUUID()}` : fallback
+      contextByAgent.set(key, id)
+      return id
+    }
+    const disposers = registerAgentTools(this.opts.registrar, {
+      agentName: record.name,
+      client,
+      ...(this.opts.toolPrefix !== undefined ? { toolPrefix: this.opts.toolPrefix } : {}),
+      contextFor,
+    })
+    const skillCount = client.card.skills?.length ?? 0
+    this.live.set(record.id, { record, client, disposers, skillCount })
+    this.views.set(record.id, {
+      id: record.id,
+      name: record.name,
+      agentCardUrl: record.agentCardUrl,
+      enabled: record.enabled,
+      state: 'connected',
+      skillCount,
+      toolCount: disposers.length,
+    })
+  }
+
+  private findRecord(id: string): OutboundAgentRecord | undefined {
+    const current = () => this.opts.store.list().find((r) => r.id === id)
+    return current() ?? this.seedRecords?.find((r) => r.id === id)
+  }
+
+  private persist(record: OutboundAgentRecord): void {
+    const next = [...this.opts.store.list().filter((r) => r.id !== record.id), record]
+    void this.opts.store.save(next).catch((err: unknown) => {
+      this.opts.onError?.(`[a2a] failed to persist agent list: ${String(err)}`)
+    })
+  }
+
+  private async persistAll(): Promise<void> {
+    const liveRecords = [...this.live.values()].map((c) => c.record)
+    const liveIds = new Set(liveRecords.map((r) => r.id))
+    // Non-live known records (disabled agents) keep the store record with the
+    // view's up-to-date enabled flag; removed agents (gone from live AND
+    // views) are dropped so a restart does not resurrect them.
+    const kept = this.opts.store.list()
+      .filter((r) => !liveIds.has(r.id) && this.views.has(r.id))
+      .map((r) => {
+        const view = this.views.get(r.id)
+        return view === undefined ? r : { ...r, enabled: view.enabled }
+      })
+    await this.opts.store.save([...kept, ...liveRecords])
+  }
+}

package/src/outbound/tools.ts

@@ -0,0 +1,118 @@
+/**
+ * Outbound half: register one remote agent's skills as model-facing tools on
+ * `ctx.tools`. Tool names are `a2a__<agent>__<skill>` normalized to the DSH
+ * function-name contract (≤64 chars, collision hash), mirroring the naming
+ * rule of dsh-mcp-client. An agent advertising zero skills registers nothing.
+ * @module dsh-a2a/client/tools
+ */
+
+import { Role, partsToText, type AgentSkill, type Message, type Part } from '../protocol.ts'
+import { A2AError, type A2AClient } from './calls.ts'
+
+/** Structural slice of `ctx.tools` used for registration. */
+export interface ToolRegistrar {
+  register(definition: unknown): (() => void) | void
+}
+
+export interface AgentToolsOptions {
+  readonly agentName: string
+  readonly client: A2AClient
+  /** Tool prefix; default 'a2a'. */
+  readonly toolPrefix?: string
+  /**
+   * Resolve the remote conversation contextId for one calling local agent
+   * (stable per caller, so multi-turn tool use is one remote conversation).
+   */
+  readonly contextFor: (agentId: string | undefined) => string
+}
+
+export interface RegisteredTool {
+  readonly name: string
+  dispose(): void
+}
+
+function normalizeToolName(raw: string): string {
+  const norm = raw.replace(/[^A-Za-z0-9_-]/g, '_').slice(0, 64)
+  if (norm.length > 0 && /^[A-Za-z0-9_-]+$/.test(norm)) return norm
+  let hash = 0
+  for (let i = 0; i < raw.length; i++) hash = (hash * 31 + raw.charCodeAt(i)) >>> 0
+  return `_${hash.toString(16)}`
+}
+
+/** Register one tool per advertised skill; empty skills register nothing. */
+export function registerAgentTools(registrar: ToolRegistrar, opts: AgentToolsOptions): RegisteredTool[] {
+  const prefix = opts.toolPrefix ?? 'a2a'
+  const skills = opts.client.card.skills ?? []
+  const out: RegisteredTool[] = []
+  for (const skill of skills) {
+    const raw = `${prefix}__${opts.agentName}__${skill.id}`
+    const name = normalizeToolName(raw)
+    let toolName = name
+    if (out.some((t) => t.name === toolName)) {
+      let hash = 0
+      for (let i = 0; i < raw.length; i++) hash = (hash * 31 + raw.charCodeAt(i)) >>> 0
+      toolName = `${name.slice(0, 56)}_${hash.toString(16)}`
+    }
+    const dispose = registrar.register(makeTool(toolName, opts.client, skill, opts.contextFor))
+    if (dispose) out.push({ name: toolName, dispose })
+  }
+  return out
+}
+
+function makeTool(
+  name: string,
+  client: A2AClient,
+  skill: Pick<AgentSkill, 'id' | 'name' | 'description' | 'examples'>,
+  contextFor: (agentId: string | undefined) => string,
+): unknown {
+  const description = [
+    skill.description,
+    ...(skill.examples?.length ? [`Examples: ${skill.examples.join(' | ')}`] : []),
+  ].filter(Boolean).join('\n')
+
+  return {
+    name,
+    description,
+    parameters: {
+      type: 'object',
+      properties: {
+        prompt: {
+          type: 'string',
+          description: 'The task or instruction to send to the remote agent.',
+        },
+      },
+      required: ['prompt'],
+    },
+    output: {
+      schema: { type: 'string' },
+      render: (_args: unknown, value: unknown) => [{ type: 'text', text: String(value) }],
+    },
+    async execute(args: { prompt: string }, exec: { signal?: AbortSignal; agent?: { id?: string } }): Promise<string> {
+      const message: Message = {
+        messageId: crypto.randomUUID(),
+        role: Role.USER,
+        contextId: contextFor(exec.agent?.id),
+        parts: [{ text: args.prompt }],
+      }
+      const task = await client.sendMessage(message)
+      return textOf(task.artifacts, task.status.state, task.status.message?.parts)
+    },
+  }
+}
+
+/** Render a settled task's output as tool text (INPUT_REQUIRED surfaced, not thrown). */
+function textOf(
+  artifacts: readonly { readonly parts?: readonly Part[] }[] | undefined,
+  state: string,
+  statusParts: readonly Part[] | undefined,
+): string {
+  const output = partsToText(artifacts?.flatMap((a) => a.parts ?? []))
+  if (state === 'FAILED') {
+    throw new A2AError(-32000, `Remote agent task failed: ${output || partsToText(statusParts) || 'no detail'}`)
+  }
+  if (state === 'INPUT_REQUIRED' || state === 'AUTH_REQUIRED') {
+    const ask = partsToText(statusParts) || output || 'agent awaits input'
+    return `[remote agent ${state}] ${ask}`
+  }
+  return output || '(remote agent returned no output)'
+}

package/src/protocol.ts

@@ -0,0 +1,212 @@
+/**
+ * Agent2Agent (A2A) Protocol v1.0 — types, task states, JSON-RPC methods and
+ * error codes used by this plugin's JSON-RPC over HTTP binding.
+ *
+ * The surface mirrors the normative `a2a.proto` of the A2A project (Apache-2.0);
+ * this file is the plugin's own transcription and the single source of protocol
+ * truth. Bindings other than JSON-RPC over HTTP (gRPC, REST) are not provided.
+ * @module dsh-a2a/protocol
+ */
+
+/** Task lifecycle states (spec `TaskState`). */
+export enum TaskState {
+  SUBMITTED = 'SUBMITTED',
+  WORKING = 'WORKING',
+  INPUT_REQUIRED = 'INPUT_REQUIRED',
+  AUTH_REQUIRED = 'AUTH_REQUIRED',
+  COMPLETED = 'COMPLETED',
+  FAILED = 'FAILED',
+  CANCELED = 'CANCELED',
+  REJECTED = 'REJECTED',
+}
+
+/** States that settle a task; a settled task no longer transitions. */
+export const TERMINAL_STATES: ReadonlySet<TaskState> = new Set([
+  TaskState.COMPLETED,
+  TaskState.FAILED,
+  TaskState.CANCELED,
+  TaskState.REJECTED,
+])
+
+/** @returns whether the state settles the task. */
+export function isTerminal(state: TaskState): boolean {
+  return TERMINAL_STATES.has(state)
+}
+
+/** Message sender role (spec `Role`). */
+export enum Role {
+  USER = 'user',
+  AGENT = 'agent',
+}
+
+/** One message part: text, file (bytes or uri), or structured data. */
+export type Part =
+  | { readonly text: string; readonly metadata?: Record<string, unknown> }
+  | {
+    readonly file: {
+      readonly mimeType?: string
+      readonly name?: string
+      readonly bytes?: string
+      readonly uri?: string
+    }
+    readonly metadata?: Record<string, unknown>
+  }
+  | { readonly data: unknown; readonly metadata?: Record<string, unknown> }
+
+/** An interaction payload exchanged between agents. */
+export interface Message {
+  readonly messageId: string
+  readonly role: Role
+  readonly contextId?: string
+  /** Continuation: attaches this message to an existing task's conversation. */
+  readonly taskId?: string
+  readonly parts: readonly Part[]
+  readonly metadata?: Record<string, unknown>
+}
+
+/** Current state of a task, with an optional explanatory message. */
+export interface TaskStatus {
+  readonly state: TaskState
+  readonly message?: Message
+  readonly timestamp: string
+}
+
+/** A chunk of task output. */
+export interface Artifact {
+  readonly name?: string
+  readonly parts: readonly Part[]
+  readonly artifactId?: string
+}
+
+/** A task: the durable work unit of A2A. */
+export interface Task {
+  readonly id: string
+  readonly contextId?: string
+  readonly status: TaskStatus
+  readonly artifacts?: readonly Artifact[]
+  readonly history?: readonly Message[]
+  readonly metadata?: Record<string, unknown>
+}
+
+/** JSON-RPC 2.0 request as used by the A2A binding. */
+export interface JsonRpcRequest {
+  readonly jsonrpc: '2.0'
+  readonly id?: string | number | null
+  readonly method: string
+  readonly params?: unknown
+}
+
+export interface JsonRpcSuccess {
+  readonly jsonrpc: '2.0'
+  readonly id: string | number | null
+  readonly result: unknown
+}
+
+export interface JsonRpcErrorBody {
+  readonly code: number
+  readonly message: string
+  readonly data?: unknown
+}
+
+export interface JsonRpcError {
+  readonly jsonrpc: '2.0'
+  readonly id: string | number | null
+  readonly error: JsonRpcErrorBody
+}
+
+export type JsonRpcResponse = JsonRpcSuccess | JsonRpcError
+
+/** A skill advertised by an agent. */
+export interface AgentSkill {
+  readonly id: string
+  readonly name?: string
+  readonly description?: string
+  readonly tags?: readonly string[]
+  readonly examples?: readonly string[]
+  readonly inputModes?: readonly string[]
+  readonly outputModes?: readonly string[]
+}
+
+export interface AgentCapabilities {
+  readonly streaming?: boolean
+  readonly pushNotifications?: boolean
+  readonly stateTransitionHistory?: boolean
+  readonly extensions?: readonly string[]
+}
+
+/** One supported interface (transport binding) of an agent. */
+export interface AgentInterface {
+  readonly url: string
+  readonly protocolBinding?: 'JSONRPC' | 'REST' | 'gRPC' | string
+  readonly protocolVersion?: string
+  readonly authSchemes?: readonly string[]
+}
+
+/** Bearer-token security scheme advertised by the AgentCard. */
+export interface AgentSecurityScheme {
+  readonly type: 'http'
+  readonly scheme: 'bearer'
+  readonly description?: string
+}
+
+/** The discovery manifest of an A2A agent. */
+export interface AgentCard {
+  readonly name: string
+  readonly description: string
+  readonly version: string
+  readonly url?: string
+  readonly provider?: { readonly url: string; readonly organization: string }
+  readonly skills?: readonly AgentSkill[]
+  readonly capabilities?: AgentCapabilities
+  readonly defaultInputModes?: readonly string[]
+  readonly defaultOutputModes?: readonly string[]
+  readonly securitySchemes?: Record<string, AgentSecurityScheme>
+  readonly securityRequirements?: readonly Record<string, readonly string[]>[]
+  readonly supportedInterfaces?: readonly AgentInterface[]
+  readonly custom?: Record<string, unknown>
+}
+
+/** Streamed updates during a task run (SSE payloads). */
+export type StreamResponse =
+  | { readonly statusUpdate: { readonly taskId: string; readonly contextId?: string; readonly status: TaskStatus } }
+  | { readonly artifactUpdate: { readonly taskId: string; readonly contextId?: string; readonly artifact: Artifact; readonly lastChunk?: boolean } }
+  | { readonly task: Task }
+  | { readonly error: { readonly code: number; readonly message: string } }
+
+/** A2A v1.0 JSON-RPC method names (canonical PascalCase as in a2a.proto). */
+export const A2A_METHODS = {
+  sendMessage: 'SendMessage',
+  sendStreamingMessage: 'SendStreamingMessage',
+  getTask: 'GetTask',
+  listTasks: 'ListTasks',
+  cancelTask: 'CancelTask',
+  subscribeToTask: 'SubscribeToTask',
+  getExtendedAgentCard: 'GetExtendedAgentCard',
+} as const
+
+/** JSON-RPC error codes for the A2A binding (spec §error codes). */
+export const A2A_ERROR_CODES = {
+  INVALID_REQUEST: -32600,
+  METHOD_NOT_FOUND: -32601,
+  INVALID_PARAMS: -32602,
+  INTERNAL_ERROR: -32603,
+  UNAUTHORIZED: -32000,
+  TASK_NOT_FOUND: -32001,
+  TASK_CANCEL_NOT_ALLOWED: -32002,
+  AGENT_CARD_NOT_FOUND: -32004,
+  AGENT_CARD_SIGNATURE_INVALID: -32005,
+} as const
+
+/** Read a message's text parts as a single string (model-facing convenience). */
+export function partsToText(parts: readonly Part[] | undefined): string {
+  if (!parts) return ''
+  return parts
+    .map((p) => {
+      if ('text' in p && p.text) return p.text
+      if ('data' in p && p.data !== undefined) return JSON.stringify(p.data)
+      if ('file' in p) return p.file.uri ?? `[file ${p.file.name ?? p.file.mimeType ?? 'binary'}]`
+      return ''
+    })
+    .filter(Boolean)
+    .join('\n')
+}