dsh-agora-plugin 0.6.0

package/src/http-api.ts

@@ -0,0 +1,269 @@
+import { timingSafeEqual } from 'node:crypto'
+import type { IncomingMessage, ServerResponse } from 'node:http'
+import type { AgoraRequestContext, DshAgoraServiceApi } from './contracts.js'
+import type { DshWebServer } from './context-types.js'
+
+export const API_PREFIX = '/dsh-agora/api'
+const MAX_BODY_BYTES = 1_048_576
+
+export interface HttpApiOptions {
+  readonly accessToken?: string | undefined
+}
+
+export function registerHttpApi(webServer: DshWebServer, service: DshAgoraServiceApi, options: HttpApiOptions): () => void {
+  return webServer.register({
+    kind: 'prefix',
+    path: API_PREFIX,
+    handler: (request, response) => handleHttpRequest(request, response, service, options),
+  })
+}
+
+export async function handleHttpRequest(
+  request: IncomingMessage,
+  response: ServerResponse,
+  service: DshAgoraServiceApi,
+  options: HttpApiOptions,
+): Promise<void> {
+  try {
+    if (!authorized(request, options.accessToken)) {
+      writeJson(response, 403, { ok: false, error: { code: 'forbidden', message: 'forbidden' } })
+      return
+    }
+    if (request.method !== 'POST') {
+      writeJson(response, 405, { ok: false, error: { code: 'method-not-allowed', message: 'POST required' } })
+      return
+    }
+    const pathname = new URL(request.url ?? '/', 'http://dsh.internal').pathname
+    const method = pathname.startsWith(`${API_PREFIX}/`) ? pathname.slice(API_PREFIX.length + 1) : ''
+    if (method === '' || method.includes('/')) throw new HttpApiError(404, 'not-found', 'unknown dsh-agora API method')
+    const payload = asRecord(await readJsonBody(request))
+    const signal = AbortSignal.timeout(300_000)
+    let value: unknown
+    switch (method) {
+      case 'snapshot': value = service.snapshot(); break
+      case 'health': value = await service.health(signal); break
+      case 'nodes': value = await service.listRuntimeNodes(signal); break
+      case 'agents': value = await service.listRuntimeTargets(signal); break
+      case 'tasks': value = await service.listTasks(optionalString(payload.state), optionalString(payload.projectId), signal); break
+      case 'task': value = await service.getTask(requiredString(payload.taskId, 'taskId'), signal); break
+      case 'status': value = await service.taskStatus(requiredString(payload.taskId, 'taskId'), signal); break
+      case 'dispatch-status': value = await service.getRuntimeDispatch(requiredString(payload.dispatchId, 'dispatchId'), signal); break
+      case 'dispatch-progress': value = await service.listRuntimeDispatchProgress(requiredString(payload.dispatchId, 'dispatchId'), signal); break
+      case 'coordination-runs': value = await service.listCoordinationRuns(
+        optionalCoordinationStatus(payload.status),
+        signal,
+      ); break
+      case 'coordination-run': value = await service.getCoordinationRun(requiredString(payload.runId, 'runId'), signal); break
+      case 'scorecards': value = await service.listAgentScorecards(optionalString(payload.taskType), signal); break
+      case 'coordination-create': {
+        const mode = requiredCoordinationMode(payload.mode)
+        const taskId = optionalString(payload.taskId)
+        const taskType = optionalString(payload.taskType)
+        const verifierTargetRef = optionalString(payload.verifierTargetRef)
+        value = await service.createCoordinationRun({
+          prompt: requiredString(payload.prompt, 'prompt'),
+          mode,
+          candidates: requiredStringArray(payload.runtimeTargetRefs, 'runtimeTargetRefs').map(runtime_target_ref => ({ runtime_target_ref })),
+          idempotency_key: requiredString(payload.idempotencyKey, 'idempotencyKey'),
+          ...(taskId === undefined ? {} : { task_id: taskId }),
+          ...(taskType === undefined ? {} : { task_type: taskType }),
+          ...(verifierTargetRef === undefined ? {} : { verifier_target_ref: verifierTargetRef }),
+          ...(payload.budget === undefined ? {} : { budget: coordinationBudget(payload.budget) }),
+        }, signal)
+        break
+      }
+      case 'dispatch': {
+        const taskId = optionalString(payload.taskId)
+        const participantBindingId = optionalString(payload.participantBindingId)
+        const sessionId = optionalString(payload.sessionId)
+        const workspaceAlias = optionalString(payload.workspaceAlias)
+        const agentPreset = optionalString(payload.agentPreset)
+        const sourceSessionId = optionalString(payload.sourceSessionId)
+        const presentationMode = optionalString(payload.presentationMode)
+        const waitTimeoutMs = optionalInteger(payload.waitTimeoutMs, 'waitTimeoutMs', 0, 600_000)
+        if (presentationMode !== undefined && !['source_bot', 'destination_bot', 'silent'].includes(presentationMode)) {
+          throw new HttpApiError(400, 'bad-request', 'presentationMode is invalid')
+        }
+        value = await service.dispatchAgent({
+          runtime_target_ref: requiredString(payload.runtimeTargetRef, 'runtimeTargetRef'),
+          prompt: requiredString(payload.prompt, 'prompt'),
+          idempotency_key: requiredString(payload.idempotencyKey, 'idempotencyKey'),
+          ...(taskId === undefined ? {} : { task_id: taskId }),
+          ...(participantBindingId === undefined ? {} : { participant_binding_id: participantBindingId }),
+          ...(sessionId === undefined ? {} : { session_id: sessionId }),
+          ...(workspaceAlias === undefined ? {} : { workspace_alias: workspaceAlias }),
+          ...(agentPreset === undefined ? {} : { agent_preset: agentPreset }),
+          ...(sourceSessionId === undefined ? {} : { source_session_id: sourceSessionId }),
+          ...(waitTimeoutMs === undefined ? {} : { wait_timeout_ms: waitTimeoutMs }),
+          ...(presentationMode === undefined ? {} : {
+            presentation_mode: presentationMode as 'source_bot' | 'destination_bot' | 'silent',
+          }),
+        }, signal)
+        break
+      }
+      case 'attach-session': value = await service.bindRuntimeSession(
+        requiredString(payload.taskId, 'taskId'),
+        requiredString(payload.participantBindingId, 'participantBindingId'),
+        requiredString(payload.sessionId, 'sessionId'),
+        optionalString(payload.runtimeTargetRef),
+        signal,
+      ); break
+      case 'create': {
+        const type = optionalString(payload.type)
+        const creator = optionalString(payload.creator)
+        const description = optionalString(payload.description)
+        const projectId = optionalString(payload.projectId)
+        value = await service.createTask({
+          title: requiredString(payload.title, 'title'),
+          ...(type === undefined ? {} : { type }),
+          ...(creator === undefined ? {} : { creator }),
+          ...(description === undefined ? {} : { description }),
+          ...(projectId === undefined ? {} : { projectId }),
+        }, signal)
+        break
+      }
+      case 'command': value = await service.executeCommand(
+        optionalString(payload.input) ?? '',
+        requestContext(payload.context),
+        signal,
+      ); break
+      case 'command-event': value = await service.executeCommandEvent(payload as unknown as import('./command-adapter.js').DshAgoraCommandEventV1, signal); break
+      default: throw new HttpApiError(404, 'not-found', `unknown dsh-agora API method "${method}"`)
+    }
+    writeJson(response, 200, { ok: true, value })
+  } catch (error) {
+    if (error instanceof HttpApiError) {
+      writeJson(response, error.status, { ok: false, error: { code: error.code, message: error.message } })
+      return
+    }
+    writeJson(response, 502, { ok: false, error: { code: 'upstream-error', message: error instanceof Error ? error.message : String(error) } })
+  }
+}
+
+class HttpApiError extends Error {
+  constructor(readonly status: number, readonly code: string, message: string) {
+    super(message)
+  }
+}
+
+function authorized(request: IncomingMessage, configuredToken: string | undefined): boolean {
+  if (isLoopback(request.socket.remoteAddress)) return true
+  const token = configuredToken?.trim()
+  if (!token) return false
+  const authorization = request.headers.authorization
+  if (!authorization?.startsWith('Bearer ')) return false
+  const supplied = authorization.slice(7)
+  const expectedBytes = Buffer.from(token)
+  const suppliedBytes = Buffer.from(supplied)
+  return expectedBytes.length === suppliedBytes.length && timingSafeEqual(expectedBytes, suppliedBytes)
+}
+
+function isLoopback(address: string | undefined): boolean {
+  return address === '127.0.0.1' || address === '::1' || address === '::ffff:127.0.0.1'
+}
+
+async function readJsonBody(request: IncomingMessage): Promise<unknown> {
+  const chunks: Buffer[] = []
+  let length = 0
+  for await (const chunk of request) {
+    const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk)
+    length += bytes.length
+    if (length > MAX_BODY_BYTES) throw new HttpApiError(413, 'body-too-large', 'request body exceeds 1 MiB')
+    chunks.push(bytes)
+  }
+  const text = Buffer.concat(chunks).toString('utf8').trim()
+  if (text === '') return {}
+  try {
+    return JSON.parse(text) as unknown
+  } catch {
+    throw new HttpApiError(400, 'bad-json', 'request body must be valid JSON')
+  }
+}
+
+function asRecord(value: unknown): Record<string, unknown> {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) throw new HttpApiError(400, 'bad-request', 'request body must be an object')
+  return value as Record<string, unknown>
+}
+
+function optionalString(value: unknown): string | undefined {
+  if (value === undefined || value === null) return undefined
+  if (typeof value !== 'string') throw new HttpApiError(400, 'bad-request', 'expected a string field')
+  const normalized = value.trim()
+  return normalized === '' ? undefined : normalized
+}
+
+function requiredString(value: unknown, field: string): string {
+  const normalized = optionalString(value)
+  if (normalized === undefined) throw new HttpApiError(400, 'bad-request', `${field} is required`)
+  return normalized
+}
+
+function optionalInteger(value: unknown, field: string, minimum: number, maximum: number): number | undefined {
+  if (value === undefined || value === null) return undefined
+  if (!Number.isSafeInteger(value) || (value as number) < minimum || (value as number) > maximum) {
+    throw new HttpApiError(400, 'bad-request', `${field} must be an integer between ${minimum} and ${maximum}`)
+  }
+  return value as number
+}
+
+function requiredStringArray(value: unknown, field: string): string[] {
+  if (!Array.isArray(value) || value.length === 0) throw new HttpApiError(400, 'bad-request', `${field} must be a non-empty string array`)
+  return value.map(item => requiredString(item, field))
+}
+
+function requiredCoordinationMode(value: unknown): 'single' | 'fanout' | 'review' | 'debate' | 'council' {
+  const mode = requiredString(value, 'mode')
+  if (mode === 'single' || mode === 'fanout' || mode === 'review' || mode === 'debate' || mode === 'council') return mode
+  throw new HttpApiError(400, 'bad-request', 'mode must be single, fanout, review, debate, or council')
+}
+
+function optionalCoordinationStatus(value: unknown): import('./contracts.js').CoordinationRunStatus | undefined {
+  const status = optionalString(value)
+  if (status === undefined) return undefined
+  if (status === 'running' || status === 'verifying' || status === 'completed' || status === 'partial'
+    || status === 'failed' || status === 'cancelled' || status === 'budget_exhausted') return status
+  throw new HttpApiError(400, 'bad-request', 'coordination status is invalid')
+}
+
+function coordinationBudget(value: unknown): Partial<import('./contracts.js').CoordinationBudget> {
+  const record = asRecord(value)
+  const fields = [
+    ['max_agents', 1, 32],
+    ['max_dispatches', 1, 64],
+    ['max_wall_clock_seconds', 15, 86_400],
+    ['max_tokens', 1, Number.MAX_SAFE_INTEGER],
+    ['max_tool_calls', 1, Number.MAX_SAFE_INTEGER],
+  ] as const
+  const budget: Record<string, number> = {}
+  for (const [field, minimum, maximum] of fields) {
+    const item = optionalInteger(record[field], field, minimum, maximum)
+    if (item !== undefined) budget[field] = item
+  }
+  if (record.max_cost_usd !== undefined) {
+    if (typeof record.max_cost_usd !== 'number' || record.max_cost_usd <= 0) throw new HttpApiError(400, 'bad-request', 'max_cost_usd must be positive')
+    budget.max_cost_usd = record.max_cost_usd
+  }
+  return budget
+}
+
+function requestContext(value: unknown): AgoraRequestContext {
+  if (value === undefined) return {}
+  const record = asRecord(value)
+  const actorId = optionalString(record.actorId)
+  const provider = optionalString(record.provider)
+  const conversationRef = optionalString(record.conversationRef)
+  const threadRef = optionalString(record.threadRef)
+  return {
+    ...(actorId === undefined ? {} : { actorId }),
+    ...(provider === undefined ? {} : { provider }),
+    ...(conversationRef === undefined ? {} : { conversationRef }),
+    ...(threadRef === undefined ? {} : { threadRef }),
+  }
+}
+
+function writeJson(response: ServerResponse, status: number, body: unknown): void {
+  response.statusCode = status
+  response.setHeader('Content-Type', 'application/json; charset=utf-8')
+  response.setHeader('Cache-Control', 'no-store')
+  response.end(JSON.stringify(body))
+}

