@hanphone/dsh-a2a 0.1.0 → 0.2.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/store.ts

@@ -61,6 +61,7 @@ export const a2aDomainSpec = defineDomain({
     tasks: domainTable<string, string>(json),
     contexts: domainTable<string, string>(json),
     agents: domainTable<string, string>(json),
+    identity: domainTable<string, string>(json),
   },
 })
 
@@ -107,6 +108,10 @@ export class A2aDomain {
     return this.handle.table('agents')
   }
 
+  get identity(): KvTable<string, string> {
+    return this.handle.table('identity')
+  }
+
   async close(): Promise<void> {
     await this.handle.close()
   }

package/src/service.ts

@@ -25,6 +25,13 @@ export interface A2AServiceImpl {
   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>
+  inbounds(): unknown
 }
 
 /** The service other plugins read as `ctx.a2a`. */
@@ -75,4 +82,20 @@ export class A2AService extends Service {
   async refreshAgentCard(id: string): Promise<OpResult> {
     return this.impl.refreshAgentCard(id)
   }
+
+  identity(): unknown {
+    return this.impl.identity()
+  }
+
+  async updateIdentity(patch: { readonly name?: string; readonly description?: string; readonly version?: string }): Promise<OpResult> {
+    return this.impl.updateIdentity(patch)
+  }
+
+  async closeInbound(peerId: string): Promise<OpResult> {
+    return this.impl.closeInbound(peerId)
+  }
+
+  inbounds(): unknown {
+    return this.impl.inbounds()
+  }
 }