forked from bai/curriculum-project-hub
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:
@@ -0,0 +1,69 @@
|
||||
-- ADR-0027: org-scoped capability connections for external document/media
|
||||
-- transforms (PDF→MD, audio/video→text, …). Mirrors the Feishu Application
|
||||
-- Connection shape: reuses the ADR-0024 envelope machinery with its own
|
||||
-- payload schema and readiness probe, distinct from the model-provider
|
||||
-- connection.
|
||||
|
||||
CREATE TABLE "OrganizationCapabilityConnection" (
|
||||
"id" TEXT NOT NULL,
|
||||
"organizationId" TEXT NOT NULL,
|
||||
"capabilityId" TEXT NOT NULL,
|
||||
"status" "OrganizationConnectionStatus" NOT NULL DEFAULT 'DRAFT',
|
||||
"activeSecretVersionId" TEXT,
|
||||
"activatedAt" TIMESTAMP(3),
|
||||
"disabledAt" TIMESTAMP(3),
|
||||
"createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
|
||||
"updatedAt" TIMESTAMP(3) NOT NULL,
|
||||
CONSTRAINT "OrganizationCapabilityConnection_pkey" PRIMARY KEY ("id")
|
||||
);
|
||||
|
||||
CREATE UNIQUE INDEX "OrganizationCapabilityConnection_organizationId_capabilityId_key"
|
||||
ON "OrganizationCapabilityConnection"("organizationId", "capabilityId");
|
||||
CREATE UNIQUE INDEX "OrganizationCapabilityConnection_activeSecretVersionId_key"
|
||||
ON "OrganizationCapabilityConnection"("activeSecretVersionId");
|
||||
CREATE INDEX "OrganizationCapabilityConnection_organizationId_status_idx"
|
||||
ON "OrganizationCapabilityConnection"("organizationId", "status");
|
||||
CREATE INDEX "OrganizationCapabilityConnection_capabilityId_status_idx"
|
||||
ON "OrganizationCapabilityConnection"("capabilityId", "status");
|
||||
|
||||
CREATE TABLE "CapabilityCredentialVersion" (
|
||||
"id" TEXT NOT NULL,
|
||||
"connectionId" TEXT NOT NULL,
|
||||
"version" INTEGER NOT NULL,
|
||||
"envelopeVersion" INTEGER NOT NULL DEFAULT 1,
|
||||
"keyId" TEXT NOT NULL,
|
||||
"envelope" JSONB NOT NULL,
|
||||
"createdByUserId" TEXT,
|
||||
"createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
|
||||
"retiredAt" TIMESTAMP(3),
|
||||
CONSTRAINT "CapabilityCredentialVersion_pkey" PRIMARY KEY ("id")
|
||||
);
|
||||
|
||||
CREATE UNIQUE INDEX "CapabilityCredentialVersion_connectionId_version_key"
|
||||
ON "CapabilityCredentialVersion"("connectionId", "version");
|
||||
CREATE INDEX "CapabilityCredentialVersion_connectionId_retiredAt_idx"
|
||||
ON "CapabilityCredentialVersion"("connectionId", "retiredAt");
|
||||
CREATE INDEX "CapabilityCredentialVersion_keyId_idx"
|
||||
ON "CapabilityCredentialVersion"("keyId");
|
||||
CREATE INDEX "CapabilityCredentialVersion_createdByUserId_idx"
|
||||
ON "CapabilityCredentialVersion"("createdByUserId");
|
||||
|
||||
ALTER TABLE "OrganizationCapabilityConnection"
|
||||
ADD CONSTRAINT "OrganizationCapabilityConnection_organizationId_fkey"
|
||||
FOREIGN KEY ("organizationId") REFERENCES "Organization"("id")
|
||||
ON DELETE CASCADE ON UPDATE CASCADE;
|
||||
|
||||
ALTER TABLE "OrganizationCapabilityConnection"
|
||||
ADD CONSTRAINT "OrganizationCapabilityConnection_activeSecretVersionId_fkey"
|
||||
FOREIGN KEY ("activeSecretVersionId") REFERENCES "CapabilityCredentialVersion"("id")
|
||||
ON DELETE RESTRICT ON UPDATE CASCADE;
|
||||
|
||||
ALTER TABLE "CapabilityCredentialVersion"
|
||||
ADD CONSTRAINT "CapabilityCredentialVersion_connectionId_fkey"
|
||||
FOREIGN KEY ("connectionId") REFERENCES "OrganizationCapabilityConnection"("id")
|
||||
ON DELETE CASCADE ON UPDATE CASCADE;
|
||||
|
||||
ALTER TABLE "CapabilityCredentialVersion"
|
||||
ADD CONSTRAINT "CapabilityCredentialVersion_createdByUserId_fkey"
|
||||
FOREIGN KEY ("createdByUserId") REFERENCES "User"("id")
|
||||
ON DELETE SET NULL ON UPDATE CASCADE;
|
||||
@@ -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])
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user