@hanphone/dsh-a2a 0.1.0 → 0.3.0

package/src/server/identity.ts

@@ -0,0 +1,109 @@
+/**
+ * Service identity: the inbound AgentCard's name/description/version,
+ * editable at runtime from the GUI dashboard and persisted in the `a2a`
+ * domain's `identity` table. Skills stay derived from the live tool registry
+ * (the "card derives from ctx.tools" design); identity editing builds a fresh
+ * card preserving the endpoint URL and swaps it onto the server, so routes
+ * and the facade see the new value immediately.
+ * @module dsh-a2a/server/identity
+ */
+
+import { buildCard, type CardOptions } from './card.ts'
+import type { AgentCard, AgentSkill } from '../protocol.ts'
+import type { A2aDomain } from './store.ts'
+
+/** Persisted service identity (only the card identity fields; skills derive). */
+export interface A2aIdentity {
+  readonly name: string
+  readonly description: string
+  readonly version: string
+}
+
+const IDENTITY_KEY = 'service'
+
+function decode(raw: string | undefined): A2aIdentity | undefined {
+  if (raw === undefined) return undefined
+  try {
+    const parsed = JSON.parse(raw) as Partial<A2aIdentity>
+    if (typeof parsed.name !== 'string' || typeof parsed.description !== 'string' || typeof parsed.version !== 'string') {
+      return undefined
+    }
+    return { name: parsed.name, description: parsed.description, version: parsed.version }
+  } catch {
+    return undefined
+  }
+}
+
+function encode(value: A2aIdentity): string {
+  return JSON.stringify(value)
+}
+
+/** Read the persisted identity (undefined when never configured). */
+export function readIdentity(domain: A2aDomain): A2aIdentity | undefined {
+  return decode(domain.identity.get(IDENTITY_KEY))
+}
+
+/** Persist a new identity (fire-and-forget like the task store writes). */
+export function writeIdentity(domain: A2aDomain, identity: A2aIdentity): void {
+  void domain.identity.put(IDENTITY_KEY, encode(identity)).catch((err: unknown) => {
+    throw new Error(`a2a: identity persistence failed: ${String(err)}`)
+  })
+}
+
+/**
+ * Build the AgentCard options for a given base URL/path and the override
+ * identity. `identity` (persisted) wins over the composition `defaults`; when
+ * no identity is stored, the composition defaults stand.
+ */
+export function cardOptionsFor(
+  baseUrl: string,
+  endpointPath: string,
+  defaults: { readonly name: string; readonly description: string; readonly version: string },
+  identity: A2aIdentity | undefined,
+  skills: readonly AgentSkill[],
+  authToken?: string,
+): CardOptions {
+  return {
+    baseUrl,
+    endpointPath,
+    name: identity?.name ?? defaults.name,
+    description: identity?.description ?? defaults.description,
+    version: identity?.version ?? defaults.version,
+    skills,
+    ...(authToken !== undefined ? { authToken } : {}),
+  }
+}
+
+/**
+ * Build a fresh AgentCard from an existing one plus a new identity and skill
+ * list, preserving the endpoint URL (baseUrl/path) and security scheme.
+ */
+export function rebuildCardWithIdentity(card: AgentCard, identity: A2aIdentity, skills: readonly AgentSkill[]): AgentCard {
+  return buildCard({
+    baseUrl: endpointBaseOf(card),
+    endpointPath: endpointPathOf(card),
+    name: identity.name,
+    description: identity.description,
+    version: identity.version,
+    skills,
+    // Preserve the advertised scheme; buildCard only uses the presence (never
+    // the value) to declare securitySchemes.
+    ...(card.securitySchemes !== undefined ? { authToken: 'preserved-scheme' } : {}),
+  })
+}
+
+function endpointBaseOf(card: AgentCard): string {
+  const url = card.supportedInterfaces?.[0]?.url
+  if (!url) return 'http://127.0.0.1'
+  return url.replace(/\/[^/]*$/, '')
+}
+
+function endpointPathOf(card: AgentCard): string {
+  const url = card.supportedInterfaces?.[0]?.url
+  if (!url) return '/a2a'
+  try {
+    return new URL(url).pathname
+  } catch {
+    return '/a2a'
+  }
+}