package/src/im-bridge-v1.ts

@@ -0,0 +1,73 @@
+import type { DshAgoraImStatus, RuntimeNodeBot } from './contracts.js'
+
+export const DSH_IM_BRIDGE_PROTOCOL = 'dsh-im.bridge/v1' as const
+
+export interface DshImSessionRouteV1 {
+  readonly provider: string
+  readonly bot_ref: string
+  readonly session_id: string
+  readonly actor_ref: string
+  readonly conversation_ref: string
+  readonly thread_ref: string | null
+  readonly reply_to_message_ref: string | null
+  readonly updated_at: string
+}
+
+export interface DshImSendRequestV1 {
+  readonly provider: string
+  readonly bot_ref?: string | null
+  readonly conversation_ref: string
+  readonly thread_ref?: string | null
+  readonly reply_to_message_ref?: string | null
+  readonly text: string
+  readonly idempotency_key: string
+}
+
+export interface DshImBridgeV1 {
+  readonly protocol: typeof DSH_IM_BRIDGE_PROTOCOL
+  listBots(): readonly RuntimeNodeBot[] | Promise<readonly RuntimeNodeBot[]>
+  resolveSession(sessionId: string): DshImSessionRouteV1 | null | Promise<DshImSessionRouteV1 | null>
+  send(request: DshImSendRequestV1): Promise<{ readonly provider_message_refs: readonly string[] }>
+}
+
+export interface ImBridgeDiscovery {
+  readonly status: DshAgoraImStatus
+  readonly bridge: DshImBridgeV1 | null
+}
+
+export function discoverImBridge(ctx: { get?(name: string): unknown }, serviceNames: readonly string[]): ImBridgeDiscovery {
+  for (const serviceName of serviceNames) {
+    const candidate = safeGet(ctx, serviceName)
+    if (candidate === undefined) continue
+    if (!isBridge(candidate)) {
+      return {
+        status: {
+          state: 'incompatible', service: serviceName,
+          reason: `service does not implement ${DSH_IM_BRIDGE_PROTOCOL}`,
+        },
+        bridge: null,
+      }
+    }
+    return {
+      status: { state: 'connected', service: serviceName, protocol: candidate.protocol },
+      bridge: candidate,
+    }
+  }
+  return {
+    status: { state: 'unavailable', reason: `no ${DSH_IM_BRIDGE_PROTOCOL} provider is installed` },
+    bridge: null,
+  }
+}
+
+function safeGet(ctx: { get?(name: string): unknown }, name: string): unknown {
+  try { return ctx.get?.(name) } catch { return undefined }
+}
+
+function isBridge(value: unknown): value is DshImBridgeV1 {
+  if (typeof value !== 'object' || value === null) return false
+  const bridge = value as Partial<DshImBridgeV1>
+  return bridge.protocol === DSH_IM_BRIDGE_PROTOCOL
+    && typeof bridge.listBots === 'function'
+    && typeof bridge.resolveSession === 'function'
+    && typeof bridge.send === 'function'
+}

