@hanphone/dsh-a2a 0.2.0 → 0.3.1

package/src/server/store.ts

@@ -32,6 +32,8 @@ export interface TaskRecord {
   readonly executor: 'session' | 'subagent'
   readonly summary: string | null
   readonly error?: { readonly code: string; readonly message: string }
+  /** The inbound server instance this task arrived through. */
+  readonly serverId?: string
 }
 
 /** One durable context→session binding (inbound conversation ↔ DSH session). */
@@ -50,6 +52,31 @@ export interface OutboundAgentRecord {
   readonly lastCardAt: string | null
 }
 
+/** One durable inbound server instance. */
+export interface InboundServerRecord {
+  readonly id: string
+  readonly name: string
+  readonly description: string
+  readonly version: string
+  readonly endpointPath: string
+  /** Agent preset id composing inbound sessions; absent falls back to the deployment default. */
+  readonly preset?: string
+  readonly authTokenEnv?: string
+  readonly enabled: boolean
+}
+
+/** One durable outbound server connection instance. */
+export interface OutboundServerRecord {
+  readonly id: string
+  readonly name: string
+  readonly agentCardUrl: string
+  readonly bearerTokenEnv?: string
+  /** Preset composing this DSH's local session when talking to the remote. */
+  readonly preset?: string
+  readonly enabled: boolean
+  readonly timeoutMs: number
+}
+
 /** JSON-encoded record schema shared by every `a2a` table. */
 const json = z.string()
 
@@ -62,6 +89,8 @@ export const a2aDomainSpec = defineDomain({
     contexts: domainTable<string, string>(json),
     agents: domainTable<string, string>(json),
     identity: domainTable<string, string>(json),
+    inbound_servers: domainTable<string, string>(json),
+    outbound_servers: domainTable<string, string>(json),
   },
 })
 
@@ -112,6 +141,14 @@ export class A2aDomain {
     return this.handle.table('identity')
   }
 
+  get inbound_servers(): KvTable<string, string> {
+    return this.handle.table('inbound_servers')
+  }
+
+  get outbound_servers(): KvTable<string, string> {
+    return this.handle.table('outbound_servers')
+  }
+
   async close(): Promise<void> {
     await this.handle.close()
   }
