@hanphone/dsh-a2a 0.1.0

package/src/server/exec/agent-runtime.ts

@@ -0,0 +1,197 @@
+/**
+ * Shared agent machinery for the inbound executors: one DSH agent session per
+ * A2A context (create, or resume a persisted one), serialized turns, and
+ * optional agent-preset composition so a spawned session actually carries
+ * tools. Adapted from the createDshAgentExecutor pattern pioneered by
+ * dsh-a2a (MIT).
+ * @module dsh-a2a/server/exec/agent-runtime
+ */
+
+import type { Context } from '@deepseek-ai/cordis'
+
+/** The slice of a live DSH `Agent` this runtime drives (structural mirror). */
+export interface LiveAgent {
+  readonly session: { deriveMessages(): readonly AgentMessage[] }
+  send(message: AgentUserMessage, target: 'next-turn', wakeup: boolean): void
+  whenIdle(): Promise<void>
+  cancel(cause: string): void
+}
+
+/** One derived history message. */
+export interface AgentMessage {
+  readonly role: 'user' | 'assistant'
+  readonly content: readonly { readonly type: string; readonly text?: string }[]
+}
+
+/** One user message handed to the agent. */
+export interface AgentUserMessage {
+  readonly id: string
+  readonly role: 'user'
+  readonly content: readonly { readonly type: 'text'; readonly text: string }[]
+  readonly source: { readonly kind: 'plugin'; readonly plugin: string }
+}
+
+/** Owned agent plus its capability disposer (structural mirror of AgentHandle). */
+export interface AgentHandle {
+  readonly agent: LiveAgent
+  dispose(): Promise<void>
+}
+
+/** Structural slice of `ctx.agents` this runtime calls. */
+export interface AgentRegistryLike {
+  create(options: {
+    readonly sessionId: string
+    readonly meta?: { readonly cwd?: string; readonly agentPreset?: string }
+    readonly agentOptions?: { readonly provider?: string; readonly model?: string; readonly maxTokens?: number }
+    readonly setup?: (agentCtx: unknown) => void | Promise<void>
+  }): Promise<AgentHandle>
+  resume(options: {
+    readonly resumeSessionId: string
+    readonly agentOptions?: { readonly provider?: string; readonly model?: string; readonly maxTokens?: number }
+    readonly setup?: (agentCtx: unknown) => void | Promise<void>
+  }): Promise<AgentHandle>
+}
+
+/** Structural slice of `ctx.agentPresets` (preset roster). */
+export interface AgentPresetsLike {
+  resolve(id?: string): Promise<{ readonly id: string }>
+  mount(agentCtx: unknown, id: string): Promise<unknown>
+}
+
+/** Runtime options shared by the executors. */
+export interface AgentRuntimeOptions {
+  /** Absolute cwd frozen into each spawned session's durable header. */
+  readonly cwd: string
+  /** Optional per-task model resolution (reads the deployment default). */
+  readonly resolveAgentOptions?: () => { readonly provider?: string; readonly model?: string; readonly maxTokens?: number } | undefined
+  /** Preset roster; when present every spawned session joins the default preset. */
+  readonly agentPresets?: AgentPresetsLike
+  /** Once-per-context hook after the first prompt lands (cosmetic naming). */
+  readonly onSessionOpened?: (info: { readonly sessionId: string; readonly contextId: string; readonly firstPrompt: string }) => void | Promise<void>
+}
+
+/**
+ * Per-context session pool: one live DSH agent per A2A contextId, created or
+ * resumed through the registry, turns serialized per context, every session
+ * disposeable on teardown.
+ */
+export class ContextSessionPool {
+  private readonly handles = new Map<string, AgentHandle>()
+  private readonly tails = new Map<string, Promise<unknown>>()
+
+  constructor(
+    private readonly agents: AgentRegistryLike,
+    private readonly opts: AgentRuntimeOptions,
+  ) {}
+
+  /** Session id derived from the A2A context id (stable across restarts). */
+  static sessionIdFor(contextId: string): string {
+    return `a2a-${contextId}`
+  }
+
+  /** Get or open the live agent for a context; errors propagate. */
+  async agentFor(contextId: string): Promise<{ readonly agent: LiveAgent; readonly sessionId: string; readonly justOpened: boolean }> {
+    const sessionId = ContextSessionPool.sessionIdFor(contextId)
+    const existing = this.handles.get(contextId)
+    if (existing !== undefined) return { agent: existing.agent, sessionId, justOpened: false }
+    const agentOptions = this.opts.resolveAgentOptions?.()
+    const withModel = agentOptions ? { agentOptions } : {}
+    const presets = this.opts.agentPresets
+    let presetId: string | undefined
+    let setup: ((agentCtx: unknown) => Promise<void>) | undefined
+    if (presets !== undefined) {
+      presetId = (await presets.resolve()).id
+      setup = async (agentCtx: unknown): Promise<void> => {
+        await presets.mount(agentCtx, presetId!)
+      }
+    }
+    const meta: { readonly cwd: string; readonly agentPreset?: string } = presetId
+      ? { cwd: this.opts.cwd, agentPreset: presetId }
+      : { cwd: this.opts.cwd }
+    const createOptions = {
+      sessionId,
+      meta,
+      ...withModel,
+      ...(setup ? { setup } : {}),
+    }
+    let handle: AgentHandle
+    try {
+      handle = await this.agents.create(createOptions)
+    } catch (err) {
+      if (/already (has|owns)|persisted/i.test((err as Error).message)) {
+        handle = await this.agents.resume({ resumeSessionId: sessionId, ...withModel, ...(setup ? { setup } : {}) })
+      } else {
+        throw err
+      }
+    }
+    this.handles.set(contextId, handle)
+    return { agent: handle.agent, sessionId, justOpened: true }
+  }
+
+  /** Run one turn on a context's session, serialized behind its tail. */
+  async runTurn(contextId: string, prompt: string, signal: AbortSignal): Promise<string> {
+    const { agent, sessionId, justOpened } = await this.agentFor(contextId)
+    const onAbort = (): void => agent.cancel('a2a-canceled')
+    if (signal.aborted) onAbort()
+    else signal.addEventListener('abort', onAbort, { once: true })
+    const userMessage: AgentUserMessage = {
+      id: crypto.randomUUID(),
+      role: 'user',
+      content: [{ type: 'text', text: prompt }],
+      source: { kind: 'plugin', plugin: 'a2a' },
+    }
+    agent.send(userMessage, 'next-turn', true)
+    if (justOpened) {
+      try {
+        await this.opts.onSessionOpened?.({ sessionId, contextId, firstPrompt: prompt })
+      } catch {
+        // Cosmetic naming must never fail the task.
+      }
+    }
+    await agent.whenIdle()
+    return lastAssistantText(agent)
+  }
+
+  /** Dispose every live per-context session (called on plugin unload). */
+  async disposeAll(): Promise<void> {
+    const live = [...this.handles.values()]
+    const pending = [...this.tails.values()]
+    this.handles.clear()
+    this.tails.clear()
+    await Promise.allSettled(pending)
+    await Promise.allSettled(live.map((h) => h.dispose()))
+  }
+}
+
+/** Read the last assistant message's text off the derived history. */
+function lastAssistantText(agent: LiveAgent): string {
+  const history = agent.session.deriveMessages()
+  for (let i = history.length - 1; i >= 0; i--) {
+    const message = history[i]
+    if (message === undefined) continue
+    if (message.role === 'assistant') {
+      return message.content
+        .map((b) => ('text' in b && typeof b.text === 'string' ? (b.text ?? '') : ''))
+        .filter(Boolean)
+        .join('\n')
+        .trim()
+    }
+  }
+  return ''
+}
+
+/**
+ * Probe for a readable service method via the reflection layer WITHOUT taking
+ * an inject dependency (optional services). Returns undefined when the service
+ * is absent or the method missing.
+ */
+export function probeService(ctx: Context, name: string, method: string): unknown {
+  try {
+    const reflect = (ctx as unknown as { reflect?: { get(n: string, strict?: boolean): unknown } }).reflect
+    const svc = reflect?.get(name, true)
+    if (svc !== undefined && svc !== null && typeof (svc as Record<string, unknown>)[method] === 'function') return svc
+  } catch {
+    // reflection unavailable or resolution threw — treat as absent
+  }
+  return undefined
+}

