For AI agents: the complete documentation index is available at https://a3s-lab.github.io/Use/en/llms.txt, the full documentation bundle is available at https://a3s-lab.github.io/Use/en/llms-full.txt, and this page is available as Markdown at https://a3s-lab.github.io/Use/en/guide/architecture.md.
A3S Use
  • English

      • Architecture

      The target architecture separates package management, workload scheduling, and host rendering. Its most important constraint is: CLI, Web, and agent management MCP must call one shared Plugin Manager instead of implementing separate lifecycles.

           local package          release bundle          TUF registry
           └──────────────────────┬──────────────────────┘
                                  │
                    shared host Plugin Manager
         catalog · policy · confirmation · plan/apply · replay
                                  │ reviewed package input
                                  ▼
                         a3s-use package engine
       verify · stage · receipt · grant · bind · reconcile · drain
                    ┌─────────────┴─────────────┐
                    │                           │
               native plane               cognitive plane
          Runtime Task/Service       MCP · Skill · UI · OKF · context
                    │                           │
                    └─────────────┬─────────────┘
                                  ▼
                 A3S Code · Web · Knowledge · agents

      Ownership

      ComponentOwnsDoes not own
      Umbrella hostRegistry config, trust roots, ACL policy, confirmation, secrets, and Runtime provider compositionPackage storage or a second lifecycle manager
      Shared Plugin ManagerCatalog, policy, plan/apply, operation replay, and parent sagaPackage archive format or provider scheduling internals
      A3S UsePackage verification, immutable generations, receipts, grants, binding evidence, route leases, and capability reconciliationGeneric scheduling, UI rendering, or an agent RPC protocol
      A3S RuntimeTask/Service workloads and provider capabilityPackage parsing, trust roots, or user authorization
      A3S Code/Web/KnowledgeSkill session registry, sandboxed UI, OKF registry/index, and product experiencePackage transactions or Runtime provider registration
      Package processIts own CLI, HTTP, and MCP vocabularyHost policy or ambient authority

      Single sources of truth

      The current implementation reuses these existing mechanisms:

      • a3s-use-core: canonical package/plugin, catalog, plan, permission, grant, release, and OKF bundle contracts;
      • a3s-use-extension: ACL manifests, TUF catalog, package store, receipts, leases, and workspace grants;
      • src/plugin_runtime: Runtime selection, bindings, receipts, invocation, and observation;
      • src/surface_reconciler plus src/capability_registry: dependency readiness and capability publication;
      • the umbrella CLI shared Plugin Manager: the only lifecycle application service.

      Do not add another manager, grant store, Runtime selector, capability registry, or generic execution protocol.

      Host-owned Runtime Broker

      A package may declare workload requirements but cannot select a provider. The host supplies an explicit RuntimeClientRegistry and assignment. Planning performs two deterministic selections:

      1. Before archive download, a signed planning target proves that a compatible provider exists.
      2. After the grant proposal is fixed, the same provider/build/capability evidence binds final semantics.

      If no provider satisfies the request at either stage, planning fails closed. It must not fall back to native execution or another provider. ADR-001 freezes this boundary.

      Why a saga

      Package storage, workspace grants, Runtime, Gateway, projection, and capability publication do not share a database transaction. The complete apply is therefore a durable, idempotent parent saga:

      intent
  → package checkpoint
  → grant checkpoint
  → Runtime checkpoint
  → Gateway checkpoint
  → projection checkpoint
  → capability publication checkpoint
  → old-generation drain checkpoint
  → terminal result

      Each checkpoint uses an operation ID and surface idempotency key. Crash recovery continues from durable intent and the last completed checkpoint. Repeated apply returns the same terminal result without duplicating side effects.

      Runtime visibility

      The Surface Reconciler observes desired state, generation receipt, grants, bindings, Runtime/Gateway health, and Skill/UI/target OKF projection. The Capability Registry publishes a new snapshot only when complete evidence agrees on one generation. Resident hosts can watch generation plus revision and hot-refresh without restarting.

      OKF has a different host boundary from Runtime: it runs no process. Use verifies and records the exact package generation; A3S Knowledge owns conformant atomic promotion, indexing, and cited retrieval. A failed new OKF generation must not replace the last searchable generation.

      Read the full Plugin Platform Architecture.