None), refuses it, asks a host, caps its output, or
picks the machine that runs it.
Lifecycle
A policy implements any of nine methods: four pairs, pluspre_workspace
on a server. A pre_ method runs before an action; a post_ method runs
after it, with the same context and what came back. A post_ method never
undoes what ran: its Deny or Ask holds back what came back.
TypeScript spells each method in camelCase (
preExecute).
Every entry point reaches the same methods:
Context
Each method gets one argument,ctx: what its method is about, on that
method’s page, plus the session. TypeScript spells the fields in camelCase
(ctx.sessionId). Every ctx carries:
A method only reads. A write it makes through Mirage is refused (
EROFS
for a file, EACCES for a variable), and its reads are not judged again.
The session’s history is /.bash_history, which a method reads through
ctx.vfs like any file.
What the agent controls
Most of actx comes from what the agent did, so a policy reads it as a
claim to check, not as a credential:
The host sets
session_id (caller.session.session_id too), profile,
mounts, prefix and mode, and what vfs shows: the agent cannot
change them from inside the session. Decide who may do what from those, and
from a variable only when the workspace’s or the profile’s env sets it with
readonly: true. session.is_readonly() is also true for a name the agent
marked with readonly NAME itself.
A policy written as a program, on monty or Python on wasm, gets the same
ctx as JSON: see Scripts.
Variables
A variable write reaches no method: a variable does nothing until a command, a file call or a connection uses it, and each of those methods reads the session (ctx.session, and a command’s env), so a rule about
a value goes in the method that uses it.
Answers
TypeScript returns
{ kind: 'deny', reason }, with
path for a path, { kind: 'ask', reason },
{ kind: 'route', machine } and new Limit({ maxLines }). A method that
raises refuses too. What the agent reads for each is on
Explain.
Asks
An Ask records a question in the workspace’s ledger:- With
on_ask(onAsk), an inline allow answer continues the current request; a deny answer refuses it. - Without an inline answer, including when the callback returns no decision, the request returns pending. The host records a decision in the ledger, allowing the caller to retry.
allow, scopeonce(default): the retry runs and spends it.allow, scopesession: everything the ask covers, for the rest of that session.deny: the retry is refused; running it again asks again.
ws.decisions,
mirage workspace allow or
POST /asks/{ask_id}. An Ask from a post_
method comes after the action ran, so nothing is undone: what came back is
held, and the approved retry runs it again.
When answers disagree
- Any Deny beats any Ask, so answering an ask never reopens a refusal.
- The first Deny speaks. The built-ins come first, then the session’s
profile, then its script, then
policies=, thenadd(). - Every Ask is put to the host, and the action runs once all are approved.
- Limits merge to the tightest value of each field.
- Two Routes to different machines refuse the line.
- A policy may give several answers at once, a tuple in Python or an array in TypeScript; each counts as if a policy of its own gave it.