Extensions
What is true now about Fiber's extension system. Vocabulary is GLOSSARY.md.
The seams are docs/architecture.md; the runtime choice and its reasoning are
ADR 0006; the trust model is
docs/permissions.md. The measurements behind all of it are in
research/extension-runtime/ and research/extension-process/.
What an extension is
An extension is a package Fiber installs and loads. Its code runs with the
account's full rights. It registers capabilities through the same three seams a
built-in uses — tool, provider and hook — and a registration by an existing
name replaces the built-in, recorded in the session log. An extension that registers a tool named
read becomes the read tool; the loop never learns whether the answer came
from Fiber or from the extension. It can also register watchers, which learn
what happened without changing it, and commands, which a person or a driver
invokes by name.
An extension is meant to build anything a person wants on top of a coding agent: a memory system, a connector to an outside service, a goal that keeps the agent working, a research prototype of a better compaction.
Its code runs in one of two ways, and a package may use both:
- a Lua extension runs Lua 5.4 inside the session's own process, at about 120 to 150 KiB
- a process extension is a separate program in any language, which the session starts and talks to over a pipe
Both register the same things, receive the same calls and have the same host calls, with the same names and meaning. The only difference is what the operating system gives a process directly: files, sockets, timers and any library in its language, npm's included. A package that draws in the terminal also carries a TUI extension ("Commands and screens").
What a package holds
An extension is one directory. Its manifest, extension.json, states
(docs/configuration.md, "An extension's manifest"):
- its name, which is also where it is fetched from (see Names)
- its version
- the lowest Fiber version it runs on
- the extension API version it was written for ("The extension API version")
- the session-half version range the TUI extension works with
(
tui.session_versions) - the other extensions it depends on, each with a minimum version
- the native binaries it ships, if any, with one download URL and one sha256 per platform
- for a process extension, the program to run and its arguments, whether the
session needs it (
required), and how long it may take to finish when the session ends (exit_timeout_ms, no default) - an install step, if it has one, such as
npm ci - the built-in tools and commands it replaces, and the providers it
registers with each one's base URLs (
replacesandproviders).replacescovers the names inBUILT_IN_TOOLS, which are the built-in tools indocs/tools.md, plus built-in commands. An MCP tool ormcp_resourcesis replaced without areplacesentry, by registering its name (docs/mcp.md, "Tools and their names"). An extension that registers a replacement or a provider its manifest does not declare is not loaded for the session, with the noticeextension_failed, and a model whose base URL its provider's entry does not list is left out of the model list. A base URL with a per-account host lists its pattern, such ashttps://{workspace}/ai-gateway/anthropic/v1, and the setting that fills it (docs/model-routing.md, "A per-account host"). So what an install or an offer shows is everything the extension can take over - the commands it registers, each with a description and an optional argument
hint (
commands,docs/configuration.md, "An extension's manifest"). Acommandskey makes the extension lazy: itsinit.luaruns on the first run of one of its commands instead of at session start, and it registers only the commands the manifest declares. Any other registration from a lazy start stops the extension loading with the noticeextension_failed, as a replacement or provider the manifest does not declare does. An extension that also registers tools, hooks, watchers, harnesses or search backends leavescommandsout of its manifest and registers its commands at session start - the files in its data directories whose text goes in the opening message,
and their byte budget (
opening;docs/system-prompt.md, "Extension sections") - the names of the secrets it reads with
host.secret(secrets), whichfiber logincan then store (docs/configuration.md, "Secrets")
Beside the manifest it may hold:
- data, such as a provider's models and flags
- Lua scripts, as many as it needs
- libraries it vendors: a copy of someone else's Lua code, kept inside the extension's own directory
- a process extension's program and its dependencies
- a TUI extension's Lua scripts
- skills, prompt templates and themes, each kind in its own directory
- a prompt file, whose text goes in the system prompt (
docs/system-prompt.md, "Extension texts")
These live in fixed directories at the top of the package, so an author lists nothing in the manifest and an install finds them by looking:
| Directory | Holds |
|---|---|
skills/ | one directory per skill, each with a SKILL.md |
prompts/ | one directory per prompt template, in the same format; every skill here is one only a person runs, as if its header set disable-model-invocation: true |
themes/ | one file per theme; a switched-off extension's themes are not listed or loaded |
tui/ | the TUI extension's Lua scripts, entered at tui/init.lua |
What a skill and a prompt template are, and where Fiber finds them besides
packages, is docs/system-prompt.md, "Skills". A theme sets the terminal's
colours and nothing else (docs/tui.md, "Themes").
A script loads another script with require. require finds files inside the
extension's own directory and nowhere else, so one extension cannot load
another's code by path. Code shared between extensions reaches an extension in
one of two ways: the extension vendors a copy, or it depends on the extension
that holds the code (see Shared dependency modules).
Shared dependency modules
An extension that needs another extension's Lua declares it in depends, a
mapping of each dependency's name to the minimum version it runs with:
"depends": { "example.com/acme/strings": "1.0" }. Installing the
extension installs its dependencies beside it, at the lowest tags that meet
every minimum: Fiber installs nothing newer than someone asked for, and a
dependency's own depends resolves the same way.
A script loads a dependency's module with the dependency's name, a colon, and
the module path: require("example.com/acme/strings:trim"). The module path
works exactly as it does inside the dependency — dots become directory
separators — and everything after the first colon is the path, so a second
colon stays in the module. A name with no colon loads the extension's own
file; a name nobody declared, an empty module, and a leading colon all fail
the same way, naming the unknown dependency. The modules are available from
the moment the extension starts, in a session and in the login-time provider
that asks for credentials.
Each read canonicalizes the dependency's directory and serves only what stays
under it: a link pointing outside the dependency is refused, and a dependency
whose directory is missing names the dependency rather than reaching the file
loader. A repository copy serves its own .fiber-depends before the
personal install, so a copy's dependency answers even when a different
version sits beside it, and a copy whose dependency is missing names it
without reading Fiber home.
The binary for this platform installs as bin/<last segment of the manifest name>: with "name": "github.com/acme/fiber-acme" that is bin/fiber-acme on every platform. A binary installed before this change gets that name at the next fiber extension update. A native binary is run as a process extension, or through host.exec ("Host calls") as host.exec("bin/fiber-acme", args).
Lua extensions
Lua extensions are written in Lua 5.4, embedded through mlua (vendored, so
Fiber's build compiles Lua's C itself and takes no system dependency). The
choice and the alternatives weighed — JavaScript via QuickJS, Luau, Starlark,
WASM, and full TypeScript — are in ADR 0006.
The embedding is bare. An extension sees a stripped standard library — table,
string, math, utf8, coroutine — plus a require limited to its own
directory and its declared dependencies, and nothing else. There is no io, no os, no package, no
debug. Every capability reaches it through a host-provided global, and the
host calls give it what a process has natively: files, programs, HTTP and
timers. Routing them through the host lets Fiber stop them on cancel and at
shutdown, which it cannot do to a blocking C call inside Lua.
This is not a security boundary. Per docs/permissions.md, an extension runs
with the account's full rights; the stripped stdlib is a structural fact — the
host owns I/O — not a sandbox. A hostile extension is contained the way npm install is contained: not at all at runtime, only by the decision to install
it. Trust is resolved when an extension is installed or approved, not while
it runs, and an approval holds only for the exact files approved. How that
works is Distribution.
Process extensions
A process extension is a client of its session with extra rights. It is not
an MCP server: MCP covers tools, questions to a person and model calls, and
has nothing for hooks, watchers, state, providers or commands. An extension
that only brings tools can still ship an MCP server (docs/mcp.md).
The session starts the program with pipes on its stdin and stdout, in the
session's workspace. The pipe carries JSON lines with the event stream's
envelope and schema_version (docs/events.md), and three kinds of traffic:
- what any client gets: the event stream, and the driver commands it may
send (
docs/invocation.md, "Driver commands") - from Fiber: a first message,
extension_hello, with the session's id, why it started (new, resume, fork, rewind or compaction), its workspace, the extension's data directories and its folded state; then each hook, watcher delivery and command as a request the extension answers - from the extension: its registrations, and host calls as requests Fiber answers
The extension's calls are driver commands. A registration, a
hostcall or astatecall is the commandcall, withargs{ "call": "<name>", "args": [ ... ] }: the name as Lua writes it, such asfiber.tool,host.httporstate.set, and the Lua call's arguments as a JSON array. A key whose Lua value is a function, such asrun, a computedeffects, or a provider'ssignorcost, is sent astrue, and Fiber calls it with a request. A call is answered bycommand_accepted, whoseresultis{ "value": <what the Lua call returns> }, withvalueabsent when it returns nothing, or bycommand_rejectedwith thecodeandmessagea Lua call raises. A registration that would fail in Lua is rejected with the message its notice carries.host.after,host.every,host.utf8_lossyandhost.driveare not calls: the program keeps its own timers and sends driver commands directly. The extension ends its registrations with the commandready, which takes noargs. The startup deadline is met whenreadyarrives. A call made while answering a request names it withrequest_idin itsargs. Fiber treats it as made inside that request's callback, with every rule a Lua call in that callback follows: which calls it may make, whatran_bynames, the timeout it counts against, whether a state write goes with a hook's change, and what is cancelled when the callback ends. A call with norequest_idbeforereadyis treated as made while the entry script runs. One afterreadyis treated as made from a timer with no timeout of its own. A call naming a request that is no longer pending, because it was answered, timed out or was cancelled, is rejectedstale_requestand runs nothing. When a request ends, each call still running under it is stopped as the Lua callback's would be, and answeredstale_request.Bytes are base64. JSON strings are text, so every position below that holds bytes in Lua carries them as a string of standard base64, both ways. Every other string is text, as JSON carries it.
Call Bytes positions host.httpopts.body; the result'sbodyhost.oauth.pollbodyhost.execopts.input; the result'sstdoutandstderrhost.fs.readits result host.fs.writethe contents argument host.sha256its argument (the result is hex text) host.hmac_sha256both arguments and the result, so one result passes unchanged as the next call's key A bytes position that is not valid base64 is rejected
invalid_arguments, naming the call and the argument.Functions are requests. A function passed as a value, whether a key such as
run,sign,costor a computedeffects, or a positional argument such ashost.oauth.refresh's, is sent astrue. Fiber calls it with anextension_request. Itskeyis the key's name or, for a positional argument, its 1-based position as a string, such as"1".host.after,host.every,host.utf8_lossyandhost.driveare not calls (above). Thejsonhelpers are available, but are not host calls.JSON is exact. Lua cannot tell an empty object from an empty list (an empty table), and the rule that settles it in Lua ("
json.encode({})is{}") does not apply on the wire. What the extension sends is read as sent, and what Fiber sends is the value as recorded, so{}and[]stay distinct. A whole number Lua requires, such as atimeout, must be a JSON integer, and a fraction there is rejected as it is in Lua.Size. Each line is bounded by the framing cap (64 MiB), counted after base64, which adds a third. A line the extension sends over the cap closes the pipe, as it closes a client's connection, and the extension counts as dead ("One that dies is restarted once"). A result Fiber cannot fit under the cap is answered
command_rejectedtoo_largein place of the result. The call's own limits still apply first, such asstate_too_large.Fiber's requests are lines the extension answers with
reply. Each is an ephemeral line of kindextension_request, whose payload holdsrequest_id,registration(theidof thecallcommand that registered it),key(the function's key, such asrun) andargs(the arguments the Lua function receives, as a JSON array). The extension answers withreply:request_idandresult(what the Lua function returns), orrequest_idanderror,{ code, message }, which fails the call as a Lua error does. Stream items, meaning hooks, watcher deliveries and commands, are sent one at a time, each after the reply to the last one. Tool calls are sent as they arrive, so several can be outstanding. A reply to a request that is no longer pending, such as one past its timeout, is rejectedstale_requestand changes nothing. That is how a late reply is dropped.
extension_hellois the first line Fiber sends, ephemeral, with payload keyssession_id,reason(new,resume,fork,rewind,compaction, orcallfor a provider call outside a session, such as a call case or the credential precheck),workspace(the workspace root),data_dirs({ machine, project }, the pathshost.data_dirreturns) andstate(the extension's folded state, asstate.getreads it). After a restart it is sent again, with the state as it stands in the session. With reasoncall,session_idis absent andstateis{}. The extension hashost.http,host.exec,host.oauth,host.secret,host.data_dir,host.log,host.fsreads, the hashes andjson; any other host call raisesnot_available(<call>: not available here).
Every session starts its own process extensions, a delegate included, as it
starts its own MCP servers. Nothing is shared between sessions
(ADR 0009). They start at session
start, in parallel with MCP servers, and must send their registrations within
the same startup deadline: 5 seconds, which configuration can change per
extension. One that misses it, or fails to start, is left out for the session
and the log records a notice; one marked required makes that fatal, as a
required MCP server does (docs/mcp.md, "Starting servers").
One that dies is restarted once, on its next call. If it dies again it stays
dead for the session: its tools stay declared, so the prompt cache holds, and
every call to them fails with code extension_unavailable. Its hooks then
fail as their on_failure says.
A process extension that misses a hook's timeout is not stopped. The hook has failed ("When a hook fails"), and a late reply is dropped.
A process extension written in Node, Bun or Python costs a runtime: an idle
Node process measured 40 MiB, Bun 20 MiB and Python 10 MiB, against about
120 to 150 KiB for a Lua extension (macOS arm64, research/extension-process/). A
round trip over the pipe took 56 to 79 µs for 16 KiB, against under 10 µs into
Lua. An extension too heavy to run once per session is its author's to make
smaller.
How an extension runs
A Lua VM runs one piece of code at a time, so each Lua extension in a session
has one thread and one inbox, created the first time it is used. A TUI
extension runs on the terminal's own thread instead (docs/tui.md, "How a TUI
extension runs"). Hook calls, watcher
deliveries, command invocations, timer firings and replies to host calls all
arrive there.
Session order is kept. Hooks, watcher deliveries and commands form one stream, in the order they happened in the session. Each finishes, including any host call it waits on, before the next starts, so a hook never sees state that misses an earlier event. Timers are not ordered against the session. They run in the gaps: when the stream is empty, or while its current item waits on a host call. A tool call runs in the gaps, as timers do, so a long tool never holds up the extension's hooks.
A host call that fails raises a Lua error whose value is
{ code, message }, which pcall catches. An uncaught one fails the
callback, and the callback's own failure rule applies. state_too_large and
closing reach Lua this way. host.drive raises the rejection's code and
message on command_rejected, and returns the command's result, or
true, on command_accepted.
A host call suspends the code that made it. Fiber runs every callback as
a coroutine. A host call such as host.http or host.model suspends it until
the reply arrives, and the thread serves other work meanwhile, as await does
in JavaScript. So a timer that polls a slow service does not hold up the
extension's hooks. Code that reads and writes the extension's own globals must
expect another callback to have run in between.
Every callback declares its timeout, with no default. Tools, hooks,
watchers, commands and timers alike. A timeout is in milliseconds, a whole number above
0. No single value fits every callback: a computation needs milliseconds, a
notifier seconds and a test run minutes. A missing timeout fails once, at
registration, with a notice naming it, where a wrong default would fail
quietly: spurious failures when it is too short, a frozen session when it is
too long. A hook's on_failure has no default for the same reason: non-blocking
would let a forgotten guard fail open, and blocking would let a forgotten
notifier stop a session. A hook's clock starts when Fiber asks, so time
spent waiting behind earlier items in the stream counts against it. A callback
past its timeout is stopped ("When an extension misbehaves"). When the interrupt cannot stop the VM, Fiber abandons the VM 1 second after the timeout.
Fiber runs a Lua extension's entry script, init.lua, when it creates the VM.
Reading, compiling and running it is bounded at 2 seconds. A provider file,
providers/<name>.lua, has the same bound, starting when Fiber asks to load it.
These scripts are not callbacks, so they declare no timeout.
A process extension keeps the same order: Fiber sends it the stream's items one at a time and waits for each reply. How it schedules its own timers and background work is up to the program.
Fiber's own Rust code has no async runtime (ADR 0004). An extension's loop runs on the extension's thread, or in its own process.
What an extension can do
A Lua extension reaches everything through three globals: fiber to register,
host for capabilities, and state for its state in the session. A process
extension sends the same calls as messages.
Registering
fiber.tool(name, { description, input_schema, effects, timeout, run, keep? })
fiber.provider(name, { models, quota, credential, sign, cost })
fiber.harness(name, { auto, models, command, line, quota })
fiber.search_backend(name, { timeout, run })
fiber.hook(point, { phase, on_failure, timeout, run })
fiber.watch(kinds, { timeout, run })
fiber.command(name, { description, timeout, run })
fiber.harness is not built yet: see #545.
What a harness declares is docs/delegates.md, "Harness extensions".
A tool's effects is a table, { effects, paths?, reversible, hosts? } as
docs/permissions.md, "Effects", and docs/tools.md, "What a tool declares",
declare, or a function of the call's
arguments that returns one. The function is bounded by the tool's timeout,
and an error fails the call tool_error before it runs. run returns a
string, one text part, or { content, details?, error = { code, message }?, control?, hosts_surfaced? }, where control and hosts_surfaced take what
any tool may set (docs/tools.md, "What a result carries"). A raised error fails the call
tool_error with its message. keep = { head, tail } is the byte counts of the start and
of the end of a long result the model is sent: head maps to Bound.start and tail to
Bound.end. Either may be omitted (0), both are whole numbers, and at least one is above 0.
Absent keep means the first 16 KiB. It is a value, not a function of the call. Any other key,
including start and end, fails registration with a message naming it. A configured tools."<name>".max_result_bytes still wins
(docs/tools.md, "Bounded results"). When two extensions register one tool name,
neither gets it, a notice names both, and configuration can leave one out
(extensions."<name>".tools.disabled, docs/configuration.md).
A search backend's run takes one table, { query } with
allowed_domains or blocked_domains when the call gave one, and returns
a list of { title, url, snippet } results, every field a string. An empty
list is a success; anything else fails the call tool_error, naming the
backend, its extension and the result's position.
A tool, harness, search backend, hook or watcher registers before the
session's tool set is fixed (docs/prompt-cache.md, "Tools"), which is why
every enabled Lua extension with init.lua runs it at session start ("Loading,
and cost when nothing is loaded"), except a lazy extension whose manifest
declares commands: its init.lua runs on the first run of one of its
commands ("Commands and screens"). A provider is the exception: its manifest
declares it, so providers/<name>.lua waits for first use. That file registers
exactly one provider, matching its filename, and nothing else. init.lua holds
the other registrations. A fiber.provider call in init.lua refuses the whole
extension with extension_failed; the message names the provider file it
belongs in. At session start its data is refused with it. In a lazy extension
the call fails the first command's start, every command of the extension
rejects until reload, and its data stays until the next reload or session.
Catching a forbidden or duplicate registration
with pcall still fails the load. After a file finishes loading,
fiber.command, fiber.hook and fiber.provider raise, including from a timer
or callback.
Host calls
host.secret(name) -- the secret stored at credentials/<name>
host.http(opts) -- one HTTP request; returns { status, body }
host.model(opts) -- one model request; returns { text, usage }
host.exec(program, args, opts) -- run a program; returns { exit_code, signal, stdout, stderr }
host.tool(name, args) -- run a tool the session can call; returns its outcome
host.delegate(spec, { timeout, run }) -- start a delegate job; returns its job_id
host.fs.read / write / list / stat / mkdir / remove / rename
host.config.get(key) / host.config.set(key, value, scope) -- scope: "machine" or "project"
host.data_dir(scope) -- "machine" or "project"
host.after(ms, fn, opts) / host.every(ms, fn, opts) -- timers; return a handle with :cancel()
host.drive(command, args) -- send a driver command
host.ask(kind, spec) -- raise an interaction; returns the answer, or declined
host.status(text) / host.widget(id, lines)
host.emit(data) -- data for this extension's own TUI extension
host.log(msg) -- write a diagnostic line (see below)
host.oauth.open(url) -- open the browser at url, and show the URL to copy
host.oauth.show(url, code) -- show the device code to enter at url; opens nothing
host.oauth.callback(opts) -- serve one request on localhost; returns its query parameters
host.oauth.pkce() -- returns { verifier, challenge }
host.oauth.poll(opts) -- poll a device-code token endpoint; returns the token reply
host.oauth.refresh(fn) -- lock the call's stored credential file, re-read it, refresh once
host.sha256(bytes) -- SHA-256; returns hex
host.hmac_sha256(key, bytes) -- HMAC-SHA256; returns raw bytes
host.utf8_lossy(bytes) -- bytes as a string with each invalid UTF-8 sequence replaced by U+FFFD; only codemode's print capture calls it
json.decode(str [, { lenient }]) / json.encode(value) -- JSON, host-provided (Lua has none built in); { lenient = true } escapes raw control characters inside strings, strict stays the default
host.secretreads only a name the manifest'ssecretslists. Any other name is an error in the calling code. A declared secret that is not stored returnsnil, andfiber doctornames it.host.modeltakes a model reference, never a role, an optional system text, messages and a token limit, and returns{ text, usage }:host.model({ model, system, messages, max_tokens }). A message'scontentis a string or content parts (docs/events.md), andusagehas thetokensandcostof itsusage_recorded. It goes through the session's provider routing and credentials, and writesusage_recordednaming the extension. Its prompt-cache key is"{id}:extension:{name}", where{id}is the calling session's own id, a fork's included, so it never shares the session's key or the reviewer's (docs/prompt-cache.md). The retry policy applies within the callback's timeout. Atbudget.usdit raisesbudget_exceededand does not fail the turn. Wrong arguments are an error in the calling code, ashost.tooldocuments for its own:optsmust be a table;modelaprovider/modelreference, never a role;systema string when present;messagesa non-empty list of{ role, content }withroleuserorassistantandcontenta string or a list oftext,imageorpdfparts;max_tokensa positive integer.usage.costis null when the provider knew no cost for the call. Any callback may call it, bounded by that callback's timeout.host.execruns a program in its own process group, which is stopped on cancel and at shutdown as a tool's is (docs/tools.md, "Shell"). Aprogramcontaining/that is not absolute resolves against the extension's directory and must stay inside it; a path that leaves the directory is an error naming the path. A bare name resolves onPATH, and an absolute path is used as written.optstakescwd,env, andinput. The child's working directory is unchanged: the workspace, by default.envis a table of string names to string values added to the inherited environment, overriding a variable of the same name; there is no unset. A name must be non-empty and free of=and NUL, and a value free of NUL.inputis a string streamed to the child's standard input, which closes (EOF) once written; withoutinputstdin stays null.extension_execdoes not log it. Inside a tool call, the tool's declaredexecuteseffect is what the permission decision judges. Outside one, in a hook, watcher, timer, command or provider callback, it runs without asking: the person approved the extension, and a process extension can start programs unseen anyway. Fiber logs each such run asextension_exec(docs/events.md), so the session shows it happened.host.toolruns a tool through the same path a model's call takes, judged at the extension's own tool call ("Running a tool").host.delegatetakes the arguments the model's delegate tool takes and starts a job the session owns, with the same limits and the same stop (docs/delegates.md).job_startednames the extension. The delegate's final message goes torun, not to the model.rungets the message after theafter_toolhooks, as an inner call's output is.speccarries the delegate tool's keys (description,prompt,model, and the optionalisolation,workspaceandtimeout_ms), as a JSON object: an empty table becomes{}, which the service refuses as missingdescriptionandprompt(invalid_arguments); a non-empty list raises the stringhost.delegate:specmust be a table of named argumentsbefore the call yields; a valueto_jsonrefuses raises the stringhost.delegate:specjson: <reason>before the call yields. The second argument is checked like every other registration: it must be a table,timeouta whole number of milliseconds above 0, andruna function, else the call raiseshost.delegate:specmust be a table,host.delegate:timeoutmust be a whole number of milliseconds above 0orhost.delegate:runmust be a function. These are errors in the calling code, raised as strings, before any service call. A refusal from the service reaches Lua aserror({ code, message }): the codes and messages are the start's,depth_exceeded,invalid_arguments,credential_missing,not_availableandtool_error(docs/errors.md). From a command, a hook, a timer or a tool call it starts the delegate; from a watcher, a provider function, a search function or an effects function it raisesnot_available(host.delegate: not available here) and starts nothing. While the entry script runs it raisesclosing. Once the session's end has begun stopping its jobs, on a normal end, a shutdown or a rewind, it raisesclosingand starts nothing. The end wakes nothing and is not shown to the model,jobs listlists the job, anddelegate_messagerefuses it. A reload keeps the delegates running, a removal cancels them, and an abandoned VM's delegates are cancelled. Before the session runs, and after a reload until the new set's hub has its inbox, it raisesclosingwithhost.delegate: the session is not running yet. On every completion (completed,failed,cancelled) the bound extension'srunreceives one table:job_idandstatusalways, plus thedelegate_finishedfields when one was written —text(the bounded final message; the full text stays inartifacts/, never the raw transcript),artifact,questions,usageandworktree, each under itsdocs/events.mdkey name and only when the finish carries it, and no other key. With no finish onlyjob_idandstatus.run's timeout counts from the push of its stream item. Arunthat times out or raises fails as a callback error does: it emitshook_failedwithextensionset. Ajob_completedarriving while a hook is parked waits behind it. A reload keeps the delegates running; the oldrunnever runs, and the finish reaches the reloaded extension asdelegate_finishedthrough a watcher. A set loaded without the extension stops that extension's jobs with norun. Shutdown runs norun. On a normal end Fiber releases the extension-owned ids, then stops them, with norun.host.fsreads and writes anywhere, as a process can. The per-path lock Fiber's own file tools take is offered (docs/architecture.md, "Tool calls in a step").host.configreads and writes the extension's own settings, taking Fiber home's lock before a read-change-write (docs/state.md, "Concurrent access"). A picker that enables models writes its choice here.getreturns the value merged across layers;setwrites the machine or the project file, asscopesays. The files and layers aredocs/configuration.md("Extension settings").host.drivesends any driver command except an answer to an approval or to an offer of a repository's code. An extension never approves a tool call, here or in a hook. An inbox extension usessteerorprompt; a/goalextension may usecancel. This is the extension contract, not a wall: a process extension could open the session's socket as an ordinary client, and the trust model accepts that.host.askraises one of the closed interactions ("Commands and screens"). With nobody to answer, as in a session started byfiber ask, it returns declined.host.oauthis what a provider'scredential()builds an OAuth login from (docs/model-routing.md, "Credentials"). The extension adds its vendor's own steps.host.oauth.refreshtakes the lock on the stored credential,credentials/<credential>/<label>for the provider and label the call was made for, and re-reads it. It callsfnonly if the token still needs refreshing, then stores whatfnreturns, so two sessions never refresh one token twice. A value already expired is refused before anything is stored, by a refresh or a login. Duringfiber loginthere is no file to lock yet, sorefreshholds none:fnseesnil, and what it returns is kept forfiber login, which stores it under the chosen label's lock.callbackserves only itspath, when one is given, and answers any other path with 404 while it keeps waiting.pollwaits through the statuses itspendinglists, as well asauthorization_pending. With nobody attached to answer,open,show,callbackandpollfail withauthentication_failedbefore they open, show, listen or send anything (docs/model-routing.md, "Keys, tokens and OAuth"). Somebody is attached while afullconnection is, asclientscounts them (docs/events.md); asummaryconnection andfiber asknever are. Each helper asks just before it acts.openandshowalso send the URL, andshowthe code, to every attached client as anoticewith codelogin_url, so a person on another machine can finish a device-code login. Acredential()still waiting incallback, or betweenpollrequests, when its timeout passes fails withauthentication_failed.host.sha256andhost.hmac_sha256exist sosign()never needs crypto written in Lua.host.hmac_sha256returns raw bytes because a signing scheme such as AWS SigV4 feeds each HMAC into the next as its key, and hex-encodes only the last.host.logwrites one line to the session's diagnostic log inlogs/(docs/state.md, "What each part holds"), and sends it live to attached clients andfiber askas anextension_logevent (docs/events.md). Fiber records the line as given. People attachlogs/to bug reports, so an extension never logs a secret, a token or a person's content.
Running a tool
host.tool(name, args) runs any tool the session can call: a built-in, an MCP
server's tool or another extension's. It returns the call's outcome: status,
content, artifact, and reason or error when the call did not complete.
It carries no details or changes, which the model never sees. The outcome
reaches the script whole: an inner call bypasses the loop's cut, and the
read tool's own cut does not apply to it, while the outer call's own result
to the model stays bounded (docs/tools.md, "Bounded results"). An inner
shell call also bypasses the shell's spill, so its whole output reaches the
script without a shell artifact. Direct shell calls retain the 1 MiB spill
(docs/tools.md, "Shell", "Result and output"). A call that does not complete is an ordinary return, not a
Lua error, so the extension decides what to do next. A codemode extension is
built on it: the model sends one script, and the script calls tools, filters
their output and returns only what the model needs
(#445).
A call host.tool makes is an inner call. The extension's own tool call
that is running when it makes one is the outer call.
- Admission is the outer call. The outer call declares its effects and is
judged as every call is (
docs/permissions.md, "The order a call is judged in"). A tool whose inner calls cannot be known in advance, such as one that runs a script, declaresexecutes, so the reviewer sees the script. An inner call is not reviewed, raises no standing ask or approval, and counts toward no block budget. - What still applies to an inner call: the credential deny, the person's
standing denies, and every
before_toolandafter_toolhook, in all three phases. A call one of them refuses returnsdeniedwith the reason, so asanitizehook redacts an inner call's output before the script sees it. A command's inner call, or an inner call made inside one, that reaches abefore_tool,checkorafter_toolhook of the command's own extension fails withhook_failed, because that hook would wait behind the command ("How an extension runs");host.toolreturns the failure to the command. - When it may be made: only while one of the extension's own tool calls
is running, or while one of its commands runs ("Commands and screens"),
where the command's invocation is the anchor. A person or a driver invoked
the command, which is the admission. A watcher, a timer or a hook has no
anchor:
host.toolcalled from one is an error in the calling code, which fails as any callback error does ("When an extension misbehaves"). - A tool cannot run itself. A chain of inner calls across extensions, in which A's tool runs B's and B's runs A's, is cut at a depth of 8. That is a starting point, not a measurement. Both are errors in the calling code.
- Each inner call is logged as a call of its own, with its own
action_id:tool_call_requested,tool_call_startedandtool_call_completed, the first carryingran_bywith the extension and the outer call or command (docs/events.md). An inner call is never sent to a provider as one of the model's calls; the model sees only the outer call's result. A later review sees inner calls in its transcript as the agent's actions (docs/permissions.md, "What it is shown"). - An inner call runs inside its outer call. It counts against the outer call's or command's timeout, and cancelling the outer call cancels its inner calls.
host.tool is not a fence. host.exec, host.fs and host.delegate run
with no judgement of their own, inside a tool call or outside one: an
extension has the account's full rights, and a process extension can start
programs unseen
(#39). host.tool exists so
that a well-behaved extension's tool runs get the same denies, hooks and log
as the model's, not to contain an extension.
Code mode
codemode is a first-party Lua extension that registers one tool, codemode,
which runs a Lua script. The script calls tools with host.tool ("Running a
tool"), filters what they return and prints only what the model needs. Every
other tool the session can call is reachable this way: a built-in, an MCP
server's tool or another extension's. Its shipped manifest raises the Lua
memory cap to 16 MiB so an inner result reaches the script whole up to what
fits.
- Input. An object with one required string,
source, the Lua to run:{"source": "print('hi')"}. The script's output is what it passes toprint; a chunk's return value is ignored.host.toolis its only host call. - It is on by default. It is part of a fresh install ("A fresh install") and loads unless switched off. It has a 60 s timeout.
- Three ways to turn it off, each different.
extensions."codemode".enabled = falsestops the extension's parts loading, in every project when set globally or in one project's file (docs/configuration.md, "Keys"). The package stays installed.- The
/toolsswitch turns off thecodemodetool alone, for this project or everywhere, by writingtools.enabledortools.disabled. It takes effect on reload, and the view says what the reload's cache rebuild costs (docs/tui.md, the/toolsentry). fiber extension remove codemodeuninstalls the package.
- What the model gets back. The script's printed lines, then one status
line, then one ledger row per inner call that finished.
- The result is bounded like any other (
docs/tools.md, "Bounded results"): at the 16 KiB default, a cut keeps the first and last 8 KiB, with a notice between them. The status line and ledger rows follow the printed lines, so a long enough print or ledger pushes them into the cut part. The whole output goes to the session'sartifacts/. - The status line is
Script finished, orScript failed: <error>when the script did not load or raised an error. Lines printed before a failure are kept. - A ledger row is
- <tool> <status>: the inner call's tool name and its outcome status. The row adds the inner call'sartifactpath when its outcome carries one, and the job id when adelegate_spawnordelegate_forkcall started a delegate. A call that raised instead of returning leaves no row. An inner call's output reaches the script whole, so a row has a path only when the outcome supplies an artifact, such as one anafter_toolhook wrote; an ordinary uncut call has none.
- The result is bounded like any other (
State
An extension keeps what it knows in four places, by what the thing describes.
| What it describes | Where it lives | A rewind or fork |
|---|---|---|
| What happened in this session: a goal, what an inbox delivered, a test count | extension state, in the session's log | follows the key's fork rule |
| What a person set: enabled models, a workspace URL | host.config, in Fiber home | leaves it alone |
| A secret: an API key | credentials/ (docs/model-routing.md) | leaves it alone |
| What it keeps across sessions: a memory store, an index | its data directories (docs/state.md, "What each part holds") | leaves it alone |
Lua globals are none of these. They are memory, lost when the process exits and never moved by a rewind. Use them for scratch and caches only.
Extension state
state.get(key)
state.set(key, value, { on_fork }) -- on_fork: "at_point" (default), "latest" or "fresh"
state.unset(key)
state.keys()
Keys are strings. state.get returns nil for an absent key.
state.keys returns a Lua array of keys sorted by byte order.
Unsetting an absent key does nothing and logs no line. Invalid arguments,
including a nil value, raise invalid_arguments; use state.unset to remove a key.
- A key holds one whole value. Each
state.setwrites the key's whole new value as JSON, logged asextension_state_set(docs/events.md, "Extensions").state.unsetremoves a key.state.setwithnilis an error, so a missing value is never mistaken for a deletion. - A value is at most 64 KiB. A larger write fails with code
state_too_large. The limit counts serialized JSON bytes. Bigger things go in a data directory. A value nests at most 125 tables deep. - History takes one key per record. A value that grows with the session,
such as one record per turn or per delegate, is written under one key per
record, so no write repeats the ones before it (
docs/events.md, "Writing"). - Fiber folds it. When an extension is loaded into a session, Fiber reads
its latest values from the log and hands them over before its first call,
including before
session_start. The extension never replays the log itself. - The fork rule rides on each write. A fork, a rewind or a delegate's fork
folds its parent's log. For each key, the
on_forkof its last write decides what the new session gets:at_point, its value as of the point;latest, its value at the end of the parent's log;fresh, nothing. For a delegate's fork, the end of the parent's log is the fork's point,forked_from.seq, so the first run and every resume get the same values. A test budget isat_point. A list of files the person already approved islatest. A delegate that is not a fork starts with no extension state. - A hook's writes go with its change. A write made inside a hook is
logged just before the line the hook changed, and is dropped if the hook
fails. A hook that changes no line has its writes logged when it returns,
before whatever it ran for. Any other write takes effect for the extension at once and is logged
at the loop's next drain of its inbox, so a crash before then loses it.
Once
fiber_exitedis written there is no next drain:state.setandstate.unsetfail with codeclosing("When a session ends"). - A compaction keeps it. The session continues, and so does its extension
state. Only the conversation restarts, which
session_startis told ("The hook points").
What writing a provider looks like
A provider extension is mostly data: its name, how its credential is found, and
its models, each with a protocol, a base URL, flags and metadata. The wire
protocols are native Rust, so a provider never parses a stream. What a provider
declares, and why, is docs/model-routing.md. The file is
providers/<name>.json (docs/configuration.md, "A provider's data"). Its Lua
lives beside it in providers/<name>.lua, even when the extension also ships
tools or hooks.
A provider may have five pieces of Lua:
models(), which receives{ key, placeholders }(docs/model-routing.md, "Model discovery") and discovers its models; an entry it deliberately leaves out keeps its place in the list and carriesomit_reasonwith the provider's reasonquota(), which receives{ label, credential, key, token, headers }, wherekeyis the label's key (absent when the provider's token comes fromcredential()), andtokenandheadersare whatcredential()last returned for the label, refreshed as a request's are (absent for a key provider), and reports its quota (docs/model-routing.md, "Quota"):{ windows = { { name, used_percent, resets_at } } }withresets_atin Unix seconds where the vendor reports one,{ credit = { remaining, limit } }withlimitwhere there is one, or nothing when the label reports no quota. Anything else is a failed fetch, reported asunreachable.credential(), which receives{ label, credential }and returns{ token = <string>, expires_at = <Unix seconds> }, and optionallyheaderssent with the token and the login'semail, for a cloud sign-in or an OAuth login (docs/model-routing.md, "Keys, tokens and OAuth")sign(), which adds headers to each request, for a scheme such as AWS SigV4 (docs/model-routing.md, "Signing a request")cost({ generation_id, base_url, key }), which looks up the cost of a call that ended without one (docs/model-routing.md, "Cost")
Each function is { timeout, run }, like fiber.command: timeout in
milliseconds, run the function Fiber calls. Only sign() runs while a
request is being sent. It sees the body's SHA-256, never the body, and the
time in whole Unix seconds as time. A sign()
that errors or returns unusable headers fails the call with credential_failed
(docs/errors.md). Here is providers/acme.lua for a gateway that lists its
models at /models:
fiber.provider("acme", {
models = {
timeout = 10000,
run = function()
local key = host.secret("acme.api_key")
local reply = host.http({
url = "https://api.acme.dev/v1/models",
headers = { authorization = "Bearer " .. key },
})
local list = {}
for _, m in ipairs(json.decode(reply.body).data) do
table.insert(list, {
id = m.id,
protocol = m.id:find("^claude") and "anthropic-messages" or "openai-completions",
base_url = "https://api.acme.dev/v1",
context_window = m.context_length,
})
end
return list
end,
},
})
In plain terms: Fiber calls models.run when it needs the model list. The function
fetches the API key, asks the gateway for its models, and returns one entry per
model, choosing each model's protocol from its name. Fiber caches the list on
disk and refreshes it in the background at startup. The function never runs
while a request is being sent.
The first-party provider extensions are the fuller examples, including
credential() and sign().
Writing a tool or a hook has the same shape: register a name, receive a call, do pure work plus host calls, return. The hook points are Hooks.
Testing an extension
Run fiber extension test in a package directory, or pass the package path.
The runner reads each *.json file directly inside tests/, in filename byte
order. Each file is one case. Its optional name defaults to the file stem.
Each case runs with a fresh Fiber home and workspace.
Before any case, the runner checks each provider that has a providers/<name>.json
file against its Lua. It loads the package in a temporary Fiber home and reads which
functions the provider registered; it calls none of them. If credential() is
registered and the data declares neither login nor credential_label, or if
credential_label is declared and credential() is not registered, the run prints
one fiber: line on stderr for each mismatch, naming the field to add or remove,
runs no case and exits 1. Malformed provider data or a provider script that fails to
load fails the run the same way, with one line. A provider with no data file is
exempt.
Session cases
A session case requires script, expect and exactly one of prompt and
command. script uses the
format in docs/model-routing.md, "The scripted provider". expect lists the
complete ordered durable event stream. Each expected object checks only its
fields, so {"kind":"turn_completed"} checks the event kind. Ephemeral lines
are ignored. Objects match a subset of fields; arrays and scalar values match
exactly. An expected null matches a missing field or a field set to null.
command is an object with name (string, required) and text (string,
optional; omitted is the empty string). The runner sends it as the protocol's
command driver command after extensions_loaded, as a person typing
/name text. A command case requires until and has no default. until
may name an ephemeral kind (extension_ui, notice) with nth. A rejected
command (unknown_command, extension_failed) fails the case with its code
and message. Giving both prompt and command, neither, or a command case
with no until is a malformed case (FAIL <name>, exit 2).
{
"script": {"steps": [{"text": "Hello."}]},
"prompt": "hi",
"expect": [
{"kind": "session_started"},
{"kind": "fiber_started"},
{"kind": "extensions_loaded"},
{"kind": "preamble_built"},
{"kind": "opening_message"},
{"kind": "turn_started"},
{"kind": "step_started"},
{"kind": "assistant_message_started"},
{"kind": "text_completed", "payload": {"text": "Hello."}},
{"kind": "usage_recorded"},
{"kind": "assistant_message_completed"},
{"kind": "turn_completed"},
{"kind": "fiber_exited"}
]
}
A command case names no turn, so its stream has none. The lines below are the
ones docs/events.md proves for a session that runs no turn: session_started
is the log's first line, fiber_started follows it in a new session,
extensions_loaded is written before the first model request, and fiber_exited
is the last line the process writes. That is the whole durable stream the
export command cases observe: no turn runs, so nothing writes between
extensions_loaded and fiber_exited. The expect lists in
extensions/export/tests/export-writes-no-durable-line.json and
extensions/export/tests/export-text-reaches-the-extension.json pin this
order under docs/testing.md, "What a test asserts" ("A test asserts an order
or a count only where a doc promises it"): the promise is expect lists the
complete ordered durable event stream above, and each position is proved by
docs/events.md as the preceding sentences cite.
{
"script": {"steps": [{"text": "unused"}]},
"command": {"name": "export"},
"until": {"kind": "extension_ui"},
"expect": [
{"kind": "session_started"},
{"kind": "fiber_started"},
{"kind": "extensions_loaded"},
{"kind": "fiber_exited"}
]
}
A case may add config, written as the temporary home's global
configuration. A case may add settings, an object keyed by extension name;
each value is written as that extension's global settings file,
config/<extension>.json, in the temporary home (docs/configuration.md,
"Extension settings"). host.http and host.exec list requests and replies in order.
An HTTP reply has status and body, or an error with code and message.
An exec reply has stdout and stderr and either code or signal, an
integer signal number the extension sees as a name such as SIGKILL. A reply
of {"hang": true} stands for a process that never exits: the scripted exec
parks on the case clock until the callback's deadline, as a real host.exec
parks on the injected clock.
Requests match the fields the
case gives; a mismatch, an unscripted call or an unused reply fails the case.
These host replies prevent network requests and program execution.
clock is a list of positive advance_ms values. An entry may use after to
name the event kind and its optional 1-based nth occurrence. An entry may
use hang to name the 1-based exec entry it waits for: the runner holds that
advance until the entry has matched as a hang. The runner
advances only when the operation is parked on that clock deadline. After the
last entry, a hang still parked fails the case, naming the request, and the
runner advances to its deadline to end the session. until
selects the event after which the runner closes the session; for a prompt case,
by default it
closes after the first turn_completed or turn_failed. attended
defaults to true; attended: false runs the session with nobody attached,
as it does for a call case: a call that would escalate to a person is
denied instead ("Testing a tool that executes").
Provider call cases
A call case invokes a provider function without starting a session. It requires
call with provider, function and arg, plus exactly one of returns or
error. The runner supports cost, models, quota, login, credential and
sign. A cost return is null or a finite number at or above 0. models takes {}
with an optional key (a string or null) and an optional placeholders (an object of
strings) as its arg, and its return is the model list, matched as a session case's
expect is: an object checks only the fields it gives, an array matches in
full, and an expected null matches a missing field. An error checks its
code and may also check its message. The case can script the same host
replies as a session case. quota takes {}, with an optional label and
key; its return is null or the table quota() returned, matched as
expect is.
The credential functions take these arguments:
login:{"method":"browser"}or{"method":"device"}, with an optionallabel; returns the logged-in record and stores it under that label, the returned email, ordefaultcredential:{}, with an optionallabel; returns{token, expires_at, headers}from the provider's credential cachesign:{method, url, headers}; signs an empty-body request at the case clock's time, which starts at 1,700,000,000 Unix seconds, and returns the headers the signer adds
credentials maps <credential>/<label> to stored JSON, written before the
first call. expect_credentials checks those files after the calls, using
expect's matching rules. Set exact_credentials to true to compare each
listed file as a whole JSON value instead. In exact mode, extra object fields
at any depth fail, and a missing field differs from a field set to null. The
field defaults to false. A seeded credential listed with its seeded value is
unchanged when its stored value equals the seed; the bytes need not match.
Files not listed in expect_credentials are not compared. attended: false
runs with nobody attached.
Use calls instead of call for an ordered list on one provider instance in
one Fiber home. A case cannot have both. Each entry has call and exactly
one of returns or error. An entry's optional clock advances before its
call. Call clocks cannot use after, because call cases have no event stream.
The case's top-level clock advances while its first call is parked on the
clock deadline, as in a session case.
A calls entry {"await":"credential_idle"} invokes no function. It waits
for the case's pair to finish fetching a credential, with a wall-clock bound.
At the bound the case fails, naming the await. Put it between a sign that
starts a background refresh and a sign that must use the refreshed credential.
host.oauth scripts OAuth calls in order:
{"pkce":{"verifier":"fixed", "challenge":"fixed"}}supplies a PKCE pair{"open":{"url":"https://example.test"}}checks the URL without opening it{"show":{"url":"https://example.test", "code":"1234"}}checks the URL and code{"callback":{"reply":{"query":{"code":"answer", "state":"fixed"}}}}supplies a callback query without listening on a port{"callback":{"error":{"code":"io_failed", "message":"busy"}}}raises the scripted callback error
A mismatch, missing reply or unused OAuth entry fails the case, as for
host.http. Interactive calls still fail when nobody is attached.
{
"call": {
"provider": "openrouter",
"function": "cost",
"arg": {
"generation_id": "gen-abc",
"base_url": "https://openrouter.ai/api/v1",
"key": "sk-test"
}
},
"host": {
"http": [{
"request": {
"method": "GET",
"url": "https://openrouter.ai/api/v1/generation?id=gen-abc",
"headers": {"authorization": "Bearer sk-test"}
},
"reply": {
"status": 200,
"body": "{\"data\":{\"total_cost\":0.0000072}}"
}
}]
},
"returns": 0.0000072
}
A package with no case files fails the command. An invalid package path is a
usage error. The runner reports each case and exits non-zero if any case fails
(docs/invocation.md, "Commands and flags").
Testing a tool that executes
A call to a tool that declares executes goes to the reviewer, as every
reviewed call does (docs/permissions.md, "The reviewer"). A case has no
field that approves a call, so it approves one through configuration:
config sets reviewer.model to scripted/script.json, and the script's
first step carries the reviewer's reply.
A case writes exactly one file into its workspace, the session script, so the
reviewer reads the same script.json from its own step 1. The allow case's
first step therefore carries both halves: "text": "allow" answers the
reviewer's first stage, and the tool_calls entry is the session's call. The
reviewer takes the text and never sees a tool call, because a review request
carries no tools. The expected stream records the reviewer's verdict as
permission_resolved with decided_by: reviewer and decision: allow, and
the call runs to tool_call_completed with status: completed.
With no reviewer.model the call cannot be allowed: a notice with code
no_model is written and the failure escalates (docs/permissions.md,
"How it runs"). The escalation goes to a person as permission_requested,
so a session case with no reviewer waits for an answer instead of finishing.
Where no person can answer, such as a headless run (docs/permissions.md,
"Headless"), the same failure denies the call with decided_by: no_reviewer and it never runs, and tool_call_completed has status: denied.
The reviewer's first stage answers allow or check; a check goes to a
second stage whose reply is a reason followed by allow or block
(docs/permissions.md, "Its verdict"). The case below answers the first
stage with allow.
The launch tool declares executes and returns without a host call:
fiber.tool("launch", {
description = "Launches the job.",
input_schema = { type = "object" },
timeout = 2000,
effects = { effects = { "executes" }, reversible = false },
run = function() return "launched" end
})
tests/launch-allowed.json sets the reviewer through config and expects
the allowed stream:
{
"script": {"steps": [{"text": "allow", "tool_calls": [{"name": "launch", "arguments": {}}]}, {"text": "Launched."}]},
"prompt": "launch it",
"config": {"reviewer": {"model": "scripted/script.json"}},
"expect": [
{"kind": "session_started"},
{"kind": "fiber_started"},
{"kind": "extensions_loaded"},
{"kind": "preamble_built"},
{"kind": "opening_message"},
{"kind": "turn_started"},
{"kind": "step_started"},
{"kind": "assistant_message_started"},
{"kind": "text_completed", "payload": {"text": "allow"}},
{"kind": "tool_call_requested"},
{"kind": "usage_recorded"},
{"kind": "assistant_message_completed"},
{"kind": "usage_recorded"},
{"kind": "permission_resolved", "payload": {"decided_by": "reviewer", "decision": "allow"}},
{"kind": "tool_call_started"},
{"kind": "tool_call_completed", "payload": {"status": "completed"}},
{"kind": "step_started"},
{"kind": "assistant_message_started"},
{"kind": "text_completed", "payload": {"text": "Launched."}},
{"kind": "usage_recorded"},
{"kind": "assistant_message_completed"},
{"kind": "turn_completed"},
{"kind": "fiber_exited"}
]
}
tests/launch-denied.json sets no reviewer and attended: false, so the
same call is denied: no reviewer can be set up and nobody can answer. The
denial is recorded as permission_resolved with decided_by: no_reviewer and
decision: deny, no permission_requested is written, and
tool_call_completed has status: denied:
{
"script": {"steps": [{"tool_calls": [{"name": "launch", "arguments": {}}]}, {"text": "Denied."}]},
"prompt": "launch it",
"attended": false,
"expect": [
{"kind": "session_started"},
{"kind": "fiber_started"},
{"kind": "extensions_loaded"},
{"kind": "preamble_built"},
{"kind": "opening_message"},
{"kind": "turn_started"},
{"kind": "step_started"},
{"kind": "assistant_message_started"},
{"kind": "tool_call_requested"},
{"kind": "usage_recorded"},
{"kind": "assistant_message_completed"},
{"kind": "permission_resolved", "payload": {"decision": "deny", "decided_by": "no_reviewer"}},
{"kind": "tool_call_completed", "payload": {"status": "denied"}},
{"kind": "step_started"},
{"kind": "assistant_message_started"},
{"kind": "text_completed", "payload": {"text": "Denied."}},
{"kind": "usage_recorded"},
{"kind": "assistant_message_completed"},
{"kind": "turn_completed"},
{"kind": "fiber_exited"}
]
}
Hooks
A hook is asked at a fixed point in a session and may change what happens
there. Fiber has eight hook points. Each one runs before the thing it changes
is written to the session log or sent to the model, never after. That one rule
keeps two settled promises: the log holds exactly what happened
(ADR 0001), and no hook
rewrites a message the model has already been sent (docs/prompt-cache.md,
"Rules for other areas").
A hook only changes things. Something that only needs to know what happened,
such as a job that writes a worklog when a session ends, is a watcher: it reads
the event stream (docs/events.md) and has no hook point. How an extension watches is Watchers.
The tool hooks, before_tool and after_tool, run for an extension's inner
calls exactly as for the model's ("Running a tool").
The hook points
| Hook point | When it runs | What the hook sees | What it may return |
|---|---|---|---|
session_start | A session starts, resumes, forks or rewinds, before the first model request; and at each compaction, once the note is ready | why it started, the session's id and workspace root | context to add |
before_message | A person's or a driver's message arrives, as a turn's input or as steering, before it is logged | the message's text and images, and for a session message the sender's id and its parent's id | a replacement message, a refusal with a reason, context to add |
turn_start | A turn has started, before its first model request | the turn's input and what started it | context to add |
before_tool | A call has passed its schema check and its effects function, before permission is decided | the tool's name, the arguments, the declared effects, paths and reversibility | replacement arguments, a refusal with a reason |
before_model_call | A step's model request is built and the budget allows it, before it is sent (docs/loop.md, "Spending budget") | the model reference, and the session's usage so far, its delegates included (docs/events.md) | a refusal with a reason |
after_tool | A call that ran has returned, before its output is cut, its artifact is written or it is logged (a tool that already wrote its output to the call's artifact file has cut it first); and each job delivery, before it joins the conversation or is logged | the tool's name, the arguments, status, the full output, or the cut output with its artifact file's path and size when the tool already wrote that file, details, process, and delivery for a job delivery | replacement content, replacement details, text for the artifact |
turn_end | The model has replied without calling a tool, so the turn would complete, before turn_completed is written | the model's final reply | a message to continue the turn with |
before_compaction | A compaction has started, before the note request | the trigger, the person's instructions, and the conversation as Fiber's messages of content parts, without the note request | a compaction note (a string) |
Returning nothing leaves things as they were.
Context a hook adds is appended to the conversation as its own message and
logged as context_added, naming the extension. An extension that delivers an
inbox of messages from other agents does it this way, at session_start or
turn_start. session_start runs again on every resume, and each time its
context is appended again. The hook sees why the session started, so an
extension that must not repeat itself keeps what it delivered in its
extension state ("Extension state") and adds only what is new.
session_start also runs at every compaction, with reason compaction, so what an
extension adds at start is not lost when the conversation restarts. Extension
state carries across a compaction but the model's context does not, so an
extension that keeps what it delivered sees compaction and delivers it again,
as it is now. The hook sees the reason, as at every other start, and not the
compaction note. Its context follows the new opening message, before the turn's
input and the note (docs/compaction.md, "What the model sees after a
compaction"). A non-blocking hook that fails there has its context dropped with
a notice, and the compaction completes ("When a hook fails"). turn_start does
not run again, because the turn has not restarted.
before_message covers every message a person or a driver sends, so a
secret pasted into a prompt can be removed before anything records it. A
refused message is neither logged nor sent, and the sender is told why.
before_tool may rewrite a call or refuse it, but never approve one.
Approval is the permission decision's (docs/permissions.md). Fiber checks rewritten arguments against the
tool's schema and runs its effects function again, so the permission decision
judges the call that will run, not the one the model asked for. A refused call
completes denied with reason hook and the extension's name, and never
starts.
The model's call is sent back to it exactly as the model wrote it. What ran is
stated in the result instead: Fiber begins the result's content with a line
naming the extension and giving the arguments that ran. That line is part of
content, so the tool's size cap applies to it. Editing the model's own call
would tell the model it asked for something it did not, and a provider that
signs the reasoning before a call may reject the edited request.
before_model_call is where an extension enforces a spending limit, such
as one a central service keeps. A refusal fails the turn with
budget_exceeded, naming the extension, exactly as budget.usd does. It runs
before every step's model request, so it must answer fast: an extension that
reports spend to a service does that from a watcher on usage_recorded
("Watchers"), keeps the service's verdict in its state ("Extension state"), and the
hook only reads it. A reviewer's call, a compaction note request, a
host.model call and a cache-warming refresh (docs/prompt-cache.md,
"Warming while idle") are counted in usage but never reach this hook.
after_tool runs on every call that ran: completed, failed and
cancelled alike, since a cancelled command's partial output can hold a
secret too. It does not run on a call that never started. What the hook
returns is what the rest of the pipeline sees: the size cap applies to the
returned content (docs/tools.md, "Bounded results"), and the artifact holds
the hook's artifact text when it returns one, or the returned output when it
does not, unless the tool already wrote the artifact file, as below. So a redaction hook removes a secret from the model's view and from
disk in one pass, and the original output is never stored.
A foreground shell call whose output passes 1 MiB has already written it to
the call's artifact file (docs/tools.md, "Result and output"), so its
original output is stored until a hook rewrites the file. The hook gets the
cut output, as the model would be sent it, with the file's path and size,
and rewrites the file through host.fs under the per-path lock or returns
artifact text that replaces it, as for an output_file. Every hook in the
chain gets the same path and size. The file is the call's artifact: with
no artifact text returned it keeps what the tool or a hook wrote there, and a
returned content over the cap is cut with a notice naming it.
after_tool also runs on every job delivery: a job's completion notice, each
batch of a monitor's lines, and a delegate's full, unbounded final message (docs/tools.md,
"Background jobs"). It gets the tool name of the call that started the job, and
delivery says what arrived: completion, monitor or delegate. A job
an extension started with host.delegate passes "" as the tool name. When a
job ends, it runs once more on the job's whole output file, with delivery
output_file, and the artifact text it returns replaces the file. A Fiber
delegate's events.jsonl is another session's log, so the output_file pass
skips it. delivery
is absent for an ordinary call. A completion delivery hands the hook, as
content, the notice as the model would be sent it, with the job's status.
An output file of at most 1 MiB is handed as content; a larger one is handed
as path and size, and the hook rewrites it through host.fs under the
per-path lock or returns artifact text that replaces it. When an
output_file hook fails blocking, the file is replaced with a one-line note
that the output was withheld; a non-blocking failure keeps the file and
gives a notice. Apart from that large-file case, a redaction hook can ignore
delivery and treat every input alike, so job output takes the same path as
every other tool output.
Two windows remain: while a job runs, its output file is written directly by
the program, so it holds raw output until the job ends; and a foreground
shell call's artifact file holds raw output past 1 MiB until the hook runs. An extension that
compacts build and test output returns a short summary as content and the
full log as the artifact text. The hook cannot change status: whether a call
succeeded is the tool's answer.
turn_end runs only when a turn would complete normally, not when it is
cancelled or fails. A returned message joins the turn at the step boundary as a
steering message would, and is logged as steering_applied with the extension
as its source. The model then takes another step, and turn_end runs again
when that step ends without a tool call. Fiber puts no limit on how often a
hook continues a turn. An extension that does this should keep its own limit in its extension state,
and a person can always end the turn with the cancel key. A goal that keeps the
agent working until a condition is met is built on this point.
before_compaction lets an extension write the compaction note instead of the
session's own model. When a hook returns a note, Fiber makes no note request.
When none does, Fiber makes its own (docs/compaction.md, "The compaction note").
With several hooks, each sees the note the one before returned, and the last
note wins; compaction_completed.extension names the extension whose note was
used. The hook does not run for a compaction a tool started, which already has
its note. The hook is handed the whole conversation, so a Lua extension that
registers it raises memory_mib to fit the conversations it handles.
What a hook is given and returns
A Lua hook's run gets one table and returns nil or one table, with the
keys below; values use the shapes of docs/events.md ("Content parts",
"Declared effects").
| Hook point | What run is given | What it may return |
|---|---|---|
session_start | reason, why the session started: start, resume, fork, rewind or compaction; session_id; workspace, the workspace root | context, a non-empty string to add |
before_message | content, the message's content parts as logged; from_session_id, the sending session, and parent_session_id, its parent, for a session message, each absent otherwise | content, a non-empty list of parts that replaces the message: text parts, and image or pdf parts the message holds; context, a non-empty string to add; or refuse, a non-empty string, alone |
turn_start | input, the turn's input as the turn_started event logs it | context, a non-empty string to add |
before_tool | tool; arguments; effects, a list of effect names; paths, absent when the call declares none; reversible | arguments, a table that replaces the arguments, or refuse, a non-empty string, alone |
before_model_call | model, the model reference; usage, the session's usage so far, its delegates included, with cost absent when unknown | refuse, a non-empty string, alone |
after_tool | tool; arguments; status; content, the output's text parts joined; details and process, each absent when the call has none; details never hold the reserved file_seen record (docs/tools.md, "Stale files"); what a job delivery is given is in the after_tool paragraph above | content, a string; details, any value; artifact, a string |
turn_end | reply, the model's final reply | message, a non-empty string to continue the turn with |
before_compaction | trigger, what started the compaction: auto, person or overflow; instructions, absent when there were none; messages, the conversation as host.model takes it, without the note request; note, absent until a hook before this one returned one | note, a string with the compaction note |
Returning nil or an empty table changes nothing; so does a before_compaction
note that is empty after trimming. A key a hook returns is a
change, even when its value is the one it was given, so a check hook that
returns arguments, content or context has failed; a check hook refuses
with refuse. Any other key, or a value of another kind, is the hook's
failure, which its on_failure decides ("When a hook fails"). Lua cannot tell
an empty table from an empty list: arguments = {} is an empty object, but an
empty table inside it comes back as a list.
When several hooks share a point
Hooks at the same point run one after another, in three phases. A hook names its phase when it registers:
sanitizemakes the content safe to handle, such as removing a secret or masking personal data. Sanitize hooks run first, so every later hook, including one that calls a network service, sees the cleaned content.transformchanges or adds to it, such as rewriting a call's arguments or adding context. A hook that names no phase is a transform hook.checkrefuses or lets it pass, without changing it. Check hooks run last, so a check judges what will actually happen. A check hook exists only at the points that can refuse:before_message,before_toolandbefore_model_call; one registered at any other point is not registered. A check hook that returns a change has failed, and itson_failuredecides what happens ("When a hook fails").
Within a phase, configuration can set the order of extensions at each hook
point (hooks.order, docs/configuration.md). Extensions it does not name
run after those it does, ordered by name, and one extension's hooks at the
same point and phase run in the order it registered them. Each hook sees what
the one before it returned. A refusal ends the chain. At session_start,
turn_start and turn_end every hook is shown the same input and every
return is kept, in run order. The order is fixed so
that the same inputs give the same result on every run.
The order is precedence, not protection. Every hook runs with the account's full rights, so a hook placed later could read a secret from wherever it came from. Phases exist so that well-meaning hooks run in the right order: a company's redaction hook, shipped with its repository, runs before a person's own notifier sees the text.
When a hook fails
Every hook declares two things when it registers, and neither has a default. A hook that leaves either out is not registered. Its phase is optional ("When several hooks share a point").
-
timeout: how long it may run. Its author knows whether it only computes or calls a web service or a model. Configuration can override the timeout for any extension. A hook past its timeout is stopped ("When an extension misbehaves") and has failed. -
on_failure:blockingornon-blocking. -
non-blocking: if the hook errors or runs out of time, Fiber drops its change, carries on as if it had returned nothing, and gives anoticenaming the extension. A formatter isnon-blocking. -
blocking: if the hook errors or runs out of time, the thing it guards does not happen. A secret scanner isblocking, because carrying on without it would send the secret.
What a blocking failure stops, at each point:
| Hook point | What happens |
|---|---|
session_start | The session does not start. Fiber exits with error hook_failed, naming the extension. |
session_start at a compaction | The compaction completes failed with code hook_failed, as for before_compaction. The session does not exit. |
before_message | The message is neither logged nor sent, and the sender gets hook_failed. |
turn_start | The turn completes failed with code hook_failed, before any model request. |
before_tool | The call completes failed with code hook_failed and never starts. |
before_model_call | The request is not sent, and the turn completes failed with code hook_failed. |
after_tool | The call keeps the status the tool reported, since it ran. Its only content is a line saying its output was withheld because the extension's hook failed, and no artifact is written. A job delivery is withheld the same way. A foreground shell call's artifact file is replaced with the same line, as an output_file is. |
turn_end | The turn completes failed with code hook_failed. |
before_compaction | The compaction completes failed with code hook_failed, as a failed note request does. |
What a hook cannot do
- Change a message the model has already been sent, the system prompt or the tool definitions.
- Approve a tool call, or change a call's
status. - Run during a shutdown. When a signal stops Fiber, no hook runs
(
docs/invocation.md, "Shutdown"). - Run a tool with
host.tool. A hook has no outer call to anchor one ("Running a tool").
Recording a change
The log holds what a hook returned, never what it was given. Each line a hook
changed names the extensions that took attribution for the change in changed_by, so a reader can
see that a message or result was rewritten and by whom (docs/events.md). A change no extension took
attribution for carries no changed_by key.
Handing a value to a hook and taking its answer back is cheap next to the hook's own work. A 16 KiB tool result crosses into Lua and back in under 10 µs, and a 1 MiB one in about 50 µs (macOS arm64, research/hook-conversion-cost).
Hooks declared in configuration
A person can declare a hook or a watcher as a command in configuration,
without writing an extension. The first-party hooks extension,
github.com/aakshintala/fiber/extensions/hooks, reads the declarations and
registers each one as a real hook or watcher, so a declared hook follows every
rule on this page. Installing Fiber installs it ("A fresh install"), and it
loads only in a session whose configuration has a hooks key.
If a person removed hooks and configuration still declares hooks, they are
not silently dropped. When any entry is blocking, a headless run fails with
extension_missing, and the terminal offers to install hooks before the
session starts, so a guard never fails open. When every entry is
non-blocking, the session starts and a notice names the missing
extension. An entry that is not an object fails the session with
config_invalid, naming it, whether or not hooks is installed. When
several entries are malformed, the error names the first in sorted key
order.
The terminal asks in an overlay (docs/tui.md, "Look", "Overlays"): the title "Install hooks?", then "Configuration declares blocking hooks: fiber extension install hooks, then starts the session. When the install fails, no session starts and the overlay is replaced by the failure, naming fiber extension install hooks. When the terminal cannot read the declarations, it shows the refusal without the offer, and no session starts. Esc, the ✕ and a click outside start no session, run no hook point, and show the message the terminal shows without the offer.
The declarations are the extension's settings (docs/configuration.md,
"Extension settings"), under hooks, one entry per name, so each layer adds
entries instead of replacing the list:
{
"hooks": {
"fmt": {
"point": "after_tool", "tools": ["edit", "write"],
"command": "cargo", "args": ["fmt"],
"timeout": 30000, "on_failure": "non-blocking"
},
"main-checked-out": {
"point": "session_start", "command": "scripts/warn-main.sh",
"timeout": 2000, "on_failure": "non-blocking"
},
"done": {
"watch": ["turn_completed"], "command": "notify-send", "args": ["turn done"],
"timeout": 2000
}
}
}
- A hook entry names its
point, itscommandandargs, atimeoutand anon_failure, and may name aphase. An entry missingtimeoutoron_failureis not registered, and anoticenames the entry and the missing field, as for any hook ("When a hook fails"). toolslists exact tool names, with no patterns, on abefore_toolorafter_toolhook. The command runs only for those tools, so a formatter does not start a process on everyread. Withouttools, the command runs for every tool call; an entry whosetoolsis empty is not registered, and anoticenames the entry and the field.- A watcher entry names
watch, the event kinds it wants (docs/events.md), itscommandandargs, and atimeout. It has noon_failure: a watcher changes nothing, so its failure only gives anotice. An entry missingtimeoutis not registered, and anoticenames the entry and the missing field. required, on an entry a repository declares, is a boolean, default false, read only from the repository's file, asmcp.servers."<name>".requiredis for a server. A required entry nobody approved fails a run that has nobody to ask, withhook_unapproved("Code a repository ships"). An approved entry runs from its pinned copy. When that copy cannot be made, arequiredentry stops the session starting, and Fiber exits with errorhook_failednaming it; any other entry is skipped, with anoticewith codehook_failednaming it.- A repository entry with the name of one of the person's. An unapproved repository entry is withheld before the layers merge, so the person's entry of that name runs unchanged. Once approved, it merges key by key like any other layer.
The command runs as host.exec runs a program ("Host calls"): in the
session's workspace, in its own process group, with the session's
environment. The command's program resolves as follows: a bare name on
PATH, a path containing / against the workspace (the command's working
directory), an absolute path as written. The package-relative rule is for
host.exec and process.program only. It runs once for each time its hook point or event comes round.
What the command reads. Standard input carries one JSON line: the table
a Lua hook's run is given at that point ('What a hook is given and returns'),
with point naming the hook point and schema_version, or, for a watcher,
the event.
How the command answers. Standard output may carry, as one JSON line, the table a Lua hook may return at that point. Two shorthands keep a shell script short:
- Exit 0 with plain text on standard output adds the text as context at the
points that take context:
session_start,before_messageandturn_start. Exit 0 with nothing on standard output changes nothing. - Exit 2 refuses, with standard error as the reason, at the points that can
refuse:
before_message,before_toolandbefore_model_call.
Any other exit, exit 2 at a point that cannot refuse, a signal or a timeout is
a failure, which the entry's on_failure decides. A failure is never a pass,
so a blocking guard fails closed. A watcher's answer is ignored.
The extension registers its entries in name order, so declared hooks at the
same point and phase run in name order. hooks.order places the hooks
extension among the others.
A repository may declare hooks in its layer of these settings. Each one runs
only after a person approves it, pinned to its exact content ("Code a
repository ships"); one nobody has approved is withheld from what the
extension reads, so the person's entry of that name runs unchanged. An
approved entry merges key by key in normal layer order: the person's
project and run layers still beat it. A repository cannot set hooks.order
or a hook timeout override, so the order within a phase and every timeout
stay the person's; an entry-local timeout is the hook's own.
A hook's command and args strings that name repository files run from
the pinned copy in Fiber home, never the repository: Inside paths map to
their pinned files, Outside strings (including absolute symlink spellings)
and unmapped names, flags and missing paths stay exactly as written, and
gathered Inside symlink resolutions stay frozen. Only approved entries are
installed, each through a blocking copy that rebuilds a pruned copy; a copy
that cannot be made fails only that hook, classified by the repository's
required. A skipped, unapproved or failed replacement never removes a
running snapshot: only an approved and materialized replacement swaps it,
and the old copy stays held until then. Watchers use the same authorized
mapping and holds. A pinned script runs in the workspace, reads live
workspace files outside its copy, and sees none of its unpinned siblings.
Watchers
A watcher learns what happened in a session and changes nothing. A worklog, a memory written as a session ends, and a counter of test runs are watchers.
A Lua extension registers one with fiber.watch(kinds, { timeout, run }),
naming the event kinds it wants (docs/events.md). A process extension
already reads the whole event stream as a client does, and asks Fiber to send
it the kinds it wants in the stream it answers in order ("How an extension
runs").
A watcher that falls behind loses ephemeral events and never durable ones, as
any watcher does (docs/architecture.md, "Streaming"). A watcher that fails
or passes its timeout gives a notice naming the extension. There is no
on_failure, because a watcher changes nothing.
Commands and screens
fiber.command(name, { description, timeout, run }) adds a command. A person
types /name and any text after it, which reaches run as its arguments. A
driver sends the command driver command (docs/invocation.md). Names are
plain: /databricks-models, not
/databricks:models. When two extensions register the same name, neither
gets it, a notice names both, and configuration can rename one. An
extension may replace a built-in command by name, as it may a tool.
A lazy extension's declared commands appear in the / list and the
commands answer from its manifest, without starting its VM: each entry
carries the manifest's name, description and argument hint, the extension's
name as its tag, and extension set to true, and the manifest's description
and hint win over any in the fiber.command call. A disabled extension lists
none. Configuration's rename (extensions."<name>".commands."<command>",
docs/configuration.md) applies to a declared name. A same-name clash
between two declared commands, or between a declared command and one a
session-start extension registers, follows the rule above: neither gets it,
and a notice names both. The clash resolves when the list is fixed, after
every non-lazy extension has started.
The command driver command is answered with command_accepted once it is
admitted, before run runs, and run's return value is ignored. A command
reports through host.status, host.widget, host.ask or host.emit, and a
run that errors gives a notice naming the extension. A command is allowed
during a turn and joins the extension's ordered stream in session order; a
host.drive inside it follows each driver command's own rules.
Running one of a lazy extension's commands starts the extension first, under
the 2 s init.lua bound ("How an extension runs"); command_accepted still
comes before run runs. A start that fails or passes the bound rejects the
command with extension_failed, and the extension stays unstarted for the
session, as one that fails at session start does; reload tries again
(docs/invocation.md). A declared command the started extension did not
register is rejected extension_failed, naming the command. Concurrent first
runs share one start: later commands wait for it, and there is one VM and
one init.lua run.
host.ask(kind, spec) takes the keys of interaction_requested for that kind
(prompt, options, fields) and returns the answer keys of
interaction_resolved (confirmed, labels, text, answers, note), or
{ declined = true }. When the callback's timeout passes while a host.ask
is pending, the interaction is resolved declined with by fiber. So is a
pending host.ask when the session exits: the VM that waited for the answer
does not survive the exit.
A command may run tools with host.tool. The person or driver who invoked it
is the admission, and each inner call names the command's invocation
("Running a tool"). While a turn runs, a command's inner call starts at the
next step boundary, in the order the calls arrived; a step waiting on an
interaction leaves it queued. The command's timeout covers the wait.
A command talks to the person through the closed interactions every client
answers (docs/architecture.md, "Asking a human"): confirm, select,
multi-select, text input and form, raised with host.ask. A model picker is
a multi-select and a setup wizard is a series of forms. host.status sets one
line of status and host.widget sets a named block of lines. Both are data:
each client shows them or not, and a client that attaches late gets the
latest of each. In a session nobody can answer, such as one started by
fiber ask, host.ask returns declined.
A session never sends drawing code to a client. An extension that draws
carries a TUI extension: Lua 5.4 scripts in its package that run in the
terminal's process, with the same embedding as a Lua extension, and reach the
session only as a client does. It reads the event stream, including its
session half's extension state and what that half sends with host.emit, and
sends driver commands, including its own extension's commands. A crash in a
TUI extension cannot stop the session (docs/invocation.md, "Processes").
A TUI extension registers each slot it fills with fiber.slot(name, { timeout, render, animate, on_key, on_click }), the same shape as
fiber.command above: timeout in milliseconds is required, render draws
the slot, and animate is present only on a slot that animates
(docs/tui.md, "Animation"). A missing timeout fails at registration, as a
missing callback timeout does ("How an extension runs").
on_key and on_click are optional, and each is { timeout, run } with its
own timeout. on_key acts only on a slot that takes focus: the input box, a
view or an overlay. run receives session_id and one of three keys:
{ key = "ctrl+o" } for a named key in the canonical grammar of keys,
{ text = "a" } for typed text, and { paste = "…" } for a bracketed paste
as one event holding the whole pasted text. on_click acts on any slot whose
spans carry click ids, and run receives { session_id = "…", click = "<id>" }. Each returns true when it handled the input, as fiber.key's
run does below. Enter on a click target that has focus in navigate mode
calls on_click as a click does (docs/tui.md, "Input and focus").
on_key, on_click, fiber.key's run and fiber.command's run make no host call: the terminal needs each answer before the next input. A host call from one raises a Lua error.
fiber.on_focus({ timeout, run }) runs run when the session on screen
changes, with { session_id = "…" }, or no session_id key on home. It
runs as an event handler does and may call host.http; any other host call
raises a Lua error, as it does from on_key. Its return value is
ignored. An extension registers it once, and a second call records one
rejection and is skipped.
A TUI extension adds a slash command with fiber.command(name, { description, timeout, run }) in tui/init.lua, and run runs in the
terminal's VM. It receives { session_id = "…", args = "…" }: the session
on screen, with no session_id key on home, and the text after the name,
"" when there is none. Only a true, false or nil return is ignored;
any other value is a wrong-shape failure. run makes no host
call, as the key handler's does not. The terminal shows one
/ list, and a name registered twice, by either half of any extensions,
follows the rule above: neither gets it, a notice names both, and the
configuration rename applies. A TUI command never takes a built-in
command's name, so /quit and /reload stay reachable. Naming one records
one rejection and skips that registration.
An animated slot declares animate = { interval_ms = N }, a whole number of
milliseconds above 0: below 120 ms the terminal fires at 120 ms instead. Any
other shape fails registration, naming the slot. Each frame reaches render
with frame counting in its input, alongside the session id and the width. A
plain list or { lines } keeps animating; { lines, animate = false } draws
once and stops until the input changes. Any other return is the usual
wrong-shape failure, and a frame past its timeout switches the extension off
until /reload, exactly as a still call does.
Whole-screen keys
A TUI extension binds whole-screen keys with fiber.key(name, spec),
registered only while the extension loads, where spec is
{ timeout, run } or { action, variant }. run is a function taking
exactly { session_id = "…" } and returning true when it handled the
key; timeout is its whole milliseconds above 0. action is a built-in
action id with its optional variant, as keys binds them
(docs/tui.md, "Bindings"); clear_then_quit is never bindable. Any
other shape records one rejection naming the offending field, skips that
registration, and loads on. The same canonical names as keys apply:
Ctrl+O reads as ctrl+shift+o with that modifier, while a second
spelling of one key, such as control+o for ctrl+o, is a duplicate and
keeps the first.
A TUI extension has the host calls that need no session: host.http,
host.exec, host.fs, host.config, host.data_dir, host.after,
host.every, host.drive, host.log, the hashes and json. It has no
host.model, host.delegate, host.ask, host.emit or state.set, since
each of those acts inside the session. There is no process TUI extension: a
program that wants to draw everything itself is a separate client of the hub.
What a TUI extension may change on screen is docs/tui.md, "Extension
seams": every slot the terminal draws, the root layout, the key map and the
slash commands. A future GUI's extensions take the same shape.
Client halves
A TUI extension, or any other client's half of an extension, belongs to the client.
- It loads only from the client's own Fiber home, never from a repository: a repository's package brings only its session half ("Code a repository ships"). A remote client could not load one from the session's disk, and a session never sends drawing code.
- One instance serves every session the client shows. Each callback
receives the
session_idit is for (docs/tui.md, "How a TUI extension runs"). - A client half with a session half declares the session-half versions it
works with, as a version range in its package. Each session names the
extensions it loaded, with their versions, in
extensions_loaded(docs/events.md). Where a session has not loaded the session half, or has loaded a version outside the range, the client half is inert for that session: the built-in rendering, and one notice naming the extension and both versions. A client half with no session half, such as a layout or a ledger row for a built-in tool, draws for every session. - Anything Fiber itself needs from a person goes through the contract, so a client without an extension's client half loses decoration, never function.
Loading, and cost when nothing is loaded
Each Lua extension gets its own Lua VM and thread. At session start, every
installed Lua extension with init.lua that is enabled for the project runs it,
except a lazy extension whose manifest declares commands ("Commands and
screens"),
because a tool, hook, watcher, harness or search backend must register before
the session's tool set is fixed (docs/prompt-cache.md, "Tools"), and Fiber
cannot know a non-provider extension's registrations without running it. Each started
extension costs about 120 to 150 KiB and a thread for the whole session. These cost
nothing at start:
- an extension disabled for the project, which never starts;
- an extension with no Lua, only data, skills, themes, prompt templates,
opening-message files or binaries, which starts no VM, such as the
first-party
memoryandinitextensions; - a provider, which its manifest's
providersand its data file declare. Itsmodels(), if it has one, may run at start to refresh a stale model list, and the provider is unloaded once the list is written. Its other Lua functions run only when the session uses one of its models; - the first-party
hooksextension in a session whose configuration has nohookskey ("Hooks declared in configuration"); - an extension whose only Lua registrations are declared commands, which starts on the first run of one of them ("Commands and screens").
A provider-only package starts no VM until its provider file is needed. First
use loads the file into the extension's running VM, or creates one when none
runs. Providers in one extension share that VM. Model discovery on a missing
or stale list uses the same path; its VM is dropped after discovery unless
another provider or the extension's hooks, tools or commands still hold it.
Fresh cached lists are read without loading provider Lua and show models
only for providers with credential presence (docs/model-routing.md,
"Credentials"). Providers without presence never run discovery. A cached list
is stale when its age is past model_cache_age or its provider's extension
source is newer than the cache; equal source and cache mtimes read fresh, and
an unreadable source reads stale. The cache-side time is reconstructed as the
current time minus the cached age (cached_at); a source newer than cached_at
is stale, regardless of whether it is future-dated relative to now. Provider data
and credentialed discovery ignore extensions."<name>".enabled; in a disabled
mixed package, init, commands and hooks still stay off, even when its provider
Lua starts later.
A provider file runs at most once per VM, including when it fails. A load that
expires while still queued has not run and can be retried. Pending loads run
before queued jobs. A load error, wrong or missing registration, or the 2 s
bound fails first use with extension_failed, naming the file and reason.
The rest of the extension keeps running, and its tools are unchanged. The
exception is a load stuck where the hook cannot stop it: after the timeout
plus 1 second, Fiber abandons the VM. That extension's tools, hooks and
commands are unavailable until restart; other providers and the session go on.
A process extension costs its process from session start, because it
must register before the session's first request. A TUI extension's VM is
created before the terminal's first frame, since a replaced layout or input
box changes that frame (docs/tui.md, "How a TUI extension runs").
One VM per extension (rather than one shared VM for all) costs about 120 to 150 KiB per
extension — measured, research/extension-runtime/vm-isolation/ — and buys real
isolation: each extension has its own globals, its own garbage collector, a
per-extension memory cap, and a crash or runaway allocation contained to
that one VM. A shared VM with per-extension environments is leaner at large
extension counts and is the documented fallback if that ever matters.
Each Lua extension's memory is capped at 1 MiB by default. Past the cap, an
allocation fails with a Lua error in that extension's VM, and Fiber does not
read a file larger than the cap. A Lua extension measures about 120 to 150 KiB, and
the busy-session budget is 24 MiB (docs/performance.md), so a small default
keeps one extension from using the budget. An extension that needs more sets
memory_mib in its manifest (docs/configuration.md, "An extension's
manifest"). The install summary shows a raised cap ("What an install shows").
The reload driver command (docs/invocation.md) reloads extensions. It is how
a running session picks up an installed or updated extension. Each reloaded
Lua extension with init.lua runs it again in a new VM before the new tool set is
declared, except a lazy extension that never started, which stays unstarted,
and each process extension is restarted. Both are handed their current state again, as it stands in the session.
When an extension misbehaves
- It errors. A Lua error is caught at the call boundary. The extension's call fails; the session survives and the VM stays usable. Errors carry the extension's filename and line. A process extension's error reply fails the call the same way.
- It loops or hangs. Every callback answers under the timeout it declared
("How an extension runs"). In Lua, enforcement is a two-stage
interrupt: a cheap instruction hook normally, escalating to fire on every
instruction once the deadline passes, so an extension cannot swallow the
deadline with
pcall. Measured inresearch/extension-runtime/pass1/. A Lua hook belongs to one coroutine, not to the VM: Fiber arms it on every coroutine a callback runs on, and it replacescoroutine.createandcoroutine.wrapwith versions that arm it on each new coroutine. With either one left as Lua ships it, a loop inside a coroutine is never stopped (research/extension-runtime/linux-containment/). A process extension is not interrupted: Fiber stops waiting, and its late reply is dropped. - It allocates without bound. A per-extension memory cap turns this into an error in that extension's VM, not an out-of-memory kill of the process. A process extension's memory is its own process's.
- It dies. A process extension is restarted once ("Process extensions").
- It is hostile. Nothing stops it at runtime; it has the account's rights. This is the trust model, not a gap. Fiber's obligation is that installing or approving an extension is a deliberate act.
When a session ends
Fiber closes extension state, writes the lines it holds, then writes fiber_exited.
From that close, state.set and state.unset fail with code closing.
On a normal exit, when a session is idle with no client or has been sent
close, Fiber delivers every remaining event to each watcher and waits for
each to finish, within its timeout. That is where a worklog or a memory
written at session end runs. It writes to the extension's data directory
(docs/state.md, "What each part holds"), not to extension state: these
deliveries come after fiber_exited, the last line the log takes, so
state.set, state.unset, host.model and host.drive fail with code
closing. host.delegate is refused to a watcher at any time, so there
it fails with not_available, not closing. A process extension
then has its manifest's exit_timeout_ms to finish, and after that gets
the shutdown sequence every child gets: SIGTERM, 800 ms, then SIGKILL
(docs/invocation.md, "Shutdown").
Before replaying, the drain waits until no watcher delivery is still
queued or running: a durable delivery the live fan-out already covered
runs first, so tearing the session down after the drain cannot lose it.
The drain replays each watcher's (cursor, end] log range — every line at
or after the registration end the live fan-out did not already offer — in
extension-name order, then watcher registration order. Each watcher runs
once per line within its declared timeout; one past it fails, and the
stream continues with the next watcher. A failure never becomes a notice:
the log already holds fiber_exited, so it is printed on stderr under it,
in every session, naming the watcher and its failure. A log the drain
cannot read, or a line it cannot read, is collected and printed the same
way, naming the drain instead of a watcher. host.fs and
host.data_dir keep working through the drain; host.model and
host.drive answer closing, and host.delegate stays refused to
watchers, as ever.
When a signal stops Fiber, no extension code runs, as no hook does. The
5-second shutdown bound has no room for it. A signal that stops the
drain makes Fiber exit with the signal's code; fiber_exited keeps the
line it already wrote. A signal after the drain finished changes
nothing.
Notes for authors
- The embedding is Lua 5.4, not LuaJIT and not Luau. Write ordinary Lua 5.4.
requireloads files from your extension's own directory only. To use someone else's Lua, vendor a copy into your directory or depend on the extension that holds it.- Give your extension a version tag for every release (see Versions). Dependents name a minimum version, and Fiber installs nothing newer than someone asked for.
- JSON is
json.decode/json.encode, provided by the host. Lua has none.json.encode({})is{}, while a callback returning{}gives[]. JSONnulldecodes to the null value: compare withjson.decode('null')for equality, since indexing null raises an error. - In Lua, do not reach for
io,os,fetch, sockets or environment variables — they are absent. Route every side effect throughhost. - Keep what must survive a resume in
state, never in globals. - Need npm, a long-lived connection or a language other than Lua? Write a process extension.
- Test with
fiber extension test: use a session case to test a run or a call case to test a provider function. See Testing an extension for the case format. Fiber tests its own extensions with the same tooling (docs/testing.md, "Testing an extension").
The extension API version
An extension's manifest names the major version of the extension API it was
written for, as api (docs/configuration.md, "An extension's manifest").
The API is everything an extension touches: the registrations, the host calls,
the hook points and what each receives, and the terminal's slots, their
inputs, the span shape and the theme's roles (docs/tui.md, "Extension
seams"). One number covers both halves of a package, because they ship
together.
- Additions keep the number. A new slot, hook point, host call or optional field changes nothing for an existing extension. An extension that needs one raises its manifest's lowest Fiber version.
- A removal or a rename raises it. Fiber loads an extension only when its
apiis Fiber's own. Otherwise the extension is not loaded, and anoticewith the codeextension_incompatiblenames it and both numbers.fiber extension installrefuses it with the same code.
The API starts at 1.
Distribution
Names
An extension's name is where it lives, as with Go modules:
github.com/owner/repo/path. A dependency is written the same way. Any git host
works, there is no registry, and two authors cannot claim the same name. A
local path also works, for an extension under development.
Without a marker, the first three parts of a name are the repository and the
rest is a path inside it. A name can mark where the repository ends with a
.git suffix, as Go does, so a repository inside subgroups can be named:
gitlab.com/group/subgroup/repo.git/path. A name whose repository or tag does
not exist fails with extension_not_found.
Every first-party extension also has a short name: its last path segment.
First-party means every extension Fiber builds and ships, so every package
under providers/ or extensions/ in Fiber's own repository has one, and a
new package adds one. fiber extension install openrouter means
github.com/aakshintala/fiber/providers/openrouter. Today the provider short
names are anthropic, openai, gemini, codex, openrouter, opencode,
databricks, muse, bedrock, vertex and azure, and claude,
cursor-agent, hooks, init, memory, export and codemode are short names for
github.com/aakshintala/fiber/extensions/<name>. A harness's short name is
the name it registers (docs/delegates.md, "Harness extensions").
azure, claude and cursor-agent are not built yet: see #224, #545 and
#546.
A short name also names the extension's directories in Fiber home
(docs/state.md, "What each part holds").
The first-party provider extensions live in Fiber's own repository, one
directory each under providers/, so muse is
github.com/aakshintala/fiber/providers/muse. They are versioned by Fiber's
release tags, and CI tests them against the binary built from the same
commit.
Fiber fetches with the system git, so your SSH keys and credential helpers
apply. If git is missing, the command fails with a stable error.
Versions
A version is a git tag, such as v1.4.0. When extensions depend on the same
extension, Fiber installs the lowest version that meets every stated minimum.
If openrouter needs oauth-helper 1.2 or later, databricks needs 1.4 or
later, and 1.9 is the newest, Fiber installs 1.4. The same inputs always give
the same result, so there is no lockfile and no solver. A newer version arrives
only when something raises its minimum.
A git address a person installs by name gets the repository's newest version tag. A repository with no version tag cannot be installed from its git address: the install fails with extension_not_found. A local path install needs no tag.
A version a person installed or updated by name counts as one more minimum,
and it stays until they remove that extension. So fiber extension update <name> on a
dependency keeps the newer version, and the same installed set always gives
the same result.
Updating everything, with fiber extension update and no name or with
fiber update, moves every installed extension, dependencies included, to its
newest tag within the major version every extension that needs it accepts. A
dependency moved this way keeps the new version as a floor. Later installs and
removals never resolve it lower, but a floor does not keep the extension
installed: when the last extension that needs it is removed, the dependency and
its floor go too.
Two extensions that need different major versions, such as 1.x and 2.x, stop
the install with version_conflict, naming both. So does a minimum that no
tag meets. A pre-release tag, such as v0.0.1-nightly.20261030, counts only
when some minimum on that extension is itself a pre-release. It then counts
like any other tag, and sorts below the stable release on its base.
Fiber records the exact commit it installed and loads only that. Nothing is
signed. The fetch runs over TLS or SSH, and a binary is checked against the
sha256 in its manifest. Fiber downloads only the binary for the platform it is
running on.
A download that connects to no address within 15 seconds, or receives nothing
for 300 seconds, fails with fetch_failed.
Installing
| Command | What it does |
|---|---|
fiber extension install <name> | Installs an extension and its dependencies. If any part fails, nothing is installed. |
fiber extension update [<name>] | Moves one extension, or every installed extension when no name is given, to its newest version and re-resolves dependencies. A version updated by name stays a minimum, and a dependency moved by updating everything keeps a floor (see Versions). It never touches a repository's extension. |
fiber extension remove <name> | Removes an extension, and any dependency nothing else uses. It fails with extension_not_installed when no directory exists under the name, and deletes nothing. |
fiber extension reinstall <name> | Removes an extension and installs it again. When its install record can be read, it installs the recorded source at the recorded commit. When the extension is damaged, it installs <name> as given, a short name or a git address. |
fiber extension list | Lists installed extensions with their versions and commits, and each repository extension with its project, its path in the repository and the content it loads. |
fiber approve [--yes] | Shows everything the current repository declares and approves it ("Code a repository ships"). |
An install from a git address needs a version tag (see Versions).
In a terminal, install and update show a summary and ask before going
ahead. The summary is the one in
What an install shows, and on update it adds the
diff since the installed version. Without a terminal they go
ahead without asking, so scripts can set up a machine.
Choosing a provider in the terminal's model picker installs it without
asking: choosing it is the approval.
Each prints installed <name> on stderr for every extension it put in place.
Installing an extension that is already installed installs it again: a name
at its newest version, a path from that path's current files. An extension
installed from a path keeps its path, so fiber extension update on it
installs again from that path, not from a tag. fiber extension list shows
local in place of the commit for an extension installed from a path.
The step runs at the extension's final path, never in a temporary
directory, because a step such as creating a Python virtualenv records its
own location.
Install refuses an extension whose manifest needs a newer Fiber than the one
running, or a different extension API version, with extension_incompatible.
Update fiber, or install a version of the extension that fits.
A fetch that fails, because git or the network failed, stops the install with
fetch_failed. Neither it nor version_conflict is retried automatically.
Installed extensions live in Fiber home, one directory each, at
extensions/<name>/.
A damaged extension does not block the others. Each extension's directory
holds an install record, .fiber.json, which says what was installed and from
where. A directory whose record is missing or cannot be read is damaged. It can
be left by an install that was killed, a disk error, or a directory copied in by
hand. Fiber treats it the same way in every command:
fiber extension listlists it as damaged, then lists the rest.installandupdateskip it and go on. Each prints one line on stderr naming it, and saying that its dependency minimums are unknown, so the versions chosen did not count them.fiber extension remove <name>deletes the directory by its name without reading the record, so it always works.- A session skips it when loading extensions, with the notice
extension_failed. - Loading providers skips it, so its models are left out of the model list,
for sessions,
fiber modelsandfiber loginalike. fiber extension reinstall <name>installs it again.
Every message names the extension and the fix:
`opencode` is damaged; run `fiber extension reinstall opencode`.
No operating-system error is shown for a damaged extension, and skipping one
does not change a command's exit code.
Installing an extension runs none of its code, except an install step its
manifest declares, such as npm ci. Fiber runs that step in the extension's
directory at install and at every update. A step that runs longer than 1800 s,
and a git call that runs longer than 300 s, is stopped and fails the install.
Fiber does not pass
--ignore-scripts, so a dependency's
own install scripts run too, and the install summary says so. A pure-data
provider is only ever read. A provider's providers/<name>.lua waits for first
use or model discovery. Other enabled Lua extensions run init.lua at session
start ("Loading, and cost when nothing is loaded").
A fresh install
A fresh install has every first-party extension: the ten built providers,
the Claude Code and cursor-agent harnesses (not built yet: see #545 and #546), hooks, init (docs/system-prompt.md, "Skills"), memory (docs/memory.md), export and codemode ("Code mode"). They arrive in the release's extensions archive, which install.sh
installs into Fiber home's extensions/ (docs/releasing.md), so a first run needs no
git and no network beyond the download. They are ordinary extensions,
recorded under their full names: nothing is compiled in, and
fiber extension remove <name> removes any of them.
Installed is not switched on. A provider is switched on exactly when it has
credential presence (docs/model-routing.md, "Credentials"). Without it,
the provider shows no models and never refreshes its list. Login supplies a
stored credential; removing the last one switches the provider off unless
another source remains. Logout leaves the extension and model cache installed.
External-source providers use their declared environment variables or paths,
not fiber login. Presence checks do not validate or acquire credentials.
A provider, hooks, init, memory or export costs nothing in a session that does not use it. A
provider that is pure data is only read, a Lua provider runs only to refresh a
stale model list or when a session uses one of its models, and hooks loads only when configuration has
a hooks key. init has no code, and its one prompt template is read only as a
skill. memory has no code, and its opening-message section adds
nothing while the store is empty. export runs nothing until the first run
of /export.
A person who removed a provider can install it again with
fiber extension install <name>, or by choosing it in the terminal's model
picker. A headless run whose provider is not installed fails with
extension_missing. Its message names the first-party extension that serves
the provider, so opencode-go/<id> says to run
fiber extension install opencode. For a provider no first-party extension
serves, it says to install the extension that provides it, by name or URL. An
extension a repository declares and nobody has
approved is skipped, or fails the run when the repository marks it required
("Code a repository ships").
Staying current
fiber update updates the Fiber binary and every installed extension
together, so a new Fiber and the extensions written for it arrive at the same
time. The first-party extensions come from the same release's extensions
archive, so they always match the binary. A repository's extensions are not among them: one changes only through a
new offer ("Code a repository ships"). fiber extension update <name> updates one extension, and
fiber extension update with no name updates every extension.
Nothing checks for updates on a timer. Extensions change only when someone runs one of these commands, so an idle Fiber does no work.
Code a repository ships
A repository can ship three kinds of code: extensions, hooks declared in
configuration ("Hooks declared in configuration") and MCP servers
(docs/mcp.md, "A repository's servers"). All three follow one rule: the
repository declares the code, the session offers it, the person approves it,
and the approval holds for the exact content, so a change brings a new offer.
A cloned repository is someone else's text, read before anything is approved,
so nothing it declares runs before a person has seen it.
Declaring. A repository lists the extension packages it ships in
.fiber/config.json, under repository_extensions, each as a path inside the
repository and whether the repository needs it (required)
(docs/configuration.md). It declares hooks in the hooks extension's
settings and MCP servers under mcp.servers. A package's client half never
loads from a repository ("Client halves"): only its session half is offered.
Offering. Before its first model request, a session gathers everything
its repository declares that has no approval for this project and this
content, and raises one offer listing all of it, so approving costs no
prompt-cache rebuild. Each item shows what an install shows ("What an install
shows"), and an item whose content changed shows the diff against the copy
approved before that is still kept, or none. For each item the person chooses: approve, skip for this
session, or never. The offer is its own event pair, repository_code_offered
and repository_code_resolved, never an interaction a model or an extension
raises (docs/events.md, "Repository code"). Any client may answer, local or
remote, and the first answer wins (docs/invocation.md, "Replying").
Whether the session waits depends on whether a client that can answer is
connected, not on how the session started. A client that can answer is a
full connection, direct or through the hub: the connections clients
counts. A summary connection and the fiber ask door never are.
- With one connected, the session waits for the answer before its first
request. Waiting counts as idle, so the idle exit bounds it
(
docs/invocation.md, "Lifecycle"). - With none, as in a
fiber askrun, a schedule or a CI job, it does not wait. Each unapproved item is skipped, and anoticewith coderepository_code_skippednames it and says to runfiber approve. An item the repository marksrequiredfails the run instead, withextension_unapproved,hook_unapprovedormcp_server_unapproved. An item this session already answered is not offered again, so a skip holds: no second notice, and a skippedrequireditem does not fail the run. - A delegate never asks. It checks the same approvals and skips or fails in the same way.
Approving outside a session. fiber approve, run in the repository, shows
everything the repository declares now, as one offer would, and approves it.
--yes approves without asking, for a script or a machine image. It is the
only way to approve without a session, and only a person runs it: nothing in
configuration or in a repository starts it. It prints each approval it
records on stderr.
Pinning. An approval holds for one SHA-256 hash of the content:
- An extension: every file in its package directory that git does not
ignore. Approving copies the package into Fiber home (
docs/state.md, "What each part holds") and runs its install step there, and its dependencies install inside the same copy, so two versions never share one. A session loads the copy, never the repository's files. - A declared hook or a repository's MCP server: its declaration, plus each
file its
commandorargsnames inside the repository. Approving copies those files into Fiber home, and the copy is what runs, in the session's workspace.
A path counts as inside the repository after symbolic links are resolved, so
a link that points out of the repository is not pinned. What a pinned program
fetches or reads while it runs is not pinned: a server started with npx -y
can run different code later under the same approval, and a hook script that
reads other files of the repository reads them as they are now.
Approval pins the declaration and the repository files that a command or
args entry names, and nothing else. A script that finds a file beside itself
by its own path, such as $(dirname "$0")/lib.sh, does not find it in the
pinned copy, because only the files named were copied. A path relative to the
workspace reads the live file. A package extension pins all its files, so it
has no such gap.
Every approved version is kept. All worktrees of a repository are one
project, but each branch can carry its own version of a package. Each session
loads the version that matches its own worktree's files, so two sessions on
two branches each run their own, and switching back to a branch finds its
version still approved. fiber sessions prune removes pinned copies that no
worktree matches any more, and keeps their approvals (docs/invocation.md,
"Deleting and pruning").
What an approved extension may do. Everything an installed one may. Its
manifest declares the built-ins it replaces and the providers it registers,
with their base URLs ("What a package holds"), and the offer states each in
plain words, such as "replaces shell" or "registers provider acme at
https://api.acme.dev/v1".
Scope. An approved repository extension loads in its project only.
fiber update and fiber extension update never touch it: it changes only
through a new offer. fiber extension remove <name>, run in the project,
removes it and records never for that content, so it is not offered again
until its content changes.
Where approvals live. An approval, or a never, is recorded per project and
content for extensions and hooks, and per machine for an MCP server
(docs/state.md, "What each part holds"). A repository cannot write or read them.
What a session checks at start. It hashes only the paths its repository
declares, never the rest of the tree. One index in Fiber home records each
declared path's size, modification time and hash, so a session reads an
unchanged file only to compare those two (docs/performance.md).
A person can still install a repository's package as their own, with
fiber extension install ./tools/fiber-lint. That is an ordinary install,
global unless --project is given, and does not follow the repository's
copy.
The same extension, declared and installed. When a repository declares an
extension that the person also installed, under the same name and so the same
git address, the repository's approved, pinned copy loads in that project and
the personal install loads everywhere else. The order is the one skills use:
repository before personal ("Skills" in docs/system-prompt.md). It holds for
first-party extensions too. A notice with code extension_shadowed names both
versions, so a personal install that is newer than the repository's copy is
visible. When one load shadows several installs, the pass raises one grouped
notice: its message gives the count and lists each install with both versions.
Two repository copies of one name load the same way: the first
declared loads, and the same notice names both versions.
Commands that read an approved copy. A session loads its project's
approved, pinned copies. Three commands read the same set when run in the
project: fiber models lists the providers the approved copies register
and runs their model lists, fiber login logs into those providers, and
fiber config checks a config set model reference against them and
prints their load notices. Run outside the project, each reads the personal
installs only. No other user-facing command reads approved copies: the hidden
fiber refresh-model-lists child reloads the same set to refresh the providers'
cached lists.
An extension can be scoped to projects. fiber extension install --project
installs it for the current project only: it loads in that project's sessions
and no others, except for provider data and discovery, whose switch is
credential presence. In a mixed package, its non-provider init, commands and
hooks remain project-scoped. Approved repository copies retain their existing
project scope. The personal-install scope is the person's extensions."<name>".enabled key:
false in the global configuration and true in the project's, both in Fiber
home (docs/configuration.md). A repository cannot set it. For each
extension the command installs for the first time, its dependencies included,
it writes false globally and true for the project. For one already
installed, it writes only the project's true, so it never turns off an
extension that is on elsewhere. It writes the keys before it installs, so a
failed install leaves nothing loading outside the project. A plain install,
update or remove never writes or clears the key;
fiber config set extensions."<name>".enabled true enables a scoped extension
everywhere.
What an install shows
fiber extension install, fiber extension update and an offer
("Code a repository ships") show:
- its name, where it comes from and its version, and for an offer, its path in the repository and that it loads in this project only
- the built-in tools and commands it replaces, and the providers it registers, each with its base URLs
- the program a process extension runs, and its install step, which runs its dependencies' own install scripts too
- the memory cap of a Lua extension, when its manifest raises it above 1 MiB
- the skills, prompt templates, themes, binaries and TUI files it carries
The summary shows what the manifest and the files tell. It does not list the
new tools, hooks, watchers or commands an extension adds: a Lua extension
registers those only when its script runs, and installing runs none of its
code. The full source is one key away, so a person can read them. An offer
lists each item's files; a client reads one with offered_file
(docs/invocation.md, "Driver commands").
Comparisons with other tools, and the owner's usage, behind this area's rules: research/reference-comparisons/README.md.