dsh-agora-plugin 0.6.0

package/patches/dsh-im/README.md

@@ -0,0 +1,82 @@
+# Versioned dsh-im Agora bridge patches
+
+This directory contains reviewed pnpm patches for exact versions of the third-party `@xmanrui/dsh-im` package.
+
+| Package | Patch |
+| --- | --- |
+| `@xmanrui/dsh-im@2.1.0` | `@xmanrui__dsh-im@2.1.0.patch` |
+| `@xmanrui/dsh-im@2.3.0` | `@xmanrui__dsh-im@2.3.0.patch` |
+
+Each patch adds the public, token-free `dsh-im.bridge/v1` Cordis service used by `dsh-agora`:
+
+- safe Bot identity, connectivity, and capability discovery;
+- DSH Session to IM conversation/thread route observation;
+- idempotent proactive delivery through a selected Bot;
+- Discord outbound delivery without accepting Bot-authored inbound messages.
+
+The patches include a rebuilt upstream `lib/index.js`, so a target host does not need dsh-im development dependencies.
+
+## Version rule
+
+Apply a patch only to the exact package version in its filename. A dsh-im upgrade requires regenerating, reviewing, and testing a new patch. pnpm intentionally rejects a version mismatch.
+
+## Installation
+
+Pin dsh-im first, for example:
+
+```bash
+dsh plugin --profile web add @xmanrui/dsh-im@2.3.0
+```
+
+Copy the matching patch to the DSH profile:
+
+```bash
+PROFILE="${DSH_HOME:-$HOME/.dsh}/profiles/web"
+mkdir -p "$PROFILE/patches"
+cp @xmanrui__dsh-im@2.3.0.patch "$PROFILE/patches/"
+```
+
+Merge the matching declaration into `$PROFILE/pnpm-workspace.yaml` without removing existing `allowBuilds` or other patches:
+
+```yaml
+patchedDependencies:
+  '@xmanrui/dsh-im@2.3.0': patches/@xmanrui__dsh-im@2.3.0.patch
+```
+
+Apply it and make the lockfile reproducible:
+
+```bash
+pnpm --dir "$PROFILE" install
+pnpm --dir "$PROFILE" install --frozen-lockfile
+```
+
+Restart DSH, then verify the local snapshot:
+
+```bash
+curl -fsS -X POST http://127.0.0.1:3080/dsh-agora/api/snapshot \
+  -H 'content-type: application/json' \
+  -d '{}'
+```
+
+Expected bridge state:
+
+```text
+imBridge.state: connected
+imBridge.protocol: dsh-im.bridge/v1
+```
+
+`dsh-im.command-gateway/v1` is a separate optional interface and is not added by these patches. Seeing `im.state: unavailable` together with a connected bridge is expected.
+
+## Rebuilding a patch for a new dsh-im version
+
+Use pnpm's patch workflow in an isolated profile or test project:
+
+```bash
+pnpm patch @xmanrui/dsh-im@<version>
+# edit and rebuild the extracted package
+pnpm patch-commit <path-printed-by-pnpm>
+```
+
+Review the resulting source and bundled diff, run the dsh-im build/package checks, apply it to a clean exact-version install, and run a real bridge smoke test before adding the artifact here.
+
+Do not disable pnpm's build-script policy globally. If a reviewed dependency needs an install script, add only the exact package key under `allowBuilds`.

package/src/agora-client.ts