package/src/server/exec/session.ts

@@ -0,0 +1,25 @@
+/**
+ * The `session` executor: one inbound task is one turn on the context's DSH
+ * agent session; reply text becomes the task's output part. Works on any
+ * composition with an agent loop (the `chat` skill and the default path).
+ * @module dsh-a2a/server/exec/session
+ */
+
+import type { A2aExecutor, A2aExecutorInput, A2aExecutorOutput } from '../executor.ts'
+import { ContextSessionPool } from './agent-runtime.ts'
+
+/** Build the session executor over a context session pool. */
+export function createSessionExecutor(pool: ContextSessionPool): A2aExecutor {
+  return {
+    name: 'session',
+    async execute(input: A2aExecutorInput): Promise<A2aExecutorOutput> {
+      if (!input.prompt) {
+        return { parts: [{ text: 'No prompt provided.' }] }
+      }
+      const reply = await pool.runTurn(input.contextId, input.prompt, input.signal)
+      const text = (input.signal.aborted && !reply ? '(canceled)' : reply) || '(no reply)'
+      return { parts: [{ text }] }
+    },
+    disposeAll: () => pool.disposeAll(),
+  }
+}

package/src/server/exec/subagent.ts

@@ -0,0 +1,67 @@
+/**
+ * The `subagent` executor: one inbound task is delegated to a named one-shot
+ * subagent under the context's parent session. The child runs with the
+ * composition's own tools and the delegation boundary; its output becomes the
+ * task's artifact. The subagent seam must be mounted, else the skill binding
+ * fails loudly at resolution time.
+ * @module dsh-a2a/server/exec/subagent
+ */
+
+import type { A2aExecutor, A2aExecutorInput, A2aExecutorOutput } from '../executor.ts'
+import { ContextSessionPool } from './agent-runtime.ts'
+
+/** Structural slice of `ctx.subagents` this executor calls. */
+export interface SubagentsLike {
+  start(
+    name: string,
+    request: {
+      readonly label?: string
+      readonly prompt: readonly { readonly type: 'text'; readonly text: string }[]
+      readonly parent: unknown
+      readonly signal: AbortSignal
+    },
+  ): Promise<{ readonly result: Promise<{ readonly output: readonly { readonly type: string; readonly text?: string }[] }>; dispose(): Promise<void> }>
+}
+
+export interface SubagentExecutorOptions {
+  readonly pool: ContextSessionPool
+  readonly subagents: SubagentsLike
+  /** Provider name (e.g. 'in-process'); configurable per deployment. */
+  readonly provider: string
+}
+
+/** Build a subagent executor delegating inbound tasks to one-shot children. */
+export function createSubagentExecutor(opts: SubagentExecutorOptions): A2aExecutor {
+  const { pool, subagents, provider } = opts
+  return {
+    name: 'subagent',
+    async execute(input: A2aExecutorInput, execCtx): Promise<A2aExecutorOutput> {
+      if (!input.prompt) {
+        return { parts: [{ text: 'No prompt provided.' }] }
+      }
+      const { agent } = await pool.agentFor(input.contextId)
+      const run = await subagents.start(provider, {
+        label: `a2a:${input.skill}`,
+        prompt: [{ type: 'text', text: input.prompt }],
+        parent: agent,
+        signal: input.signal,
+      })
+      const result = await run.result
+      const text = result.output
+        .filter((b): b is { readonly type: string; readonly text: string } => typeof b.text === 'string')
+        .map((b) => b.text)
+        .filter(Boolean)
+        .join('\n')
+        .trim()
+      execCtx.onEvent({
+        type: 'artifact',
+        artifactId: 'result',
+        parts: [{ text: text || '(subagent returned no output)' }],
+        name: input.skill,
+        lastChunk: true,
+      })
+      return { parts: [{ text: text || '(subagent returned no output)' }] }
+    },
+    disposeAll: () => pool.disposeAll(),
+  }
+}

