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