is_effects library
The shared vocabulary of actions: what reading, writing, starting a program, reaching the world and calling the model take and give back, and the drivers that carry them out.
Tools describe actions in these words, the airlock decides on them, and drivers carry them out. A driver is given only the action's program and input; the trajectory, the decision and what follows stay with the airlock.
Classes
- Args
- What a started program is given. How long it may run, and when it is killed, is the driver's to decide.
- AsksTheModel
-
Calls the model. Holds every model sign-in: the model is outside the
station, so the loop that proposes a call reaches it only through here,
never directly.
systemPromptandrequestare each the exact bytes the airlock has approved, verbatim;reportcarries each ReplyArriving piece as it streams, never recorded, until the whole ModelReply is. - CarriesOutActions
- Operates one part of the world. A machine loads the drivers it can run: a phone's loads no RunsPrograms.
- CarriesOutWebRequests
- Reaches the world: carries out requests. Holds each sign-in's secret and applies it, so the airlock decides a Request without ever seeing one.
- ExecResult
- What a program did once it started: it Exited, or it was Killed.
- Exited
- It ended by itself, with exitCode.
- FileText
- text for the file at path. The driver decides whether it may be written, including whether path must stay within its root.
-
Finished<
O> - The action is over, with outcome; nothing follows it.
- Killed
-
The driver killed it, because why, such as
timed out after 600s; it has no exit code. - ModelName
-
A model this machine can call, by id, such as
claude-opus-5-5. - ModelReply
-
The model's final text, whole: not the transport it arrived in, nor
the pieces streamed beforehand (ReplyArriving, never recorded) —
a driver whose wire is a stream of events gives the one marking the
call as done (such as a
resultevent's own text). Recorded once, as an outcome. - ModelSignInName
-
One of the person's model sign-ins, by name, such as
anthropic-api. Never the secret: the driver holds that, so it reaches neither a tool nor the record. - Origin
-
An http(s) site a Request may be sent to: scheme, host and port only,
with no path, query, fragment or credentials. A rule grants or denies by
comparing one of these with
==, so naming a site covers every request to it. -
Outcome<
O> - What became of an action.
- Printed
- A started program printed text on channel.
-
ProgramMessage<
O> -
What a program driver sends back about one action it was asked to start:
any number of Reported while the action is underway, then one
Finished with an Outcome of
O— an ExecResult for a started program, a ModelReply for a model call. - ProgramName
-
A program this machine can start, by name, such as
git. - Progress
- What a driver reports while an action is underway, before its outcome.
-
Ran<
O> - It ran, and gave output.
- ReadMissing
- No file at the path.
- ReadResult
- What a read found.
- ReadsAndWritesFiles
-
Reads and writes files under its own root. Whether a path may leave that
root — by its text, or by a symlink only the disk can show — is the
operator's choice; this driver is where that choice is enforced, with
isInsideTree. - ReadText
- Refused
-
It did not run: the airlock denied it, the trajectory was stopped, its
driver refused it, or this machine has no driver for its program. An
Outcome of every program, since
Neveris a subtype of every type. - RelativePath
-
A path relative to wherever a driver's root is,
/-separated and normalised. The root itself is the empty path. - ReplyArriving
- A piece of the model's reply as it arrives. Never recorded: only the whole reply, once the call is over, is kept.
-
Reported<
O> - The driver reported progress while the action was underway.
- Request
- Something a CarriesOutWebRequests carries out to origin, reaching the world.
- RunsPrograms
- Runs a program as a process from start to exit (or kill), reporting what it prints as it prints it. How long it may run, and when it is killed, is the driver's.
- SignIn
-
One of the person's sign-ins, by name, such as
some-bot. Never the secret: the driver holds that, so it reaches neither a tool nor the record. - WebPath
-
A path appended to an Origin's address, never able to change which
site is reached:
@evil.exampleafterhttps://a.examplewould be a login toevil.exampleif a path could carry an authority of its own. - WebRequestOutcome
- What a Request did: status, and either created (the id the destination made of it, when it made one) or refusedBecause (why, when status was not 2xx).
- Wrote
- Written; replaced when a file was there before.
Functions
-
decodeArgs(
Object? json, [String field = 'args']) → Args -
decodeExecResult(
Object? json, [String field = 'execResult']) → ExecResult -
decodeFileText(
Object? json, [String field = 'file']) → FileText -
decodeHeaders(
Object? json, [String field = 'headers']) → Map< String, String> -
decodeMethod(
Object? json, [String field = 'method']) → Method -
decodeModelCall(
Object? json, [String field = 'modelCall']) → (ModelSignInName, ModelName, String, String) -
decodeModelName(
Object? json, [String field = 'model']) → ModelName -
decodeModelReply(
Object? json, [String field = 'modelReply']) → ModelReply -
decodeModelSignInName(
Object? json, [String field = 'modelSignIn']) → ModelSignInName -
decodeOrigin(
Object? json, [String field = 'origin']) → Origin -
decodeOutcome<
O> (Object? json, O decodeOutput(Object? json, String field), [String field = 'outcome']) → Outcome< O> -
decodeProgramMessage<
O> (Object? json, O decodeOutput(Object? json, String field), [String field = 'programMessage']) → ProgramMessage< O> -
decodeProgramName(
Object? json, [String field = 'program']) → ProgramName -
decodeProgramToRun(
Object? json, [String field = 'programToRun']) → (ProgramName, Args) -
decodeProgress(
Object? json, [String field = 'progress']) → Progress -
decodeReadResult(
Object? json, [String field = 'readResult']) → ReadResult -
decodeRelativePath(
Object? json, [String field = 'path']) → RelativePath -
decodeRequest(
Object? json, [String field = 'request']) → Request -
decodeSignIn(
Object? json, [String field = 'signIn']) → SignIn -
decodeWebPath(
Object? json, [String field = 'path']) → WebPath -
decodeWebRequestOutcome(
Object? json, [String field = 'webRequestOutcome']) → WebRequestOutcome -
decodeWrote(
Object? json, [String field = 'wrote']) → Wrote -
encodeArgs(
Args args) → Object? -
encodeExecResult(
ExecResult result) → Object? -
encodeFileText(
FileText file) → Object? -
encodeHeaders(
Map< String, String> headers) → Object? -
encodeMethod(
Method method) → Object? -
encodeModelCall(
ModelSignInName signIn, ModelName model, String systemPrompt, String request) → Object? -
encodeModelName(
ModelName model) → Object? -
encodeModelReply(
ModelReply reply) → Object? -
encodeModelSignInName(
ModelSignInName signIn) → Object? -
encodeOrigin(
Origin origin) → Object? -
encodeOutcome<
O> (Outcome< O> outcome, Object? encodeOutput(O output)) → Object? -
encodeProgramMessage<
O> (ProgramMessage< O> message, Object? encodeOutput(O output)) → Object? -
encodeProgramName(
ProgramName name) → Object? -
encodeProgramToRun(
ProgramName program, Args args) → Object? -
encodeProgress(
Progress progress) → Object? -
encodeReadResult(
ReadResult result) → Object? -
encodeRelativePath(
RelativePath path) → Object? -
encodeRequest(
Request request) → Object? -
encodeSignIn(
SignIn signIn) → Object? -
encodeWebPath(
WebPath path) → Object? -
encodeWebRequestOutcome(
WebRequestOutcome outcome) → Object? -
encodeWrote(
Wrote wrote) → Object? -
isCredentialHeader(
String name) → bool -
Whether
nameis a credential header (authorization,proxy-authorization,cookie,x-api-key): a sign-in's secret to add, never a tool's or a renderer's to write into the record. -
validatedHeaders(
Map< String, String> headers) → Map<String, String> -
headers, unmodifiable, or an ArgumentError when one of them is isCredentialHeader: that is a sign-in's secret to add, so it must never be something a tool wrote and the record kept.