mosaicstack/stack
25
0
Fork 1
Code Issues 413 Pull Requests 13 Actions Packages Projects Releases 15 Wiki Activity

honker: PRD 1.8 draft for Vikunja #434 (mos-1117, sage-1525): trusted actions within role guardrails, the manual-mode action list, grant requests the chief of staff raises and the user approves, the grant methods, the user's tokens, REQ-CRED-4 generalized from row 210, instant revoke, Q188 quoted as the source

Browse Source
This commit is contained in:
jason.woltje
2026-10-20 17:16:42 -05:00
parent 2ad8c4f5b0
commit 3c30f1036a
1 changed files with 228 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
agents/honker/work/queue-194/PRD-1.8-DRAFT.md
+228
View File
@@ -0,0 +1,228 @@
# PRD 1.8 draft: trusted actions within role guardrails, the manual mode, and grants the chief of staff
# requests and the user approves
Draft by Honker for Vikunja #434, under Mos's assignment mos-1117 (through Sage, sage-1525). Not approved.
It changes nothing until Jason approves it as a `prd.approve` decision. Sage opens that decision and sends
Mos its id. Base: `docs/prd/mosaic-stack.md` version 1.6 at 008746b6e, plus the version 1.7 text Jason
approved (PRD-1.7-DRAFT.md r2, 9ba31b5b3, decision d52febb5, mos-1089). Where 1.7 is not yet written into
the PRD file, this draft's anchors name 1.7's sections.
## What it changes
Today an agent acts without a raise only on actions its role file grants within-role, and the role
files grant few. Every other use of a tool or command waits on a decision. Row 210 builds `host.sudo` as a
hard wait, so Jason would decide each command run on another machine. Grants themselves are hand work:
Jason makes every token and key from a runbook (REQ-CRED-1).
Jason's ruling Q188 turns this around. Roles set what each agent may do, and by default agents do it at
will within their sandbox and guardrails. A per-use raise happens only in a manual mode. No agent creates
a grant. The chief of staff brings a grant request to the user's inbox, the user clicks Approve or Deny, and
protected stack code does every step of making the grant. The user's own tokens are entered once in the
WebUI and never reach an agent.
This version adds:
1. Trusted actions within role guardrails as the default mode (REQ-TRUST-1).
2. Manual mode, a list of actions that each need a decision per use: who sets it, where it lives and what
it changes (REQ-TRUST-2).
3. Grant requests, raised only by the chief of staff through the chain of command (REQ-GRANT-1).
4. Approve and the protected grant code, with three grant methods: machine key, Gitea and GitHub
(REQ-GRANT-2).
5. The user's tokens, entered in the WebUI and used only by the grant code (REQ-GRANT-3).
6. Row 210's REQ-CRED-4, generalized from `host.sudo` to every role-listed action that uses a grant
(REQ-CRED-4).
7. Instant revoke (REQ-GRANT-4).
The hard waits stay with the user (Mos, mos-1117): spending money, deleting data, new external accounts,
messages outside the fleet and the rest of REQ-WAIT-1. Approving a grant is the user resolving one of
those hard waits, `credential.mint` and, when the grant makes an account, `account.create`. So no hard
wait moves to an agent.
When this version lands, reviewed commits:
1. add the manual-mode list to the organization file schema, written only on the human's path
(REQ-TRUST-2), and make the broker classify a listed action as needing a decision for each use, before
any other routing.
2. add the grant request: a decision the chief of staff raises with action `credential.mint`, naming the
agent, the method and target, and the exact rights (REQ-GRANT-1). The broker refuses the raise from any
other role.
3. add the grant code that runs on a resolved Approve, one method at a time, and the grant record it
writes (REQ-GRANT-2, Vikunja #435 and #436).
4. add the user's token store, written from the WebUI (or the CLI until the Console knows the signed-in
human) and read only by the grant code (REQ-GRANT-3).
5. move `host.sudo` into both `ROUTED` lists, as row 199 does for `git.push.remote`, and route it under
REQ-CRED-4. Which definitions list it within-role is a separate reviewed role commit in `roles/`.
## Text for the PRD
Status line, appended to the current paragraph:
> Version 1.8 records Jason's ruling Q188 of 2026-10-20: trusted actions within role guardrails by
> default, a manual mode for per-use raises, and grants the chief of staff requests and the user
> approves, approved by Jason in decision <prd.approve decision id>.
Source, a new bullet above "Version 1.7 source":
> - Version 1.8 source, Jason's ruling Q188 (DECISIONS, 2026-10-20), his answers to Q8 and Q10, in part.
> Q8: "I would rather grant the grant right to an agent that runs with strict guardrails. That agent
> presents the final authorization for the user. Upon approval, the grant is created programmatically.
> I see this as: User configures their PATs, API tokens, authorizations within the WebUI. The agent
> presents the request for grant with X rights for another agent. The user reviews, then clicks
> Approve/Deny. Click of Approve fires off protected mechanical methods to handle the grants on Github,
> Gitea, .... services as needed. The tooling would need to exist and must be guarded." And "Disallowing
> the agents to create grants autonomously is a necessary evil for better security. Requiring the user
> to manually perform the steps is a no-fly." Q10: "Agents should have tools and command access based on
> roles. Those roles dictate the allowed tools and commands. The use of a tool or command should not be
> raised to the user unless the system is configured with a manual mode that requires user
> interaction. By default I want to have the agents capable of running commands and tools at will
> within their sandbox/guardrails. This allows autonomous actions by agents within their lanes. Perhaps
> a "Trusted actions within approved guardrails" methodology." And "The main agent or chief of staff
> would be responsible for surfacing the request to the user's inbox for approval. Not all agents are
> capable or authorized to request directly. It must follow the chain of command properly." He agreed
> with Mos's Q10 points 3 to 6: protected stack code does every step on Approve, his tokens are entered
> in the WebUI and agents never see them, a command on the approved list runs without a click and any
> other is refused, and he, Mos or the tester can revoke a grant at once.
Under "Decisions", after REQ-DEC-6, a new section:
> ### Trusted actions
>
> Added in version 1.8 (Q188).
>
> - **REQ-TRUST-1.** Agents act within their role guardrails without asking. The default mode is
> "trusted actions within approved guardrails". An action a role file grants within-role is done at
> will, inside the agent's sandbox, its tool limit and its grants, and is logged. It raises nothing to
> the user. An action the file doesn't grant within-role still routes by REQ-DEC-2, and a hard wait
> still goes to the user (REQ-WAIT-1). Only a reviewed role change adds an action to a role file, and
> REQ-WAIT-2 still keeps every hard wait out of every role file.
> - **REQ-TRUST-2.** The user can put chosen actions in manual mode. The organization file holds the list
> of actions in manual mode, empty by default. While an action is on the list, every use of it by any
> role becomes a decision for that use, raised to the user, and the action waits until the user
> resolves it. A decision denied, or not resolved, refuses the action. Each decision is used once. For a
> command on another host, the decision names the host, the command and its input. Actions not on the
> list are unchanged. Only the user changes the list, through the WebUI or the CLI. The chief of
> staff's organization writes (REQ-ROLE-3) can't change it, and no agent can. Every change is logged
> with who made it. A change applies to the next use, and a run already in progress keeps no
> exemption.
Under "Credentials", after REQ-CRED-3 (version 1.7):
> Added in version 1.8 (Q188):
>
> - **REQ-CRED-4.** An action a role definition lists within-role, and that uses a grant, runs without a
> decision for each use only when all of these hold:
> - the definition declares the credential kind the action uses;
> - a grant names that agent, and that host or service;
> - for a command, the command matches the grant's allowlist. A grant lists exact argv prefixes. A
> wildcard grant is refused;
> - the agent's key or token for that grant is issued and not revoked.
>
> A command off the allowlist is refused, and adding one takes a new grant request (REQ-GRANT-1). An
> action whose definition doesn't list it within-role still needs a decision for each use. Only a
> reviewed role change adds an action to a definition. `host.sudo` routes under this requirement.
> - **REQ-GRANT-1.** No agent creates or writes a grant. A grant request follows the chain of command,
> and only the chief of staff raises it to the user's inbox. Any other role that needs a grant for itself or for an
> agent it directs asks the chief of staff, through its chain: a worker role through its PM, the PM and
> the CTO directly. The assistant passes the user's own request to the chief of staff (REQ-ASSIST-1).
> The request names the agent, the grant method and its target, the exact rights, and a rotate-by or
> expiry date. The chief raises one only for an agent whose reviewed role definition allows that kind of
> credential, and the broker refuses any other. A grant can't name a wildcard, a shell or an empty
> command. The request is a decision with the action `credential.mint`, so it goes to the user as a hard
> wait (REQ-WAIT-1). A request that makes an account, such as a new Gitea user, is also
> `account.create`.
> - **REQ-GRANT-2.** The user approves or denies each grant request in the inbox. Approve is the only thing
> that creates a grant. On Approve, protected stack code does every step, not an agent and not the user:
> it records the grant, makes the key or token, installs it on the machine or creates it on the service,
> and logs each step. On Deny nothing is made, and the denial is logged. The grant methods are:
> - machine key: a key for one agent on one enrolled host, with the command allowlist of REQ-CRED-4. A
> host's identity comes from the host side when the user enrolls it, never from a first connection;
> - Gitea: a token for one agent, with named read or write scopes and an expiry. The all scope and the
> admin scope are never granted;
> - GitHub: a grant for one agent, with the rights unit set by a later design that Jason approves.
>
> The approval binds the exact rights the user saw. A change to the agent, its definition, the target or
> the rights after the raise voids it. An approval is used once. A grant the code couldn't finish undoes
> what it made, and a new grant needs a new approval, never an automatic retry. The grant code runs only
> on a request the user resolved. A request resolved by an arbiter, the tester or any agent makes
> nothing. Until the Console knows the signed-in human, Approve is `mosaic decide` in the CLI
> (REQ-DEC-3).
> - **REQ-GRANT-3.** The user enters their own personal access tokens and API tokens in the WebUI, or the
> CLI. Only the grant code reads them, to make grants. No agent ever sees a token value or a key's
> private half. Values appear in no event, log, message, prompt or agent file, and no agent can read
> them back (REQ-VAR-2). Until the Console knows the signed-in human, they are entered through the
> CLI.
> - **REQ-GRANT-4.** A grant can be revoked at once by the user, the assistant or the tester. A revoke needs
> no decision and no new trust. It takes effect at once on the stack's side, without waiting on the
> network, so the next use is refused. Removing the key or token at the host or service follows. Until
> that removal is done it stays visible as pending. Every revoke is logged with who made it.
REQ-CRED-1, appended:
> Since version 1.8, a token or key made for a grant is made by the grant code on the user's Approve
> (REQ-GRANT-2), not by hand. Tokens that exist stay as they are.
REQ-WAIT-3, appended:
> `host.sudo` was added as a hard wait and routes under REQ-CRED-4 since version 1.8.
Under "Risks and open questions", a new bullet:
> - Trusted mode lets an agent run its allowed commands at will. On another host, an allowed command that
> writes a file as root or starts a shell can plant a key, and the seat sandbox doesn't confine the
> network, so root can outlive the grant and a revoke. The allowlist narrows this. A seat sandbox with
> its own network namespace closes it. Until then the host's own audit log is the check after the fact
> (row 210 design section 6).
## Notes for the reviewer and for Mos
- REQ-TRUST-1 restates what REQ-DEC-2 already does for within-role actions ("routine and within-role
decisions are logged") and names it as the default mode. It grants nothing new by itself. What widens
is the role files, one reviewed commit at a time.
- The hard waits stay with the user (mos-1117). REQ-GRANT-1 makes the grant request a `credential.mint`
decision, already a hard wait under REQ-WAIT-1, so Approve is the user resolving it. REQ-WAIT-2 stands:
no role file grants `credential.mint`. The grant code acts on the user's resolution, not on a role
grant. So 1.8 doesn't change the hard-waits list.
- Manual mode: Sage asked who sets it, where it lives and what it changes. Choices made here, for Mos and
Jason to change: a list of actions in the organization file, empty by default, changed only by the
user, outside the chief's organization writes. A list rather than one switch follows Gizmoduck's #436
draft section 7 (gizmoduck/machine-grant-design f6b6a04b6), so Jason can make host commands manual
without making every action manual. Listing every within-role action gives the whole-organization
manual mode. Row 210's per-call `host.run` decision, bound to host, argv and stdin and spent once, is
this mode's decision for a host command (Q188, Mos's reading).
- Gizmoduck's draft proposes REQ-CRED-5 (section 8) for the machine grant. Its content is in REQ-GRANT-1
to REQ-GRANT-4 here, generalized to all three methods, so 1.8 has no REQ-CRED-5. Their bounds in
gizmoduck-0062 items 4a to 4g are in the text: the chief raises only for an allowed definition, the
approval binds the rights shown, it is used once with no automatic retry, no value is ever seen, revoke
is at once on the stack's side with the host or service removal visible until done, every grant has a
rotate-by or expiry date, and the host identity comes from the host side. Duckworth hasn't reviewed
their draft yet, so a change there may need a change here.
- Approving a grant doesn't by itself let a command run without a click. That needs REQ-CRED-4 and
`host.sudo` in the routed lists, step 5 of "When this version lands" (gizmoduck-0062 item 4i).
- Which roles may request: Q188 says "Not all agents are capable or authorized to request directly. It
must follow the chain of command properly." The text makes the chief of staff the only role that raises,
the PM and the CTO ask it directly, and worker roles ask through their PM. Jason's words also name "the
main agent", but REQ-ASSIST-1 keeps the assistant out of directing agents, so it passes the user's
request to the chief rather than raising one. Mos to confirm.
- REQ-CRED-4 keeps row 210's conditions (origin/gizmoduck/row210-on-199-r2,
agents/gizmoduck/work/queue-210/DESIGN.md:376-392): the definition declares the kind, the grant names
the agent, an exact argv-prefix allowlist with wildcards refused, the key issued, and only a reviewed role
change adds the action. Row 210 put the grant in a hand-edited business file. Under 1.8 the grant is
what Approve records, so "the business file grants that agent that host" becomes "a grant names that
agent and that host".
- Revoke: Q188 says "you, Mos or the tester". Mos is Jason's assistant (REQ-ROLE-4), so the text says the
assistant. If revoke should stay with Mos the seat and not every user's assistant, the line needs a
different name. Mos to confirm.
- Approve in the Console needs the Console to know the signed-in human (Q175 phase 2, #412). Until then
Approve is `mosaic decide`, which REQ-DEC-3 already allows. This draft doesn't take REQ-WEB-2, the id
held for the Console decide buttons amendment (Vikunja 19/266). That amendment, or a later version,
moves Approve into the Console.
- The Gitea unit is the scoped token roles already use (`<read|write>:<category>`, all and admin never
granted, `packages/business/src/vocabulary.mjs:105-106` on origin/refactor). Only the machine key is
designed so far. Gitea and GitHub are a later #436 draft, and minting a Gitea token needs an admin
credential the user enters, which is a design of its own (Gizmoduck's draft section 11). GitHub's
rights unit isn't settled, so the text leaves it to a later design Jason approves. The PRD names
outcomes and checks, not the grant code's steps, as REQ-CRED-3 does.
- Jason expects the inbox Approve and the Gitea and GitHub grants by 10-27 (Q188 point 6). That is a
delivery date, so it is in the source and not in the requirement text.
- This draft follows the PRD's own style: plain words, no semicolons in new sentences, and the status
paragraph never edited in place except to append.