package/src/server/inbound-registry.ts

@@ -0,0 +1,129 @@
+/**
+ * Inbound connection registry: which remote peers are talking to this DSH's
+ * A2A server. Fed by the A2A server's `onInbound` hook (every JSON-RPC
+ * request / SSE open), surfaced through the dashboard API, and disconnectable
+ * (`closePeer` cancels the peer's active tasks and drops the record).
+ * @module dsh-a2a/server/inbound-registry
+ */
+
+/** One live inbound connection (observed peer). */
+export interface InboundPeerRecord {
+  /** Stable per-process id (random). */
+  readonly id: string
+  /** Short display label derived from the request source. */
+  readonly label: string
+  /** Source socket address, when visible ("127.0.0.1:54321"). */
+  readonly source: string | null
+  /** First-seen ISO timestamp. */
+  readonly firstSeen: string
+  /** Last-activity ISO timestamp. */
+  readonly lastSeen: string
+  /** Number of tasks this peer created or continued. */
+  readonly taskCount: number
+  /** Ids of tasks still running for this peer. */
+  readonly activeTaskIds: readonly string[]
+  /** True while at least one streaming (SSE) connection is open. */
+  readonly streaming: boolean
+}
+
+/** Control and observation contract the dashboard API and facade use. */
+export interface InboundRegistry {
+  list(): readonly InboundPeerRecord[]
+  /** Cancel a peer's active tasks and remove its record. */
+  closePeer(peerId: string): { readonly ok: boolean; readonly message: string }
+  /** Active task ids of one peer (the facade cancels them on close). */
+  activeTasksOf(peerId: string): readonly string[]
+}
+
+/** Mutable tracking state behind one peer record. */
+interface PeerState {
+  readonly id: string
+  readonly label: string
+  readonly source: string | null
+  readonly firstSeen: string
+  lastSeen: string
+  taskCount: number
+  readonly active: Set<string>
+  streamingCount: number
+}
+
+function newPeerId(): string {
+  return `peer-${crypto.randomUUID()}`
+}
+
+/** In-memory inbound peer registry. */
+export class LiveInboundRegistry implements InboundRegistry {
+  private readonly peers = new Map<string, PeerState>()
+
+  private findBySource(source: string | null): PeerState | undefined {
+    if (source === null) return undefined
+    for (const peer of this.peers.values()) {
+      if (peer.source === source) return peer
+    }
+    return undefined
+  }
+
+  /** Observe one inbound event: method, source, task ids, streaming flag. */
+  note(input: { readonly method: string; readonly source?: string; readonly taskIds: readonly string[]; readonly streaming: boolean }): void {
+    const now = new Date().toISOString()
+    const source = input.source ?? null
+    let peer = this.findBySource(source)
+    if (peer === undefined) {
+      peer = {
+        id: newPeerId(),
+        label: source ?? 'unknown',
+        source,
+        firstSeen: now,
+        lastSeen: now,
+        taskCount: 0,
+        active: new Set<string>(),
+        streamingCount: 0,
+      }
+      this.peers.set(peer.id, peer)
+    }
+    peer.lastSeen = now
+    peer.taskCount += input.taskIds.length
+    for (const id of input.taskIds) peer.active.add(id)
+    if (input.streaming) peer.streamingCount += 1
+  }
+
+  /** A task settled: drop it from every peer's active set. */
+  settle(taskId: string): void {
+    for (const peer of this.peers.values()) {
+      if (peer.active.delete(taskId)) peer.lastSeen = new Date().toISOString()
+    }
+  }
+
+  /** Decrement streaming count when an SSE connection closes. */
+  endStream(source?: string): void {
+    const peer = this.findBySource(source ?? null)
+    if (peer !== undefined && peer.streamingCount > 0) {
+      peer.streamingCount -= 1
+      peer.lastSeen = new Date().toISOString()
+    }
+  }
+
+  list(): readonly InboundPeerRecord[] {
+    return [...this.peers.values()].map((p) => ({
+      id: p.id,
+      label: p.label,
+      source: p.source,
+      firstSeen: p.firstSeen,
+      lastSeen: p.lastSeen,
+      taskCount: p.taskCount,
+      activeTaskIds: [...p.active],
+      streaming: p.streamingCount > 0,
+    })).sort((a, b) => (a.lastSeen < b.lastSeen ? 1 : -1))
+  }
+
+  closePeer(peerId: string): { readonly ok: boolean; readonly message: string } {
+    const peer = this.peers.get(peerId)
+    if (peer === undefined) return { ok: false, message: `inbound peer ${peerId} not found` }
+    this.peers.delete(peerId)
+    return { ok: true, message: `inbound peer ${peer.label} closed` }
+  }
+
+  activeTasksOf(peerId: string): readonly string[] {
+    return [...(this.peers.get(peerId)?.active ?? [])]
+  }
+}

