@hanphone/dsh-a2a 0.2.0 → 0.3.0

package/src/servers/outbound-manager.ts

@@ -0,0 +1,289 @@
+/**
+ * Outbound server manager: owns every outbound A2A connection instance. Each
+ * instance is one connected remote — its own AgentCard URL, auth env, timeout,
+ * creator-declared name, and an optional agent-preset binding. Each live
+ * instance is one `OutboundAgentRegistry` with an isolated per-instance agent
+ * store; enabled instances map their remote skills to `a2a__<name>__<skill>`
+ * model tools. The manager owns the full lifecycle (add/enable/disable/remove/
+ * refresh) driven from the GUI and facade, persists each instance in the
+ * `outbound_servers` domain table, and disposes every connection on teardown.
+ *
+ * The `preset` field names the agent preset this DSH would compose its local
+ * hand-off session with when driving that remote. P0 connects skills to tools
+ * and manages the connection; the hand-off session composition behind `preset`
+ * is a documented extension point (the outbound tools currently call the
+ * remote directly) and the value is persisted metadata surfaced to the GUI.
+ * @module dsh-a2a/servers/outbound-manager
+ */
+
+import { OutboundAgentRegistry, type AgentStore } from '../outbound/registry.ts'
+import type { OutboundAgentRecord, OutboundServerRecord } from '../server/store.ts'
+
+/** Tool-registrar slice (structural `ctx.tools.register`). */
+export interface ToolRegistrar {
+  register(def: unknown): (() => void) | void
+}
+
+/** Host slices one manager needs. */
+export interface OutboundManagerHost {
+  readonly registrar: ToolRegistrar
+  readonly tokenOf: (env: string | undefined) => string | undefined
+  readonly onError: (message: string) => void
+  readonly defaultTimeoutMs: number
+}
+
+export interface OpResult {
+  readonly ok: boolean
+  readonly message: string
+}
+
+/** One outbound instance as the GUI/facade reads it. */
+export interface OutboundServerView {
+  readonly id: string
+  readonly name: string
+  readonly agentCardUrl: string
+  readonly preset?: string
+  readonly enabled: boolean
+  readonly timeoutMs: number
+  readonly state: 'connected' | 'disconnected' | 'failed'
+  readonly skillCount: number
+  readonly toolCount: number
+  readonly lastError?: string
+}
+
+/** An `AgentStore` bound to one outbound server instance's agents-table key. */
+export class ServerAgentStore implements AgentStore {
+  constructor(
+    private readonly table: {
+      get(key: string): string | undefined
+      put(key: string, value: string): Promise<void>
+    },
+    private readonly key: string,
+  ) {}
+
+  list(): OutboundAgentRecord[] {
+    const raw = this.table.get(this.key)
+    if (raw === undefined || raw === '') 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(this.key, JSON.stringify(records))
+  }
+}
+
+/** Persisted-instance store over the outbound_servers table. */
+export class DomainOutboundStore {
+  private static KEY(id: string): string {
+    return `out:${id}`
+  }
+
+  constructor(private readonly table: {
+    get(key: string): string | undefined
+    put(key: string, value: string): Promise<void>
+    entries?(): IterableIterator<[string, string]>
+  }) {}
+
+  list(): OutboundServerRecord[] {
+    const out: OutboundServerRecord[] = []
+    const entries = this.table.entries
+    if (entries === undefined) return out
+    // Call through the table (method `this` stays bound); the real KvTable's
+    // `entries()` reads instance state.
+    for (const [key, raw] of entries.call(this.table)) {
+      if (!key.startsWith('out:')) continue
+      const parsed = safeParse(raw)
+      if (parsed !== undefined) out.push(parsed)
+    }
+    return out
+  }
+
+  get(id: string): OutboundServerRecord | undefined {
+    const raw = this.table.get(DomainOutboundStore.KEY(id))
+    return raw === undefined ? undefined : safeParse(raw)
+  }
+
+  async save(record: OutboundServerRecord): Promise<void> {
+    await this.table.put(DomainOutboundStore.KEY(record.id), JSON.stringify(record))
+  }
+
+  async remove(id: string): Promise<void> {
+    await this.table.put(DomainOutboundStore.KEY(id), '')
+  }
+}
+
+function safeParse(raw: string): OutboundServerRecord | undefined {
+  try {
+    const parsed = JSON.parse(raw) as OutboundServerRecord
+    if (typeof parsed.id !== 'string' || typeof parsed.name !== 'string' || typeof parsed.agentCardUrl !== 'string') return undefined
+    return parsed
+  } catch {
+    return undefined
+  }
+}
+
+/** Creator input for a new outbound instance (id optional; manager allocates). */
+export interface OutboundCreateInput {
+  readonly id?: string
+  readonly name: string
+  readonly agentCardUrl: string
+  readonly bearerTokenEnv?: string
+  readonly preset?: string
+  readonly enabled?: boolean
+  readonly timeoutMs?: number
+}
+
+/** Manages the live set of outbound connection instances. */
+export class OutboundServerManager {
+  private readonly registries = new Map<string, OutboundAgentRegistry>()
+
+  constructor(
+    private readonly host: OutboundManagerHost,
+    /** Persistence sink for each instance's agent records (the `agents` table). */
+    private readonly agentSink: { get(key: string): string | undefined; put(key: string, value: string): Promise<void> },
+    /** Persisted OutboundServerRecord store (the `outbound_servers` table). */
+    private readonly records: DomainOutboundStore,
+    /** Allocate a fresh stable instance id. */
+    private readonly newId: () => string,
+  ) {}
+
+  /** The host default connection timeout (what a minimal record falls back to). */
+  get defaultTimeoutMs(): number {
+    return this.host.defaultTimeoutMs
+  }
+
+  private agentKeyFor(id: string): string {
+    return `out:${id}`
+  }
+
+  private makeRegistry(record: OutboundServerRecord): OutboundAgentRegistry {
+    return new OutboundAgentRegistry({
+      registrar: { register: (def) => this.host.registrar.register(def) },
+      store: new ServerAgentStore(this.agentSink, this.agentKeyFor(record.id)),
+      toolPrefix: 'a2a',
+      defaultTimeoutMs: this.host.defaultTimeoutMs,
+      tokenOf: (env) => this.host.tokenOf(env),
+      onError: this.host.onError,
+    })
+  }
+
+  /** Record → registry spec for connecting one instance. */
+  private toSpec(record: OutboundServerRecord): { name: string; agentCardUrl: string; bearerTokenEnv?: string; enabled?: boolean; timeoutMs?: number } {
+    return {
+      name: record.name,
+      agentCardUrl: record.agentCardUrl,
+      ...(record.bearerTokenEnv !== undefined ? { bearerTokenEnv: record.bearerTokenEnv } : {}),
+      enabled: record.enabled,
+      timeoutMs: record.timeoutMs ?? this.host.defaultTimeoutMs,
+    }
+  }
+
+  /** Boot every persisted enabled instance as a connected registry. */
+  boot(): void {
+    for (const record of this.records.list()) {
+      try {
+        const registry = this.makeRegistry(record)
+        this.registries.set(record.id, registry)
+        if (record.enabled) registry.loadAll()
+      } catch (err) {
+        this.host.onError(`[a2a:out:${record.id}] failed to boot: ${String((err as Error).message)}`)
+      }
+    }
+  }
+
+  /** One view per live instance (enriched from its registry / record). */
+  list(): readonly OutboundServerView[] {
+    return [...this.registries.keys()].map((id) => this.viewFor(id)).filter((v): v is OutboundServerView => v !== undefined)
+  }
+
+  get(id: string): OutboundServerRegistryHandle | undefined {
+    const registry = this.registries.get(id)
+    return registry === undefined ? undefined : { id, registry }
+  }
+
+  private viewFor(id: string): OutboundServerView | undefined {
+    const registry = this.registries.get(id)
+    const record = this.records.get(id)
+    if (registry === undefined || record === undefined) return undefined
+    const agent = registry.list()[0]
+    return {
+      id,
+      name: record.name,
+      agentCardUrl: record.agentCardUrl,
+      ...(record.preset !== undefined ? { preset: record.preset } : {}),
+      enabled: agent?.enabled ?? record.enabled,
+      timeoutMs: record.timeoutMs,
+      state: agent?.state ?? 'disconnected',
+      skillCount: agent?.skillCount ?? 0,
+      toolCount: agent?.toolCount ?? 0,
+      ...(agent?.lastError !== undefined ? { lastError: agent.lastError } : {}),
+    }
+  }
+
+  /** Create, persist, and connect a new outbound instance. */
+  async add(input: OutboundCreateInput): Promise<OpResult & { readonly id?: string }> {
+    const record: OutboundServerRecord = {
+      id: input.id ?? this.newId(),
+      name: input.name,
+      agentCardUrl: input.agentCardUrl,
+      ...(input.bearerTokenEnv !== undefined ? { bearerTokenEnv: input.bearerTokenEnv } : {}),
+      ...(input.preset !== undefined ? { preset: input.preset } : {}),
+      enabled: input.enabled ?? true,
+      timeoutMs: input.timeoutMs ?? this.host.defaultTimeoutMs,
+    }
+    if (this.registries.has(record.id)) return { ok: false, message: `outbound server ${record.id} already exists` }
+    const registry = this.makeRegistry(record)
+    await this.records.save(record)
+    this.registries.set(record.id, registry)
+    if (record.enabled) {
+      const result = await registry.add(this.toSpec(record))
+      return result.ok ? { ...result, id: record.id } : result
+    }
+    return { ok: true, message: `outbound server "${record.name}" added (disabled)`, id: record.id }
+  }
+
+  async setEnabled(id: string, enabled: boolean): Promise<OpResult> {
+    const registry = this.registries.get(id)
+    if (registry === undefined) return { ok: false, message: `outbound server ${id} not found` }
+    const view = registry.list()[0]
+    const record = this.records.get(id)
+    if (record !== undefined) await this.records.save({ ...record, enabled })
+    if (view === undefined) return { ok: true, message: `outbound server ${id} marked ${enabled ? 'enabled' : 'disabled'}` }
+    return registry.setEnabled(view.id, enabled)
+  }
+
+  async remove(id: string): Promise<OpResult> {
+    const registry = this.registries.get(id)
+    if (registry === undefined) return { ok: false, message: `outbound server ${id} not found` }
+    const view = registry.list()[0]
+    if (view !== undefined) await registry.remove(view.id)
+    await registry.disposeAll()
+    this.registries.delete(id)
+    await this.records.remove(id)
+    return { ok: true, message: `outbound server ${id} removed` }
+  }
+
+  async refresh(id: string): Promise<OpResult> {
+    const registry = this.registries.get(id)
+    if (registry === undefined) return { ok: false, message: `outbound server ${id} not found` }
+    const view = registry.list()[0]
+    if (view === undefined) return { ok: false, message: `outbound server ${id} has no connected agent` }
+    return registry.refresh(view.id)
+  }
+
+  async disposeAll(): Promise<void> {
+    for (const registry of this.registries.values()) await registry.disposeAll()
+    this.registries.clear()
+  }
+}
+
+/** Handle to one live outbound connection (registry + derived view). */
+export interface OutboundServerRegistryHandle {
+  readonly id: string
+  readonly registry: OutboundAgentRegistry
+}

