dsh-agora-plugin 0.6.0

package/src/contracts.ts

@@ -0,0 +1,413 @@
+export type TaskPriority = 'low' | 'normal' | 'high'
+
+export interface AgoraTask {
+  readonly id: string
+  readonly version?: number
+  readonly title: string
+  readonly description?: string | null
+  readonly type: string
+  readonly priority: TaskPriority
+  readonly creator: string
+  readonly locale?: string
+  readonly project_id?: string | null
+  readonly state: string
+  readonly current_stage: string | null
+  readonly error_detail?: string | null
+  readonly created_at?: string
+  readonly updated_at?: string
+  readonly [key: string]: unknown
+}
+
+export interface AgoraTaskStatus {
+  readonly task: AgoraTask
+  readonly flow_log: readonly Record<string, unknown>[]
+  readonly progress_log: readonly Record<string, unknown>[]
+  readonly subtasks: readonly Record<string, unknown>[]
+  readonly [key: string]: unknown
+}
+
+export interface AgoraHealth {
+  readonly ok?: boolean
+  readonly status?: string
+  readonly service?: string
+  readonly [key: string]: unknown
+}
+
+export const DSH_AGORA_NODE_PROTOCOL = 'dsh-agora.node/v1' as const
+
+export interface RuntimeNodeAgent {
+  readonly agent_ref: string
+  readonly display_name?: string | null
+  readonly preset?: string | null
+  readonly model?: string | null
+  readonly workspace_alias?: string | null
+  readonly roles: readonly string[]
+  readonly capabilities: readonly string[]
+  readonly metadata?: Readonly<Record<string, unknown>> | null
+}
+
+export interface RuntimeNodeBot {
+  readonly provider: string
+  readonly bot_ref: string
+  readonly platform_id?: string | null
+  readonly display_name?: string | null
+  readonly agent_ref?: string | null
+  readonly connected: boolean
+  readonly capabilities: readonly string[]
+}
+
+export interface RuntimeNodeHeartbeatInput {
+  readonly protocol: typeof DSH_AGORA_NODE_PROTOCOL
+  readonly instance_id: string
+  readonly plugin_version: string
+  readonly host_framework: 'deepseek-harness'
+  readonly runtime_provider: 'dsh'
+  readonly agents: readonly RuntimeNodeAgent[]
+  readonly bots: readonly RuntimeNodeBot[]
+  readonly capacity: { readonly max_concurrent: number; readonly active: number }
+  readonly lease_seconds: number
+  readonly metadata?: Readonly<Record<string, unknown>> | null
+}
+
+export interface RuntimeNode extends RuntimeNodeHeartbeatInput {
+  readonly node_id: string
+  readonly presence: 'online' | 'stale'
+  readonly registered_at: string
+  readonly last_seen_at: string
+  readonly expires_at: string
+}
+
+export interface RuntimeTarget {
+  readonly runtime_target_ref: string
+  readonly runtime_provider: string | null
+  readonly runtime_flavor: string | null
+  readonly host_framework: string | null
+  readonly primary_model: string | null
+  readonly channel_providers: readonly string[]
+  readonly enabled: boolean
+  readonly display_name: string | null
+  readonly presentation_mode: 'headless' | 'im_presented'
+  readonly presentation_provider: string | null
+  readonly presentation_identity_ref: string | null
+  readonly [key: string]: unknown
+}
+
+export interface CreateRuntimeDispatchInput {
+  readonly task_id?: string | null
+  readonly participant_binding_id?: string | null
+  readonly runtime_target_ref: string
+  readonly session_id?: string | null
+  readonly workspace_alias?: string | null
+  readonly agent_preset?: string | null
+  readonly prompt: string
+  readonly idempotency_key: string
+  readonly metadata?: Readonly<Record<string, unknown>> | null
+}
+
+export interface DispatchAgentInput extends CreateRuntimeDispatchInput {
+  readonly source_session_id?: string
+  readonly wait_timeout_ms?: number
+  readonly presentation_mode?: 'source_bot' | 'destination_bot' | 'silent'
+}
+
+export interface RuntimeDispatch extends CreateRuntimeDispatchInput {
+  readonly id: string
+  readonly node_id: string
+  readonly status: 'pending' | 'claimed' | 'completed' | 'failed' | 'cancelled'
+  readonly claimed_by: string | null
+  readonly claim_token: string | null
+  readonly claim_expires_at: string | null
+  readonly attempt: number
+  readonly claimed_at: string | null
+  readonly claim_renewed_at: string | null
+  readonly latest_progress?: RuntimeDispatchProgress | null
+  readonly progress_updated_at?: string | null
+  readonly result: Readonly<Record<string, unknown>> | null
+  readonly result_envelope?: RuntimeResultEnvelope | null
+  readonly error: string | null
+  readonly created_at: string
+  readonly updated_at: string
+  readonly completed_at: string | null
+}
+
+export interface RuntimeDispatchProgressInput {
+  readonly phase: string
+  readonly message?: string | null
+  readonly percent?: number | null
+  readonly details?: Readonly<Record<string, unknown>> | null
+}
+
+export interface RecordRuntimeDispatchProgressInput extends RuntimeDispatchProgressInput {
+  readonly instance_id: string
+  readonly claim_token: string
+  readonly sequence: number
+}
+
+export interface RuntimeDispatchProgress extends RuntimeDispatchProgressInput {
+  readonly id: string
+  readonly dispatch_id: string
+  readonly node_id: string
+  readonly instance_id: string
+  readonly attempt: number
+  readonly sequence: number
+  readonly created_at: string
+}
+
+export interface RuntimeResultEvidence {
+  readonly id: string
+  readonly kind: 'file' | 'url' | 'commit' | 'measurement' | 'log' | 'command' | 'other'
+  readonly label?: string | null
+  readonly uri?: string | null
+  readonly content_hash?: string | null
+  readonly revision?: string | null
+  readonly line_start?: number | null
+  readonly line_end?: number | null
+  readonly metadata?: Readonly<Record<string, unknown>> | null
+}
+
+export interface RuntimeResultClaim {
+  readonly id: string
+  readonly statement: string
+  readonly evidence_ids: readonly string[]
+  readonly confidence?: number | null
+}
+
+export interface RuntimeResultEnvelope {
+  readonly schema: 'agora.runtime-result/v1'
+  readonly answer: string
+  readonly claims: readonly RuntimeResultClaim[]
+  readonly evidence: readonly RuntimeResultEvidence[]
+  readonly confidence?: number | null
+  readonly environment?: {
+    readonly runtime_provider: string
+    readonly agent_ref?: string | null
+    readonly model?: string | null
+    readonly workspace_alias?: string | null
+    readonly revision?: string | null
+    readonly metadata?: Readonly<Record<string, unknown>> | null
+  } | null
+  readonly usage?: RuntimeUsage | null
+}
+
+export interface RuntimeUsage {
+  readonly input_tokens: number | null
+  readonly output_tokens: number | null
+  readonly total_tokens: number | null
+  readonly tool_calls: number | null
+  readonly cost_usd: number | null
+  readonly duration_ms: number | null
+}
+
+export type CoordinationMode = 'single' | 'fanout' | 'review' | 'debate' | 'council'
+export type CoordinationRunStatus = 'running' | 'verifying' | 'completed' | 'partial' | 'failed' | 'cancelled' | 'budget_exhausted'
+
+export interface CoordinationBudget {
+  readonly max_agents: number
+  readonly max_dispatches: number
+  readonly max_wall_clock_seconds: number
+  readonly max_tokens: number | null
+  readonly max_tool_calls: number | null
+  readonly max_cost_usd: number | null
+  readonly min_information_gain: number
+}
+
+export interface CreateCoordinationRunInput {
+  readonly task_id?: string | null
+  readonly task_type?: string
+  readonly prompt: string
+  readonly mode: CoordinationMode
+  readonly candidates: readonly {
+    readonly runtime_target_ref: string
+    readonly capabilities?: readonly string[]
+    readonly priority?: number
+  }[]
+  readonly verifier_target_ref?: string | null
+  readonly budget?: Partial<CoordinationBudget>
+  readonly memory_scopes?: readonly ('task' | 'agent_private' | 'project_shared' | 'decision' | 'episodic')[]
+  readonly idempotency_key: string
+  readonly metadata?: Readonly<Record<string, unknown>> | null
+}
+
+export interface CoordinationRun {
+  readonly id: string
+  readonly task_id: string | null
+  readonly task_type: string
+  readonly prompt: string
+  readonly mode: CoordinationMode
+  readonly status: CoordinationRunStatus
+  readonly budget: CoordinationBudget
+  readonly usage: RuntimeUsage
+  readonly synthesis: {
+    readonly answer: string
+    readonly agreements: readonly string[]
+    readonly conflicts: readonly {
+      readonly id: string
+      readonly kind: 'claim_conflict' | 'environment_drift' | 'unsupported_claim'
+      readonly key: string
+      readonly member_ids: readonly string[]
+      readonly statements: readonly string[]
+      readonly detail: string
+      readonly resolved: boolean
+    }[]
+    readonly evidence_ids: readonly string[]
+    readonly verified: boolean
+    readonly information_gain: number
+    readonly result_envelope: RuntimeResultEnvelope | null
+  } | null
+  readonly stop_reason: string | null
+  readonly deadline_at: string
+  readonly created_at: string
+  readonly updated_at: string
+  readonly completed_at: string | null
+  readonly members: readonly {
+    readonly id: string
+    readonly dispatch_id: string
+    readonly runtime_target_ref: string
+    readonly role: 'primary' | 'investigator' | 'reviewer' | 'verifier' | 'arbitrator'
+    readonly round: number
+    readonly status: 'dispatched' | 'claimed' | 'completed' | 'failed' | 'cancelled'
+    readonly selection_score: number
+    readonly selection_reason: readonly string[]
+    readonly result_envelope: RuntimeResultEnvelope | null
+    readonly usage: RuntimeUsage | null
+  }[]
+}
+
+export interface AgentScorecard {
+  readonly runtime_target_ref: string
+  readonly task_type: string
+  readonly observations: number
+  readonly success_rate: number | null
+  readonly failure_rate: number | null
+  readonly cancellation_rate: number | null
+  readonly retry_rate: number | null
+  readonly timeout_rate: number | null
+  readonly median_duration_ms: number | null
+  readonly p95_duration_ms: number | null
+  readonly evidence_yield: number | null
+  readonly verifier_acceptance_rate: number | null
+  readonly agreement_rate: number | null
+  readonly unique_information_rate: number | null
+  readonly environment_drift_rate: number | null
+  readonly total_tokens: number | null
+  readonly total_cost_usd: number | null
+  readonly score: number
+  readonly updated_at: string | null
+}
+
+export interface RuntimeDelivery {
+  readonly id: string
+  readonly dispatch_id: string
+  readonly node_id: string
+  readonly payload: Readonly<Record<string, unknown>>
+  readonly status: 'pending' | 'claimed' | 'delivered' | 'failed'
+  readonly attempt: number
+  readonly claimed_by: string | null
+  readonly claim_token: string | null
+  readonly claim_expires_at: string | null
+  readonly next_attempt_at: string
+  readonly receipt: Readonly<Record<string, unknown>> | null
+  readonly error: string | null
+  readonly created_at: string
+  readonly updated_at: string
+  readonly delivered_at: string | null
+}
+
+export interface RuntimeSessionBinding {
+  readonly id: string
+  readonly participant_binding_id: string
+  readonly runtime_provider: 'dsh'
+  readonly runtime_session_ref: string
+  readonly runtime_actor_ref: string | null
+  readonly continuity_ref: string | null
+  readonly presence_state: 'active' | 'idle' | 'closed'
+  readonly last_seen_at: string
+  readonly [key: string]: unknown
+}
+
+export interface AgoraImTarget {
+  readonly provider?: string
+  readonly conversation_ref?: string
+  readonly thread_ref?: string
+  readonly visibility?: 'public' | 'private'
+  readonly participant_refs?: readonly string[]
+}
+
+export interface CreateAgoraTaskInput {
+  readonly title: string
+  readonly type?: string
+  readonly creator?: string
+  readonly description?: string
+  readonly priority?: TaskPriority
+  readonly locale?: 'zh-CN' | 'en-US'
+  readonly projectId?: string
+  readonly imTarget?: AgoraImTarget
+}
+
+export interface AgoraRequestContext {
+  readonly actorId?: string
+  readonly provider?: string
+  readonly conversationRef?: string
+  readonly threadRef?: string
+}
+
+export type AgoraCommandResult =
+  | { readonly kind: 'success'; readonly text?: string }
+  | { readonly kind: 'error'; readonly text: string }
+
+export type DshAgoraImStatus =
+  | { readonly state: 'connected'; readonly service: string; readonly protocol: string }
+  | { readonly state: 'unavailable'; readonly reason: string }
+  | { readonly state: 'incompatible'; readonly service: string; readonly reason: string }
+
+export interface DshAgoraSnapshot {
+  readonly serverUrl: string
+  readonly command: string
+  readonly im: DshAgoraImStatus
+  readonly imBridge: DshAgoraImStatus
+  readonly commandAdapter: {
+    readonly state: 'ready'
+    readonly protocol: 'dsh-agora.command-adapter/v1'
+  }
+  readonly node: DshAgoraNodeStatus
+  readonly extensions: readonly DshAgoraExtensionSummary[]
+}
+
+export type DshAgoraNodeStatus =
+  | { readonly state: 'disabled'; readonly nodeId: string }
+  | { readonly state: 'connecting'; readonly nodeId: string }
+  | { readonly state: 'online'; readonly nodeId: string; readonly lastHeartbeatAt: string }
+  | { readonly state: 'error'; readonly nodeId: string; readonly error: string; readonly lastHeartbeatAt?: string }
+
+export interface DshAgoraExtensionSummary {
+  readonly id: string
+  readonly protocol: string
+  readonly kind: string
+  readonly capabilities: readonly string[]
+}
+
+export interface DshAgoraServiceApi {
+  readonly serverUrl: string
+  health(signal?: AbortSignal): Promise<AgoraHealth>
+  listTasks(state?: string, projectId?: string, signal?: AbortSignal): Promise<AgoraTask[]>
+  getTask(taskId: string, signal?: AbortSignal): Promise<AgoraTask>
+  taskStatus(taskId: string, signal?: AbortSignal): Promise<AgoraTaskStatus>
+  createTask(input: CreateAgoraTaskInput, signal?: AbortSignal): Promise<AgoraTask>
+  listRuntimeNodes(signal?: AbortSignal): Promise<RuntimeNode[]>
+  listRuntimeTargets(signal?: AbortSignal): Promise<RuntimeTarget[]>
+  createRuntimeDispatch(nodeId: string, input: CreateRuntimeDispatchInput, signal?: AbortSignal): Promise<RuntimeDispatch>
+  getRuntimeDispatch(dispatchId: string, signal?: AbortSignal): Promise<RuntimeDispatch>
+  listRuntimeDispatchProgress(dispatchId: string, signal?: AbortSignal): Promise<RuntimeDispatchProgress[]>
+  createCoordinationRun(input: CreateCoordinationRunInput, signal?: AbortSignal): Promise<CoordinationRun>
+  getCoordinationRun(runId: string, signal?: AbortSignal): Promise<CoordinationRun>
+  listCoordinationRuns(status?: CoordinationRunStatus, signal?: AbortSignal): Promise<CoordinationRun[]>
+  listAgentScorecards(taskType?: string, signal?: AbortSignal): Promise<AgentScorecard[]>
+  dispatchAgent(input: DispatchAgentInput, signal?: AbortSignal): Promise<RuntimeDispatch>
+  bindRuntimeSession(taskId: string, participantBindingId: string, sessionId: string, agentRef?: string, signal?: AbortSignal): Promise<RuntimeSessionBinding>
+  executeCommand(rawInput: string, context?: AgoraRequestContext, signal?: AbortSignal): Promise<AgoraCommandResult>
+  executeCommandEvent(
+    event: import('./command-adapter.js').DshAgoraCommandEventV1,
+    signal?: AbortSignal,
+  ): Promise<import('./command-adapter.js').DshAgoraCommandEventResultV1>
+  snapshot(): DshAgoraSnapshot
+}

