Proposal: a design simplification pass: one decision path, one grant, one principal
Maintainers usually reply within 1 day
Nobody has claimed this yet.
Assessment
- Difficulty
- 5/5
- Estimated time
- Over a week
- Newbie friendliness
- 6/100
- Issue type
- Refactor
- Clarity
- Needs clarification
- Activity status
- Active
- Tech stack
- rust
- Domain
- authentication, authorization, backend
Research direction
This is a design decision, not a task: a yes or no from maintainers is needed before any of it is built. Read docs/explanation/design.md and the duplicated gateway tools in wicket-proxy/src/gateway.rs and nodegw.rs to see the overlap. The only parts a newcomer could take are the listed code consolidations, such as RESERVED_METHODS in op.rs, once maintainers approve them.
Written by the indexing model from the issue text.
Description
Proposal. A design simplification pass over the code, the open issues and docs/explanation/design.md, before 0.0.2 grows further. It needs a yes or no before anything here is built. Code facts are from main at e17cca5.
Summary
wicket has grown several mechanisms for the same few ideas. Six primitives cover almost everything:
- One decision path. Only the node decides. The control host is a node and keeps no second decider, proxy set or grant format.
- One grant. Resource × principal × lifetime × amount-or-uses, made by any principal within its own authority. Every approval, lease and quota is one.
- One principal. Humans, agents, programs and nodes have one record, one identity format and one message envelope.
- The harness decides its lifetime. wicket stops ending, pausing and hibernating runs on turn boundaries and timers.
- One workload. A program is an agent with no model that may not ask.
spawn_agent,on_pendingand the overloadedkindgo. - One content-addressed store. Snapshots, bundles, volume snapshots, ledger snapshots and versions are digests in our own format. Approving an artifact is a grant on its digest.
Result: fewer nouns (run, box, activation; lease, grant, block; ask, escalation, queued), one approval flow instead of about six, MCP tools implemented once, and the 0.0.3 pieces that 0.0.2 already depends on pulled forward.
1. One decision path
Today. Every box has two proxy stacks.
run.rs(around 890–935) starts the run's ownEgress,LlmandGatewayonctl/*.sock, deciding through theCentraldecider: compiled zone plus ledger grants.- The node then starts a second set:
NodeDecideron the feed replica,Llm::relayed, and thenodegw.rsgateway.
So there are two decision engines, and grants exist in three forms (ledger rows, feed LiveGrant, Biscuit grant blocks) kept in step by noderun::sync_grants. Gateway tools are implemented twice: wicket-proxy/src/gateway.rs and nodegw.rs (tool, around line 233) both implement whoami, request_access, await_grant, pending_requests, spawn/spawn_agent, send_message and await_message. Spawn is also done two ways: control-host re-exec with --parent-run, and node-side attenuation adopted with --adopt.
Proposal. The node is the only enforcement point, which is what #164 and "the control host is a node like any other" already say.
- The control host's per-run side becomes forward-only: the vault for host-bound secrets, the ledger, approvals and the feed.
- Grants exist as Biscuit blocks delivered by the feed. Ledger rows record issuance; they are not a second copy that decides.
- Each gateway tool and spawn has one implementation, on the node.
This is the largest code item, and it costs a protocol version (handled by #241's jumps). It removes the Central path and most shares_host branches.
2. One grant
Today.
- SPAWN, LINK, CAPACITY and UPDATE requests already share one table on
wicket.internal. That's good. ButRESERVED_METHODS(op.rs:233) lists only SPAWN, LINK and CAPACITY, and UPDATE has its own consumer. - Outside the table:
place create's terminalSpendApprover. #248 just fixed two bugs that existed only because it was a separate flow.- The console's passkey actions.
- Release-key and CI-key acceptance for updates.
- The console's
apply(serve/mod.rs, around 1206) re-implementscmd/approve.rswithout prefix or zone-wide scope, and without the capacity-lease handling (provision on approve, release on deny). - "Lease" means three things in code (capacity leases, budget slices, the feed's
Escalation::Lease) and five in design.md.
Proposal. One grant record, one way to decide it, one decide function shared by the CLI, the console and agents.
- A grant names a resource, a principal, a lifetime (renewable; every grant has one) and an amount or a number of uses.
- What becomes a grant:
- every quota: model budget, money, bytes, children;
- every request kind, including
place create(a CAPACITY request) and UPDATE; - the new kinds now proposed as separate mechanisms: volumes (#251), forks (#177), one approval per push (#26), secret mounts (#36), listeners (#33), network modes (#63), inspection (#34).
- Who may grant is policy on the granter (#50). That replaces "only a human" hard-coded in #33, #36 and #63.
- "Lease" names one thing: a grant of capacity.
3. One principal
Today. Each kind of principal has its own identity and channel.
- Identities: agents carry 10-minute JWS documents, nodes carry certificates, humans are a unix peercred, a passkey or
$USER/WICKET_PRINCIPAL/WICKET_OPERATORstrings, and Remote Control sessions are a claude.ai account. Principals are recorded as free-form JSON. - Two compact-JWS implementations:
wicket-identity(around line 400) andwicket-feed/src/jws.rs. - Messages: humans message with
say(noaccept_fromcheck, its ownoperator_messagestable, written in three places); agents usesend_message.
Proposal.
- A principal record with one identifier format, one JWS module and one envelope for every kind. Only enrolment differs: passkey, node token, issued at spawn.
- Messages address principals (#250), through the gateway protocol (#252), and humans use the same calls from the CLI and console.
saybecomes a message (#198).accept_fromlists principals.- #11 is this primitive. #52 and #53 are formats and enrolment for it.
4. The harness decides its lifetime (#249)
Drop idle_timeout, hibernate_after, the "write result.json when you finish" notice and the §13.2 timer ladder.
- A run ends when its process exits, or at its timeout or the end of its authority.
- Hibernation is the agent's or an operator's request (the gateway already has
hibernate). - A message to a hibernated principal wakes it, so
wakeis not a separate verb and #29's "wake on schedules and events" needs nothing more. - Lifetimes reduce to one renewable authority grant plus a hard timeout.
5. One workload
- Programs:
- a program is an agent without a model;
on_pending: failisrequest: falsefrom #50;- the separate program registry and promotion from §17 aren't needed;
- approving a program is a grant on its digest (primitive 6).
- Spawn:
spawn_agentis a narrowing ofspawn(gateway.rs:349builds aspawnrequest withkind: "agent"). Keep one tool. kind: it means harness in manifests and workload type inspawn. Rename the manifest fieldharness.- Remote Control and
wrapare harness modes, not workload kinds. - Claude specifics move into the Claude adapter (#174):
run.rs's hard-codedclaude-oauthandapi.anthropic.com,state/claude, hibernation'sclaudeprocess list, andwicket.yaml's only setting.
6. One content-addressed store
- One store, our own format. Bundles, named snapshots (#177), volume snapshots (#251), ledger snapshots (#167) and installed versions are blobs and trees by sha256, in our own format, as decided for #195. Caching (#139, #193) and transfer between nodes become properties of the store, not features.
- OCI only for images. #191 is the place for it.
- One rule for "may this digest run". Today the question has four answers: release keys, a human-approved sha256, image pins, and program digests. It becomes a grant on the digest by a principal whose authority covers it. A release key is the CI principal holding a standing grant.
Code consolidations that can start now, whatever the answer
| change | where |
|---|---|
spawn_agent into spawn |
gateway.rs, nodegw.rs |
reap into reconcile (nodes.md already says reconcile subsumes it) |
reap.rs, reconcile.rs |
| one compact-JWS module | wicket-identity, wicket-feed/jws.rs |
console decisions through cmd/approve's function |
serve/mod.rs apply |
UPDATE in RESERVED_METHODS, or a test that request_access can't file one (#117's class) |
op.rs:233 |
one org-entities.json loader (read in three places) |
policy.rs, serve/authority.rs, serve/manifests.rs |
wicket.yaml's single setting into the Claude adapter's config |
settings.rs |
the test-only Replica<ZoneSpec> decide path |
wicket-feed/src/replica.rs |
before 0.0.1 is tagged: compatibility shims for audit chain v1, LEGACY_TRUST_DOMAIN, runs with no node or record (pre-#146/#153), and older-protocol fallbacks. Nothing is released; #241 handles the installed control host's jump. |
store, identity, noderun, nodesrv, llm |
design.md
Fix the contradictions in favour of the decisions above:
- the "Nothing is built yet" header;
- the parent tier "off in v1" (§11, §20) against #50's default-on;
- §13.6 "policy decides; the agent never does" against #249;
- §8.1 "placed through Kubernetes" against #45 having no milestone;
- §20's own capability algebra next to Biscuit.
Then one pruning PR cuts the designed-only subsystems to a line each under "Deferred": the LLM manifest proposer and ratchets, IFC labels and handles (#27 keeps a one-bit flag), separate mandate and program subsystems, the six-cloud HostProvider and attestation levels, service zones, crews, and Kubernetes placement.
Open issues
| fate | issues |
|---|---|
| 2. one grant | #56 grants as leases; #50 escalation rights as policy; #26 one approval per push; #36 secret mounts; #33 inbound listeners; #31 port previews; #63 network modes; #34 read-only inspection; #9 MCP servers per zone; #10 agent-built MCP servers; #54 scoped downstream credentials; #27 taint tracking (one bit) |
| 3. one principal | #11 humans as principals; #52 SPIFFE compatibility; #53 identity from the org's IdP; #250 address principals; #252 agent-to-agent protocol; #197 external MCP control plane; #32 connections carry the caller's identity; #15 RFC 9421 signatures; #14 signed result attestations |
| 4. the harness decides | #249 the harness decides when it's done; #198 ACP sessions replace say; #67 editor front for ACP editors; #22 Remote Control follow-ups; #169 Remote Control in the box; #174 harness adapters. Close #29 (long-lived agents) into #249 and #250 |
| 6. one store | #177 snapshots and forks; #251 shared volumes; #69 attach and detach volumes; #71 gVisor checkpoint and restore; #167 ledger snapshot to the store; #140 bulk data host-side; #191 images by digest. Close #194 (OCI bundles: own format decided), #139 and #193 (caches as a store property) |
| unchanged | #8 move a running agent; #17 node transport; #25 e2e tests in wicket; #35 webhook example; #45 Kubernetes; #47 / #48 / #49 macOS; #61 OpenSandbox; #64 Firecracker; #155 Raft (later, as decided); #165 self-update units; #215 attack matrix; #216 host-side hardening; #236 offline flow failure; #246 CI label race. Close #219 (faster builds) once its last PR lands |
Milestones are inverted. 0.0.2 items depend on 0.0.3 ones: #251 needs #69, #250/#252/#197 assume #11, and #251's grants are #56. I propose pulling the minimal parts of #11 (the principal record), #50 (grant within your own authority), #56 (lifetime and renewal on every grant) and #69 into 0.0.2. The rest of each stays in 0.0.3.
Not changing (decided)
- Cedar stays inside the control plane, compiled into Biscuit at issuance; decisions happen at the edge.
- Nodes keep an in-memory cache of only the secrets they fetched. Boxes stop when their grants expire. Every grant has a lifetime.
- Each node runs its own model proxy and MCP gateway. Model calls run on the Claude Code subscription, never an API key.
- Hibernation keeps our own format with minimal dependencies. Raft waits for later. gVisor is the only isolation tier built.
Order, if yes
- The code consolidations above.
- Primitive 4 (#249) and primitive 5.
- Primitive 2's decide function, and
place createas a CAPACITY request. - Primitive 3's principal record, with #250 and #252 on it.
- Primitive 1's single decision path: one protocol version, behind the jump.
- Primitive 6 alongside #177 and #251.
- The design.md pruning PR, then the issue closes and milestone moves listed above.
- Dominant language
- Rust
- Stars
- 0
- Forks
- 0
- Avg merge
- 1h 43m
- Merged PRs (30d)
- 190
Getting set up
This project ships no dev container, Dockerfile or contributing guide, so setting up is up to you: start from its README, and see our first-contribution guide for the general steps.
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from public/wicket
-
Don't break the machines: node health alerts, admission control, reserved headroom, volume lifecycle, collection trackingPossibly taken @public claimed this today. Openenhancement
Difficulty 5/5 Over a week Newbie friendliness 20/100
Maintainers usually reply within 1 day
-
documentation
Difficulty 3/5 1-2 days Newbie friendliness 55/100
Maintainers usually reply within 1 day
-
enhancement parked
Difficulty 5/5 Over a week Newbie friendliness 12/100
public/wicket#371 · 1 comment ·
Maintainers usually reply within 1 day
-
enhancement
Difficulty 5/5 Over a week Newbie friendliness 12/100
Maintainers usually reply within 1 day
-
Windowed egress caps and standard OTLP decision records (from AgentCore, Strands Box and Dogwood)Openenhancement
Difficulty 5/5 Over a week Newbie friendliness 22/100
Maintainers usually reply within 1 day
Similar issues
-
benchmark-review
Difficulty 2/5 1-3 hours Newbie friendliness 63/100
Maintainers usually reply within 1 day
-
area:filesystem bug need-triage
Difficulty 2/5 1-3 hours Newbie friendliness 85/100
Maintainers usually reply within 1 day
-
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
Maintainers usually reply within 1 day
-
Captions panel does not offer to show an existing transcriptPossibly taken @thedavidweng claimed this today. Open
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
CapSoftware/Cap#4276 · 1 comment ·
Maintainers usually reply within 1 day
-
Difficulty 2/5 1-3 hours Newbie friendliness 76/100
libracoder/kiri#364 ·
Maintainers usually reply within 1 day