Trusted principal-scoped protocol for unattended Team definition management

[jaaacki]

A1 — Trusted principal-scoped protocol for unattended Team definition management

Parent and authority

• Program epic: sparkfn/pc-client#1082
• Shared discovery/auth/attestation and assistant capability: iOfficeAI/AionCore#795
• This body is the complete Team protocol contract. Teams are separate resources, not assistant metadata.

Current verified baseline — 2026-08-08

• AionCore public main: 560ffb47b1a058413f60941d0cc559738226eb5a.
• AionUi public main: 31ec26a902edf7bdda90026b1f9d6f4d0507b706.
• Installed /Applications/AionUi.app: 2.1.52.
• Current public code confirms user-owned persisted Teams, ordered assistant slots, exactly one leader, distinct slot/conversation IDs, legal duplicate assistant references, team_selectable checks, per-Team membership/session locks, runtime/run/mailbox/task domains, and destructive conversation/resource deletion.
• Existing /api/teams is an application API, not a supported external least-privilege provisioning protocol with managed provenance, expected-revision whole-Team reconcile, and exact resource-disposition readback.

Objective

Provide a separately advertised, adopted-principal, conversation-independent team_definition capability for unattended Team definition create/read/update/delete while preserving Team runtime and user work as unmanaged state.

Managed definition

• stable managed logical Team identity and native provenance;
• name;
• canonical ordered members: leader first, then requested teammate order;
• stable caller logical member_key per slot;
• exactly one leader;
• per-slot display name;
• exact same-principal assistant identity/revision and resulting native assistant ID;
• per-slot model derived from that assistant revision;
• vendor_auto_shared workspace policy only; caller supplies no arbitrary local path.

Explicitly unmanaged

Runtime start/stop, Team runs/turns/messages, tokens, leases, mailbox, tasks, activity, pending confirmations, UI state, arbitrary local paths, and user-selected session mode.

Required scope

1. Separate least-privilege Team-definition scope using A0 discovery/auth/attestation.
2. Conditional whole-Team create/read/update/delete with exact structured readback.
3. Native managed provenance and opaque handles.
4. Exact roster readback including logical/native slot mapping, roles, conversations, assistant IDs, models, workspace result, runtime/work state, and deletion adjacency.
5. Explicit runtime-active/starting/stopping/removing behavior.
6. Explicit member replacement/removal and Team deletion resource-disposition semantics.
7. Stable bounded errors and black-box qualification procedure.

Constraints

• Team-only scope cannot mutate assistants, MCPs, skills, runtime, runs, messages, tasks, mailbox, leases, or session mode.
• Caller cannot select user/installation/profile/subject/native Team/slot/conversation IDs as authority.
• Duplicate assistant refs are legal only with distinct member keys.
• Leader replacement is one explicit conditional definition operation.
• Create must not start or warm runtime.
• Active/indeterminate runtime fails closed by default; unattended provisioning never silently stops user work.
• Failed operations preserve prior coherent definition/conversations or expose an authoritative safe journal.
• Account switch, expiry, revocation, wrong subject, restart, closed app, unsupported version, and downgrade are explicit zero-mutation states.

Deliverables

1. Versioned team_definition protocol/capability specification.
2. Conditional create/read/update/delete and exact readback implementation.
3. Managed provenance and stable opaque handles.
4. Runtime/member replacement/deletion disposition contract.
5. Unit/integration/concurrency/failure tests.
6. Native black-box qualification checklist and minimum versions.

Acceptance criteria

• A1-AC1: A non-conversation process reaches the correct attested principal and obtains Team-only authority.
• A1-AC2: Create an exact Team with duplicate assistant refs in distinct slots, stable ordered member keys, one leader, per-slot native IDs/conversations, and no runtime startup.
• A1-AC3: Invalid leader/key/assistant/principal/revision/native-ID inputs fail before mutation.
• A1-AC4: Rename/reorder/rename-member/add/remove/replace/model-refresh/leader-replace have conditional semantics and exact readback.
• A1-AC5: Concurrent UI/agent/provisioner edits conflict deterministically and never drop a slot or overwrite user work.
• A1-AC6: Active/starting/stopping/removing/unknown runtime is zero mutation unless a proven vendor-atomic safe transition exists.
• A1-AC7: Member replacement/removal reports exact old-conversation disposition; hybrid roster cannot be reported converged.
• A1-AC8: Delete requires exact provenance/revision, verifies Team absence, and reports disposition of every owned conversation/mailbox/task/history resource.
• A1-AC9: Definition operations never create/mutate runs, messages, tasks, mailbox, leases, runtime tokens, session mode, or UI preferences.
• A1-AC10: Provenance and logical-member/native-slot mapping survive restart and compatible upgrade.
• A1-AC11: Account switch, wrong subject, expiry/revocation, unsupported version, closed app, and downgrade are stable zero-mutation results.
• A1-AC12: Full lifecycle passes on real ordinary-user macOS and Windows second-release upgrade paths with adopted principals.

Mandatory negative cases

• Names, positions, prefixes, and native IDs alone cannot identify/adopt/delete Team resources.
• No system_default_user, --local, cookies, conversation/runtime tokens, port scanning, direct DB/filesystem edit, or caller-selected native authority exists.
• Team-only scope cannot mutate assistants/MCPs/skills.
• Runtime uncertainty is never interpreted as idle.
• Delete cannot report success while any required owned-resource disposition is unknown.

Dependencies and blocked-work rule

A0 supplies/shared discovery, auth, attestation, and exact assistant handles. Downstream dark fakes/contracts may proceed, but live Team mutation stays off until all A1 acceptance items have evidence. If blocked, keep the issue open and name the exact acceptance ID and next executable step; do not invent a raw API or local-default workaround.

Release boundary

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

[jaaacki]

Status: Team definition protocol surface in #807. Native A1-AC10/12 still open.

[jaaacki]

macOS Team protocol evidence (2026-08-08)

PR head: ba9a314. Team create with duplicate assistant refs, one leader, idle runtime, disposition on delete, ordered Team-before-assistant removal.

A1-AC12 Windows + second-release upgrade still open. Issue remains open.

[jaaacki]

sparkfn stance: Team unattended provisioning is not gated on an iOfficeAI PR merge. Closed/withdrew #807. Downstream keeps Team mutation dark until a shipped vendor protocol exists in a real AionUi/AionCore release.