package/src/server/routes.ts

@@ -17,7 +17,7 @@ export interface WebServerLike {
   }): () => void
 }
 
-const CARD_PATH = '/.well-known/agent-card.json'
+const DEFAULT_CARD_PATH = '/.well-known/agent-card.json'
 
 /** Runtime-registered HTTP routes for one A2A server. */
 export class A2aRoutes {
@@ -27,6 +27,8 @@ export class A2aRoutes {
   constructor(
     private readonly webServer: WebServerLike,
     private readonly server: A2AServer,
+    /** AgentCard route path; default = the well-known A2A path. */
+    private readonly cardPath: string = DEFAULT_CARD_PATH,
   ) {}
 
   get active(): boolean {
@@ -39,7 +41,7 @@ export class A2aRoutes {
     this.disposers.push(
       this.webServer.register({
         kind: 'exact',
-        path: CARD_PATH,
+        path: this.cardPath,
         handler: (_req, res) => {
           res.writeHead(200, { 'content-type': 'application/json' })
           res.end(JSON.stringify(this.server.card))
@@ -100,8 +102,8 @@ export class A2aRoutes {
       return
     }
 
-    // GET AgentCard at the well-known path; anything else is the server's call.
-    const out = await this.server.handle(toServerReq(req), path === CARD_PATH ? '' : '')
+    // GET AgentCard at this instance's card path; anything else is the server's call.
+    const out = await this.server.handle(toServerReq(req), path === this.cardPath ? '' : '')
     res.writeHead(out.status, { 'content-type': out.contentType, ...(out.headers ?? {}) })
     res.end(out.body)
   }

package/src/server/store.ts

@@ -15,7 +15,7 @@ import {
   type DomainFacility,
   type KvTable,
 } from '@deepseek-ai/dsh-storage-domain'
-import { TaskState, type Part } from '../protocol.ts'
+import { TaskState, type AgentSkill, type Part } from '../protocol.ts'
 
 /** One durable inbound/outbound task record. */
 export interface TaskRecord {
@@ -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,33 @@ 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 = deployment default. */
+  readonly preset?: string
+  readonly authTokenEnv?: string
+  /** Advertised skills (creator-entered declarations, default = preset name). */
+  readonly skills: readonly AgentSkill[]
+  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()
 
@@ -61,6 +90,9 @@ export const a2aDomainSpec = defineDomain({
     tasks: domainTable<string, string>(json),
     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),
   },
 })
 
@@ -107,6 +139,18 @@ export class A2aDomain {
     return this.handle.table('agents')
   }
 
+  get identity(): KvTable<string, string> {
+    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()
   }
@@ -114,7 +158,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
@@ -141,7 +185,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,
@@ -155,6 +199,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
@@ -239,7 +284,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,
@@ -253,6 +298,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.