Trusted local provisioning protocol for adopted-principal assistants, MCPs, and skills

[jaaacki]

A0 — Trusted local provisioning protocol for adopted-principal assistants, MCPs, and skills

Parent and authority

• Program epic: sparkfn/pc-client#1082
• Team-definition capability: iOfficeAI/AionCore#798
• This body is the complete protocol/implementation contract. Historical comments and old downstream baselines are non-authoritative.

Current verified baseline — 2026-08-08

• AionCore public main: 560ffb47b1a058413f60941d0cc559738226eb5a.
• AionUi public main: 31ec26a902edf7bdda90026b1f9d6f4d0507b706.
• Installed /Applications/AionUi.app: 2.1.52.
• pc-tools production currently integrates an unversioned internal HTTP surface by spawning a closed-app aioncore --local; sparkfn/pc-tools#643 is removing the unsafe inference that this can represent an adopted/AionPro principal.
• Public AionCore exposes user-owned assistant, MCP, skill, and adoption behavior, but still does not expose a stable conversation-independent, least-privilege external provisioning protocol with attestation, managed provenance, conditional whole-resource reconcile, and exact readback.

Objective

Provide one vendor-supported local provisioning protocol that pc-tools can use for an exact adopted AionUi principal without port discovery, browser/session credential extraction, conversation authority, direct database access, or system_default_user fallback.

Required capability model

Advertise separately scoped, revocable capabilities for:

1. assistant definition/rule/default/placement management;
2. MCP registration/configuration management;
3. skill registration/activation management.

Possession of one scope must not authorize another. A1 Team-definition authority remains separate.

Required scope

1. Stable local discovery/IPC to the correct running or closed installation/profile without caller-provided port.
2. Conversation-independent short-lived authorization and attestation of installation, profile, subject/issuer claims, capability version, AionCore version, and AionUi version.
3. Vendor-native managed provenance that survives restart and compatible upgrade.
4. Conditional/transactional assistant reconcile covering rule, model, permission, thought level, skills, MCPs, and placement as one coherent revision.
5. Conditional MCP and skill reconcile with exact readback and preservation of foreign/user resources.
6. Structured bounded error/reason vocabulary and explicit account-switch, expiry, revocation, restart, running-app, and closed-app behavior.
7. Assistant readback that reports exact Team adjacency or explicit unknown so a Team-referenced assistant cannot be deleted as unreferenced.

Constraints

• Caller cannot select installation/profile/subject/native IDs as authority.
• Account switch exposes a distinct subject and invalidates/blocks old authority; no automatic rebinding.
• Conditional conflict cannot overwrite a concurrent UI edit.
• Failed operations leave the prior coherent resource or an authoritative journal that can safely resume/revert.
• No machine token is sent to AionCore and no vendor credential is placed in AionUi-readable configuration.
• No port scanning, cookies, CSRF, conversation/runtime tokens, direct SQLite/filesystem mutation, or --local fallback.
• Assistant-only authority cannot mutate Teams; Team adjacency must still be readable enough to block unsafe deletion.

Deliverables

1. Versioned protocol and capability specification with schemas, limits, lifecycle, and stable errors.
2. Discovery/IPC, authorization, attestation, managed provenance, conditional reconcile, and exact readback implementation.
3. Unit/integration/concurrency/failure/revocation/account-switch tests.
4. Black-box qualification runner/checklist for downstream pc-tools.
5. Exact minimum supported AionCore/AionUi versions.

Acceptance criteria

• A0-AC1: A non-conversation process reaches the correct installation/profile without caller-provided port or browser/session state.
• A0-AC2: It obtains least-privilege scope and reads exact attested installation/profile/subject before any write.
• A0-AC3: On an adopted AionPro principal, create a disabled managed assistant, write rule and all five axes, verify UI visibility/readback, update, disable, and delete.
• A0-AC4: Concurrent UI edit yields deterministic conflict/transaction outcome and no silent overwrite.
• A0-AC5: Managed provenance survives backend restart and compatible app upgrade.
• A0-AC6: Account switch blocks old subject and exposes a distinct new identity with no rebinding.
• A0-AC7: Expired/revoked/wrong-profile authority returns stable codes and performs zero mutation.
• A0-AC8: Full black-box assistant lifecycle passes on real ordinary-user macOS and Windows second-release upgrade paths.
• A0-AC9: Running-app and closed-app behavior is explicit and never implicitly targets local-default identity.
• A0-AC10: Scoped adopted-principal MCP and skill create/update/read/remove passes; foreign/user state remains unchanged and assistant-only scope cannot invoke it.
• A0-AC11: Assistant readback exposes exact Team references/unknown adjacency and delete refuses a Team-referenced assistant until safe Team removal.

Mandatory negative cases

• Wrong installation/profile/subject fails before write.
• Missing/expired/revoked credentials are not anonymous authority.
• No port scan, cookie/CSRF/runtime-token reuse, direct DB/filesystem write, machine-token forwarding, or system_default_user fallback exists.
• Partial/failed assistant transaction cannot leave a newly enabled hybrid resource or false success.
• Dependency removal cannot delete foreign/user resources or a still-referenced managed dependency.
• Team adjacency cannot be silently omitted or guessed absent.

Dependencies and blocked-work rule

Downstream pc-tools may land dark interfaces/fakes/contracts before A0 closes, but adopted-principal mutation stays off until all A0 acceptance items have native evidence. If work is blocked, keep the issue open and name the exact unmet acceptance ID, completed evidence, dependency, and next executable step; do not propose an unsafe workaround.

Release boundary

Completion authorizes merge consideration only. It does not authorize a release, deployment, promotion, fleet gate, or secret mutation.

[jaaacki]

Status: protocol surface PR #807. Unit/CLI tests green. Native A0-AC3/5/8 black-box still open — do not close until ordinary-user macOS+Windows upgrade evidence.

[jaaacki]

macOS ordinary-user evidence (2026-08-08)

PR head: ba9a314 on #807

Against adopted AionPro install (auth.enc subject attested, not cookie/token):

AC	Status
A0-AC1	macOS pass — provision discover no caller port
A0-AC2	macOS pass — attested subject aionpro
A0-AC3	partial — durable protocol-engine create/readback/delete; not live UI/vendor SQLite
A0-AC4	macOS pass — concurrent conflict
A0-AC5	partial — engine state file survives CLI restart
A0-AC8	open — Windows + second-release upgrade still required
A0-AC11	macOS pass — Team adjacency blocks assistant delete

Issue stays open until Windows + full vendor-path UI black-box.

[jaaacki]

sparkfn stance (pc-client#1082): we are not depending on iOfficeAI merging any PR (including the now-closed #807).

Downstream will:

• treat AionCore/AionUi as a black-box vendor product
• use only what a released install already exposes
• fail dark for adopted/AionPro mutation until a shipped conversation-independent protocol exists in a real app release (no fork, no unmerged PR, no --local/cookie/port-scan workarounds)

#807 was withdrawn. This issue remains a vendor-capability observation only for our program; it is not a sparkfn delivery dependency on a GitHub merge.