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