package/src/server/executor.ts

@@ -0,0 +1,73 @@
+/**
+ * Executor abstraction for inbound tasks: an executor turns one task into
+ * output parts while reporting status and artifact updates. The registry is
+ * INTERNAL (built by the plugin from config) — public registration was cut:
+ * there is no external caller yet, so the seam stays an interface with two
+ * built-in implementations (session, subagent).
+ * @module dsh-a2a/server/executor
+ */
+
+import type { Part, TaskState } from '../protocol.ts'
+
+/** One update from a running executor. */
+export type A2aExecutorEvent =
+  | { readonly type: 'status'; readonly state: TaskState; readonly message?: string }
+  | { readonly type: 'artifact'; readonly artifactId: string; readonly parts: readonly Part[]; readonly name?: string; readonly lastChunk?: boolean }
+
+/** Input a task executor receives. */
+export interface A2aExecutorInput {
+  readonly taskId: string
+  readonly contextId: string
+  readonly skill: string
+  readonly prompt: string
+  readonly signal: AbortSignal
+}
+
+/** Output contract of one executor run. */
+export interface A2aExecutorOutput {
+  readonly parts: readonly Part[]
+}
+
+/** One inbound task executor. */
+export interface A2aExecutor {
+  /** Stable kind name ('session' | 'subagent'). */
+  readonly name: string
+  /**
+   * Run one task. The executor reports progress through `opts.onEvent` and
+   * must honor `opts.signal` (cancel = abort remaining work).
+   */
+  execute(input: A2aExecutorInput, opts: { readonly onEvent: (ev: A2aExecutorEvent) => void }): Promise<A2aExecutorOutput>
+  /** Dispose resources owned by the executor (sessions, children). */
+  disposeAll?(): Promise<void>
+}
+
+/** Executor kind names configurable per skill. */
+export type ExecutorKind = 'session' | 'subagent'
+
+/**
+ * Skill → executor resolution. The subagent executor is absent on
+ * compositions without the subagent seam; resolving a skill bound to a
+ * missing kind fails loudly with a readable message.
+ */
+export class ExecutorSet {
+  constructor(
+    private readonly bySkill: Readonly<Record<string, ExecutorKind>>,
+    private readonly session: A2aExecutor,
+    private readonly subagent: A2aExecutor | undefined,
+  ) {}
+
+  resolve(skill: string): A2aExecutor {
+    const kind = this.bySkill[skill] ?? 'session'
+    if (kind === 'session') return this.session
+    const subagent = this.subagent
+    if (subagent === undefined) {
+      throw new Error(`a2a: skill "${skill}" is bound to the subagent executor but no subagent seam is mounted`)
+    }
+    return subagent
+  }
+
+  async disposeAll(): Promise<void> {
+    await this.session.disposeAll?.()
+    await this.subagent?.disposeAll?.()
+  }
+}

