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