@@ -0,0 +1,333 @@
+import type {
+  AgoraHealth,
+  AgoraTask,
+  AgoraTaskStatus,
+  AgentScorecard,
+  CoordinationRun,
+  CoordinationRunStatus,
+  CreateCoordinationRunInput,
+  CreateAgoraTaskInput,
+  CreateRuntimeDispatchInput,
+  RuntimeDispatch,
+  RecordRuntimeDispatchProgressInput,
+  RuntimeDispatchProgress,
+  RuntimeResultEnvelope,
+  RuntimeDelivery,
+  RuntimeNode,
+  RuntimeNodeHeartbeatInput,
+  RuntimeSessionBinding,
+  RuntimeTarget,
+} from './contracts.js'
+
+export interface AgoraClientOptions {
+  readonly serverUrl: string
+  readonly apiToken?: string | undefined
+  readonly timeoutMs?: number | undefined
+  readonly fetch?: typeof globalThis.fetch | undefined
+}
+
+export class AgoraApiError extends Error {
+  constructor(
+    message: string,
+    readonly status: number,
+    readonly path: string,
+    readonly detail: unknown,
+  ) {
+    super(message)
+    this.name = 'AgoraApiError'
+  }
+}
+
+export class AgoraClient {
+  readonly serverUrl: string
+  private readonly apiToken: string | undefined
+  private readonly timeoutMs: number
+  private readonly fetchImpl: typeof globalThis.fetch
+
+  constructor(options: AgoraClientOptions) {
+    const url = new URL(options.serverUrl)
+    if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+      throw new TypeError('Agora serverUrl must use http or https')
+    }
+    this.serverUrl = url.toString().replace(/\/$/u, '')
+    this.apiToken = nonEmpty(options.apiToken)
+    this.timeoutMs = normalizeTimeout(options.timeoutMs)
+    this.fetchImpl = options.fetch ?? globalThis.fetch
+  }
+
+  health(signal?: AbortSignal): Promise<AgoraHealth> {
+    return this.request('/api/health', { signal })
+  }
+
+  listTasks(state?: string, projectId?: string, signal?: AbortSignal): Promise<AgoraTask[]> {
+    const query = new URLSearchParams()
+    if (nonEmpty(state)) query.set('state', state!.trim())
+    if (nonEmpty(projectId)) query.set('project_id', projectId!.trim())
+    const suffix = query.size === 0 ? '' : `?${query.toString()}`
+    return this.request(`/api/tasks${suffix}`, { signal })
+  }
+
+  getTask(taskId: string, signal?: AbortSignal): Promise<AgoraTask> {
+    return this.request(`/api/tasks/${encodeURIComponent(requireValue(taskId, 'task id'))}`, { signal })
+  }
+
+  taskStatus(taskId: string, signal?: AbortSignal): Promise<AgoraTaskStatus> {
+    return this.request(`/api/tasks/${encodeURIComponent(requireValue(taskId, 'task id'))}/status`, { signal })
+  }
+
+  createTask(input: CreateAgoraTaskInput, signal?: AbortSignal): Promise<AgoraTask> {
+    const title = requireValue(input.title, 'task title')
+    const body = {
+      title,
+      type: nonEmpty(input.type) ?? 'general',
+      creator: nonEmpty(input.creator) ?? 'dsh',
+      description: input.description ?? '',
+      priority: input.priority ?? 'normal',
+      locale: input.locale ?? 'zh-CN',
+      ...(nonEmpty(input.projectId) ? { project_id: input.projectId!.trim() } : {}),
+      ...(input.imTarget === undefined ? {} : { im_target: compactImTarget(input.imTarget) }),
+    }
+    return this.request('/api/tasks', { method: 'POST', body, signal })
+  }
+
+  heartbeatRuntimeNode(nodeId: string, input: RuntimeNodeHeartbeatInput, signal?: AbortSignal): Promise<RuntimeNode> {
+    return this.request(`/api/runtime-nodes/${encodeURIComponent(requireValue(nodeId, 'node id'))}/heartbeat`, {
+      method: 'PUT', body: input, signal,
+    })
+  }
+
+  listRuntimeNodes(signal?: AbortSignal): Promise<RuntimeNode[]> {
+    return this.request<{ nodes: RuntimeNode[] }>('/api/runtime-nodes', { signal }).then(value => value.nodes)
+  }
+
+  listRuntimeTargets(signal?: AbortSignal): Promise<RuntimeTarget[]> {
+    return this.request<{ runtime_targets: RuntimeTarget[] }>('/api/runtime-targets', { signal }).then(value => value.runtime_targets)
+  }
+
+  createRuntimeDispatch(nodeId: string, input: CreateRuntimeDispatchInput, signal?: AbortSignal): Promise<RuntimeDispatch> {
+    return this.request(`/api/runtime-nodes/${encodeURIComponent(requireValue(nodeId, 'node id'))}/dispatches`, {
+      method: 'POST', body: input, signal,
+    })
+  }
+
+  getRuntimeDispatch(dispatchId: string, signal?: AbortSignal): Promise<RuntimeDispatch> {
+    return this.request(`/api/runtime-dispatches/${encodeURIComponent(requireValue(dispatchId, 'dispatch id'))}`, { signal })
+  }
+
+  listRuntimeDispatchProgress(dispatchId: string, signal?: AbortSignal): Promise<RuntimeDispatchProgress[]> {
+    return this.request<{ events: RuntimeDispatchProgress[] }>(
+      `/api/runtime-dispatches/${encodeURIComponent(requireValue(dispatchId, 'dispatch id'))}/progress`,
+      { signal },
+    ).then(value => value.events)
+  }
+
+  createCoordinationRun(input: CreateCoordinationRunInput, signal?: AbortSignal): Promise<CoordinationRun> {
+    return this.request('/api/coordination-runs', { method: 'POST', body: input, signal })
+  }
+
+  getCoordinationRun(runId: string, signal?: AbortSignal): Promise<CoordinationRun> {
+    return this.request(`/api/coordination-runs/${encodeURIComponent(requireValue(runId, 'coordination run id'))}`, { signal })
+  }
+
+  listCoordinationRuns(status?: CoordinationRunStatus, signal?: AbortSignal): Promise<CoordinationRun[]> {
+    const suffix = status ? `?status=${encodeURIComponent(status)}` : ''
+    return this.request<{ runs: CoordinationRun[] }>(`/api/coordination-runs${suffix}`, { signal }).then(value => value.runs)
+  }
+
+  listAgentScorecards(taskType?: string, signal?: AbortSignal): Promise<AgentScorecard[]> {
+    const suffix = nonEmpty(taskType) ? `?task_type=${encodeURIComponent(taskType!.trim())}` : ''
+    return this.request<{ scorecards: AgentScorecard[] }>(`/api/agent-scorecards${suffix}`, { signal }).then(value => value.scorecards)
+  }
+
+  claimRuntimeDispatch(nodeId: string, instanceId: string, leaseSeconds: number, signal?: AbortSignal): Promise<RuntimeDispatch | null> {
+    return this.request<{ dispatch: RuntimeDispatch | null }>(
+      `/api/runtime-nodes/${encodeURIComponent(requireValue(nodeId, 'node id'))}/dispatches/claim`,
+      { method: 'POST', body: { instance_id: instanceId, lease_seconds: leaseSeconds }, signal },
+    ).then(value => value.dispatch)
+  }
+
+  renewRuntimeDispatch(
+    nodeId: string,
+    dispatchId: string,
+    instanceId: string,
+    claimToken: string,
+    leaseSeconds: number,
+    signal?: AbortSignal,
+  ): Promise<RuntimeDispatch> {
+    return this.request(
+      `/api/runtime-nodes/${encodeURIComponent(requireValue(nodeId, 'node id'))}/dispatches/${encodeURIComponent(requireValue(dispatchId, 'dispatch id'))}/renew`,
+      {
+        method: 'POST',
+        body: {
+          instance_id: requireValue(instanceId, 'instance id'),
+          claim_token: requireValue(claimToken, 'claim token'),
+          lease_seconds: leaseSeconds,
+        },
+        signal,
+      },
+    )
+  }
+
+  recordRuntimeDispatchProgress(
+    nodeId: string,
+    dispatchId: string,
+    input: RecordRuntimeDispatchProgressInput,
+    signal?: AbortSignal,
+  ): Promise<RuntimeDispatchProgress> {
+    return this.request(
+      `/api/runtime-nodes/${encodeURIComponent(requireValue(nodeId, 'node id'))}/dispatches/${encodeURIComponent(requireValue(dispatchId, 'dispatch id'))}/progress`,
+      { method: 'POST', body: input, signal },
+    )
+  }
+
+  completeRuntimeDispatch(
+    nodeId: string,
+    dispatchId: string,
+    input: {
+      readonly instance_id: string
+      readonly claim_token: string
+      readonly status: 'completed' | 'failed'
+      readonly session_id?: string | null
+      readonly result?: Readonly<Record<string, unknown>> | null
+      readonly result_envelope?: RuntimeResultEnvelope | null
+      readonly error?: string | null
+      readonly delivery_payload?: Readonly<Record<string, unknown>> | null
+    },
+    signal?: AbortSignal,
+  ): Promise<RuntimeDispatch> {
+    return this.request(
+      `/api/runtime-nodes/${encodeURIComponent(requireValue(nodeId, 'node id'))}/dispatches/${encodeURIComponent(requireValue(dispatchId, 'dispatch id'))}/complete`,
+      { method: 'POST', body: input, signal },
+    )
+  }
+
+  claimRuntimeDelivery(
+    nodeId: string,
+    instanceId: string,
+    leaseSeconds: number,
+    signal?: AbortSignal,
+  ): Promise<RuntimeDelivery | null> {
+    return this.request<{ delivery: RuntimeDelivery | null }>(
+      `/api/runtime-nodes/${encodeURIComponent(requireValue(nodeId, 'node id'))}/deliveries/claim`,
+      { method: 'POST', body: { instance_id: instanceId, lease_seconds: leaseSeconds }, signal },
+    ).then(value => value.delivery)
+  }
+
+  completeRuntimeDelivery(
+    nodeId: string,
+    deliveryId: string,
+    input:
+      | { readonly instance_id: string; readonly claim_token: string; readonly status: 'delivered'; readonly receipt?: Readonly<Record<string, unknown>> | null }
+      | { readonly instance_id: string; readonly claim_token: string; readonly status: 'retry'; readonly error: string; readonly retry_delay_seconds: number }
+      | { readonly instance_id: string; readonly claim_token: string; readonly status: 'failed'; readonly error: string },
+    signal?: AbortSignal,
+  ): Promise<RuntimeDelivery> {
+    return this.request(
+      `/api/runtime-nodes/${encodeURIComponent(requireValue(nodeId, 'node id'))}/deliveries/${encodeURIComponent(requireValue(deliveryId, 'delivery id'))}/complete`,
+      { method: 'POST', body: input, signal },
+    )
+  }
+
+  bindRuntimeSession(
+    taskId: string,
+    participantBindingId: string,
+    sessionId: string,
+    agentRef?: string,
+    signal?: AbortSignal,
+  ): Promise<RuntimeSessionBinding> {
+    return this.request(
+      `/api/tasks/${encodeURIComponent(requireValue(taskId, 'task id'))}/runtime-session-bindings/${encodeURIComponent(requireValue(participantBindingId, 'participant binding id'))}`,
+      {
+        method: 'PUT',
+        body: {
+          runtime_provider: 'dsh',
+          runtime_session_ref: requireValue(sessionId, 'session id'),
+          runtime_actor_ref: nonEmpty(agentRef) ?? null,
+          continuity_ref: `dsh:${requireValue(sessionId, 'session id')}`,
+          presence_state: 'active',
+          binding_reason: 'runtime_node_dispatch',
+        },
+        signal,
+      },
+    )
+  }
+
+  async request<T>(
+    path: string,
+    options: {
+      readonly method?: string | undefined
+      readonly body?: unknown
+      readonly signal?: AbortSignal | undefined
+    } = {},
+  ): Promise<T> {
+    const timeoutSignal = AbortSignal.timeout(this.timeoutMs)
+    const signal = options.signal === undefined
+      ? timeoutSignal
+      : AbortSignal.any([options.signal, timeoutSignal])
+    const headers: Record<string, string> = { Accept: 'application/json' }
+    if (options.body !== undefined) headers['Content-Type'] = 'application/json'
+    if (this.apiToken !== undefined) headers.Authorization = `Bearer ${this.apiToken}`
+
+    const response = await this.fetchImpl(`${this.serverUrl}${path}`, {
+      method: options.method ?? 'GET',
+      headers,
+      ...(options.body === undefined ? {} : { body: JSON.stringify(options.body) }),
+      signal,
+    })
+    const text = await response.text()
+    const payload = parsePayload(text)
+    if (!response.ok) {
+      const detail = errorDetail(payload, text)
+      throw new AgoraApiError(`Agora API ${response.status} at ${path}: ${detail}`, response.status, path, payload)
+    }
+    return payload as T
+  }
+}
+
+function compactImTarget(target: NonNullable<CreateAgoraTaskInput['imTarget']>): Record<string, unknown> {
+  return {
+    ...(nonEmpty(target.provider) ? { provider: target.provider!.trim() } : {}),
+    ...(nonEmpty(target.conversation_ref) ? { conversation_ref: target.conversation_ref!.trim() } : {}),
+    ...(nonEmpty(target.thread_ref) ? { thread_ref: target.thread_ref!.trim() } : {}),
+    ...(target.visibility === undefined ? {} : { visibility: target.visibility }),
+    ...(target.participant_refs === undefined ? {} : { participant_refs: [...target.participant_refs] }),
+  }
+}
+
+function normalizeTimeout(value: number | undefined): number {
+  const timeout = value ?? 10_000
+  if (!Number.isSafeInteger(timeout) || timeout < 100 || timeout > 300_000) {
+    throw new TypeError('requestTimeoutMs must be an integer between 100 and 300000')
+  }
+  return timeout
+}
+
+function requireValue(value: string, label: string): string {
+  const normalized = nonEmpty(value)
+  if (normalized === undefined) throw new TypeError(`${label} is required`)
+  return normalized
+}
+
+function nonEmpty(value: string | undefined): string | undefined {
+  const normalized = value?.trim()
+  return normalized === '' ? undefined : normalized
+}
+
+function parsePayload(text: string): unknown {
+  if (text.trim() === '') return {}
+  try {
+    return JSON.parse(text) as unknown
+  } catch (error) {
+    throw new SyntaxError(`Agora returned invalid JSON: ${error instanceof Error ? error.message : String(error)}`)
+  }
+}
+
+function errorDetail(payload: unknown, fallback: string): string {
+  if (typeof payload === 'object' && payload !== null) {
+    const record = payload as Record<string, unknown>
+    for (const key of ['detail', 'message', 'error']) {
+      if (typeof record[key] === 'string' && record[key].trim() !== '') return record[key]
+    }
+  }
+  return fallback.trim() || 'request failed'
+}

