@sigitcodereview / sigit
Code Commits Issues Pulls Cloud Agent CI/CD
fix/dsml-doubled-bar-markers
claude/github-issue-40-0au5ua claude/linked-issue-acp-tui-u4vvpa claude/minor-release-cut-vkugow claude/sigit-acp-local-chat-cx6380 claude/sigit-cloud-agent-expansion-reox0a claude/tool-permission-system claude/zen-feynman-0u78dk development feature/acp-cancel-request feature/acp-session-list-cursor feature/acp-v1-conformance feature/agent-tools-multiedit-glob-todos-remember feature/cargo-workspace feature/hooks feature/load-local-model-explicitly feature/sigit-agent-profile feature/sigit-code-cloud feature/xcode-mcp-server fix/acp-replay-loaded-session-history fix/acp-replay-reasoning-and-attachments fix/dsml-doubled-bar-markers main release/v1.5.10 release/v1.5.6 release/v1.6.1
md 582 lines 44.5 KB
Rendered Raw
1 # AGENTS.md
2
3 This file provides guidance to AI coding agents when working with code in this repository.
4
5 ## What this is
6
7 `sigit` ("siGit Code") is a single Rust binary: a local-first AI coding agent that runs LLM
8 inference on-device (via the `onde` crate / GGUF models) or against a hosted/OpenAI-compatible
9 endpoint. It exposes itself two ways from the *same* binary, chosen at startup by whether stdin
10 is a TTY:
11
12 - **ACP mode** (stdin not a TTY): speaks the Agent Client Protocol over stdio for editor
13 integration (Zed, VS Code ACP Client). Cross-platform.
14 - **Interactive terminal mode** (stdin is a TTY): a full-screen ratatui chat UI. **Unix-only** —
15 it relies on fd redirection to keep logs out of the TUI, so Windows gets ACP mode only.
16
17 Before the TTY/ACP split, `main` also dispatches the account subcommands `sigit login`,
18 `sigit logout`, `sigit whoami` (see `src/main.rs` `main()`).
19
20 ## Working in this repo
21
22 **IMPORTANT — branch naming:** Prefix every working branch with `feature/` (new functionality)
23 or `fix/` (bug fixes) — never a tool- or agent-name prefix like `claude/`. Name the branch after
24 the *changes it contains*, as a short, descriptive, kebab-case slug that is self-explanatory
25 from the name alone (e.g. `feature/tool-permission-system`, `fix/glob-mtime-sort`), never after
26 a task, ticket, or session id (not `feature/task-q003hm`).
27
28 **IMPORTANT — pull request target:** Always open pull requests against the `development` branch,
29 never `main`. `main` is release-only; `development` is where day-to-day work integrates, and the
30 release merge (see the `sigit-code-release` skill) is the one thing that ever puts commits on
31 `main`.
32
33 This rule needs help to hold, because the repository's default branch is `main`: both
34 `gh pr create` and the GitHub web form pre-select it, so a PR lands on the wrong base unless the
35 base is passed explicitly. Pass it every time, and check that it took:
36
37 ```sh
38 gh pr create --base development --head <branch>
39 gh pr view <number> --json baseRefName
40 ```
41
42 Retargeting a PR that was opened against `main` costs nothing before it merges:
43 `gh pr edit <number> --base development`. After it merges it costs real work — the change sits on
44 `main` while `development`, which the next release is cut from, does not have it, and someone has
45 to carry it back by hand. PR #65 went in that way.
46
47 **IMPORTANT — branch off `development`:** Start every working branch from the latest
48 `origin/development`. Exception: when new work *depends on* a feature branch that has not merged
49 yet (e.g. it builds on tools or APIs that branch introduces), it may be stacked on top of that
50 branch instead. When stacking: merge the base PR into `development` first, then rebase the
51 stacked branch onto `development` before opening its pull request, so each PR shows only its own
52 commits.
53
54 **IMPORTANT — run CI before pushing:** Run the full CI gate locally and confirm it is green
55 *before* pushing a branch or opening a pull request — never push work that fails these:
56
57 ```sh
58 cargo fmt -- --check # formatting
59 cargo clippy --tests -- -D warnings # lint (warnings are errors)
60 cargo test --locked # tests
61 ```
62
63 ## Agent assets layout
64
65 `.agents/` is the canonical home for agent assets; every other agent path in
66 the repo is a symlink into it, never a copy:
67
68 - `.agents/AGENTS.md` — this file, the project instructions. The root
69 `AGENTS.md` and `CLAUDE.md` are symlinks to it, so agents.md-standard tools,
70 Claude Code, and sigit itself (via `src/instructions.rs`, which prefers
71 `AGENTS.md` over `CLAUDE.md` in the same directory and therefore reads it
72 once) all load the same content. Edit this file; never replace the root
73 symlinks with real files.
74 - `.agents/skills/` — all project skills. `.claude/skills` is a symlink to it,
75 which is how both Claude Code and sigit itself (via `src/skills.rs`) discover
76 them. Add new skills under `.agents/skills/<name>/SKILL.md`, never as real
77 files under `.claude/`.
78
79 ## Build / test / lint
80
81 ```sh
82 cargo build # debug build
83 cargo build --release # release binary at target/release/sigit
84 cargo run # launches interactive TUI (stdin is a TTY)
85 cargo test # CI runs: cargo test --locked --target <target>
86 cargo clippy --tests -- -D warnings # CI gate: clippy is -D warnings on all 4 targets
87 cargo fmt -- --check # CI gate (edition 2024)
88 ```
89
90 CI (`.github/workflows/ci.yml`) runs fmt + clippy + test across four targets:
91 `aarch64-apple-darwin`, `x86_64-apple-darwin`, `x86_64-unknown-linux-gnu`,
92 `x86_64-pc-windows-msvc`. Clippy is `-D warnings`, so warnings fail the build.
93
94 Run a single test: `cargo test <test_name>`.
95
96 ## Critical platform constraint: `#[cfg(unix)]` dead code
97
98 The interactive client is `#[cfg(unix)]`-only. The `InferenceBackend` seam (`backend.rs`) and
99 provider resolution (`provider.rs`) are consumed by both the interactive client and the ACP
100 server, but several of their items are reached only through the Unix-only interactive paths, so
101 the dead-code lint is suppressed *on non-Unix targets only*.
102
103 Consequence: code can pass clippy on macOS/Linux but fail on the Windows target (or vice versa).
104 When touching `backend.rs`, `provider.rs`, or the interactive path, keep the `cfg` gates intact —
105 don't "fix" an unused-warning by deleting code that's live on Unix.
106
107 ## Architecture
108
109 The agent loop is backend-agnostic. The flow: a turn (messages + tool specs) goes to an
110 `InferenceBackend`, which returns assistant text and/or tool calls; the loop executes tools and
111 feeds results back. Neither the loop nor ACP/TUI surfaces depend on a concrete backend.
112
113 - **`src/main.rs`** — entry point, mode dispatch, the full ACP `Agent` impl (session lifecycle:
114 new/load/fork/prompt/cancel, config options, slash-command advertisement), and the `SYSTEM_PROMPT`.
115 ACP session state owns its roots, conversation, and selected model even though the process has
116 one working directory and one live backend slot; activating a thread parks and restores all
117 three. A thread on an HTTP backend keeps a backend of its own (`InferenceBackend::fresh`,
118 `SessionState::remote`), so its turn can wait on the endpoint while another thread is
119 installed. Unknown session ids are rejected instead of silently borrowing the active thread's
120 cwd. Prompt cancellation takes no lock, which lets a client cancel a turn whatever it holds.
121 Message chunks carry a `messageId`: each inference round is one message, so every chunk of
122 it, reasoning included, shares `StreamedReply::message_id` and a tool round starts a new id.
123 A standalone notice (`send_assistant_message`) gets an id of its own, and replayed messages
124 get fresh ones; ids are random, so none is stored in history.
125 The Inference (local/cloud) config option is a `boolean` for a client that advertises
126 `session.configOptions.boolean` (read into `CLIENT_BOOLEAN_CONFIG_OPTIONS` in `initialize`)
127 and a two-value select for any other; `handle_set_session_config_option` takes either value.
128 `session/load` and `session/resume` share `restore_session`; the only difference is that
129 resume must not replay the history as `session/update`. `session/close` is the one place a
130 `SessionState` is dropped. It runs in two halves: `begin_close` signals the session's turn
131 from the dispatch loop (the turn holds the session's lock, so the signal cannot wait for it) and
132 marks the id in `closing_sessions`, which makes `handle_prompt` cancel a prompt that was
133 still queued; `handle_close_session` then runs under the session and workspace locks and
134 removes the state, the permission grants and the background commands
135 (`tools::kill_session_tasks`). It leaves `session_store` alone, so a closed thread still lists
136 and reopens. `session/delete` is the one that removes it from disk: it runs the same two halves
137 (`begin_close`, then `handle_close_session` from `handle_delete_session`) and then
138 `session_store::delete`, and succeeds for an id that is already gone. The
139 `SYSTEM_PROMPT` bakes in smbCloud-specific context the agent should use when the repo is clearly
140 smbCloud, and stay general otherwise.
141 - **`src/backend.rs`** — the `InferenceBackend` trait and neutral types (`ToolSpec`, `ToolCall`,
142 `ToolResult`, `TurnResult`). Two impls: `LocalBackend` (on-device via `onde::ChatEngine`) and
143 `OpenAiBackend` (any OpenAI-compatible HTTP endpoint). A `BackendError` is user-facing: the
144 ACP prompt handler passes it to the client verbatim and the editor puts it in an error banner,
145 so `describe_api_error` unwraps the OpenAI `{"error":{"message":…}}` envelope and shows that
146 message on its own, falling back to the status only when there is nothing to unwrap. An
147 endpoint can also fail *after* the response is open, reporting it as a `data:` frame holding
148 the same envelope; that frame has no `choices`, so `consume_stream` has to check for it
149 explicitly or it parses as an empty chunk and the turn ends looking like an empty answer.
150 `TurnResult::context_tokens` carries the endpoint's token count (prompt plus completion) up
151 to the loop, which sends it as a `usage_update` after each model response, with the
152 model's picker `context_window_tokens` as `size`; with no count (always on-device) the
153 history is estimated instead. A streamed request asks for the count with
154 `stream_options.include_usage`, and an endpoint that rejects the option is asked again
155 without it and never asked again (`stream_usage_refused`).
156 `TurnResult::finish` carries the endpoint's `finish_reason` up to the loop, and
157 `stop_reason_for` in `main.rs` turns it into the ACP stop reason: the tool-round cap is
158 `max_turn_requests`, `length` is `max_tokens`, `content_filter` is `refusal`. ACP defines a
159 refusal as a turn the next prompt will not include, so `handle_prompt` restores the history
160 it snapshotted before the turn instead of only relabelling the response.
161 The round that reaches the cap (24, or `SIGIT_MAX_TOOL_ROUNDS`) is followed by one forced
162 text reply with no tools. The model cannot see that the tools are gone, so
163 `round_cap_note` is appended to that round's last tool result, and the turn always closes
164 with `round_cap_stop_message`. Without both, the thread stops on the model announcing a
165 step that never runs (issue #120).
166 Some models write tool calls into content as text; `src/inline_tool_calls.rs` recovers the
167 well-formed ones. A block that doesn't parse (or never closes) is dropped from both the reply
168 and history, and `OpenAiBackend::complete` retries once with a note telling the model the call
169 didn't run. Leaving the raw block in history makes the model invent `<function_results>` later.
170 What that scanner lets through then goes through `src/harness_markup.rs`, which removes
171 markup the model makes up in the harness's shape (issue #122): a `<system_warning>`-style
172 block (any `system_*`/`system-*` tag) is dropped whole, from the reply and the history, and
173 other underscore-named tags like `<Option_Picker>` lose the tags but keep their text. Code is
174 never touched, and an opening tag only counts at the start of a line, since prose writes
175 placeholders like `<repo_url>` the same way. It has to run after the inline-call scanner,
176 because `<tool_call>` matches its underscore rule.
177 `src/repetition.rs` guards the same stream against a reply that degenerates into a loop over a
178 tiny vocabulary (issue #123): a window of 200 words with at most 40 distinct ones, fenced code
179 excepted, makes `consume_stream` stop reading, truncate the text to where the loop began (so
180 history never holds the junk), tell the user, and finish with `FinishReason::Repetition`
181 (`EndTurn` in ACP). `complete` then retries once with `REPETITION_RETRY`, like the malformed
182 tool call retry. Only the streaming path is guarded; `consume_json` and `LocalBackend` are not.
183 Image attachments: ACP fixes `promptCapabilities.image` for the whole connection, while the
184 model can change on any turn, so the capability is always advertised and the decision is made
185 per prompt. `InferenceBackend::accepts_images` answers for the active model (on-device: no;
186 remote: `provider::model_accepts_images`, which reads the hard-coded `IMAGE_TIERS` for
187 `onde-*` ids and says yes for a user's own endpoint). `images_for_turn` in `main.rs` either
188 passes the images to `send_message_with_images` or drops them with a note to the user and a
189 bracketed note to the model. A message with images is stored in history as OpenAI content
190 parts and stays that way; `OpenAiBackend` strips the images per request (`without_images`)
191 when its model cannot read them, which is what makes a mid-thread switch to a text-only tier
192 safe. Read history text through `backend::message_text`, never `content.as_str()`.
193 `IMAGE_TIERS` mirrors onde-cloud's `IMAGE_CANDIDATES`; update both together.
194 Audio attachments take the same path (`promptCapabilities.audio`, `accepts_audio`,
195 `audio_for_turn`, `without_audio`), sent as OpenAI `input_audio` parts. No cloud tier
196 takes audio, because onde-cloud drops `input_audio` parts when it parses a request, so
197 `provider::model_accepts_audio` says no for every `onde-*` id and yes for a user's own
198 endpoint. If onde-cloud ever routes audio, give it a tier table like `IMAGE_TIERS`.
199 - **`src/provider.rs`** — decides *which* backend serves inference. Resolution order, first match
200 wins: (1) override via `OPENAI_BASE_URL`+`OPENAI_API_KEY` or active profile in
201 `~/.config/sigit/providers.toml`; (2) siGit Code Cloud when logged in; (3) on-device.
202 - **`src/tools.rs`** — agent tool schemas + execution: `read_file`, `create_directory`,
203 `list_directory`, `search_files`, `glob`, `read_website`, `create_file`, `edit_file`,
204 `multi_edit`, `delete_file`, `run_command`, `write_todos`, `remember`. Add a tool in both the
205 spec list (`all_tools`) and the execute `match` (`execute_tool`). `run_command` also enforces
206 commit attribution: when a command creates a new commit that lacks the
207 `Co-Authored-By: siGit Code` trailer (`commit_co_author_trailer()`, which reads
208 `siGit Code v<version>-<acp|tui|headless>` from the surface `main` sets via `set_surface`), it amends the trailer in —
209 unless the commit already exists on a remote, which is never rewritten. Every child process it
210 spawns (`spawn_shell`, the `git` helpers, and `hooks.rs`) sets `stdin` to null and never
211 inherits it: in ACP mode sigit's stdin is the JSON-RPC pipe from the editor, so a command that
212 reads stdin both blocks forever and eats the client's next request, wedging the session past
213 any timeout. On Unix the shell also leads its own process group so the timeout kills the whole
214 tree, and stdout/stderr are drained on threads while the command runs — waiting first and
215 reading after deadlocks as soon as the output outgrows the pipe buffer. Also owns the `task`
216 tool: a nested agent loop in a fresh conversation, offered only when `subagent_available()`
217 (a subagent factory is registered — see `register_subagent_factory_for` in `main.rs`; on-device
218 registers a `None`-returning factory since onde has a single shared history). A subagent's
219 toolset is a hard-gated read-only allow-list (`SUBAGENT_TOOL_NAMES`) that is never expanded by a
220 configurable subagent type (see `src/subagents.rs`) — only ever narrowed — so a `.sigit/agents/*.md`
221 file can't grant itself `edit_file`/`run_command` and bypass the permission system. Also owns
222 `web_search`: a thin native wrapper around the official MCP server's Brave-Search-backed
223 `web_search` tool (`mcp__sigit__web_search`, implemented server-side in `sigit-si`'s
224 `WebSearchService` + `Mcp::Tools::WebSearch`), offered only when that MCP tool was actually
225 discovered (i.e. the user is signed in to siGit Code Cloud — see `web_search_available`).
226 Wrapping it natively rather than leaving it as a raw `mcp__*` tool matters for two reasons:
227 `permissions::classify` treats every `mcp__*` tool as mutating (an "ask" prompt on every call),
228 while `web_search` is read-only like `read_website`; and the raw delegate name is filtered out
229 of the assembled tool list (`is_web_search_delegate`) so the model sees one clean option, not
230 two names for the same tool. Execution still forwards verbatim to `mcp::call_tool` — no second
231 HTTP/JSON-RPC implementation.
232 - **`src/skills.rs`** — [Agent Skills](https://agentskills.io) support. Discovers skill
233 folders (each with a `SKILL.md`: YAML frontmatter `name` + `description`, then Markdown
234 instructions) from `.sigit/skills/` and `.claude/skills/` in every project root (see `src/workspace.rs`),
235 `$SIGIT_CONFIG_DIR/skills/`,
236 and `~/.claude/skills/`. Progressive disclosure: the discovery list (name + description) is
237 baked into the dynamically-built `skill` tool's description, and activating a skill (the model
238 calls `skill` with a name) loads the full `SKILL.md` body. The `skill` tool is appended in the
239 `*_as_specs`/`build_tool_specs` layer (not in `all_tools()`) so its description can be dynamic,
240 and only when at least one skill exists.
241 - **`src/commands.rs`** — user-defined slash commands. Discovers Markdown files (each an
242 optional YAML frontmatter block — `description`, `argument-hint` — followed by a prompt-template
243 body) from `.sigit/commands/` and `.claude/commands/` in every project root, `$SIGIT_CONFIG_DIR/commands/`,
244 and `~/.claude/commands/`. A subdirectory namespaces the command with `:`
245 (`.sigit/commands/git/commit.md` → `/git:commit`). Unlike skills there's no tool-call
246 indirection: invoking one works exactly like the built-in `/init` — `commands::render`
247 substitutes `$ARGUMENTS`/`$1..$9` in the body against whatever followed the command on the
248 input line, and the result is fed to the model as a normal turn through the ordinary tools and
249 permission checks. Resolution happens where each surface (`main.rs`/`chat.rs`) already
250 special-cases `/init`: an unrecognized slash command is tried against `commands::resolve_command`
251 before falling back to "unknown command". A custom command sharing a name with a built-in is
252 unreachable (built-ins match first in `parse_slash`) and is skipped when advertised to ACP
253 clients, with a warning logged.
254 - **`src/subagents.rs`** — configurable subagent types for the `task` tool. Discovers Markdown
255 files (YAML frontmatter `name` + `description`, optional comma-separated `tools:` allow-list,
256 then a Markdown body that becomes the subagent's system prompt) from `.sigit/agents/` and
257 `.claude/agents/` in every project root, `$SIGIT_CONFIG_DIR/agents/`, and `~/.claude/agents/`. Passing a
258 type's `name` as `task`'s `subagent_type` argument swaps in that system prompt and, if `tools:`
259 is set, narrows the offered toolset to its *intersection* with `SUBAGENT_TOOL_NAMES` — the
260 security-relevant narrowing logic lives in `tools.rs` next to that constant, not here; this
261 module only discovers and parses files. `SubagentFactory` (in `tools.rs`) takes the resolved
262 system prompt per call rather than baking one in at registration, so a single registered
263 factory serves both the default research subagent and every configured type.
264 - **`src/frontmatter.rs`** — shared "YAML frontmatter + Markdown body" parsing used by both
265 `src/skills.rs` (`SKILL.md`) and `src/commands.rs` (`.sigit/commands/*.md`).
266 - **`src/mcp.rs`** — [Model Context Protocol](https://modelcontextprotocol.io) *client*. Two
267 transports: **Streamable HTTP** (one JSON-RPC POST endpoint, `url` in `mcp.toml`; replies are
268 `application/json` or SSE) and **stdio** (`command` + optional `args`/`[server.env]` in
269 `mcp.toml`; sigit spawns the server and speaks newline-delimited JSON-RPC over its
270 stdin/stdout, stderr inherited into sigit's log). `url` and `command` are mutually exclusive —
271 both or neither is a config error, logged and skipped. Both transports run the same
272 `initialize`/`tools/list` handshake and forward `tools/call`. Discovery is best-effort at
273 startup (`mcp::init`, called from both branches of `main()`) and cached in a process-global so
274 the synchronous spec builders (`mcp::tool_specs`) and the async dispatch (`mcp::call_tool`) can
275 both read it; `/reload` does *not* re-run it, so config changes need a restart. stdio children
276 live for the process; a dead child fails calls with an in-band error string (no auto-restart).
277 Tools are namespaced `mcp__<server>__<tool>`, appended in the `*_as_specs`/`build_tool_specs`
278 layer and routed in `tools::execute_tool` via `mcp::is_mcp_tool`. Two servers are baked in:
279 the official server (`<cloud>/mcp`, default `https://sigit.si/api/v1/mcp`, always HTTP, authed
280 with the cloud session token) and the smbCloud CLI server (`smb --mcp`, stdio, added only when
281 the `smb` binary is on `PATH`; opt out with `smbcloud = false` in `mcp.toml` or
282 `SIGIT_MCP_SMBCLOUD=off`). A user-defined entry named `sigit` or `smbcloud` overrides the
283 corresponding baked-in one. Extra servers live in `mcp.toml` (global
284 `$SIGIT_CONFIG_DIR/mcp.toml` and project-local `.sigit/mcp.toml`). The stdio path is covered by
285 `tests/mcp_stdio.rs`, driven by the test-only `src/bin/mcp_stdio_stub.rs` helper binary
286 (excluded from the published crate via `exclude` in `Cargo.toml`). The baked-in official
287 server is *also* listed in the public MCP Registry as `si.sigit/sigit` — a **remote**
288 Streamable-HTTP listing owned by the [`getsigit/si`](https://github.com/getsigit/si) repo
289 (`server.json` at its root, published by its `release-mcp-registry.yml`), not this one. Because
290 it's a remote server, the registry's URL-match rule forces a domain namespace (`si.sigit` ↔
291 `sigit.si`) verified by a DNS TXT record, not the GitHub-OIDC scheme `smbcloud-cli` uses for its
292 package listing.
293 Separate from all of the above are the servers an ACP client passes in `mcpServers` on
294 `session/new`, `session/load` and `session/fork`. ACP requires agents to connect to the stdio
295 ones, and they belong to the session that named them, so they cannot live in the startup
296 global: `connect_session_servers` returns a `SessionServers` that `main.rs` keeps on
297 `SessionState` and installs with `set_session_servers` whenever a session becomes live, the
298 same way it swaps the roots. `tool_specs`, `call_tool` and `/mcp` read the startup servers and
299 then the live session's. A client-supplied server whose name is already taken by a startup
300 server is not connected, since both would claim the same `mcp__<server>__` prefix. Streamable
301 HTTP entries are connected too, with the URL and headers the client sent, because
302 `handle_initialize` advertises `mcpCapabilities.http`. SSE is not advertised (the MCP spec
303 deprecated it), so a conforming client never sends one and a stray entry is skipped.
304 An MCP server's `elicitation/create` is not forwarded to the ACP client as a form
305 elicitation: `ed-mcp`'s client handler declares no capabilities and has no hook for it, so
306 servers are never offered elicitation, and `rmcp` answers `ping` and refuses other server
307 requests itself. Forwarding needs that hook in `ed-mcp` first
308 (tracked upstream at `ondeinference/ed#33`).
309 - **`src/permissions.rs`** — tool permission policy. Every tool call passes through
310 `decision_for` before executing: read-only tools always run; mutating tools (and all
311 `mcp__*`/unknown tools) are governed by, in order: per-session plan mode (`/plan` — deny all
312 mutating tools with a present-a-plan message), session "always deny" and "always allow"
313 choices (deny checked first, both scoped by `session_grant_rule` and dropped with the session),
314 per-tool overrides and the default mode from `[permissions]` in `settings.toml`
315 (`allow`/`ask`/`deny`, default `ask`; `SIGIT_PERMISSIONS` env overrides the default). On `ask`,
316 the ACP path sends `session/request_permission` (allow once / allow for session / deny / deny
317 for session) and the TUI pauses the inference task on a y/a/n/d prompt. On the ACP path the decision is taken *before* the call is
318 announced, because it sets the announced status: a call that will ask starts `pending`, the
319 permission request carries that call's own id, and an `in_progress` update follows approval.
320 That update also puts the card's title back, since the permission request overwrites it
321 with the full arguments. The Manual/Auto/Plan choice reaches an ACP client twice: as the
322 `sigit-permission-mode` config option, and as session `modes` with `session/set_mode`, which
323 the spec is retiring but some clients still render instead. Both are built from
324 `PERMISSION_MODES` in `main.rs` and read the same state, so whatever changes the mode has to
325 refresh both (`ConfigOptionUpdate` and `send_current_mode`). Note: ACP turn-affecting handlers run in `cx.spawn`ed tasks
326 so the dispatch loop can route the client's permission answer mid-turn — don't move them back
327 inline, and don't await client requests from inline handlers (deadlock). Two locks order them.
328 A per-session lock (`SiGitAgent::session_lock`) is held for a whole request, so requests on one
329 thread keep their order. `SiGitAgent::workspace_lock` guards what a session installs
330 process-wide (cwd, workspace roots, session MCP servers, the live backend slot, the engine's
331 conversation); lifecycle and config handlers hold it throughout, and `handle_prompt` holds it
332 through a `WorkspaceHold` that it releases while waiting on an HTTP endpoint or a permission
333 answer and retakes (reinstalling its session via `resume_workspace`) before any tool runs. An
334 on-device turn never releases it. Take the session lock first, never the other way round. A turn registers its `PromptCancellation` at
335 the top of `handle_prompt`, before it waits on either lock, and a `PromptRegistration`
336 guard clears it on every return, so a `session/cancel` that arrives while the turn
337 is still queued, switching threads, loading a model or running a slash command ends
338 it as `cancelled`. The checks sit after each of those waits. A cancel (and
339 `begin_close`) also raises the session's `tools::AbortSignal`, which the local
340 `run_command` poll loop and `client_terminal::Route::run` watch, so a running
341 foreground command is killed instead of finishing first. The signal is reset at the
342 top of each turn, not when a tool starts, so a cancel that lands during a permission
343 prompt still stops the command that follows. Permission-mode changes
344 (`session/set_mode`, and `session/set_config_option` for `sigit-permission-mode`) are
345 the exception to the lock order: the dispatch loop runs them with neither lock, because
346 they touch only state keyed by session (`permissions`) and have to land mid-turn. They
347 check the id against `sessions` (`-32002` when unknown) and build the options from
348 that session's own model (`config_options_for_session`), never `activate_session`. Unknown session ids are `-32002` (resource not found) everywhere,
349 and `authenticate` accepts only `AUTH_METHOD_ID`. Tool
350 execution, subagents included, still runs one session at a time.
351 - **`src/instructions.rs`** — project instruction files, the always-on counterpart to skills.
352 Reads `AGENTS.md` (the cross-tool [agents.md](https://agents.md) standard) and `CLAUDE.md`,
353 walking from the session cwd up to the repo root (nearest ancestor with `.git`, never above it),
354 plus a global file under `$SIGIT_CONFIG_DIR`. Files are ordered outermost-first so the deepest
355 (most specific) wins. In a multi-root project that walk is repeated for every root
356 (`load_workspace_instructions`). The combined block is injected via `session_context_message`
357 in `main.rs` — pushed as a system message at every ACP session entry point (new/load/fork +
358 model switch) and appended to the system prompt on the cloud and TUI-startup paths.
359 - **`src/workspace.rs`** — the directories the session treats as project roots. An editor can
360 open several at once (Zed calls it a multi-root project) and ACP carries the extras as
361 `additional_directories` on every session request; the headless CLI takes them as repeatable
362 `--add-dir` flags. A client only sends those extras to an agent that advertises
363 `sessionCapabilities.additionalDirectories` in its `initialize` reply, so that capability in
364 `handle_initialize` is what makes the rest of this reachable — without it Zed keeps the first
365 root, drops the others, and shows "This agent doesn't currently support multi-root workspaces".
366 The process still has one working directory, so the extra roots live in a
367 process-global here and `project_dirs()` returns cwd-first, extras after.
368 One process also serves every thread the editor has open, so that global
369 (with the cwd, the backend conversation, and the background-task owner in
370 `tools.rs`) always belongs to the *live* session: `main.rs` keeps a
371 `SessionState` per session id and `activate_session` parks the live one and
372 installs the requested one before any prompt or config change runs. Don't
373 read another session's roots from the global. Project-local
374 discovery reads it: skills, slash commands, subagent types, and instruction files all scan
375 every root. MCP is deliberately not on that list — `mcp::init` runs once at startup, before
376 any session exists, so a second root's `.sigit/mcp.toml` has nobody to tell. (The servers a
377 client names in `mcpServers` are a different thing and are per session; see `src/mcp.rs`.)
378 - **`src/client_fs.rs`** — file reads and writes through the ACP client. A client that
379 advertises `fs.readTextFile` / `fs.writeTextFile` in `initialize` serves `fs/read_text_file`
380 and `fs/write_text_file` from its buffers, so `read_file` sees unsaved changes and
381 `edit_file` lands in the open buffer instead of underneath it. `tools.rs` has no access to the
382 connection, so this is a seam like the one `mcp::call_tool` gives MCP: `handle_initialize`
383 registers a `ClientFileSystem` (`AcpClientFs` in `main.rs`, holding the connection), and
384 `execute_tool_impl` asks `route_for` before it dispatches `read_file`, `create_file`,
385 `edit_file` or `multi_edit`. Each of those tools is split into a parse step and a pure
386 render/apply step (`ReadFileCall`, `CreateFileCall`, `EditCall`) that the disk path and the
387 client path share, so the model gets the same result text either way. The writing tools also
388 hand back the file before and after (`tools::FileChange`, via `execute_tool_with_change`), which
389 `handle_prompt` sends as ACP `diff` content ahead of the result text. A permission request for
390 one of them carries the same diff, worked out by `preview_file_change` without writing anything
391 and before the workspace is released, since a relative path resolves against the session's cwd. The two capabilities are
392 independent: a client that only reads still gets its edits written to disk. The disk is the
393 fallback throughout: nothing is registered in the TUI or headless modes, a path outside the
394 session's roots is not routed, and a request the client fails or leaves unanswered for 30
395 seconds is retried on disk with a warning in the log. The client is only ever asked from
396 inside a spawned prompt turn, never from `handle_initialize` itself (deadlock, same as
397 permission requests). Existence checks and `create_file`'s parent directories still use the
398 disk. `SIGIT_CLIENT_FS=off` turns the routing off. Covered by `tests/acp_client_fs.rs`.
399 - **`src/client_terminal.rs`** — `run_command` in the ACP client's terminal. A client that
400 advertises `terminal` in `initialize` runs a foreground command itself (`terminal/create`, with
401 the platform shell as `command` and the whole command line as one argument), and
402 `exec_run_command_via_client` embeds the terminal in the tool call as `terminal` content, so the
403 user watches the output live and can stop the command from the editor. The seam is
404 `client_fs`'s: `handle_initialize` registers `AcpClientTerminal`, and `execute_tool_impl` asks
405 `client_terminal_route` before the blocking path. Embedding needs the tool call's id, which is
406 why `execute_tool_with_change` takes one. What `run_command` promises stays put: the 120 s
407 timeout ends in `terminal/kill`, the output is capped, and `CommitWatch` still amends the
408 co-author trailer, checking HEAD on disk before and after. Background commands stay local
409 (`command_output` and `kill_command` read their pipes), and so does a command whose directory
410 is outside the session's roots, since nothing says the editor's machine can see it. A
411 `terminal/create` the client fails means nothing ran, so the command runs locally; a failure
412 after that is reported as the tool's error instead, because running it again could repeat its
413 effects. The finished card keeps the terminal and drops the result text, which still goes out
414 as `raw_output`. `SIGIT_CLIENT_TERMINAL=off` turns the routing off. Covered by
415 `tests/acp_client_terminal.rs`.
416 - **`src/chat.rs`** — the Unix-only ratatui TUI. Loading-spinner phase then chat; uses
417 `tokio::select!` to multiplex terminal events with streaming tokens.
418 - **`src/headless.rs`** — non-interactive `sigit run` execution for scripts, CI, and Factory
419 clients. The legacy `-p` form reaches the same parser. Every new run gets a UUID session id;
420 `--resume <id>` restores that session through `session_store`, and `--output jsonl` emits a
421 structured session/delta/tool/result stream while logs stay on stderr. Headless permission
422 prompts collapse to denial unless the tool was pre-approved with `--allow-tool`.
423 - **`src/session_store.rs`** — durable conversations: one JSON-lines history file per session at
424 `$SIGIT_CONFIG_DIR/sessions/<id>.jsonl`, written atomically, restorable into either backend.
425 Each save also writes a `<id>.meta.json` sidecar naming the session's `cwd` and the extra roots
426 of a multi-root project. That sidecar is what makes a thread *listable*: ACP's `session/list`
427 (advertised as `sessionCapabilities.list`, handled by `handle_list_sessions` in `main.rs` — the
428 editor's "Import Threads" picker) must report an absolute `cwd` per session and may filter on
429 it, so a session without one is skipped there while still reopening by id through
430 `session/load`. Sidecars are written at save time, not at session start, so a thread nobody
431 spoke in leaves nothing behind. Each ACP save (`persist_session` in `main.rs`) is also sent to
432 the client as a `session_info_update` carrying a fresh `updatedAt`, plus the title when it
433 differs from the last one sent (`announced_titles`), so a new thread gets its title in the
434 sidebar without waiting for the next `session/list`.
435 - **`src/setup.rs`** — model cache location, local model discovery, selected-model persistence.
436 Must run (`setup_shared_model_cache`) *before* anything touches `ChatEngine`/`hf-hub`, since
437 those read env vars once at init.
438 - **`src/account.rs`** — siGit Code Cloud auth (`/login`, `/logout`, `/whoami`); authenticates
439 against the account API and stores a session token. Performs no console I/O.
440 ACP `logout` (the editor's sign out button, shown only because `handle_initialize` advertises
441 `agentCapabilities.auth.logout`) and `/logout` both go through `SiGitAgent::sign_out` in
442 `main.rs`. The request names no session, so `leave_cloud` moves the parked threads off their
443 cloud tier along with the live one and each of them gets a fresh model picker.
444 - **`src/browser_auth.rs`** — browser sign-in, the path the editor's "Sign in to siGit Code"
445 button takes. sigit is a public OAuth client (client id `sigit-code-cli`, no secret, PKCE
446 S256) against the authorization server at `$SIGIT_API_URL/oauth`. Two ways the code gets
447 back: a loopback listener on `127.0.0.1:0` (the registration lists `http://127.0.0.1/callback`
448 with no port, and RFC 8252 §7.3 matching ignores the port, so one registration covers every
449 run), or the out-of-band URN, where the server renders the code and the user pastes it. The
450 resulting token goes into `credentials` like any other, and is served by `/api/v1/user` rather
451 than the deprecated `/api/v1/me` — OAuth tokens are rejected there. The scopes requested are
452 `user:read code:agent`; `code:agent` is what reaches `chat/completions` and the official MCP
453 server. Surfaces: ACP `authenticate` (loopback only, since a code cannot be pasted back; for a
454 client that advertises `elicitation.url`, `sign_in_via_client` hands it the authorize URL as a
455 URL-mode elicitation instead of launching a browser, ends the sign-in if the user declines, and
456 sends `elicitation/complete` once the code is redeemed; `authenticate` runs in a spawned task
457 so that answer can be routed), a bare `/login`
458 in either chat surface, and `sigit login` (which adds the paste fallback, plus `--paste` to
459 force it and `--password` for the old email/password prompt).
460 - **`src/credentials.rs`** — local session-token store (TOML, `0600` on Unix).
461 - **`src/models.rs`** — model-picker types shared across platforms.
462
463 Slash commands (`/help`, `/models`, `/skills`, `/agents`, `/commands`, `/mcp`, `/login`, `/logout`,
464 `/whoami`, `/reload`, `/plan`, `/permissions`, `/init`, `/clear`, `/status`) are advertised via
465 `advertise_commands` in `main.rs` and handled in both the TUI and ACP sessions. `/init` is
466 special: instead of replying directly it substitutes `instructions::INIT_PROMPT` for the user
467 text and runs a normal agent turn that explores the repo and writes (or improves) `AGENTS.md`
468 through the ordinary tools and permission checks. User-defined commands (see `src/commands.rs`)
469 get the same treatment via the `SlashCommand::Unknown` fallback path, so anyone can add their own
470 `/name` commands without touching the built-in command list.
471
472 ## Model cache (macOS)
473
474 On macOS the HF model cache lives in an App Group container shared with the siGit desktop app:
475 `~/Library/Group Containers/group.com.ondeinference.apps/models/`. Other platforms fall back to
476 `~/.cache/huggingface/`. The CLI reuses a model the desktop app already downloaded. First run
477 downloads a GGUF model (~1–2 GB) from Hugging Face.
478
479 ## Logging
480
481 In TTY (interactive) mode, *all* output — `log`, `tracing`, stray `println!` — is redirected to
482 `$TMPDIR/sigit.log` so the ratatui surface stays clean; the TUI holds a separate fd to the real
483 terminal. In ACP mode, stdout is reserved for protocol JSON and logs go to stderr. Control
484 verbosity with `RUST_LOG`.
485
486 ## Relevant env vars
487
488 `OPENAI_BASE_URL` / `OPENAI_API_KEY` (provider override), `SIGIT_API_URL` (account API base,
489 default `https://sigit.si`), `SIGIT_CLOUD_URL`, `SIGIT_CONFIG_DIR` (default `~/.config/sigit`),
490 `SIGIT_MODEL`, `SIGIT_MAX_TOOL_ROUNDS` (1 to 500, default 24; the tool-round cap of a
491 headless run or an ACP prompt turn), `SIGIT_MCP` (`off` disables MCP), `SIGIT_CLIENT_FS` (`off` keeps the file tools on disk even when the
492 ACP client offers `fs/read_text_file` / `fs/write_text_file`), `SIGIT_CLIENT_TERMINAL` (`off` runs
493 `run_command` locally even when the ACP client offers a terminal), `SIGIT_MCP_SMBCLOUD` (`off` drops the baked-in
494 smbCloud CLI server), `SIGIT_MCP_OFFICIAL` (`off` drops the baked-in
495 server), `SIGIT_PERMISSIONS` (`allow`/`ask`/`deny` — overrides the default permission mode for
496 mutating tools; the escape hatch for clients without permission-request support),
497 `HF_HOME` / `HF_HUB_CACHE`, `RUST_LOG`.
498
499 ## Releasing
500
501 Version lives in `Cargo.toml`. Update `CHANGELOG.md` for releases.
502
503 Publishing splits into two groups. **Language registries** each get their own tag-triggered
504 workflow: `release-crates`, `release-npm`, `release-nuget`, `release-pypi`. The `npm/`, `nuget/`,
505 and `pypi/` dirs hold their wrapper-package templates.
506
507 npm and NuGet authenticate with OIDC (Trusted Publishing), so neither needs a stored token. On
508 npm that is configured per package, not per org: all seven `@getsigit/*` names carry a trusted
509 publisher pointing at `release-npm.yml`, and a package added later needs the same setup or its
510 publish step will fail. OIDC also requires npm >= 11.5.1 and Node >= 22.14.0, which is why the
511 workflow upgrades npm and why `.nvmrc` cannot drop below 22.
512
513 **OS package managers** all publish somewhere outside this repo and all need checksums from the
514 GitHub release, so `release-github` builds the binaries, attaches the assets, and then dispatches
515 `release-homebrew`, `release-scoop`, `release-winget`, and `release-aur`. A dispatch failure in one
516 is logged as a warning rather than failing the others, so an unconfigured channel does not block a
517 release. Their inputs live in `packaging/`.
518
519 The Windows binaries link the MSVC C runtime statically (`+crt-static` in `.cargo/config.toml`).
520 winget, Scoop, npm, PyPI and NuGet all ship the bare exe with no installer, so a dynamic build
521 that imports `VCRUNTIME140.dll` fails to load on a machine without the VC++ Redistributable
522 (`0xC0000135`, which is what failed winget's first validation).
523 `packaging/windows/check-static-crt.ps1` runs in CI and in `release-github` and fails the build if
524 a Windows exe imports the runtime again. Don't set a `RUSTFLAGS` env var in those workflows: it
525 replaces the config rustflags instead of adding to them.
526
527 Every release asset now carries a `.sha256` sidecar, not just the macOS Homebrew tarball. Scoop,
528 winget, and the AUR PKGBUILD each need one, and they consume the raw binaries rather than the
529 tarball. `release-github` also builds a `.deb` and `.rpm` per Linux target with nfpm
530 (`packaging/nfpm.yaml`), packaging the already-built binary rather than re-invoking cargo.
531
532 Re-pushing a tag fires every release workflow a second time, so each one is grouped by tag in a
533 `concurrency` block with `cancel-in-progress: false` — the duplicate queues behind the original
534 rather than interrupting a publish that is halfway through uploading. What keeps the queued run
535 from going red is the "is this version already published?" check each publishing workflow does
536 before it uploads. Those checks are load-bearing, not belt-and-braces: v1.5.6 published twice
537 because the crates.io one asked the API with curl's default User-Agent, which crates.io answers
538 with a 403, which read as "not published yet".
539
540 Three of these need credentials or a one-time manual step before they work:
541
542 - Scoop needs a `getsigit/scoop-bucket` repo and a `SCOOP_BUCKET_TOKEN` secret, mirroring the
543 Homebrew tap setup.
544 - winget files a Package Request issue first and then opens the manifest PR that resolves it,
545 authored by two separate classic PATs (replacing the old single `WINGET_TOKEN`):
546 `WINGET_ISSUE_TOKEN` (`public_repo`) for the issue and `WINGET_PR_TOKEN` for the PR.
547 `WINGET_PR_TOKEN` needs `public_repo` plus `read:org` and `read:discussion`: `public_repo`
548 lets `wingetcreate` fork `microsoft/winget-pkgs` and open the PR, and the later `gh pr edit`
549 that sets the PR body runs a GraphQL query resolving org/team and discussion fields that
550 fails with a scope error on a `public_repo`-only token. The PR token is passed as
551 `WINGET_CREATE_GITHUB_TOKEN` rather than `--token`, which wingetcreate warns can leak the
552 token into logs. `wingetcreate update` only works on a package that already exists in
553 `microsoft/winget-pkgs`, so the workflow checks the `manifests/g/getSigit/siGitCode` path
554 first and falls back to rendering `packaging/winget/*.yaml.in` and running
555 `wingetcreate submit` for a first submission. That fallback runs once, then every later
556 release takes the `update` path. Two non-obvious things in the update path: the `--urls`
557 arguments carry a trailing `|x64` / `|arm64` suffix that tells wingetcreate which installer
558 entry each URL replaces — without it, wingetcreate guesses from the file name, and
559 "sigit-win-amd64.exe" is not a spelling it recognises; and the first-submission render
560 uppercases the SHA256 (`tr '[:lower:]' '[:upper:]'`) to match the community validation
561 pipeline, which writes 64-hex checksums uppercase. The update path also passes
562 `--release-date`, `--release-notes-url`, `--submit`, and `--no-open` explicitly.
563 - The AUR needs `AUR_USERNAME`, `AUR_EMAIL`, and `AUR_SSH_PRIVATE_KEY`. It publishes `sigit-bin`
564 (a prebuilt binary) so Arch users are not compiling the on-device inference stack to install a
565 CLI.
566
567 `[profile.release]` sets `strip = "symbols"` because binary size is a distribution constraint, not
568 just a nicety. See the NuGet note below.
569
570 The NuGet package (`SiGit.Code`, installed with `dotnet tool install --global SiGit.Code`) is the
571 odd one out among the language registries: npm and PyPI publish one artifact per platform, but a
572 .NET tool is a single package, so `nuget/sigit/` bundles all six binaries under
573 `native/<os>-<arch>/` and a small managed shim (`Program.cs`) execs the right one. That shim leaves
574 stdin/stdout/stderr unredirected on purpose, since siGit Code chooses TUI or ACP mode by testing
575 whether stdin is a TTY. It also sets `RollForward=Major`: it targets `net8.0`, and without that a
576 machine carrying only the .NET 10 runtime installs a tool that refuses to start.
577
578 Bundling every target means the package is large, so `release-nuget.yml` fails the pack job if the
579 `.nupkg` crosses nuget.org's 250 MB limit. At v1.5.1 it lands around 160 MB. If a future release
580 trips that check, the fix is not to drop targets but to split into RID-specific tool packages
581 (.NET 10's `DotnetToolRidPackage`), which ship one binary per platform the way npm already does.
582 That also needs a fallback package for pre-.NET-10 SDKs.