feat(hub): external capability registry for PDF/ASR transforms (ADR-0027)

Introduces the External Capability abstraction: platform-registered,
org-enabled document/media transform services invoked as side effects of
an AgentRun. The first concrete capability is pdf_to_md_bundle backed by
MinerU. This lands the contract, schema, adapter interface, and a fully
mock-tested adapter; the real MinerU HTTP client is deferred until
credentials and pricing are confirmed.

Contract:
- spec/Spec/System/Agent/Capability.lean pins ExternalCapability,
  OrganizationCapabilityConnection (reuses ADR-0024 envelope, distinct
  from model-provider connection), and CapabilityInvocation.Authorized
  (workspace containment predicate, ADR-0018). lake build green (41 jobs).
- ADR-0027 records why capability credentials are a separate connection
  type (MinerU/Whisper have their own auth shape, not OpenRouter /v1/models),
  the adapter seam, and what is deferred (capability invocation record,
  pricebook, agent-facing tool discovery).

Schema:
- OrganizationCapabilityConnection + CapabilityCredentialVersion, mirroring
  the Feishu Application Connection shape. Unique by (organizationId,
  capabilityId). Migration 20260718130000 applied.

Adapter (hub/src/capability):
- types.ts: CapabilityId, CapabilityAdapter interface, secret payload,
  CapabilityConnectionUnavailable.
- mineruClient.ts: MineruClient interface + MineruParseResult + errors.
  Real HTTP client deferred; the interface is the seam.
- capabilityConnections.ts: resolveCapabilityCredential — org-scoped,
  fail-closed, reuses LocalSecretEnvelope with purpose="capability".
- pdfToMdBundle.ts: adapter that resolves credential, confines input/output
  to the run workspace (ADR-0018), calls MineruClient, writes md + images
  into workspace, and writes a UsageFact (kind=external_capability,
  quantity=pages, costSource=provider_reported|unknown per ADR-0022).

Tests (7, all green):
- md + images written to workspace, UsageFact attributes pages + cost
- costUsd null -> costSource=unknown (missing cost != zero, ADR-0022)
- no ACTIVE connection -> fail-closed, no fact written
- input/output path escape -> CapabilityPathEscape
- MinerU client error propagates, no fact written
- empty markdown -> parse failure

Deferred (needs operator): MinerU account/API key/pricing, real MineruClient
HTTP implementation, org admin UI for capability connection management,
agent-facing tool exposure (MCP vs built-in).
This commit is contained in:
2026-07-18 15:54:00 +08:00
parent aaa098bb8b
commit 8df8156969
10 changed files with 1057 additions and 1 deletions
+54
View File
@@ -44,6 +44,7 @@ model Organization {
externalDirectoryConnections ExternalDirectoryConnection[]
providerConnections OrganizationProviderConnection[]
feishuApplicationConnection OrganizationFeishuApplicationConnection?
capabilityConnections OrganizationCapabilityConnection[]
agentSkills OrganizationAgentSkill[]
agentRoles OrganizationAgentRole[]
projectGroupBindings ProjectGroupBinding[]
@@ -198,6 +199,7 @@ model User {
auditEntries AuditEntry[] @relation("auditActor")
providerCredentialVersions ProviderCredentialVersion[] @relation("providerCredentialVersionCreator")
feishuCredentialVersions FeishuApplicationCredentialVersion[] @relation("feishuCredentialVersionCreator")
capabilityCredentialVersions CapabilityCredentialVersion[] @relation("capabilityCredentialVersionCreator")
feishuIdentities FeishuUserIdentity[]
}
@@ -869,3 +871,55 @@ model UsageFact {
@@index([provider, model, occurredAt])
@@index([capabilityId, occurredAt])
}
// --- External capability connections (ADR-0027) -------------------------
/// ADR-0027: org-scoped credential connection for an external capability
/// (PDF→MD, audio/video→text, …). Structurally mirrors the Feishu Application
/// Connection: reuses the ADR-0024 envelope (KEK→DEK→AES-256-GCM, AAD-bound)
/// but has its own payload schema and readiness probe, distinct from the
/// model-provider connection. Unique by (organizationId, capabilityId).
model OrganizationCapabilityConnection {
id String @id @default(cuid())
organizationId String
capabilityId String
status OrganizationConnectionStatus @default(DRAFT)
activeSecretVersionId String? @unique
activatedAt DateTime?
disabledAt DateTime?
createdAt DateTime @default(now())
updatedAt DateTime @updatedAt
organization Organization @relation(fields: [organizationId], references: [id], onDelete: Cascade)
secretVersions CapabilityCredentialVersion[] @relation("capabilityCredentialVersions")
activeSecretVersion CapabilityCredentialVersion? @relation("activeCapabilityCredentialVersion", fields: [activeSecretVersionId], references: [id], onDelete: Restrict)
@@unique([organizationId, capabilityId])
@@index([organizationId, status])
@@index([capabilityId, status])
}
/// ADR-0024/0027: one immutable authenticated envelope per capability secret
/// version. Same encryption machinery as Provider/Feishu credential versions;
/// the payload inside is CapabilitySecretPayloadV1 (baseUrl, apiToken,
/// optional projectId).
model CapabilityCredentialVersion {
id String @id @default(cuid())
connectionId String
version Int
envelopeVersion Int @default(1)
keyId String
envelope Json
createdByUserId String?
createdAt DateTime @default(now())
retiredAt DateTime?
connection OrganizationCapabilityConnection @relation("capabilityCredentialVersions", fields: [connectionId], references: [id], onDelete: Cascade)
activeFor OrganizationCapabilityConnection? @relation("activeCapabilityCredentialVersion")
createdBy User? @relation("capabilityCredentialVersionCreator", fields: [createdByUserId], references: [id], onDelete: SetNull)
@@unique([connectionId, version])
@@index([connectionId, retiredAt])
@@index([keyId])
@@index([createdByUserId])
}