package/src/server/routes.ts

@@ -0,0 +1,156 @@
+/**
+ * HTTP binding for the inbound server: registers the AgentCard route and the
+ * JSON-RPC / SSE endpoint on a structural webServer (normally
+ * `@deepseek-ai/dsh-host-webserver`), with runtime enable/disable.
+ * @module dsh-a2a/server/routes
+ */
+
+import type { IncomingMessage, ServerResponse } from 'node:http'
+import type { A2AServer } from './a2a-server.ts'
+
+/** Structural slice of `ctx.webServer` this module registers on. */
+export interface WebServerLike {
+  register(route: {
+    readonly kind: 'exact' | 'prefix'
+    readonly path: string
+    handler(req: IncomingMessage, res: ServerResponse): void | Promise<void>
+  }): () => void
+}
+
+const CARD_PATH = '/.well-known/agent-card.json'
+
+/** Runtime-registered HTTP routes for one A2A server. */
+export class A2aRoutes {
+  private disposers: Array<() => void> = []
+  private registered = false
+
+  constructor(
+    private readonly webServer: WebServerLike,
+    private readonly server: A2AServer,
+  ) {}
+
+  get active(): boolean {
+    return this.registered
+  }
+
+  /** Register the AgentCard + endpoint routes (idempotent). */
+  enable(): void {
+    if (this.registered) return
+    this.disposers.push(
+      this.webServer.register({
+        kind: 'exact',
+        path: CARD_PATH,
+        handler: (_req, res) => {
+          res.writeHead(200, { 'content-type': 'application/json' })
+          res.end(JSON.stringify(this.server.card))
+        },
+      }),
+    )
+    this.disposers.push(
+      this.webServer.register({
+        kind: 'prefix',
+        path: endpointPathOf(this.server),
+        handler: (req, res) => this.onRequest(req, res),
+      }),
+    )
+    this.registered = true
+  }
+
+  /** Unregister the routes (idempotent). */
+  disable(): void {
+    for (const disposer of this.disposers.splice(0)) disposer()
+    this.registered = false
+  }
+
+  dispose(): void {
+    this.disable()
+  }
+
+  private async onRequest(req: IncomingMessage, res: ServerResponse): Promise<void> {
+    const path = (req.url ?? '').split('?')[0] ?? ''
+    const streaming = (req.method === 'POST' && (req.headers.accept ?? '').includes('text/event-stream'))
+
+    if (req.method === 'POST' && path === endpointPathOf(this.server)) {
+      const body = await readBody(req)
+      if (streaming) {
+        // Authorize BEFORE writing 200 so a 401 can still carry a plain status.
+        if (!this.server.authorized(toServerReq(req))) {
+          res.writeHead(401, { 'content-type': 'text/plain', 'WWW-Authenticate': 'Bearer' })
+          res.end('Unauthorized')
+          return
+        }
+        res.writeHead(200, {
+          'content-type': 'text/event-stream',
+          'cache-control': 'no-cache',
+          connection: 'keep-alive',
+          'x-accel-buffering': 'no',
+        })
+        const outcome = await this.server.handleStream(toServerReq(req), body, (frame) => res.write(frame))
+        if (outcome.status !== 200) {
+          res.writeHead(outcome.status, { 'content-type': 'text/plain', ...(outcome.headers ?? {}) })
+          res.end('Unauthorized')
+          return
+        }
+        res.end()
+        return
+      }
+      const out = await this.server.handle(toServerReq(req), body)
+      res.writeHead(out.status, { 'content-type': out.contentType, ...(out.headers ?? {}) })
+      res.end(out.body)
+      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 ? '' : '')
+    res.writeHead(out.status, { 'content-type': out.contentType, ...(out.headers ?? {}) })
+    res.end(out.body)
+  }
+}
+
+function endpointPathOf(server: A2AServer): string {
+  const url = server.card.supportedInterfaces?.[0]?.url
+  if (!url) return '/a2a'
+  try {
+    return new URL(url).pathname
+  } catch {
+    return '/a2a'
+  }
+}
+
+function readBody(req: IncomingMessage): Promise<string> {
+  return new Promise<string>((resolve, reject) => {
+    const chunks: Buffer[] = []
+    req.on('data', (chunk: Buffer) => chunks.push(chunk))
+    req.on('end', () => resolve(Buffer.concat(chunks).toString('utf8')))
+    req.once('error', reject)
+  })
+}
+
+function toServerReq(req: IncomingMessage): {
+  readonly method?: string
+  readonly url?: string
+  readonly headers?: Record<string, string>
+  readonly socket?: { readonly remoteAddress?: string; readonly remotePort?: number }
+} {
+  const headers: Record<string, string> = {}
+  for (const [key, value] of Object.entries(req.headers)) {
+    if (typeof value === 'string') headers[key] = value
+    else if (Array.isArray(value)) headers[key] = value.join(', ')
+  }
+  const method = req.method
+  const url = req.url
+  const socket = req.socket
+  return {
+    ...(method !== undefined ? { method } : {}),
+    ...(url !== undefined ? { url } : {}),
+    headers,
+    ...(socket
+      ? {
+        socket: {
+          ...(socket.remoteAddress !== undefined ? { remoteAddress: socket.remoteAddress } : {}),
+          ...(socket.remotePort !== undefined ? { remotePort: socket.remotePort } : {}),
+        },
+      }
+      : {}),
+  }
+}