internal/ was 141 packages side by side, so nothing but a reader's memory
said which were foundations and which assembled the rest. Each now sits in a
layer directory, and the directory is the declaration:
base L0 foundation with no domain in it
contract L1 types and interfaces the layers above agree on
model, tools, safety, ext, state, platform
L2 subsystems, peers of one another
runtime L3 the turn engine
session L4 the controller
assembly L5 the composition root
frontend L6 cli, serve, acp and the host adapters
Only paths change: package names, code and behaviour do not. Imports,
repolint and coverage baselines, sensitive paths, CI package lists and docs
follow the new paths; release notes keep the paths they were written with,
and sample paths inside tests and fixtures keep theirs.
repolint gains layer-order: a package may import its own layer and those
below it, read from where it lives. The 47 imports that point upward today
are recorded as that rule's opening debt (-allow-widen, a new rule's first
baseline) and can only go down. Most of it is config, which still reaches
into eight subsystems and is the next thing to take apart; the rest is
event, history and a few tools reaching into runtime for types that belong
in contract.
A runtime could only replace a tool by name, and that slot was never routed
to it, so a plugin that wanted to add one had to ship an MCP server. A
runtime now declares tools in its manifest, under runtime.tools with the
tools capability: a name, a description and an object input schema, known
before the process starts and shown in the install plan and the package
list. At initialize the runtime names the declared tools it serves; one the
manifest does not describe fails the handshake as capability_not_declared.
The model sees each as ext__<plugin>__<tool> and reaches it through the
capability catalog the way it reaches MCP tools, so installing or reloading
a plugin never moves the cached prompt prefix, and every call passes the
permission check under that name. A call is the new host request
extension/tool/call, bounded at five minutes; isError carries a failure the
tool reports about its own work, apart from a call that could not run.
A runtime that failed to start contributes no tools.
The Go SDK serves them from Options.Tools and names them in the handshake.
An effect test drives a call through the real assembly to a fake runtime and
back to the model, and fails with the registration removed.
Both were parsed by pluginpkg and went nowhere, while the docs said they
worked. A package's prompts are now discovered with its commands and invoked
the same way, /<plugin>:<name>, which is what the manifest documented. Its
themes are Studio theme packs: an entry names a pack's theme.json, and the
theme library lists it as plugin:<plugin>:<directory>, read in place from the
plugin root with its own images, never copied into the user's library, and
gone when the plugin is disabled. The retired desktop's .reasonix-theme
archives are not a format Studio reads, and the docs now say so.
The plugin docs are brought in line with the code: the Studio installer takes
a repository address or a folder (a .zip installs through the CLI), the routes
Studio drives replace a list of Wails methods that no longer exist, and the
protocol documents the panel and view surface kinds it already carries.
Problem:
Runtime publish gates, receipts, file priors, message deduplication, and stream cancellation were process-global, so rebuilding one session could drain or overwrite another session's lifecycle evidence. The v2 manifest path also still exposed migration behavior for versioned manifests.
Root cause:
Lifecycle state was wired through package globals instead of the controller/session lineage, and migration/parser compatibility retained assumptions from the unpublished manifest v1 design. Drain cancellation also allowed callbacks to register after a generation had already expired.
Fix:
Introduce an explicit RuntimeOwner carried through boot, controller, provider, UI, host streams, receipts, and file-write compensation. Reuse it only within a rebuild lineage, defer replacement publication until commit, reject draining turns, make late drain registrations cancel immediately, and enforce v2-only versioned manifests while limiting explicit migration to pre-extension manifests without apiVersion.
Verification:
- go test -race ./internal/agent ./internal/boot ./internal/control ./internal/extension ./internal/extension/providerext ./internal/extension/uihub ./internal/tool/builtin -count=1
- go test ./internal/extension ./internal/pluginpkg ./internal/recovery ./internal/agent ./internal/control ./internal/boot -count=1
- go test ./... -count=1 (sdk/go)
- focused Desktop plugin lifecycle tests
Problem:
Sidecar protocol errors could surface credential-shaped peer messages, and stalled optional runtimes could multiply boot latency by the installed package count.
Root cause:
The host preserved JSON-RPC error messages verbatim and started every runtime sequentially with an independent handshake timeout.
Fix:
Redact peer, startup, crash, and boot-warning messages at host boundaries. Start runtime packages with a four-worker pool under one shared 30-second generation budget while preserving deterministic result ordering. Document the lifecycle and performance contract.
Verification:
- focused redaction and bounded-start regressions repeated 10-20 times
- go test -race ./internal/extension/... ./internal/boot ./internal/control ./internal/serve -count=1
- go test ./...
- go test ./... in sdk/go and desktop
- cache guard, site test/build, targeted vet, and protocol generation check
Problem:
Extension Protocol v1 had repository references but no website entry point or copyable installable starter, leaving developers without a clear path from concepts to a working sidecar.
Root cause:
The protocol implementation was not connected to the public discovery surfaces, SDK release guidance, or embedded-doc search contracts.
Fix:
Add bilingual website and README entry points, a buildable Manifest v1 starter sidecar, immutable SDK tag guidance, and regression coverage for the website and embedded docs.
Verification:
- go test ./... -count=1
- go vet ./...
- sdk/go tests, vet, and Windows cross-build
- site npm test and production build
- isolated plugin dry-run, linked install, and doctor
- desktop and mobile browser checks
Problem:
Extension catalog cold reads could issue duplicate concurrent RPCs, observation events could block the Agent behind a wedged sidecar, SDK callback concurrency was implicit, and stable enabled-extension cache behavior had no release guard.
Root cause:
Catalog caching used an unlocked check-then-fetch sequence, event notifications waited for physical writes, and equal host/SDK intercept deadlines could race into different error reasons.
Fix:
Coalesce per-plugin catalog fetches, add a bounded non-blocking notification path that preserves request capacity, freeze SDK timeout classification, document concurrent callbacks, and add real-sidecar p50/p95 benchmarks plus a stable-extension cache guard.
Verification:
go test ./...
go test -race ./internal/rpcwire ./internal/extension/providerext ./internal/extension/dispatch ./internal/extension/sidecar ./internal/boot ./internal/agent ./internal/control
(cd sdk/go && go test -race ./...)
./scripts/cache-guard.sh
go vet ./...
go run ./cmd/extension-protocol-gen -check
Follow-up to stage 7 closing the reviewer-flagged gap between the streaming
provider adapter and any production path.
Problem: sidecar providers merged into a resolver only after the controller
was built, and the merged resolver had no consumer — an extension provider
could not be the initial model, `default_model = "plugin/..."` failed with
unknown model, the CLI/Desktop model pickers enumerated only config
providers, and the stage-7 E2E bypassed the real resolution path.
Fix:
- Preflight extension runtimes before model resolution: sidecars start once
via a single Manager (a build calls StartPackages exactly once), every
pre-ownership error path closes it, and the provider merge (with
provider:<ref> claims from the same manifest data the kernel uses) happens
up front so conflicts fail before anything is built.
- The merged resolver feeds every resolution site: the model entry
(plugin/-namespaced refs only; config models keep their full config entry,
broker stays authoritative), the executor, the dual-model planner, the
guardian, the recovery reviewer, and the subagent provider. Unknown-model
errors list available plugin refs; RequireKey skips plugin refs (no config
credential exists by design).
- Discovery and switching: Controller.ProviderCatalog() on the Capabilities
port; the CLI picker, /model persistence (config.SetDefaultModel accepts
plugin refs), Desktop ModelsForTab/SetModelForTab, and ACP
session/new + SessionConfigState all enumerate and resolve plugin/... refs.
- Tests prove the real paths: first boot with default_model="plugin/..."
streams the fake completion through Controller.RunTurn; unknown plugin ref
wraps ErrUnknownModel and lists plugin refs; builtin->plugin switch via
Rebuild streams from the sidecar with the old runtime alive until closed;
required-preflight failure and unclaimed provider conflicts fail with the
fake PID reaped; a failing new plugin on Rebuild leaves the old controller
and sidecars untouched; CLI/Desktop/ACP discovery and switch coverage.
- Also fixes a merge-blocking AB-BA deadlock the branch exposed:
tool.Registry.ContractEntries held the registry read lock across
lazyTool.ReadOnly() (which takes the lazy-spawn mutex) while a lazy spawn
swap held the mutex and wanted the registry write lock. Tool methods now
run after the lock is released; output unchanged.
Verification: go test ./internal/boot ./internal/cli ./internal/acp
./internal/extension/... and cd desktop && go test . pass;
TestGoldenBaselineNoExtensions green unmodified; both protocol generators
-check green; ./scripts/cache-guard.sh 8/8 pass; go test -race on
internal/boot, internal/tool, and internal/extension/providerext pass;
gofmt/go vet clean; no new dependencies.
Stage 10 of the unified extension kernel / Extension Protocol v1 plan.
- New docs: EXTENSIONS.md/.zh-CN.md (capability map, install/manage,
fail-atomic reload semantics, development guide, compatibility,
full-trust security model) and EXTENSION_PROTOCOL.md/.zh-CN.md (prose
companion to the generated index: transport, lifecycle, content refs,
interception, streaming providers, structured UI, errors, v1 stability
contract, security model).
- Updated docs: PLUGIN_PACKAGES (Manifest v1 chapter: strict parsing,
merge rules, prompts/themes, runtime declaration, FULL TRUST disclosure
and --link trust inheritance), CAPABILITY_DIAGNOSTICS (additive v1
prompts/themes/runtime fields, schema_version stays 1), CLI (/reload),
ACP (_reasonix.io/session/reloadExtensions, extensionSurface
negotiation, /<plugin>:<action> discovery), RELEASING (sdk/go/vX.Y.Z
tag convention, three-product tag contract unchanged), THEME_PACK
(plugin theme kind and fallback-preserve, from stage 4).
- CI: new sdk job on the three-OS matrix (gofmt, vet, stdlib-only guard,
test, race on pushes) triggered by sdk/ or internal/extension/ changes;
root conformance tests run in the existing root matrix.
- Makefile: sdk-test / sdk-test-race targets.
- Bundle budget: initial raw JS+CSS 2250 -> 2265 KiB with a comment
recording the extension UI surface as the cause; every gzip budget
(the user-visible transfer cost) is unchanged and passing.
Compatibility audit (kept green by tests added in stages 1-9): legacy
manifests parse byte-identically, plugin-packages.json schema unchanged,
session JSONL untouched with extension state isolated to
<session>.extensions.json, desktop theme state preserves plugin: IDs
across uninstall while legacy files load unchanged, install-plan JSON is
omitempty-additive, plugin/... refs degrade to model-unavailable on old
versions, and the two new event kinds append at the enum end with
text fallbacks for old clients.
xiexian