# Jig plan This document describes what is built and what comes next, in this order: 1. Step 0 and milestones 1 and 2: the model registry, usage and cost, model and reasoning level. Done. 2. Milestone 3: a wire format, and the core as a child process. Done. 3. Milestone 4: session files. 4. Milestone 5: restart and reattach. 5. Milestone 6: config in ZON. 6. Milestone 7: a runtime tool registry and hooks. 7. Milestone 8: the sandbox. 8. Milestone 9: Lua extensions. 9. Milestone 10: the agent extends jig. ## Goals for extension and reload - Jig is a personal tool with one user. There is no plugin distribution. - The user changes jig while it runs, as far as possible. A change to the config, to an extension or to the core itself must not lose the session. - The agent can later extend jig in a session: it writes a tool and then uses it. So jig needs a language that it can load without a compiler. That language is Lua. - The Zig toolchain is not always where the core runs. So the core never builds itself. The user builds a new binary, and the core replaces itself with it. - Data and logic are apart. Data (providers, models, defaults) is ZON, which the Zig types check. Logic (tools, hooks) is Zig behind interfaces first, and Lua behind the same interfaces later. - One reload mechanism: the core restarts and the UI attaches again. It covers the config, the extensions and the core. The core does not reload a part of itself in place, until a restart proves too slow. - The harness limits what the model can do. The sandbox is a main feature, and nothing the agent writes may run with more rights than the agent has (see "Trust"). - An extension keeps no state of its own that must survive. It registers things and answers calls. The session state is in the core and in the session file. ## Architecture - One binary. Today `main` runs the agent and the TUI in one process. Milestone 3 splits them: `jig` runs the TUI, which starts the core as a child process. - The TUI (libvaxis and vxfw) runs on the main thread. The agent's tasks and the TUI timers run as `std.Io` tasks. - Core and UI share only `src/protocol.zig`. Neither imports the other, and the core does not import vaxis. They talk with requests, responses and notifications (see "Core/UI protocol"). - Tools (`read`, `write`, `edit`, `bash`) are in Zig. Each tool owns its schema, execution and renderers. Tools return content (`content.Block`), and the UI owns the frame. `tools.Context` carries the `Io`, the environment for child processes and the `Abort` signal. - Provider interface (`src/provider.zig`): - `Request{system, messages, tools, model, level}` - `StreamSink{ctx, text_delta, thinking_delta, tool_call, usage}`, passed by value. Slices are valid only during the call. Callbacks can run on another thread, but never two at once, and none runs after `stream` returns. - `Finish{stop, length, tool_calls, filtered, other}` - `StreamError{Aborted, Http, Provider, OutOfMemory}` - `Diagnostics`: a buffer that the caller owns. The provider writes the reason for a failure or an early end into it. - `Provider.stream(request, sink, abort, diagnostics)`. - `src/providers/chat_completions.zig` holds the HTTP streaming, the SSE parser and the OpenAI Chat Completions body. It reuses connections and retries once when a reused connection was closed. - `src/models.zig` is the model registry. `main.zig` builds the provider instances and gives the agent a table from provider name to instance. - The agent (`src/agent.zig`) runs three tasks, and none of them holds a lock: - The owner holds the attached UI, the queued prompts and all state that a UI can change. Only the owner sends to the UI. - The runner runs one prompt at a time: the provider requests and the tools. - The forwarder moves requests from the inbox to the owner. - New state follows the same rule. One task owns it, and another task gets it as a message or as one atomic value. ### Core/UI protocol The core and a UI exchange typed messages, in the style of Neovim's RPC: requests, responses and notifications. In one process the messages are Zig unions, and nothing is encoded. Between two processes each message is one line of JSON (`src/wire.zig`). - **Startup:** the core starts with no UI. A UI attaches to it, and detaches before it goes away. - **Sinks:** each side gives the other a `Sink(T)` with one `send`. The core's sink never blocks, so a UI never waits for the core in its event loop. The TUI's sink blocks while the TUI queue is full. The TUI puts input, core messages and timer ticks into one queue. - **Requests from a UI** carry an id that the UI picks. The core answers each request once, with the same id, in the order it received them. - `attach{sink, version}`: the core sends its messages to `sink` from now on. The response carries the session: the model, the level and the working directory. A second `attach` while a UI is attached gets `already_attached`. A UI with another protocol version than the core gets `incompatible`. - `detach{sink}`: the core answers on `sink`. When `sink` is the attached sink, the core detaches it, and the response is the last message the core sends to it. - `submit{text}`: the response is `queued`, or `refused` when the prompt queue is full. The core answers `queued` before the prompt can start, so a UI gets it before the `prompt_start` of that prompt. A UI keeps the text of a submit until the response, and puts a refused prompt back in the editor. - `interrupt`: the response only confirms it. - `select_model{name}`, `cycle_model` and `cycle_level`: the response is `ok`, or `unknown_model` for a name that cannot be selected. The new model and level come in the `selection` notification, which arrives before the response. So a UI has one source for what it shows, and every attached UI gets it. - **Notifications from the core:** `text_delta`, `thinking_delta`, `tool_call`, `tool_result`, `notice`, `selection`, `usage`, `prompt_start`, `prompts_returned`, `agent_start` and `agent_end`. With no UI attached, the core drops them. - **Flow control:** the core's inbox is bounded, and its sink refuses a message when the inbox is full. A UI keeps at most one request less than the inbox holds without a response. So a request is never refused, and one slot is always free for `detach`. This is why `interrupt` is a request: its response frees the slot. - **Detach:** the UI sends `detach`, then reads and frees its own queued messages until the `detach` response arrives. It keeps reading, so the core never waits forever on a full UI queue. After the response, the UI can free its sink. When the core refuses the request because it stopped, the UI does not wait. - **One UI** for now. More UIs need a copy of each notification for each UI, and a slow UI would hold up the others. Until then, only the attached UI may send `submit` and `interrupt`. These requests do not name their sender, so the core answers them on the attached sink. - **Later:** requests from the core to a UI, for Lua dialogs such as confirm and select, with responses from the UI. The core waits for an answer only in the task that asked, and an interrupt cancels the wait. ### Provider layers Three layers, with plain data between them (strings, enums, raw JSON). Provider errors are messages. 1. Core transport in Zig: HTTP streaming, SSE framing, abort. 2. API shape in Zig: for example OpenAI Chat Completions. `writeBody` and `Parser` in `chat_completions.zig` are this layer. The transport is in the same file. Split the two when a second API shape needs the transport. 3. Provider as data: URL, auth, extra headers, model list. `main.zig` holds these for Workers AI until milestone 6 moves them to ZON. A quirk that data cannot express is a Lua hook (milestone 9). ### Trust Two levels, and the line between them is who wrote the code. - **Harness:** the jig binary, `config.zon`, and the Lua that the user wrote or approved. It runs with the user's rights. The sandbox does not apply to it, because it is what applies the sandbox. - **Agent:** everything the model asks for: tool calls, commands, and code that the model wrote. It runs inside the sandbox. Rules that follow: - The agent cannot write where harness code and policy live. The sandbox always denies writes to the config directory, to the session files and to the jig binary, and no rule in the config can allow them. - Code decides its level by where it is, not by what it says. Lua in the config directory is harness code. Lua that the agent wrote is in another directory and is agent code. - Agent code becomes harness code only when the user moves it, after a review. Jig never does this by itself. - A built-in tool is harness code that acts for the agent. So `read`, `write` and `edit` check each path against the policy, and `bash` runs its command inside the sandbox. ## Decisions - **Keys:** - Ctrl+T cycles the reasoning level. - Ctrl+P cycles the model. - Shift+Tab shows or hides thinking. A hidden thinking block shows only `Thinking...` in italics. - No slash commands for now. - **Processes:** - `jig` runs the TUI and starts the core as a child. - `jig --embed` runs only the core. It reads requests from stdin and writes messages to stdout, as `nvim --embed` does. - `--headless` is kept for a later core that runs without a parent and listens on a socket. - **Wire format:** JSON lines. `std.json` does the work, and a person can read and type it. Change to a binary format only when large payloads, such as images, cross the channel. - **Directories:** XDG base directories. - Config is in `$XDG_CONFIG_HOME/jig` (fallback `~/.config/jig`), with `config.zon`, and later `init.lua` and a `lua/` folder for modules. - State is in `$XDG_STATE_HOME/jig` (`~/.local/state/jig`), data in `$XDG_DATA_HOME/jig` (`~/.local/share/jig`), and cache in `$XDG_CACHE_HOME/jig` (`~/.cache/jig`). - macOS uses the same paths, not `~/Library`. - Windows is out of scope. - **Sessions:** one directory for each working directory, named by a hash of its real path, as Bazel names its output base. - **Config language:** ZON for data. Not Nickel (its only implementation needs Rust) and not CEL (an expression language with a large C++ implementation; Lua hooks do its job). - **Usage:** cost in USD from a price table. The footer shows session totals and the context percent. Hide the cost when a model has no price. No totals per prompt, no price tiers, no 1-hour cache pricing. - **Reasoning:** levels `off`, `low`, `medium`, `high`, `max`. Thinking is shown by default. Send reasoning back to the model (see "Workers AI facts"). - **First models:** `deepseek-v4.1-flash`, `kimi-k2.6`, `gpt-oss-120b`. Ctrl+P cycles all of them, with no popup selector. - **Lua:** - PUC Lua 5.5.1. Not LuaJIT, not Luau, not Teal, not ziglua. - A global `jig` table, not `require("jig")`. - Static types come from the editor, as in Neovim. Jig ships a LuaLS definition file for the whole `jig` API, and a command writes it to the config directory. - Tests of an extension are Zig tests that load the Lua file into a core with the scripted provider. - A Lua tool can replace a built-in tool or an earlier Lua tool with the same name. It must be able to call the tool that it replaced, so tools compose. Several replacements stack in load order. - Extensions are trusted and run with the user's permissions, as in pi. - Extensions of the UI are deferred. Only the core gets a Lua VM. - **edit tool:** one file per call. Writes to several files cannot be all-or-nothing. ## Workers AI facts All measured on `@cf/deepseek-ai/deepseek-v4.1-flash-1017` through `/ai/v1/chat/completions`. - **Usage in the stream:** - Every chunk carries `usage`, and the values are running totals. Jig does not need to send `stream_options`. - A chunk with all zeros can come before the final totals. Keep the snapshot with the largest total, not the last one. - **Cached tokens:** `prompt_tokens` includes `prompt_tokens_details.cached_tokens`. So uncached input = `prompt_tokens - cached_tokens`. - Test: the same 8387-token prompt sent 4 times gave `prompt_tokens` 8387 each time, with `cached_tokens` 0, 8320, 8384, 8384. - **Prices** (USD per million tokens): input 0.30, cached input 0.006, output 1.20. Context window: 1,048,576 tokens. - **Neurons:** the `neurons` field equals tokens times the published rates, so a price table gives the same cost. Jig does not need to parse `neurons`. - **Prompt caching:** send `x-session-affinity: ` on every request, so requests reach the instance that holds the cache. - **Reasoning levels:** `reasoning_effort` accepts `none`, `low`, `high`, `max`. The default is `high`. Aliases: `minimal` is `none`, `medium` is `high`, `xhigh` is `max`. - **Reasoning replay:** the chat template keeps reasoning only inside the current tool-call sequence. - An assistant tool-call message with 295 tokens of reasoning raised `prompt_tokens` from 369 to 664. Both `reasoning_content` and `reasoning` are accepted on input. - After a new user message, the template drops the earlier reasoning. - So jig stores reasoning on the assistant message and sends it back as `reasoning_content`. The server drops old reasoning by itself. - **Other models:** `kimi-k2.6` accepts `none` and `high`, and `gpt-oss-120b` accepts `low`, `medium`, `high` and cannot turn reasoning off. - Recorded streams of both are in `src/providers/testdata`. `scratch/fixtures/record-v1.sh` records them again. - Both send usage in every chunk as running totals, like deepseek. - Both send thinking as `reasoning_content`. `gpt-oss-120b` sends the same delta in `reasoning` too, so the parser reads only `reasoning_content`. - Prices and context windows come from the model catalog (`GET /accounts/{id}/ai/models/search`). `kimi-k2.6`: input 0.95, cached input 0.16, output 4.00, window 262,144. `gpt-oss-120b`: input 0.35, output 0.75, no cached price, window 128,000. - The output limit of each model is not known. The registry asks for 16,384 tokens. ## Done: step 0 and milestones 1 and 2 The history of the repository has the detail. What exists: - **Model registry** (`src/models.zig`): a comptime table of `Entry{name, id, provider, levels, context_window, max_output, cost}`. A model can be selected only when its provider has an instance, so `fake` is never part of the Ctrl+P cycle of a normal session. - **Usage:** - `provider.Usage{input, output, cache_read, cache_write}`. `input` means uncached prompt tokens, and `output` includes reasoning tokens. - The parser reports usage at most once for each stream, also for a stream that failed or was aborted. - The runner keeps the session totals and sends a `usage` notification after each request: the request, the session, both costs, and the context tokens and window. A cost is null when a price is unknown. - The footer shows `↑in ↓out R $cost pct%/window`, and colors the percent above 70% and above 90%. - Each request carries `x-session-affinity` with one random id for each jig process. - **Model and level:** - The owner holds the selection and publishes it as one atomic value. The runner loads it before each request, so a change applies from the next request and never to one that streams. - The owner keeps the level the user asked for. A model that lacks it gets the nearest higher level, then the nearest lower one. - Each request sends the model id, `reasoning_effort` and `max_completion_tokens` from the registry entry, and earlier thinking as `reasoning_content`. - `--model` and `--thinking` set the defaults. Without `--thinking` the level is `medium`. ## Done: milestone 3, the wire format and the core as a child process - **Encoding** (`src/wire.zig`): - One JSON object on each line. A request is `{"id":N,"method":"submit","params":...}`, a response is `{"id":N,"result":{"kind":"queued",...}}`, and a notification is `{"method":"text_delta","params":...}`. - `wire.zig` encodes and decodes the types of `protocol.zig`. The types stay the form in memory, and a new field of a notification needs no code in `wire.zig`. - A reader ignores a field it does not know. So a message can get a new field, such as the ones "Directions" names, and an older side still reads it. - `attach` and `detach` carry no sink on the wire. The reader on the core's side puts in the sink of the connection. - `attach` carries `protocol.version`. The core answers `incompatible` to another version. - **The two ends** (`src/remote.zig`): `CoreEnd` and `UiEnd` each read lines from one byte stream and write lines to another. They work on any reader and writer, so a socket can take the place of the pipes later. - A line can have any length. - The core reports a line that is not a request on stderr and goes on. The UI shows an error notice for a line that it cannot read. - There is no writer task. The owner encodes and writes each message itself, and waits when the pipe is full. - **Core** (`jig --embed`): requests on stdin, messages on stdout, problems on stderr. It never touches the terminal. The end of stdin stops it, so a core never outlives its UI. - **UI** (`jig`, `src/child.zig`): - Checks the flags and the environment itself, so an error shows before the screen changes. Then it starts its own executable with `--embed` and the same flags. - When the core ends, the TUI shows a notice with the last lines of the core's stderr, puts the prompts that did not run back in the editor and starts a new core. With milestone 4 the new core takes the session up again. - A core that ends before it answers `attach`, or less than two seconds after it started, is not started again. jig ends and prints what the core wrote. - On quit the UI closes the core's stdin and waits. It kills a core that takes more than three seconds. - **In one process:** the direct form with Zig unions stays, for tests. No flag selects it. - **Tests** start the installed binary for the child-process cases. `zig build test` installs first and gives the path in `JIG_EXE`; without it those tests are skipped. ## Milestone 4: session files 1. **File:** `$XDG_STATE_HOME/jig/sessions//.jsonl`. - `` is the first 16 hex digits of the SHA-256 of the real path of the working directory. A file `path` in that directory holds the path as text, so a person can find the directory of a project. - The id starts with the time, so the names sort by age, and ends with random characters. - The file only grows: one JSON line for each record, written when the record is complete. So a core that dies loses at most the reply that was streaming. 2. **Records:** - A header: the id, the working directory and the time. - Each message of the history: user, assistant (text, thinking and tool calls) and tool result. - With a tool result, the content a UI shows for it (collapsed and expanded). The call line is rendered again from the arguments. - The usage of each request and the model that served it. The totals and the cost are summed again at load. - The selection, when it changes: the model name and the level the user asked for. 3. **Writer:** the runner owns the file. The owner sends a selection change to the runner as a message. 4. **Load:** - A tool call without a result gets the result `not run: the core stopped`, so the history stays valid. - A model that is no longer in the registry gives the default model and a notice. - A last line that is cut off is dropped. 5. **Affinity:** the session id is the value of `x-session-affinity`. So the prompt cache of the provider survives a restart. 6. **Flags:** `--session ID` takes up that session, and `--continue` takes up the newest session of the working directory, which is the last name in its directory. 7. **Tests:** - A session written and loaded gives the same history, selection and totals. - A file that ends inside a line, and one that ends after a tool call, both load. - The second request after a load sends the whole earlier history. - `--continue` picks the newest file of the working directory and no file of another directory. - Two paths to the same directory, one through a symbolic link, give the same session directory. ## Milestone 5: restart and reattach 1. **Replay:** after an `attach` response, the core sends what the session holds as normal notifications, between `replay_start` and `replay_end`: each user prompt (a new `user_message` notification), text, thinking, tool calls and tool results, then `selection` and `usage`. The UI clears its transcript at `replay_start`. So a UI has one code path for old and for new content. 2. **Request `restart`:** - The core accepts it only while no prompt runs or waits. Else the response is `busy`. Milestone 10 lifts this limit. - The core closes the session file and replaces its process with its own executable, with the same flags and `--session `. The pipes stay open across the replace. - Like `detach`, the response `ok` is the last message of the old core. The UI sends nothing between `restart` and its response. Then it sends `attach`, which the new core reads. - When the replace fails, the core goes on and the response is `failed` with the reason. - When the new core ends at once, the UI handles it as any core that ended (milestone 3). 3. **Version:** a new core that cannot talk to the UI answers `attach` with `incompatible`. The TUI then tells the user to start jig again. 4. **Key:** Ctrl+R sends `restart`. The TUI shows a notice with the result. 5. **Tests:** - An attach to a core with a loaded session replays it in order, and the TUI shows the same rows as before. - `restart` during a prompt is `busy`, and the prompt goes on. - With the built binary: a prompt, a restart, and then a second prompt whose request holds the first one. - An `attach` with a version the core does not know is `incompatible`. ## Milestone 6: config in ZON 1. **File:** `$XDG_CONFIG_HOME/jig/config.zon`, parsed with `std.zon` into Zig structs. The struct is the schema, and an error names the field. ```zig .{ .model = "deepseek-v4.1-flash", .thinking = .medium, .providers = .{ .{ .name = "workers_ai", .shape = .chat_completions, .url = "https://api.cloudflare.com/client/v4/accounts/${CLOUDFLARE_ACCOUNT_ID}/ai/v1/chat/completions", .token_env = "CLOUDFLARE_API_TOKEN", .session_header = "x-session-affinity", .models = .{ .{ .name = "kimi-k2.6", .id = "@cf/moonshotai/kimi-k2.6", ... } }, }, }, } ``` 2. **Environment:** ZON cannot read the environment. `token_env` names the variable that holds the token, and `${NAME}` in `url` and in a header value is replaced. A variable that is not set makes that provider unavailable, with a notice, and the other providers still work. 3. **Defaults:** the Workers AI provider and its three models are a ZON file in the source, parsed at compile time. The user's file adds providers and models, and an entry with the same name replaces the built-in one. 4. **Registry at run time:** `models.Entry.provider` becomes the name of a provider, not an enum. The agent's model list and provider table are built at startup. `fake` is a provider that only `--model fake` adds. 5. **Flags:** `--model` and `--thinking` win over the file. 6. **Reload:** the restart of milestone 5. A config that does not parse gives a notice, and the core starts with the built-in defaults. 7. **Tests:** - The built-in file gives the three models with the values they have today. - A user file adds a provider, replaces one model and sets the defaults. - A missing variable, a missing file and a file with a wrong field each give the right notice and a core that works. - A flag wins over the file. ## Milestone 7: runtime tool registry and hooks 1. **Registry:** `tools.Registry` holds `Tool{name, description, parameters_json, ctx, execute, render_call}` entries. It replaces the comptime `tools.definitions` list in the agent. The built-in tools register first. 2. **Replace:** a tool registered with a name that exists replaces the entry and keeps the old one as `previous`. The new tool can call it. - **Callers:** the registry runs a tool for any caller that has a name and JSON arguments, not only for the agent loop. Every call takes the same path through the hooks and the policy. Code mode needs this (see "Directions"). 3. **Hooks:** one Zig interface with four calls, each optional: - `before_request` can change the system prompt and the messages of one request. The history does not change. - `tool_call` can block a call. The model gets the reason as an error result. - `tool_result` can change a result. - `run_end` is told that a prompt ended. 4. **Order:** hooks run in the order they were registered, on the runner task. A hook that fails gives a notice, and the run goes on as without it. 5. **Fixed after startup:** everything registers before `core.start()`. So the owner and the runner read the registry without a lock. 6. **Tests:** - A registered Zig tool appears in the request, runs, and its result reaches the history. - A tool that replaces `read` calls the tool it replaced. - Each hook does its change, and a hook that fails does not end the run. ## Milestone 8: the sandbox This milestone needs its own design before work starts. What is fixed, and what is open: 1. **What it limits:** the files a command can read and write, the network it can reach, the environment variables it sees, and which commands can run at all. 2. **macOS:** Seatbelt, through the C API of `libsandbox`, not through the `sandbox-exec` program. - A sandbox applies to the process that asks for it and cannot be taken off. So jig starts itself as a small launcher (`jig --sandbox-exec`), which applies the profile and then replaces itself with the command. - Jig builds the profile text from the policy for each command. 3. **Linux:** not designed. The policy types must not assume Seatbelt. 4. **Policy** (in `config.zon`, parsed into Zig structs like the rest): - Filesystem: lists of globs to allow and deny, for read and for write, where deny wins and a narrower allow can open a hole in a deny. - Network: open or allow-list, by domain and by HTTP method for each domain, Unix sockets, and binding to local ports. - Environment: an allow-list of variable names. - Commands: a pattern that denies a command and tells the model why, and a policy for each command name that adds to the base policy (for example `jj` may write `.jj`). - Named overlays that a command policy or the user can turn on, such as `readonly`. - Violations to ignore in the report. - ZON has no map with free keys, so commands and overlays are lists of entries with a `name`. 5. **One policy, three users:** the same Zig policy value gives the Seatbelt profile for a command, the path check of `read`, `write` and `edit`, and the text that tells the model what it may do. 6. **Fixed rules:** the write denials of "Trust" are in the code, and the config cannot remove them. 7. **Where it hooks in:** the `tool_call` hook of milestone 7 denies a command, and `tools.Context` carries the policy to the tools. 8. **Open:** - Filtering by domain and by HTTP method needs a proxy that the sandbox forces all traffic through, and HTTPS needs a local certificate authority for it. This is the largest part. A first version can offer only "no network" and "open". - Whether `read`, `write` and `edit` check paths in the core, or run in a sandboxed helper process so that the kernel does the check. A check in the core must resolve symbolic links first. - How to parse a shell command well enough to find the command names in it. - Policy files inside a project, and how the user trusts them. - How a violation reaches the user and the model. ## Milestone 9: Lua extensions Lua is one more implementer of the registry and the hooks of milestone 7. 1. **Spike:** - Fetch `https://www.lua.org/ftp/lua-5.5.1.tar.gz` with `zig fetch --save`. - Build a static library from `src/*.c` without `lua.c` and `luac.c`. - Translate `lua.h`, `lauxlib.h` and `lualib.h` with `b.addTranslateC`. Zig 0.17 has no `@cImport`. - Run `return 1 + 1`. Check cross builds for `x86_64-linux` and `aarch64-linux`. 2. **Binding** (`src/lua.zig`): - Expose only the calls Jig uses. Do not assume one global VM. - A capped allocator through `lua_newstate`, so too much memory becomes a Lua error and not a crash. - Open the standard libraries with `luaL_openselectedlibs`, and remove C module loading. - Run every entry point in `lua_pcall` with a traceback handler. - A count hook checks the abort flag and stops Lua code that never ends. - Lua errors jump over Zig frames and skip `defer`. A Zig function that Lua calls must not hold allocations or locks when it raises an error. 3. **Loading:** - Load `$XDG_CONFIG_HOME/jig/init.lua` after `config.zon`. - Set `package.path` to `/lua/?.lua;/lua/?/init.lua`. - Add a flag that skips extensions. - A load error skips that file and shows a notice. - Reload is the restart of milestone 5. 4. **Threading:** - `main` loads the extensions before `core.start()`. After the start, only the runner task enters the VM. - Host functions such as `jig.exec` block that task and stop on abort. They use the same `Io.Select` and `Abort.wait` pattern as `chat_completions.zig`. - Later, a coroutine driver (`lua_yieldk`) can run several entry points at once without a change to the Lua API. 5. **API:** - `jig.tool{name, description, parameters, execute, render_call, render_result}` and `jig.json.encode` / `jig.json.decode`. - `execute(args, ctx)` returns the text for the model. `ctx.previous.execute(args)` runs the tool that this one replaced, also when that is a Zig tool. An error in `execute` becomes an error result for the model. - `render_result(result)` is optional and returns the collapsed and the expanded content for a UI. Without it, the expanded content is the text and the collapsed content is its first lines. - `jig.on(event, fn)` for the four hooks, and `jig.notify(text, level)`. - `jig.provider{...}` and `jig.model{...}` take the same fields as `config.zon`, for entries that need a computed value. 6. **Types:** a LuaLS definition file for all of `jig.*`, written by hand next to the binding. `jig --write-types` writes it to the config directory. A test fails when a function of the binding has no entry in the file. 7. **Tests of an extension:** a helper starts a core with the scripted provider and one Lua file. The tests of jig's own bundled Lua use it, and so can the user's. 8. **Trust:** this milestone loads only harness Lua, from the config directory. The sandbox of milestone 8 keeps the agent from writing there. 9. **Tests:** - A Lua tool appears in the request and its result reaches the history. - An error in `execute` gives an error result, and the next call still works. - A syntax error in one file leaves the other tools registered. - `while true do end` stops after an interrupt within a bounded time. - Memory over the cap gives an error. - JSON round trips. - Replacing `read` and calling the replaced tool. ## Milestone 10: the agent extends jig Design this after milestones 8 and 9 work. The direction: 1. **Where agent code lives:** `$XDG_DATA_HOME/jig/agent/lua/`, which the sandbox lets the agent write. Never the config directory. 2. **What agent code can do:** less than harness Lua. - It can add tools with new names. It cannot replace a tool, register a hook, add a provider or a model, or change the config. Each of these would let it change the policy, see the tokens or send the conversation somewhere. - Its tools have no more rights than the agent's own tool calls. 3. **How the limit holds:** agent Lua runs in its own VM in its own process, which jig starts inside the sandbox, with the base policy. The kernel enforces the limit, not a list of Lua functions that jig removed. The process talks JSON lines with the core, as the core does with the UI. A second VM in the core, with `io` and `os` taken out, is weaker: every host function is then a place where a path check can be wrong. 4. **Promotion:** the user reads an agent tool and moves it to the config directory. Then it is harness code. A command can show the file and do the move, but only the user starts it. 5. **A restart inside a run:** the state of a run between two steps is only the history, and that is in the session file. So the core can restart at the next safe point (after a reply ended and its tool calls finished), and the new core goes on with the same run. - The session file gets a record that a run is open. A core that loads it continues the loop and does not wait for a prompt. - A built-in `reload` tool asks for this. The new core writes its result, with the list of tools that are new. So the agent uses a tool in the same turn in which it wrote it. - The `restart` request of a UI works the same way during a run. The `busy` answer of milestone 5 goes away. - A reply that streams, and a command that runs, finish first. 6. **Tests:** an agent tool cannot read a denied file, cannot open a network connection when the policy has none, and cannot register a hook. A run goes on after a restart with one more tool in its next request. ## Open questions 1. **How an empty Lua table encodes to JSON.** Proposal: `{}`, with a `jig.json.array()` marker for an empty array. Tool schemas and arguments are mostly objects. 2. **Lua `io` and `os` libraries.** - Keeping them gives full power and familiar APIs. - Their calls (`os.execute`, `io.popen`, reads from a pipe) cannot be interrupted and would bypass a future sandbox. - Offering only `jig.*` functions allows abort. - This is about harness Lua only. It is trusted, so the sandbox is no reason to take the libraries out. Agent Lua runs in a sandboxed process (milestone 10) and can have them. ## Directions Features without a milestone and without a design. They are here so that the milestones before them do not close a door. Each one will be an experiment. ### Compact tool calls - A tool call is one line in the transcript, and the user can expand it. Today a call is a block with padding, and that takes too much room. - Calls of the same tool that follow each other become one line. Expanded, the line shows each call, and each call can show its result. - The group line is generic: the tool name, the count, and then the one-line text of each call, cut at the width. For example `read ×3 a.zig, b.zig, c.zig`. So a tool renders one call at a time, as today, and has no function and no words for a group. - The UI does the grouping. The core still sends one `tool_call` and one `tool_result` for each call, and the session file keeps them apart. - What the UI needs from the core, and does not get today: the `tool_call` notification carries the tool name, and the rendered call has the name apart from the text after it. Today it carries one rendered block. - A tool can declare one optional text for its group line, with a place for the count, such as `Read {n} files`. It is data, not a render function, because the UI makes the group and the count changes while calls arrive. A tool without the text gets the generic line. - Open: whether a group ends at text between two calls or at the end of a reply, how a group shows that one call failed or still runs, and what a single call shows on its one line. - No milestone depends on this. It can be built at any time after milestone 3. ### Code mode - The agent writes a short program that calls tools, and jig runs it as one tool call. The program passes the result of one tool to the next, and only what it returns goes into the context. So a chain of calls costs one reply and few tokens. - The language is Lua first, because jig has the VM. Other harnesses use JavaScript or Python, and models write those more often. So measure how well each model writes Lua for this before more is built on it. The LuaLS definitions of the tools go into the tool description, so the model sees the types. - The program runs in its own process, so its language does not have to be the language of the core. If Lua does badly, that process can hold QuickJS or MicroPython, both small C libraries, and the core does not change. - The program is agent code (see "Trust"). It runs in the sandboxed process of milestone 10, not in the core's VM. A tool call from the program goes to the core over the channel, and the core runs it through the same hooks and policy as a call from the model. - What this asks of earlier milestones: - The registry runs a tool for a caller other than the agent loop (milestone 7). - A tool result has a value for a program, not only text for a model. For example `bash` gives the exit code and the output as two fields. `Tool.execute` returns both forms, and the value is optional. - A `tool_call` notification can name a parent call. The UI shows the calls of a program under the call that ran it, and groups them as above. - The session file keeps the calls of a program for the UI. They are not part of the history that goes to the model. - Open: limits on time, on memory and on the number of calls of one program; what the program can do besides tool calls; whether it can call tools at the same time; how the model learns from an error in its program. ## Later Not part of this plan, and not designed yet: - Compaction, and what happens when the context is full. The footer only shows the percent. - Retries with backoff for 429 and 5xx responses. - Context files such as `AGENTS.md` in the system prompt. - Markdown in the transcript. - `jig --headless` with a socket, a UI on another machine, and more than one UI. - The Anthropic Messages shape. - Terminal features in the TUI: kitty graphics, OSC 8 links, cursor shapes. - Extensions of the UI. - A UI that the agent can compose: the agent opens a split and draws in it, for mock-ups, graphs and plots, with terminal images. For now this only means that the content types of the protocol stay open for new kinds, and that a request from the core to a UI stays possible. - Jig saves settings, such as the last model, by writing ZON.