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. systemPrompt and request are each the exact bytes the airlock has approved, verbatim; report carries 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.
CutOffReply
The call ran and spent tokens, but text ends before the model was done.
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.
FinishedReply
The model was done: text is its whole reply.
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
What the model said, in reply to one call: 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 result event'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.
ModelUsage
What one model call spent. input, cacheRead and output are what every driver checked so far can report; cacheCreation is null for a driver that can't tell it apart from input (ChatGPT's plan has no such count). contextWindow is the model's own limit, null when the driver can't tell it (ChatGPT's plan doesn't say).
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 Never is 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.example after https://a.example would be a login to evil.example if a path could carry an authority of its own.
WebResponse
The site's response to a Request: status, and either created (the id the destination made of it, when it made one) or refusedBecause (why, in the site's own words, when status was not 2xx).
Wrote
Written; replaced when a file was there before.

Enums

Channel
Method
What a Request asks of its origin.

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
decodeModelUsage(Object? json, [String field = 'modelUsage']) → ModelUsage
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
decodeWebResponse(Object? json, [String field = 'webResponse']) → WebResponse
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?
encodeModelUsage(ModelUsage usage) → 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?
encodeWebResponse(WebResponse response) → Object?
encodeWrote(Wrote wrote) → Object?
isCredentialHeader(String name) → bool
Whether name is 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.

Typedefs

Report = void Function(Progress progress)
Where a driver reports Progress for the action it is carrying out.