package/src/command-adapter.ts

@@ -0,0 +1,106 @@
+import type { AgoraCommandResult, AgoraRequestContext } from './contracts.js'
+import type { DshImBridgeV1 } from './im-bridge-v1.js'
+
+export const DSH_AGORA_COMMAND_ADAPTER_PROTOCOL = 'dsh-agora.command-adapter/v1' as const
+
+export interface DshAgoraCommandEventV1 {
+  readonly protocol: typeof DSH_AGORA_COMMAND_ADAPTER_PROTOCOL
+  readonly idempotency_key: string
+  readonly input: string
+  readonly actor_ref: string
+  readonly provider?: string | null
+  readonly conversation_ref?: string | null
+  readonly thread_ref?: string | null
+  readonly reply?: {
+    readonly enabled: boolean
+    readonly bot_ref?: string | null
+  } | null
+  readonly metadata?: Readonly<Record<string, unknown>> | null
+}
+
+export interface DshAgoraCommandEventResultV1 {
+  readonly protocol: typeof DSH_AGORA_COMMAND_ADAPTER_PROTOCOL
+  readonly idempotency_key: string
+  readonly result: AgoraCommandResult
+  readonly delivery: {
+    readonly sent: boolean
+    readonly provider_message_refs: readonly string[]
+    readonly reason?: string
+  }
+}
+
+export interface DshAgoraCommandAdapterV1 {
+  readonly protocol: typeof DSH_AGORA_COMMAND_ADAPTER_PROTOCOL
+  ingest(event: DshAgoraCommandEventV1, signal?: AbortSignal): Promise<DshAgoraCommandEventResultV1>
+}
+
+export class DshAgoraCommandAdapter implements DshAgoraCommandAdapterV1 {
+  readonly protocol = DSH_AGORA_COMMAND_ADAPTER_PROTOCOL
+  private readonly receipts = new Map<string, Promise<DshAgoraCommandEventResultV1>>()
+
+  constructor(private readonly options: {
+    execute(input: string, context: AgoraRequestContext, signal?: AbortSignal): Promise<AgoraCommandResult>
+    bridge(): DshImBridgeV1 | null
+    receiptLimit?: number
+  }) {}
+
+  ingest(event: DshAgoraCommandEventV1, signal?: AbortSignal): Promise<DshAgoraCommandEventResultV1> {
+    validateEvent(event)
+    const existing = this.receipts.get(event.idempotency_key)
+    if (existing) return existing
+    const pending = this.execute(event, signal)
+    this.receipts.set(event.idempotency_key, pending)
+    while (this.receipts.size > (this.options.receiptLimit ?? 2_048)) this.receipts.delete(this.receipts.keys().next().value!)
+    pending.catch(() => {
+      if (this.receipts.get(event.idempotency_key) === pending) this.receipts.delete(event.idempotency_key)
+    })
+    return pending
+  }
+
+  private async execute(event: DshAgoraCommandEventV1, signal?: AbortSignal): Promise<DshAgoraCommandEventResultV1> {
+    const result = await this.options.execute(event.input, {
+      actorId: event.actor_ref,
+      ...(event.provider ? { provider: event.provider } : {}),
+      ...(event.conversation_ref ? { conversationRef: event.conversation_ref } : {}),
+      ...(event.thread_ref ? { threadRef: event.thread_ref } : {}),
+    }, signal)
+    const bridge = this.options.bridge()
+    if (!event.reply?.enabled) return envelope(event, result, { sent: false, provider_message_refs: [], reason: 'reply disabled' })
+    if (!bridge || !event.provider || !event.conversation_ref) {
+      return envelope(event, result, { sent: false, provider_message_refs: [], reason: 'IM bridge or destination unavailable' })
+    }
+    try {
+      const receipt = await bridge.send({
+        provider: event.provider,
+        conversation_ref: event.conversation_ref,
+        ...(event.reply.bot_ref === undefined ? {} : { bot_ref: event.reply.bot_ref }),
+        ...(event.thread_ref === undefined ? {} : { thread_ref: event.thread_ref }),
+        text: result.text ?? (result.kind === 'success' ? 'Agora command completed.' : 'Agora command failed.'),
+        idempotency_key: `command:${event.idempotency_key}`,
+      })
+      return envelope(event, result, { sent: true, provider_message_refs: receipt.provider_message_refs })
+    } catch (error) {
+      return envelope(event, result, {
+        sent: false,
+        provider_message_refs: [],
+        reason: `IM delivery failed: ${error instanceof Error ? error.message : String(error)}`,
+      })
+    }
+  }
+}
+
+function envelope(
+  event: DshAgoraCommandEventV1,
+  result: AgoraCommandResult,
+  delivery: DshAgoraCommandEventResultV1['delivery'],
+): DshAgoraCommandEventResultV1 {
+  return { protocol: DSH_AGORA_COMMAND_ADAPTER_PROTOCOL, idempotency_key: event.idempotency_key, result, delivery }
+}
+
+function validateEvent(event: DshAgoraCommandEventV1): void {
+  if (event.protocol !== DSH_AGORA_COMMAND_ADAPTER_PROTOCOL) throw new TypeError(`command event protocol must be ${DSH_AGORA_COMMAND_ADAPTER_PROTOCOL}`)
+  for (const [name, value] of [['idempotency_key', event.idempotency_key], ['input', event.input], ['actor_ref', event.actor_ref]] as const) {
+    if (typeof value !== 'string' || !value.trim()) throw new TypeError(`${name} is required`)
+  }
+  if (event.reply?.enabled && (!event.provider || !event.conversation_ref)) throw new TypeError('reply requires provider and conversation_ref')
+}