Proposal: a design simplification pass: one decision path, one grant, one principal

Open
#253 2 comments 0 reactions 0 assignees View on GitHub

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

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:

  1. One decision path. Only the node decides. The control host is a node and keeps no second decider, proxy set or grant format.
  2. One grant. Resource × principal × lifetime × amount-or-uses, made by any principal within its own authority. Every approval, lease and quota is one.
  3. One principal. Humans, agents, programs and nodes have one record, one identity format and one message envelope.
  4. The harness decides its lifetime. wicket stops ending, pausing and hibernating runs on turn boundaries and timers.
  5. One workload. A program is an agent with no model that may not ask. spawn_agent, on_pending and the overloaded kind go.
  6. 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 own Egress, Llm and Gateway on ctl/*.sock, deciding through the Central decider: compiled zone plus ledger grants.
  • The node then starts a second set: NodeDecider on the feed replica, Llm::relayed, and the nodegw.rs gateway.

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. But RESERVED_METHODS (op.rs:233) lists only SPAWN, LINK and CAPACITY, and UPDATE has its own consumer.
  • Outside the table:
    • place create's terminal SpendApprover. #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-implements cmd/approve.rs without 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_OPERATOR strings, 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) and wicket-feed/src/jws.rs.
  • Messages: humans message with say (no accept_from check, its own operator_messages table, written in three places); agents use send_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.
  • say becomes a message (#198). accept_from lists 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 wake is 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: fail is request: false from #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_agent is a narrowing of spawn (gateway.rs:349 builds a spawn request with kind: "agent"). Keep one tool.
  • kind: it means harness in manifests and workload type in spawn. Rename the manifest field harness.
  • Remote Control and wrap are harness modes, not workload kinds.
  • Claude specifics move into the Claude adapter (#174): run.rs's hard-coded claude-oauth and api.anthropic.com, state/claude, hibernation's claude process list, and wicket.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

  1. The code consolidations above.
  2. Primitive 4 (#249) and primitive 5.
  3. Primitive 2's decide function, and place create as a CAPACITY request.
  4. Primitive 3's principal record, with #250 and #252 on it.
  5. Primitive 1's single decision path: one protocol version, behind the jump.
  6. Primitive 6 alongside #177 and #251.
  7. 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

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from public/wicket

All issues in public/wicket

Similar issues

More Rust issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.