package/src/extension-sdk.ts

@@ -0,0 +1,225 @@
+import { createHash, createPublicKey, verify as verifySignature } from 'node:crypto'
+import type {
+  RuntimeDispatch,
+  RuntimeDispatchProgressInput,
+  RuntimeNodeAgent,
+  RuntimeResultEnvelope,
+} from './contracts.js'
+
+export const DSH_AGORA_EXTENSION_PROTOCOL = 'dsh-agora.extension/v1' as const
+export const DSH_AGORA_RUNTIME_PROTOCOL = 'dsh-agora.runtime/v1' as const
+export const DSH_AGORA_EXTENSION_MANIFEST_PROTOCOL = 'dsh-agora.extension-manifest/v1' as const
+
+export interface RuntimeExecutionResult {
+  readonly sessionId: string
+  readonly answer: string
+  readonly reason?: string | null
+  readonly metadata?: Readonly<Record<string, unknown>>
+  readonly resultEnvelope?: RuntimeResultEnvelope
+}
+
+export interface RuntimeExecutionContext {
+  reportProgress(event: RuntimeDispatchProgressInput): Promise<void>
+}
+
+export interface DshAgoraRuntimeAdapterV1 {
+  readonly protocol: typeof DSH_AGORA_RUNTIME_PROTOCOL
+  supportsTarget?(runtimeTargetRef: string): boolean
+  describeAgents(): readonly RuntimeNodeAgent[] | Promise<readonly RuntimeNodeAgent[]>
+  execute(dispatch: RuntimeDispatch, signal: AbortSignal, context?: RuntimeExecutionContext): Promise<RuntimeExecutionResult>
+  cancel?(sessionId: string, signal: AbortSignal): Promise<boolean>
+}
+
+export interface DshAgoraExtensionV1 {
+  readonly protocol: typeof DSH_AGORA_EXTENSION_PROTOCOL
+  readonly id: string
+  readonly kind: 'runtime' | 'transport' | 'context' | 'workflow' | 'artifact' | 'event-sink' | 'policy'
+  readonly capabilities: readonly string[]
+  readonly runtime?: DshAgoraRuntimeAdapterV1
+  readonly metadata?: Readonly<Record<string, unknown>>
+}
+
+export interface DshAgoraExtensionManifestV1 {
+  readonly protocol: typeof DSH_AGORA_EXTENSION_MANIFEST_PROTOCOL
+  readonly id: string
+  readonly version: string
+  readonly kind: DshAgoraExtensionV1['kind']
+  readonly integrity_sha256: string
+  readonly capabilities: readonly string[]
+  readonly permissions: readonly {
+    readonly capability: string
+    readonly resources: readonly string[]
+  }[]
+  readonly publisher: {
+    readonly id: string
+    readonly key_id: string
+  }
+  readonly signature?: {
+    readonly algorithm: 'Ed25519'
+    readonly value: string
+  } | null
+}
+
+export interface DshAgoraExtensionTrustPolicy {
+  readonly requireSignedThirdParty?: boolean
+  readonly trustedPublicKeys?: Readonly<Record<string, string>>
+  readonly builtInExtensionIds?: readonly string[]
+}
+
+export interface DshAgoraExtensionRegistryApi {
+  registerExtension(extension: DshAgoraExtensionV1, manifest?: DshAgoraExtensionManifestV1, packageBytes?: Uint8Array): () => void
+  listExtensions(): readonly DshAgoraExtensionV1[]
+}
+
+export class DshAgoraExtensionRegistry implements DshAgoraExtensionRegistryApi {
+  private readonly extensions = new Map<string, DshAgoraExtensionV1>()
+  private readonly manifests = new Map<string, DshAgoraExtensionManifestV1>()
+
+  constructor(private readonly trustPolicy: DshAgoraExtensionTrustPolicy = {}) {}
+
+  registerExtension(extension: DshAgoraExtensionV1, manifest?: DshAgoraExtensionManifestV1, packageBytes?: Uint8Array): () => void {
+    validateExtension(extension)
+    const builtIn = new Set(this.trustPolicy.builtInExtensionIds ?? ['dsh-runtime']).has(extension.id)
+    if (manifest) {
+      validateExtensionManifest(manifest, extension)
+      if (this.trustPolicy.requireSignedThirdParty && !builtIn && packageBytes === undefined) {
+        throw new Error(`extension "${extension.id}" requires package bytes for integrity verification`)
+      }
+      verifyExtensionManifest(manifest, this.trustPolicy, packageBytes)
+    } else if (this.trustPolicy.requireSignedThirdParty && !builtIn) {
+      throw new Error(`extension "${extension.id}" requires a signed manifest`)
+    }
+    if (this.extensions.has(extension.id)) throw new Error(`dsh-agora extension "${extension.id}" is already registered`)
+    const frozen = Object.freeze({
+      ...extension,
+      capabilities: Object.freeze(unique(extension.capabilities)),
+    })
+    this.extensions.set(frozen.id, frozen)
+    if (manifest) this.manifests.set(frozen.id, Object.freeze({ ...manifest }))
+    return () => {
+      if (this.extensions.get(frozen.id) === frozen) {
+        this.extensions.delete(frozen.id)
+        this.manifests.delete(frozen.id)
+      }
+    }
+  }
+
+  manifestFor(id: string): DshAgoraExtensionManifestV1 | null {
+    return this.manifests.get(id) ?? null
+  }
+
+  listExtensions(): readonly DshAgoraExtensionV1[] {
+    return [...this.extensions.values()].sort((left, right) => left.id.localeCompare(right.id))
+  }
+
+  runtimeForTarget(runtimeTargetRef: string): DshAgoraRuntimeAdapterV1 | null {
+    const runtimes = [...this.extensions.values()].filter(extension => (
+      extension.runtime && extension.capabilities.includes('runtime.execute')
+    ))
+    const explicit = runtimes.find(extension => extension.runtime!.supportsTarget?.(runtimeTargetRef) === true)
+    if (explicit?.runtime) return explicit.runtime
+    if (runtimeTargetRef.startsWith('dsh:')) {
+      const builtIn = runtimes.find(extension => extension.id === 'dsh-runtime')
+      if (builtIn?.runtime) return builtIn.runtime
+    }
+    const legacy = runtimes.filter(extension => extension.runtime!.supportsTarget === undefined)
+    return legacy.length === 1 ? legacy[0]!.runtime! : null
+  }
+}
+
+export function verifyExtensionManifest(
+  manifest: DshAgoraExtensionManifestV1,
+  policy: DshAgoraExtensionTrustPolicy,
+  packageBytes?: Uint8Array,
+): boolean {
+  if (packageBytes && createHash('sha256').update(packageBytes).digest('hex') !== manifest.integrity_sha256) {
+    throw new Error(`extension manifest integrity mismatch for ${manifest.id}`)
+  }
+  if (!manifest.signature) {
+    if (policy.requireSignedThirdParty) throw new Error(`extension manifest ${manifest.id} is unsigned`)
+    return false
+  }
+  const keyRef = `${manifest.publisher.id}:${manifest.publisher.key_id}`
+  const publicKey = policy.trustedPublicKeys?.[keyRef]
+  if (!publicKey) throw new Error(`extension publisher key ${keyRef} is not trusted`)
+  const valid = verifySignature(
+    null,
+    Buffer.from(canonicalManifest(manifest)),
+    createPublicKey(publicKey),
+    Buffer.from(manifest.signature.value, 'base64url'),
+  )
+  if (!valid) throw new Error(`extension manifest signature is invalid for ${manifest.id}`)
+  return true
+}
+
+export async function runExtensionConformance(
+  extension: DshAgoraExtensionV1,
+  manifest?: DshAgoraExtensionManifestV1,
+): Promise<{ readonly ok: true; readonly checks: readonly string[] }> {
+  validateExtension(extension)
+  if (manifest) validateExtensionManifest(manifest, extension)
+  const checks = ['extension-shape', 'capability-uniqueness']
+  if (extension.runtime) {
+    const first = normalizeAgents(await extension.runtime.describeAgents())
+    const second = normalizeAgents(await extension.runtime.describeAgents())
+    if (JSON.stringify(first) !== JSON.stringify(second)) throw new Error('runtime describeAgents must be deterministic')
+    if (new Set(first.map(agent => agent.agent_ref)).size !== first.length) throw new Error('runtime describeAgents returned duplicate agent_ref values')
+    checks.push('runtime-protocol', 'runtime-deterministic-agents', 'runtime-unique-agent-refs')
+  }
+  if (manifest) checks.push('manifest-capability-permissions')
+  return { ok: true, checks }
+}
+
+function validateExtension(extension: DshAgoraExtensionV1): void {
+  if (extension.protocol !== DSH_AGORA_EXTENSION_PROTOCOL) {
+    throw new TypeError(`extension protocol must be ${DSH_AGORA_EXTENSION_PROTOCOL}`)
+  }
+  if (!/^[a-z0-9][a-z0-9._-]{0,127}$/u.test(extension.id)) throw new TypeError('extension id is invalid')
+  if (!Array.isArray(extension.capabilities) || extension.capabilities.some(value => typeof value !== 'string' || value.trim() === '')) {
+    throw new TypeError('extension capabilities must be non-empty strings')
+  }
+  if (unique(extension.capabilities).length !== extension.capabilities.length) throw new TypeError('extension capabilities must be unique')
+  if (extension.runtime !== undefined && extension.runtime.protocol !== DSH_AGORA_RUNTIME_PROTOCOL) {
+    throw new TypeError(`runtime adapter protocol must be ${DSH_AGORA_RUNTIME_PROTOCOL}`)
+  }
+}
+
+function validateExtensionManifest(manifest: DshAgoraExtensionManifestV1, extension: DshAgoraExtensionV1): void {
+  if (manifest.protocol !== DSH_AGORA_EXTENSION_MANIFEST_PROTOCOL) throw new TypeError(`manifest protocol must be ${DSH_AGORA_EXTENSION_MANIFEST_PROTOCOL}`)
+  if (manifest.id !== extension.id || manifest.kind !== extension.kind) throw new TypeError('manifest identity does not match extension')
+  if (!/^\d+\.\d+\.\d+(?:[-+][A-Za-z0-9.-]+)?$/u.test(manifest.version)) throw new TypeError('manifest version must be semantic')
+  if (!/^[a-f0-9]{64}$/u.test(manifest.integrity_sha256)) throw new TypeError('manifest integrity_sha256 is invalid')
+  const capabilities = unique(extension.capabilities)
+  if (JSON.stringify(unique(manifest.capabilities)) !== JSON.stringify(capabilities)) throw new TypeError('manifest capabilities do not match extension capabilities')
+  const granted = new Set(manifest.permissions.map(permission => permission.capability))
+  if (granted.size !== manifest.permissions.length) throw new TypeError('manifest permissions contain duplicate capabilities')
+  for (const capability of capabilities) if (!granted.has(capability)) throw new TypeError(`manifest permission missing for capability ${capability}`)
+  for (const permission of manifest.permissions) {
+    if (!capabilities.includes(permission.capability)) throw new TypeError(`manifest permission exceeds declared capability ${permission.capability}`)
+    if (permission.resources.length === 0 || permission.resources.some(resource => !resource.trim())) {
+      throw new TypeError(`manifest permission ${permission.capability} requires explicit resources`)
+    }
+  }
+  if (!/^[a-z0-9][a-z0-9._-]{0,127}$/u.test(manifest.publisher.id) || !manifest.publisher.key_id.trim()) throw new TypeError('manifest publisher is invalid')
+  if (manifest.signature && manifest.signature.algorithm !== 'Ed25519') throw new TypeError('only Ed25519 extension signatures are supported')
+}
+
+function canonicalManifest(manifest: DshAgoraExtensionManifestV1): string {
+  const { signature: _signature, ...unsigned } = manifest
+  return stableJson(unsigned)
+}
+
+function stableJson(value: unknown): string {
+  if (Array.isArray(value)) return `[${value.map(stableJson).join(',')}]`
+  if (value && typeof value === 'object') return `{${Object.entries(value as Record<string, unknown>).sort(([left], [right]) => left.localeCompare(right)).map(([key, item]) => `${JSON.stringify(key)}:${stableJson(item)}`).join(',')}}`
+  return JSON.stringify(value) ?? 'null'
+}
+
+function normalizeAgents(agents: readonly RuntimeNodeAgent[]): RuntimeNodeAgent[] {
+  return agents.map(agent => ({ ...agent, roles: unique(agent.roles), capabilities: unique(agent.capabilities) }))
+    .sort((left, right) => left.agent_ref.localeCompare(right.agent_ref))
+}
+
+function unique(values: readonly string[]): string[] {
+  return [...new Set(values.map(value => value.trim()).filter(Boolean))].sort()
+}