package/src/service.ts

@@ -1,7 +1,7 @@
 /**
- * The `ctx.a2a` service facade: the thin read/control surface commands and
- * other plugins use. Registered as a Cordis Service so the key disappears
- * with the plugin fiber.
+ * The `ctx.a2a` service facade: the thin read/control surface commands, the
+ * GUI API, and other plugins use. Registered as a Cordis Service so the key
+ * disappears with the plugin fiber.
  * @module dsh-a2a/service
  */
 
@@ -13,25 +13,98 @@ export interface OpResult {
   readonly message: string
 }
 
+/** Agent-preset roster row shown in the instance pickers. */
+export interface PresetView {
+  readonly id: string
+  readonly name?: string
+  readonly description?: string
+  /** Whether this preset is the deployment default when none is named. */
+  readonly isDefault?: boolean
+}
+
+/** A skill declaration as the GUI reads it. */
+export interface SkillView {
+  readonly id: string
+  readonly name: string
+  readonly description?: string
+}
+
+/** One inbound server instance, as the GUI/facade reads it. */
+export interface InboundServerView {
+  readonly id: string
+  readonly name: string
+  readonly description: string
+  readonly version: string
+  readonly endpointPath: string
+  readonly preset?: string
+  readonly authTokenEnv?: string
+  readonly cardPath: string
+  readonly cardUrl?: string
+  readonly enabled: boolean
+  readonly skills: readonly SkillView[]
+}
+
+/** One outbound server instance, as the GUI/facade reads it. */
+export interface OutboundServerView {
+  readonly id: string
+  readonly name: string
+  readonly agentCardUrl: string
+  readonly preset?: string
+  readonly enabled: boolean
+  readonly timeoutMs: number
+  readonly state: 'connected' | 'disconnected' | 'failed'
+  readonly skillCount: number
+  readonly toolCount: number
+  readonly lastError?: string
+}
+
+/** Creator input for an inbound server instance. */
+export interface InboundCreateInput {
+  readonly name: string
+  readonly description: string
+  readonly version: string
+  readonly endpointPath?: string
+  readonly preset?: string
+  readonly authTokenEnv?: string
+  readonly skills?: readonly SkillView[]
+  readonly enabled?: boolean
+}
+
+/** Creator input for an outbound server instance. */
+export interface OutboundCreateInput {
+  readonly id?: string
+  readonly name: string
+  readonly agentCardUrl: string
+  readonly bearerTokenEnv?: string
+  readonly preset?: string
+  readonly enabled?: boolean
+  readonly timeoutMs?: number
+}
+
 /** The implementation the facade delegates to (owned by the plugin assembly). */
 export interface A2AServiceImpl {
   status(): unknown
-  enableServer(enable: boolean): Promise<OpResult>
+  /** Agent-preset roster for the GUI pickers. */
+  presets(): Promise<PresetView[]>
+  // ── inbound server instances ────────────────────────────────────────
+  listInboundServers(): InboundServerView[]
+  createInboundServer(input: InboundCreateInput): Promise<OpResult>
+  removeInboundServer(id: string): Promise<OpResult>
+  setInboundServerEnabled(id: string, enabled: boolean): Promise<OpResult>
+  updateInboundServer(id: string, patch: { name?: string; description?: string; version?: string; endpointPath?: string; preset?: string; authTokenEnv?: string; skills?: readonly SkillView[] }): Promise<OpResult>
+  // ── outbound server instances ───────────────────────────────────────
+  listOutboundServers(): OutboundServerView[]
+  createOutboundServer(input: OutboundCreateInput): Promise<OpResult>
+  removeOutboundServer(id: string): Promise<OpResult>
+  setOutboundServerEnabled(id: string, enabled: boolean): Promise<OpResult>
+  refreshOutboundServer(id: string): Promise<OpResult>
+  // ── tasks ───────────────────────────────────────────────────────────
   getTask(taskId: string): unknown
   listTasks(): unknown
   cancelTask(taskId: string): Promise<OpResult>
-  agents(): unknown
-  addAgent(spec: { readonly name: string; readonly agentCardUrl: string; readonly bearerTokenEnv?: string }): Promise<OpResult>
-  removeAgent(id: string): Promise<OpResult>
-  setAgentEnabled(id: string, enabled: boolean): Promise<OpResult>
-  refreshAgentCard(id: string): Promise<OpResult>
-  /** Current service identity (persisted override + composition defaults). */
-  identity(): unknown
-  /** Persist and apply a new service identity onto the live AgentCard. */
-  updateIdentity(patch: { readonly name?: string; readonly description?: string; readonly version?: string }): Promise<OpResult>
-  /** Cancel an inbound peer's active tasks and drop its record. */
-  closeInbound(peerId: string): Promise<OpResult>
+  // ── inbound peer monitoring (per instance) ──────────────────────────
   inbounds(): unknown
+  closeInbound(peerId: string): Promise<OpResult>
 }
 
 /** The service other plugins read as `ctx.a2a`. */