@@ -119,7 +156,7 @@ export class A2aDomain {
 
 /** Task-store contract shared by the domain-backed and memory stores. */
 export interface TaskStore {
-  create(input: { contextId: string; skill: string; parts: readonly Part[]; remotePeerId: string | null }): TaskRecord
+  create(input: { contextId: string; skill: string; parts: readonly Part[]; remotePeerId: string | null; serverId?: string }): TaskRecord
   get(taskId: string): TaskRecord | undefined
   list(): TaskRecord[]
   setState(taskId: string, state: TaskState, message?: { code: string; text: string }): TaskRecord
@@ -146,7 +183,7 @@ export class MemoryTaskStore implements TaskStore {
   private tasks = new Map<string, TaskRecord>()
   private contexts = new Map<string, string>()
 
-  create(input: { contextId: string; skill: string; parts: readonly Part[]; remotePeerId: string | null }): TaskRecord {
+  create(input: { contextId: string; skill: string; parts: readonly Part[]; remotePeerId: string | null; serverId?: string }): TaskRecord {
     const record: TaskRecord = {
       taskId: `a2a-${crypto.randomUUID()}`,
       contextId: input.contextId,
@@ -160,6 +197,7 @@ export class MemoryTaskStore implements TaskStore {
       artifacts: [],
       executor: 'session',
       summary: null,
+      ...(input.serverId !== undefined ? { serverId: input.serverId } : {}),
     }
     this.tasks.set(record.taskId, record)
     return record
@@ -244,7 +282,7 @@ export class DomainTaskStore implements TaskStore {
     }
   }
 
-  create(input: { contextId: string; skill: string; parts: readonly Part[]; remotePeerId: string | null }): TaskRecord {
+  create(input: { contextId: string; skill: string; parts: readonly Part[]; remotePeerId: string | null; serverId?: string }): TaskRecord {
     const record: TaskRecord = {
       taskId: `a2a-${crypto.randomUUID()}`,
       contextId: input.contextId,
@@ -258,6 +296,7 @@ export class DomainTaskStore implements TaskStore {
       artifacts: [],
       executor: 'session',
       summary: null,
+      ...(input.serverId !== undefined ? { serverId: input.serverId } : {}),
     }
     this.records.set(record.taskId, record)
     // Persist eagerly; a failed write must fail the task, not silently lose it.

package/src/servers/inbound-manager.ts

@@ -0,0 +1,416 @@
+/**
+ * Inbound server manager: owns every inbound A2A server instance. Each
+ * instance binds one concrete agent preset (its session pool is composed from
+ * that preset) 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 is DERIVED, never typed: "the preset decides its skills;
+ * everything is a plugin." An instance's AgentCard skills are the
+ * model-invocable entries of its preset's skill directory — the preset's
+ * standing scope key (`agentPresets.standingKeyFor`) plus
+ * `ctx.skills.list({ scope })` — resolved automatically at add/update/boot
+ * and cached on the live instance; the creator types no skill text. A missing
+ * skills service or standing mount falls back to a built-in `chat` skill so
+ * minimal compositions stay exercisable.
+ * @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, type SkillsLike } 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 skills?: SkillsLike
+  readonly subagents?: SubagentsLike
+  readonly sessionCwd: string
+  readonly defaultBaseUrl: string
+  readonly subagentProvider: string
+  /** Deployment default preset id (from `agentPresets.defaultId`), when known. */
+  readonly defaultPresetId?: 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
+  /** Effective preset id (record's or the deployment default). */
+  readonly preset: string | undefined
+  /** Derived skill declarations (cached at assemble time). */
+  readonly skills: readonly AgentSkill[]
+  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
+  /** Preset id; absent = the deployment default preset. */
+  readonly preset?: string
+  readonly authTokenEnv?: string
+  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`)
+    },
+  }
+}
+
+/** Built-in fallback skill when no skills service / standing mount exists. */
+export function chatFallbackSkills(): readonly AgentSkill[] {
+  return [{ id: 'chat', name: 'chat', description: 'Conversational assistance over a DSH agent session.', tags: ['chat'] }]
+}
+
+/**
+ * Derive an instance's AgentCard skills from its preset's skill directory.
+ *
+ * `agentPresets.standingKeyFor(preset)` yields the preset's standing scope
+ * key (no agent required); `ctx.skills.list({ scope })` returns the catalogue
+ * that preset agent actually sees (its layer + the deployment global). Only
+ * model-invocable entries are advertised, mapped to `AgentSkill` (id = name,
+ * name = name). Any missing service, failed mount, or empty catalogue falls
+ * back to the built-in `chat` skill.
+ *
+ * @param agentPresets - the preset roster, or undefined.
+ * @param skills - the skill registry, or undefined.
+ * @param preset - the instance's preset id; undefined = deployment default.
+ */
+export async function derivePresetSkills(
+  agentPresets: AgentPresetsLike | undefined,
+  skills: SkillsLike | undefined,
+  preset: string | undefined,
+): Promise<readonly AgentSkill[]> {
+  if (agentPresets?.standingKeyFor === undefined || skills === undefined) return chatFallbackSkills()
+  try {
+    const scope = await agentPresets.standingKeyFor(preset)
+    const rows = await skills.list({ scope })
+    const advertised: AgentSkill[] = rows
+      .filter((row) => row.invocation?.modelInvocable !== false)
+      .map((row) => ({
+        id: row.name,
+        name: row.name,
+        ...(row.description !== undefined && row.description.length > 0 ? { description: row.description } : {}),
+      }))
+    return advertised.length > 0 ? advertised : chatFallbackSkills()
+  } catch {
+    return chatFallbackSkills()
+  }
+}
+
+/** Assemble one live instance (skills already derived from the preset). */
+function assemble(record: InboundServerRecord, skills: readonly AgentSkill[], host: InboundManagerHost): LiveInboundServer {
+  const endpointPath = record.endpointPath
+  const cardPath = `${endpointPath.replace(/\/$/, '')}/agent-card.json`
+  const preset = record.preset ?? host.defaultPresetId
+  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 } : {}),
+      ...(preset !== undefined ? { presetId: () => 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,
+    preset,
+    skills,
+    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') 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 instance (skills derived per preset). */
+  async boot(): Promise<void> {
+    for (const record of this.store.list()) {
+      try {
+        const skills = await derivePresetSkills(this.host.agentPresets, this.host.skills, record.preset ?? this.host.defaultPresetId)
+        const live = assemble(record, skills, 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)
+  }
+
+  /** 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 preset = input.preset ?? this.host.defaultPresetId
+    const record: InboundServerRecord = {
+      id,
+      name: input.name,
+      description: input.description,
+      version: input.version,
+      endpointPath: input.endpointPath ?? `/a2a/${id}`,
+      ...(preset !== undefined ? { preset } : {}),
+      ...(input.authTokenEnv !== undefined ? { authTokenEnv: input.authTokenEnv } : {}),
+      enabled: input.enabled ?? true,
+    }
+    try {
+      const skills = await derivePresetSkills(this.host.agentPresets, this.host.skills, preset)
+      const live = assemble(record, skills, 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 (re-deriving skills), and apply a patch onto a live instance. */
+  async update(id: string, patch: Partial<Pick<InboundServerRecord, 'name' | 'description' | 'version' | 'endpointPath' | 'preset' | 'authTokenEnv'>>): 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 } : {}),
+      enabled: stored.enabled,
+    }
+    try {
+      await this.store.save(next)
+      const skills = await derivePresetSkills(this.host.agentPresets, this.host.skills, next.preset ?? this.host.defaultPresetId)
+      const replaced = assemble(next, skills, 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 }