package/src/im-gateway.ts

@@ -0,0 +1,82 @@
+import type { AgoraCommandResult, AgoraRequestContext, DshAgoraImStatus } from './contracts.js'
+
+export const DSH_IM_COMMAND_GATEWAY_PROTOCOL = 'dsh-im.command-gateway/v1'
+
+export interface DshImCommandInvocationV1 extends AgoraRequestContext {
+  readonly rawInput: string
+  readonly signal?: AbortSignal
+}
+
+export interface DshImCommandDefinitionV1 {
+  readonly name: string
+  readonly description: string
+  execute(invocation: DshImCommandInvocationV1): Promise<AgoraCommandResult>
+}
+
+export interface DshImCommandGatewayV1 {
+  readonly protocol: typeof DSH_IM_COMMAND_GATEWAY_PROTOCOL
+  registerCommand(definition: DshImCommandDefinitionV1): () => void
+}
+
+export interface ImGatewayContext {
+  get?(name: string): unknown
+}
+
+export interface ImRegistration {
+  readonly status: DshAgoraImStatus
+  readonly dispose?: () => void
+}
+
+export function registerImCommand(
+  ctx: ImGatewayContext,
+  serviceNames: readonly string[],
+  definition: DshImCommandDefinitionV1,
+): ImRegistration {
+  for (const serviceName of serviceNames) {
+    const candidate = safeGet(ctx, serviceName)
+    if (candidate === undefined) continue
+    if (!isGateway(candidate)) {
+      return {
+        status: {
+          state: 'incompatible',
+          service: serviceName,
+          reason: `service does not implement ${DSH_IM_COMMAND_GATEWAY_PROTOCOL}`,
+        },
+      }
+    }
+    try {
+      return {
+        status: { state: 'connected', service: serviceName, protocol: candidate.protocol },
+        dispose: candidate.registerCommand(definition),
+      }
+    } catch (error) {
+      return {
+        status: {
+          state: 'incompatible',
+          service: serviceName,
+          reason: `gateway rejected command registration: ${error instanceof Error ? error.message : String(error)}`,
+        },
+      }
+    }
+  }
+  return {
+    status: {
+      state: 'unavailable',
+      reason: `no ${DSH_IM_COMMAND_GATEWAY_PROTOCOL} provider is installed`,
+    },
+  }
+}
+
+function safeGet(ctx: ImGatewayContext, serviceName: string): unknown {
+  try {
+    return ctx.get?.(serviceName)
+  } catch {
+    return undefined
+  }
+}
+
+function isGateway(value: unknown): value is DshImCommandGatewayV1 {
+  if (typeof value !== 'object' || value === null) return false
+  const candidate = value as Partial<DshImCommandGatewayV1>
+  return candidate.protocol === DSH_IM_COMMAND_GATEWAY_PROTOCOL && typeof candidate.registerCommand === 'function'
+}