@@ -47,55 +120,67 @@ export class A2AService extends Service {
     return this.impl.status()
   }
 
-  async enableServer(enable: boolean): Promise<OpResult> {
-    return this.impl.enableServer(enable)
+  async presets(): Promise<PresetView[]> {
+    return this.impl.presets()
   }
 
-  getTask(taskId: string): unknown {
-    return this.impl.getTask(taskId)
+  listInboundServers(): InboundServerView[] {
+    return this.impl.listInboundServers()
   }
 
-  listTasks(): unknown {
-    return this.impl.listTasks()
+  async createInboundServer(input: InboundCreateInput): Promise<OpResult> {
+    return this.impl.createInboundServer(input)
   }
 
-  async cancelTask(taskId: string): Promise<OpResult> {
-    return this.impl.cancelTask(taskId)
+  async removeInboundServer(id: string): Promise<OpResult> {
+    return this.impl.removeInboundServer(id)
   }
 
-  agents(): unknown {
-    return this.impl.agents()
+  async setInboundServerEnabled(id: string, enabled: boolean): Promise<OpResult> {
+    return this.impl.setInboundServerEnabled(id, enabled)
   }
 
-  async addAgent(spec: { readonly name: string; readonly agentCardUrl: string; readonly bearerTokenEnv?: string }): Promise<OpResult> {
-    return this.impl.addAgent(spec)
+  async updateInboundServer(id: string, patch: { name?: string; description?: string; version?: string; endpointPath?: string; preset?: string; authTokenEnv?: string; skills?: readonly SkillView[] }): Promise<OpResult> {
+    return this.impl.updateInboundServer(id, patch)
   }
 
-  async removeAgent(id: string): Promise<OpResult> {
-    return this.impl.removeAgent(id)
+  listOutboundServers(): OutboundServerView[] {
+    return this.impl.listOutboundServers()
   }
 
-  async setAgentEnabled(id: string, enabled: boolean): Promise<OpResult> {
-    return this.impl.setAgentEnabled(id, enabled)
+  async createOutboundServer(input: OutboundCreateInput): Promise<OpResult> {
+    return this.impl.createOutboundServer(input)
   }
 
-  async refreshAgentCard(id: string): Promise<OpResult> {
-    return this.impl.refreshAgentCard(id)
+  async removeOutboundServer(id: string): Promise<OpResult> {
+    return this.impl.removeOutboundServer(id)
   }
 
-  identity(): unknown {
-    return this.impl.identity()
+  async setOutboundServerEnabled(id: string, enabled: boolean): Promise<OpResult> {
+    return this.impl.setOutboundServerEnabled(id, enabled)
   }
 
-  async updateIdentity(patch: { readonly name?: string; readonly description?: string; readonly version?: string }): Promise<OpResult> {
-    return this.impl.updateIdentity(patch)
+  async refreshOutboundServer(id: string): Promise<OpResult> {
+    return this.impl.refreshOutboundServer(id)
   }
 
-  async closeInbound(peerId: string): Promise<OpResult> {
-    return this.impl.closeInbound(peerId)
+  getTask(taskId: string): unknown {
+    return this.impl.getTask(taskId)
+  }
+
+  listTasks(): unknown {
+    return this.impl.listTasks()
+  }
+
+  async cancelTask(taskId: string): Promise<OpResult> {
+    return this.impl.cancelTask(taskId)
   }
 
   inbounds(): unknown {
     return this.impl.inbounds()
   }
-}
+
+  async closeInbound(peerId: string): Promise<OpResult> {
+    return this.impl.closeInbound(peerId)
+  }
+}