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).
Picture the whole framework, then pin the element-kind language layer.
System platform layer — rebuild the semantics likec4 can't draw (ADR-0001..0004):
- Prelude: opaque Identifiers carrier (ProjectId/RunId/SessionId/Principal)
- System/Run: RunState + Terminal subset (set completeness left OPEN, no invented pending)
- System/Lock: lock owner=run (typed), LockTable exclusivity, WellFormed invariant
(a lock holder must be a non-terminal run — couples Lock and Run)
- System/Permission: read<edit<manage role lattice, capability derivation,
can_mono monotonicity theorem; force-release sits outside the lattice (admin-only)
- System/Audit: intentionally thin (mostly plumbing, OPEN)
Courseware product layer — split the single Lesson file into focused modules and
fix doc tautology: Primitives / Element / Lesson / Render / Diagnostic, plus
QuestionBank and Course skeletons (core relations OPEN, not invented).
Diagnostic upgrades WarnsIgnored into a severity-tagged checker rule.
Element schema + rich-content model (ADR-0006, ADR-0007):
- docs/adr/0006: kind schema is declarative JSON Schema; field types are built-in
scalars plus a `content` extension; a `content` value is typst source taken as
module body; rich content must carry a VirtualPath (else click-to-jump and
relative import break — verified against typst source); import boundary =
within the engineering file + @package
- docs/adr/0007: on-disk form is a real directory tree (agent/grep friendly);
VirtualPath = real relative path; layout conventions deferred
- spec/Courseware/RichContent: prose anchor for rich content (opaque VPath,
RichContentRef); ElementData kept abstract — JSON/typst internals are
implementation detail, not contract
lake build green (18 jobs), no sorry, toolchain v4.31.0.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
hongjr03
sjfhsjfh