package/src/index.ts

@@ -0,0 +1,260 @@
+import { randomUUID } from 'node:crypto'
+import { hostname } from 'node:os'
+import { AgoraClient } from './agora-client.js'
+import type { DshAgoraContext, DshWebServer } from './context-types.js'
+import { registerHttpApi } from './http-api.js'
+import { registerImCommand } from './im-gateway.js'
+import { discoverImBridge } from './im-bridge-v1.js'
+import { DshAgoraService } from './service.js'
+import { createAgoraTool } from './tool.js'
+import { DshAgoraExtensionRegistry, DSH_AGORA_EXTENSION_PROTOCOL } from './extension-sdk.js'
+import { HarnessRuntimeAdapter, type ConfiguredDshAgent } from './harness-runtime.js'
+import { RuntimeNodeWorker } from './node-worker.js'
+
+export { AgoraApiError, AgoraClient } from './agora-client.js'
+export { AgoraCommandParseError, executeAgoraCommand, parseAgoraCommand } from './command.js'
+export * from './contracts.js'
+export { API_PREFIX, handleHttpRequest, registerHttpApi } from './http-api.js'
+export * from './im-gateway.js'
+export * from './im-bridge-v1.js'
+export * from './command-adapter.js'
+export * from './extension-sdk.js'
+export * from './harness-runtime.js'
+export { RuntimeNodeWorker } from './node-worker.js'
+export { DshAgoraService } from './service.js'
+export * from './tool.js'
+
+export const name = 'dsh-agora'
+// webServer is required for both the local Harness RPC adapter and the runtime
+// node worker. Declaring it here also makes Cordis delay apply() until the web
+// host is initialized instead of silently starting in command-only mode.
+export const inject = ['commands', 'tools', 'webServer']
+const PLUGIN_VERSION = '0.6.0'
+
+export interface Config {
+  readonly serverUrl?: string
+  readonly apiToken?: string
+  readonly nodeApiToken?: string
+  readonly requestTimeoutMs?: number
+  readonly defaultCreator?: string
+  readonly commandName?: string
+  readonly apiAccessToken?: string
+  readonly imGatewayServices?: readonly string[]
+  readonly imBridgeServices?: readonly string[]
+  readonly nodeEnabled?: boolean
+  readonly nodeId?: string
+  readonly heartbeatIntervalMs?: number
+  readonly dispatchPollIntervalMs?: number
+  readonly nodeLeaseSeconds?: number
+  readonly dispatchLeaseSeconds?: number
+  readonly dispatchRenewIntervalMs?: number
+  readonly deliveryPollIntervalMs?: number
+  readonly deliveryLeaseSeconds?: number
+  readonly maxConcurrent?: number
+  readonly runtimeReplyTimeoutMs?: number
+  readonly runtimeAgents?: readonly ConfiguredDshAgent[]
+  readonly nodeMetadata?: Readonly<Record<string, unknown>>
+  readonly extensionSecurity?: {
+    readonly requireSignedThirdParty?: boolean
+    readonly trustedPublicKeys?: Readonly<Record<string, string>>
+  }
+}
+
+export function apply(ctx: DshAgoraContext, config: Config = {}): void {
+  const commandName = normalizeCommandName(config.commandName ?? 'agora')
+  const nodeId = normalizeNodeId(config.nodeId ?? process.env.DSH_AGORA_NODE_ID ?? hostname())
+  const webServer = safeGet(ctx, 'webServer')
+  const imBridgeDiscovery = discoverImBridge(
+    ctx,
+    unique(config.imBridgeServices ?? ['dshImBridge', 'dshImAgoraBridge']),
+  )
+  let activeImBridge = imBridgeDiscovery.bridge
+  let worker: RuntimeNodeWorker | null = null
+  const registry = new DshAgoraExtensionRegistry({
+    ...(config.extensionSecurity?.requireSignedThirdParty === undefined
+      ? {}
+      : { requireSignedThirdParty: config.extensionSecurity.requireSignedThirdParty }),
+    ...(config.extensionSecurity?.trustedPublicKeys === undefined
+      ? {}
+      : { trustedPublicKeys: config.extensionSecurity.trustedPublicKeys }),
+    builtInExtensionIds: ['dsh-runtime'],
+  })
+  const client = new AgoraClient({
+    serverUrl: config.serverUrl ?? process.env.AGORA_SERVER_URL ?? 'http://127.0.0.1:18008',
+    apiToken: config.apiToken ?? process.env.AGORA_API_TOKEN,
+    timeoutMs: config.requestTimeoutMs,
+  })
+  const workerClient = new AgoraClient({
+    serverUrl: config.serverUrl ?? process.env.AGORA_SERVER_URL ?? 'http://127.0.0.1:18008',
+    apiToken: config.nodeApiToken ?? process.env.AGORA_NODE_API_TOKEN ?? config.apiToken ?? process.env.AGORA_API_TOKEN,
+    timeoutMs: config.requestTimeoutMs,
+  })
+  const service = new DshAgoraService({
+    client,
+    commandName,
+    defaultCreator: config.defaultCreator?.trim() || 'dsh',
+    registry,
+    imBridge: imBridgeDiscovery.bridge,
+    nodeId,
+  })
+  service.setImBridgeStatus(imBridgeDiscovery.status)
+
+  const refreshImBridge = (): void => {
+    const discovery = discoverImBridge(
+      ctx,
+      unique(config.imBridgeServices ?? ['dshImBridge', 'dshImAgoraBridge']),
+    )
+    // A bridge discovered by the optional Cordis injection below is scoped to
+    // its child context and is intentionally not visible from this parent.
+    // Do not let the legacy poller overwrite that live injected bridge.
+    if (discovery.bridge === null && activeImBridge !== null) return
+    activeImBridge = discovery.bridge
+    service.setImBridge(discovery.bridge, discovery.status)
+    worker?.setImBridge(discovery.bridge)
+  }
+  const imBridgeTimer = setInterval(refreshImBridge, 5_000)
+  imBridgeTimer.unref?.()
+  own(ctx, () => clearInterval(imBridgeTimer), 'dsh-agora: dsh-im bridge discovery')
+
+  // Optional dependency: this child fiber stays pending when dsh-im is absent,
+  // while the main dsh-agora plugin remains fully usable in headless mode. When
+  // dsh-im appears or reloads, Cordis activates this callback automatically.
+  ctx.inject?.(['dshImBridge'], bridgeCtx => {
+    const discovery = discoverImBridge(bridgeCtx, ['dshImBridge'])
+    if (discovery.bridge === null) return
+    activeImBridge = discovery.bridge
+    service.setImBridge(discovery.bridge, discovery.status)
+    worker?.setImBridge(discovery.bridge)
+    return () => {
+      if (activeImBridge !== discovery.bridge) return
+      activeImBridge = null
+      worker?.setImBridge(null)
+      service.setImBridge(null, {
+        state: 'unavailable',
+        reason: 'dsh-im.bridge/v1 provider was unloaded',
+      })
+    }
+  })
+
+  if (isWebServer(webServer) && Number.isInteger(webServer.port)) {
+    const runtime = new HarnessRuntimeAdapter({
+      baseUrl: `http://127.0.0.1:${webServer.port}`,
+      agents: config.runtimeAgents ?? [{ id: 'default', displayName: 'DeepSeek Harness', workspace: process.cwd() }],
+      ...(config.runtimeReplyTimeoutMs === undefined ? {} : { replyTimeoutMs: config.runtimeReplyTimeoutMs }),
+    })
+    const unregisterRuntime = service.registerExtension({
+      protocol: DSH_AGORA_EXTENSION_PROTOCOL,
+      id: 'dsh-runtime',
+      kind: 'runtime',
+      capabilities: ['runtime.execute', 'session.create', 'session.resume', 'session.prompt', 'session.cancel'],
+      runtime,
+    })
+    own(ctx, unregisterRuntime, 'dsh-agora: built-in DSH runtime adapter')
+  }
+
+  const unregisterCommand = ctx.commands.register({
+    name: commandName,
+    description: 'create and inspect governed Agora tasks',
+    input: { hint: '[health|nodes|agents|list|show|status|dispatch-status|create|dashboard|im]' },
+    handler: invocation => service.executeCommand(
+      invocation.rawInput,
+      { actorId: invocation.agent.id ?? invocation.agent.session?.id ?? 'dsh' },
+      invocation.signal,
+    ),
+  })
+  // commands.register() is already owned by the current Cordis effect. Keeping
+  // the returned capability alive is enough; wrapping it would double-dispose.
+  void unregisterCommand
+
+  // Primary IM-independent path: dsh-im only delivers text into a DSH Session;
+  // the Agent uses this normal DSH tool and dsh-im relays the ordinary reply.
+  const unregisterTool = ctx.tools.register(createAgoraTool(service))
+  void unregisterTool
+
+  const imRegistration = registerImCommand(
+    ctx,
+    unique(config.imGatewayServices ?? ['dshImCommandGateway', 'dshImGateway']),
+    {
+      name: commandName,
+      description: 'create and inspect governed Agora tasks',
+      execute: invocation => service.executeCommand(invocation.rawInput, invocation, invocation.signal),
+    },
+  )
+  service.setImStatus(imRegistration.status)
+  if (imRegistration.dispose !== undefined) own(ctx, imRegistration.dispose, 'dsh-agora: dsh-im command gateway')
+
+  if (isWebServer(webServer)) {
+    own(ctx, registerHttpApi(webServer, service, {
+      accessToken: config.apiAccessToken ?? process.env.DSH_AGORA_API_TOKEN,
+    }), 'dsh-agora: host API')
+  }
+
+  if (config.nodeEnabled !== false && isWebServer(webServer) && Number.isInteger(webServer.port)) {
+    worker = new RuntimeNodeWorker({
+      client: workerClient,
+      registry,
+      nodeId,
+      instanceId: randomUUID(),
+      pluginVersion: PLUGIN_VERSION,
+      ...(config.heartbeatIntervalMs === undefined ? {} : { heartbeatIntervalMs: config.heartbeatIntervalMs }),
+      ...(config.dispatchPollIntervalMs === undefined ? {} : { dispatchPollIntervalMs: config.dispatchPollIntervalMs }),
+      ...(config.nodeLeaseSeconds === undefined ? {} : { leaseSeconds: config.nodeLeaseSeconds }),
+      ...(config.dispatchLeaseSeconds === undefined ? {} : { dispatchLeaseSeconds: config.dispatchLeaseSeconds }),
+      ...(config.dispatchRenewIntervalMs === undefined ? {} : { dispatchRenewIntervalMs: config.dispatchRenewIntervalMs }),
+      ...(config.deliveryPollIntervalMs === undefined ? {} : { deliveryPollIntervalMs: config.deliveryPollIntervalMs }),
+      ...(config.deliveryLeaseSeconds === undefined ? {} : { deliveryLeaseSeconds: config.deliveryLeaseSeconds }),
+      ...(config.maxConcurrent === undefined ? {} : { maxConcurrent: config.maxConcurrent }),
+      imBridge: activeImBridge,
+      ...(config.nodeMetadata === undefined ? {} : { metadata: config.nodeMetadata }),
+      onStatus: status => service.setNodeStatus(status),
+    })
+    worker.start()
+    own(ctx, () => worker?.stop(), 'dsh-agora: runtime node worker')
+  } else {
+    service.setNodeStatus({ state: 'disabled', nodeId })
+  }
+
+  ctx.accessor?.('dshAgora', { get: () => service })
+  ctx.accessor?.('dshAgoraCommandAdapter', { get: () => service.commandAdapter })
+}
+
+function normalizeNodeId(value: string): string {
+  const nodeId = value.trim().toLowerCase().replace(/[^a-z0-9._-]+/gu, '-')
+  if (!/^[a-z0-9][a-z0-9._-]{0,127}$/u.test(nodeId)) throw new TypeError('nodeId is invalid')
+  return nodeId
+}
+
+function normalizeCommandName(value: string): string {
+  const name = value.trim().toLowerCase()
+  if (!/^[a-z][a-z0-9-]*$/u.test(name)) throw new TypeError('commandName must be lowercase letters, digits, or hyphens')
+  return name
+}
+
+function unique(values: readonly string[]): string[] {
+  return [...new Set(values.map(value => value.trim()).filter(Boolean))]
+}
+
+function safeGet(ctx: DshAgoraContext, name: string): unknown {
+  try {
+    // Cordis accessors (such as the public dsh-im bridge) are resolved through
+    // the context proxy, while ctx.get() only reads provided service values.
+    const accessorValue = Reflect.get(ctx as object, name)
+    if (accessorValue !== undefined) return accessorValue
+  } catch {
+    // Unknown, non-injected proxy properties throw by design; fall through to
+    // the provider lookup for ordinary Cordis services.
+  }
+  try {
+    return ctx.get?.(name)
+  } catch {
+    return undefined
+  }
+}
+
+function isWebServer(value: unknown): value is DshWebServer {
+  return typeof value === 'object' && value !== null && typeof (value as Partial<DshWebServer>).register === 'function'
+}
+
+function own(ctx: DshAgoraContext, dispose: () => void, label: string): void {
+  if (ctx.effect !== undefined) ctx.effect(() => dispose, label)
+}