@hanphone/dsh-a2a 0.1.0 → 0.3.0

package/src/servers/inbound-manager.ts

@@ -0,0 +1,385 @@
+/**
+ * Inbound server manager: owns every inbound A2A server instance. Each
+ * instance binds one agent preset (its session pool is composed from that
+ * preset), advertises creator-declared skills, and serves its own endpoint and
+ * AgentCard route. Instances are persisted in the `inbound_servers` domain
+ * table and assembled on boot; the manager owns route registration and the
+ * full lifecycle (add/enable/disable/update/remove) driven from the GUI and
+ * facade, and disposes every instance's environment on teardown.
+ *
+ * Skill declaration: the stored `skills` list is exactly what the creator
+ * declared. When a creator leaves it empty at creation time, the default skill
+ * derives from the bound preset's display name (else the built-in `chat`
+ * skill), per the v1.0 design — the v0.2 tool white-list derivation is gone.
+ * @module dsh-a2a/servers/inbound-manager
+ */
+
+import type { Context } from '@deepseek-ai/cordis'
+import { buildCard } from '../server/card.ts'
+import { A2AServer } from '../server/a2a-server.ts'
+import { A2aRoutes } from '../server/routes.ts'
+import { ContextSessionPool, 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 { ExecutorSet } from '../server/executor.ts'
+import { LiveInboundRegistry } from '../server/inbound-registry.ts'
+import type { TaskStore, InboundServerRecord } from '../server/store.ts'
+import type { AgentSkill } from '../protocol.ts'
+import type { GateInput, GateResult } from '../server/a2a-server.ts'
+import type { InboundTaskDecision } from '../events.ts'
+
+/** Web-server slice the manager registers instance routes on. */
+export interface WebServerLike {
+  register(route: {
+    readonly kind: 'exact' | 'prefix'
+    readonly path: string
+    handler(...args: unknown[]): unknown
+  }): () => void
+}
+
+/** Host service slices one manager needs. */
+export interface InboundManagerHost {
+  readonly ctx: Context
+  readonly webServer: WebServerLike
+  readonly tasks: TaskStore
+  readonly logger: { info(message: string): void; warn(message: string): void; error(message: string): void }
+  readonly agents?: AgentRegistryLike
+  readonly agentPresets?: AgentPresetsLike
+  readonly subagents?: SubagentsLike
+  readonly sessionCwd: string
+  readonly defaultBaseUrl: string
+  readonly subagentProvider: string
+  /** Resolve the deployment's default model options (may be undefined). */
+  readonly resolveDefaultModel?: () => { readonly provider?: string; readonly model?: string } | undefined
+  /** Allocate a fresh stable instance id. */
+  readonly newId: () => string
+}
+
+/** One live inbound instance's runtime handle. */
+export interface LiveInboundServer {
+  readonly id: string
+  readonly record: InboundServerRecord
+  readonly card: ReturnType<typeof buildCard>
+  readonly server: A2AServer
+  readonly routes: A2aRoutes
+  readonly inbound: LiveInboundRegistry
+  readonly executors: ExecutorSet
+  readonly endpointPath: string
+  readonly cardPath: string
+  dispose(): void
+}
+
+/** Creator input for a new (or updated) inbound instance. */
+export interface InboundCreateInput {
+  readonly name: string
+  readonly description: string
+  readonly version: string
+  readonly endpointPath?: string
+  readonly preset?: string
+  readonly authTokenEnv?: string
+  /** Declared skills; empty defaults to the preset name (or `chat`). */
+  readonly skills?: readonly AgentSkill[]
+  readonly enabled?: boolean
+}
+
+export interface OpResult {
+  readonly ok: boolean
+  readonly message: string
+}
+
+function refuseExecutor(reason: string) {
+  return {
+    name: 'refuse',
+    async execute(): Promise<{ parts: { text: string }[] }> {
+      throw new Error(`a2a: ${reason}; refusing inbound task`)
+    },
+  }
+}
+
+/** Default skkill when a creator declares none: the preset display name. */
+export function defaultSkillFor(
+  skills: readonly AgentSkill[] | undefined,
+  presetName: string | undefined,
+): readonly AgentSkill[] {
+  if (skills !== undefined && skills.length > 0) return skills
+  if (presetName !== undefined && presetName.length > 0) {
+    return [{ id: 'chat', name: presetName, description: `Compose inbound sessions from the "${presetName}" agent preset.`, tags: ['preset'] }]
+  }
+  return [{ id: 'chat', name: 'chat', description: 'Conversational assistance over a DSH agent session.', tags: ['chat'] }]
+}
+
+/** Assemble one live instance from a persisted record. */
+function assemble(record: InboundServerRecord, host: InboundManagerHost): LiveInboundServer {
+  const skills: readonly AgentSkill[] = record.skills
+  const endpointPath = record.endpointPath
+  const cardPath = `${endpointPath.replace(/\/$/, '')}/agent-card.json`
+  const card = buildCard({
+    baseUrl: host.defaultBaseUrl,
+    endpointPath,
+    name: record.name,
+    description: record.description,
+    version: record.version,
+    skills,
+    ...(record.authTokenEnv !== undefined && process.env[record.authTokenEnv] !== undefined
+      ? { authToken: process.env[record.authTokenEnv]! }
+      : {}),
+  })
+
+  // One preset-bound session pool per instance.
+  const sessionPool = host.agents
+    ? new ContextSessionPool(host.agents, {
+      cwd: host.sessionCwd,
+      ...(host.agentPresets !== undefined ? { agentPresets: host.agentPresets } : {}),
+      ...(record.preset !== undefined ? { presetId: () => record.preset } : {}),
+      // `?.()` yields `{ provider?, model? } | undefined`, matching the
+      // AgentRuntimeOptions.resolveAgentOptions signature under
+      // exactOptionalPropertyTypes.
+      resolveAgentOptions: () => host.resolveDefaultModel?.(),
+    })
+    : undefined
+  const sessionExecutor = sessionPool ? createSessionExecutor(sessionPool) : refuseExecutor('no agent loop mounted')
+  const subagentExecutor = sessionPool !== undefined && host.subagents !== undefined
+    ? createSubagentExecutor({ pool: sessionPool, subagents: host.subagents, provider: host.subagentProvider })
+    : undefined
+  const executors = new ExecutorSet({ chat: 'session' }, sessionExecutor, subagentExecutor)
+
+  const inbound = new LiveInboundRegistry()
+  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 host.ctx.waterfall('a2a/inbound-task', decision, async (d) => d)
+    host.logger.info(`[a2a:${record.id}] inbound skill=${decided.skill} 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: host.tasks,
+    executors,
+    ...(card.securitySchemes !== undefined ? { authToken: 'configured' } : {}),
+    cardPath,
+    gate,
+    onInbound: (facts) => inbound.note({
+      method: facts.method,
+      ...(facts.source !== undefined ? { source: facts.source } : {}),
+      taskIds: facts.taskIds,
+      streaming: facts.streaming,
+    }),
+    onTaskSettled: (taskId) => {
+      host.logger.info(`[a2a:${record.id}] task settled ${taskId}`)
+      inbound.settle(taskId)
+    },
+  })
+  const routes = new A2aRoutes(host.webServer, server, cardPath)
+
+  return {
+    id: record.id,
+    record,
+    card,
+    server,
+    routes,
+    inbound,
+    executors,
+    endpointPath,
+    cardPath,
+    dispose: () => {
+      routes.dispose()
+      void executors.disposeAll().catch(() => {})
+    },
+  }
+}
+
+/** Persisted-instance store over the inbound_servers table. */
+export class DomainInboundStore {
+  private static KEY(id: string): string {
+    return `in:${id}`
+  }
+
+  constructor(private readonly table: {
+    get(key: string): string | undefined
+    put(key: string, value: string): Promise<void>
+    entries?(): IterableIterator<[string, string]>
+    keys?(): IterableIterator<string>
+  }) {}
+
+  list(): InboundServerRecord[] {
+    const out: InboundServerRecord[] = []
+    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('in:')) continue
+      const parsed = safeParse(raw)
+      if (parsed !== undefined) out.push(parsed)
+    }
+    return out
+  }
+
+  get(id: string): InboundServerRecord | undefined {
+    const raw = this.table.get(DomainInboundStore.KEY(id))
+    return raw === undefined ? undefined : safeParse(raw)
+  }
+
+  async save(record: InboundServerRecord): Promise<void> {
+    await this.table.put(DomainInboundStore.KEY(record.id), JSON.stringify(record))
+  }
+
+  async remove(id: string): Promise<void> {
+    await this.table.put(DomainInboundStore.KEY(id), '')
+  }
+}
+
+function safeParse(raw: string): InboundServerRecord | undefined {
+  try {
+    const parsed = JSON.parse(raw) as InboundServerRecord
+    if (typeof parsed.id !== 'string' || typeof parsed.name !== 'string' || !Array.isArray(parsed.skills)) return undefined
+    return parsed
+  } catch {
+    return undefined
+  }
+}
+
+/** Manages the live set of inbound server instances. */
+export class InboundServerManager {
+  private readonly live = new Map<string, LiveInboundServer>()
+
+  constructor(
+    private readonly host: InboundManagerHost,
+    private readonly store: DomainInboundStore,
+  ) {}
+
+  /** Assemble every persisted enabled instance (boot). */
+  boot(): void {
+    for (const record of this.store.list()) {
+      try {
+        const live = assemble(record, this.host)
+        this.live.set(record.id, live)
+        if (record.enabled) live.routes.enable()
+      } catch (err) {
+        this.host.logger.error(`[a2a:${record.id}] failed to assemble: ${String((err as Error).message)}`)
+      }
+    }
+  }
+
+  list(): readonly LiveInboundServer[] {
+    return [...this.live.values()]
+  }
+
+  get(id: string): LiveInboundServer | undefined {
+    return this.live.get(id)
+  }
+
+  /** Resolve the display name of a preset id (undefined when unnamed/absent). */
+  private async presetDisplayName(preset: string | undefined): Promise<string | undefined> {
+    if (preset === undefined || this.host.agentPresets === undefined) return undefined
+    try {
+      const resolved = await this.host.agentPresets.resolve(preset)
+      return resolved.name ?? resolved.id
+    } catch {
+      return undefined
+    }
+  }
+
+  /** Create, persist, and assemble a new inbound instance. */
+  async add(input: InboundCreateInput): Promise<OpResult & { readonly id?: string }> {
+    const id = this.newId(input.name)
+    if (this.live.has(id)) return { ok: false, message: `inbound server ${id} already exists` }
+    const presetName = await this.presetDisplayName(input.preset)
+    const record: InboundServerRecord = {
+      id,
+      name: input.name,
+      description: input.description,
+      version: input.version,
+      endpointPath: input.endpointPath ?? `/a2a/${id}`,
+      ...(input.preset !== undefined ? { preset: input.preset } : {}),
+      ...(input.authTokenEnv !== undefined ? { authTokenEnv: input.authTokenEnv } : {}),
+      skills: [...defaultSkillFor(input.skills, presetName)],
+      enabled: input.enabled ?? true,
+    }
+    try {
+      const live = assemble(record, this.host)
+      await this.store.save(record)
+      this.live.set(id, live)
+      if (record.enabled) live.routes.enable()
+      return { ok: true, message: `inbound server "${record.name}" created`, id }
+    } catch (err) {
+      return { ok: false, message: `failed to create inbound server: ${String((err as Error).message)}` }
+    }
+  }
+
+  /** Persist, rebuild, and apply a patch onto a live instance. */
+  async update(id: string, patch: Partial<Pick<InboundServerRecord, 'name' | 'description' | 'version' | 'endpointPath' | 'preset' | 'authTokenEnv' | 'skills'>>): Promise<OpResult> {
+    const live = this.live.get(id)
+    const stored = this.store.get(id)
+    if (live === undefined || stored === undefined) return { ok: false, message: `inbound server ${id} not found` }
+    const next: InboundServerRecord = {
+      ...stored,
+      name: patch.name ?? stored.name,
+      description: patch.description ?? stored.description,
+      version: patch.version ?? stored.version,
+      endpointPath: patch.endpointPath ?? stored.endpointPath,
+      ...(patch.preset !== undefined ? { preset: patch.preset } : {}),
+      ...(patch.authTokenEnv !== undefined ? { authTokenEnv: patch.authTokenEnv } : {}),
+      skills: patch.skills ?? stored.skills,
+      enabled: stored.enabled,
+    }
+    try {
+      await this.store.save(next)
+      const replaced = assemble(next, this.host)
+      // Preserve the route registration state while swapping runtime halves.
+      const wasEnabled = live.routes.active
+      live.dispose()
+      this.live.set(id, replaced)
+      if (wasEnabled || next.enabled) replaced.routes.enable()
+      return { ok: true, message: `inbound server ${id} updated` }
+    } catch (err) {
+      return { ok: false, message: `failed to update inbound server: ${String((err as Error).message)}` }
+    }
+  }
+
+  /** Enable/disable an instance's routes. */
+  setEnabled(id: string, enabled: boolean): OpResult {
+    const live = this.live.get(id)
+    if (live === undefined) return { ok: false, message: `inbound server ${id} not found` }
+    if (enabled) live.routes.enable()
+    else live.routes.disable()
+    const stored = this.store.get(id)
+    if (stored !== undefined) {
+      void this.store.save({ ...stored, enabled }).catch(() => {})
+    }
+    return { ok: true, message: `inbound server ${id} ${enabled ? 'enabled' : 'disabled'}` }
+  }
+
+  /** Remove, dispose, and unpersist an instance. */
+  async remove(id: string): Promise<OpResult> {
+    const live = this.live.get(id)
+    if (live === undefined) return { ok: false, message: `inbound server ${id} not found` }
+    live.dispose()
+    this.live.delete(id)
+    await this.store.remove(id)
+    return { ok: true, message: `inbound server ${id} removed` }
+  }
+
+  /** Dispose every instance. */
+  disposeAll(): void {
+    for (const live of this.live.values()) live.dispose()
+    this.live.clear()
+  }
+
+  private newId(seed: string): string {
+    const slug = seed.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '') || 'server'
+    return `${slug}-${this.host.newId()}`
+  }
+}
+
+export type { AgentSkill }

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
+}