Improve/agent flow

[Vect0rM]

Describe Your Changes

Fixes Issues

• Closes #
• Closes #

Self Checklist

• Added relevant comments, esp in complex areas
• Updated docs (for bug fixes / features)
• Created issues for follow-up changes or refactoring needed

[Vect0rM]

397 files and +48k/−4.7k is past the point where reading the diff tells you much, so I built and ran it instead. Headline: everything the repo's own gates check is green except make test-quality, and the branch no longer merges. The code itself holds up well under the checks below — the open items are mostly hygiene, plus one real gap in a redaction helper.

Verified on improve/agent-flow merged onto current main (073c885)

• tsc -b — exit 0.
• yarn lint — 0 errors, 13 warnings. 11 are in files this branch doesn't touch. Of the two that are, ApiStatusIndicators.tsx is new here (react-refresh/only-export-components).
• Full vitest run — 264 files, 2552 passed, 16 skipped. Baseline on main is 229 / 2221 / 16, so the 36 new test files land clean with nothing else disturbed.
• make test-extensions — 22 files, 602 passed across llamacpp, llamacpp-upstream, mlx and download.
• make test-hardening-contracts — 25/25.
• make test-rust — 778 passed, 3 failed. All three reproduce on main in the same container, so none are this branch's:
  • skill_run_script::tests::{cancellation,timeout}_terminates_descendant_processes — fail on main too.
  • contract_tests::filesystem_trash_moves_directories_through_the_native_trash_api — asserts the native trash API does not create ~/.local/share/Trash/files, which on Linux it legitimately does. It's self-skipping when that directory already exists, so it passes on a second run and fails on a clean one. I confirmed on main with the directory removed: same failure. Worth an explicit #[cfg(not(target_os = "linux"))] rather than leaving it order-dependent, but that's a separate change.

Two environment notes for anyone reproducing this on Linux: the build now needs libasound2-dev (see item 6), and core has to be built and packed before the web tests resolve @janhq/core.

Blockers

1. Merge conflict against main

One file, one line — docs/decisions/INDEX.md:

<<<<<<< HEAD
216 records, 2026-05-19 → 2026-08-25.
=======
227 records, 2026-05-19 → 2026-08-27.
>>>>>>> improve/agent-flow

Taking either side is wrong. The merged tree has 228 record files, and this branch's index is missing a row for 2026-08-25-add-atomic-agent-as-a-one-click-launch-page-assistant.md, which arrived on main via #258. The index is hand-maintained, so it needs regenerating against the merged set rather than a pick.

2. make test-quality is red, and two of the three entries are new here

- [call-only-assertions] web-app/src/containers/__tests__/ThreadList.test.tsx
- [call-only-assertions] web-app/src/hooks/__tests__/useThreads.test.ts
- [call-only-assertions] web-app/src/lib/ensure-embeddings.test.ts

ThreadList.test.tsx is pre-existing — it flags on main too, and this branch doesn't touch it. The other two are yours:

• useThreads.test.ts — cleans up the vector collection with the bare thread id and clears per-thread agent state on bulk deletes assert only toHaveBeenCalledWith.
• ensure-embeddings.test.ts — warms up once and memoizes success and shares one in-flight warm-up between concurrent sends assert only toHaveBeenCalledTimes.

For the memoization and dedup cases the call count genuinely is the observable behaviour, so allowlisting looks right rather than contorting the assertions. You already extended tests/test-quality-allowlist.json by 13 entries in this branch; these two were missed. Adding them takes the gate from 3 entries to 1, and the remaining one is main's problem.

Worth deciding either way, because test-quality sits inside make verify-fast, so it gates every agent-authored change behind it.

3. maskSensitiveUrl misses the two places an MCP secret actually lives

web-app/src/lib/mask-sensitive-url.ts, rendered at ConnectedServerCard.tsx:108. The query-parameter path works. Running the function over the shapes an MCP server URL actually takes:

"https://user:s3cr3t@mcp.example.com/sse"       -> "https://user:s3cr3t@mcp.example.com/sse"
"https://mcp.example.com/sse?api_key=abc123"    -> "https://mcp.example.com/sse?api_key=******"
"https://mcp.example.com/sse#token=abc123"      -> "https://mcp.example.com/sse#token=abc123"

Basic-auth userinfo is one of the most common ways a hosted MCP endpoint carries a credential, and URL.toString() preserves it verbatim — so the card displays the password in full, which is the one thing this helper exists to prevent. The fragment has the same gap. Both are a couple of lines:

if (urlObj.password) urlObj.password = '******'
if (urlObj.username) urlObj.username = '******'

Two smaller things in the same function: ?key=a&key=b collapses to a single key=****** because params.set drops duplicates (harmless — it masks more, not less), and a token carried in the path (/sse/tok_live_…, which several hosted servers use) isn't reachable by any query-param rule. The path case may be out of scope; the userinfo one isn't.

The file has no test. Given what it's for, it should — the three lines above are most of the fixture.

Should fix before merge

4. The description is the untouched template

## Describe Your Changes is a bare -, and both Closes # lines are empty. For a change this size — carrying five new ADRs, a new OAuth provider, a new audio plugin, PTY-backed process tools and a code index — the description is what ends up in the merge commit and in git log for everyone afterwards. The ADRs are excellent and do the hard part; the description mostly needs to point at them and say what a user gets.

5. release: v2.0.24 is in the feature branch

9d8069a bumps web-app/package.json and src-tauri/tauri.conf.json. Every other version bump in this repo is its own commit on main (9097a05, 3b625ff), and carrying it here means the branch's mergeability is tied to whenever the next release is actually cut. Cleaner dropped from the branch and done separately after this lands.

Nits

6. libasound2-dev is a new build prerequisite on Linux. cpal/alsa/alsa-sys are new in Cargo.lock, and without the headers cargo fails at alsa-sys's build script rather than anywhere informative. You already added it to release.yml, which is the part that matters — but nothing tells a contributor building locally, and DEVELOP.md has no prerequisites section to put it in.

7. Prettier. 52 of the 111 new web-app source files come up unformatted, plus 5 modified files that are clean on main (NavMain.tsx, DeleteAllThreadsDialog.tsx, SettingsMenu.test.tsx, custom-chat-transport.harness.test.ts, settings/providers/__tests__/index.test.tsx). Nothing enforces this — .husky/pre-commit runs yarn lint --fix only — so it's cosmetic, but 52 files is enough drift to be worth one prettier --write pass over the added files.

8. os.code.symbols / os.code.refs aren't path-aware. Both resolve a path in prepare_call_paths, but neither is in is_path_aware_filesystem_tool, so an out-of-root path gets escaped_root and a per-call approval with no FolderAccessRequest — the user can approve once but never connect the folder. os.media.transcribe was added to that list in the same diff, so the omission reads like an oversight rather than a decision. Not a safety hole (the stricter path is the one taken), just a dead end for the user.

9. resolveThreadExecutionRoute(_threadId, turn) ignores its first argument. The underlying resolveMessageExecutionRoute is well covered in agent-route.test.ts, so this is only the store-reading adapter — but a function that takes a thread id and routes globally will mislead the next caller who assumes per-thread routing works.

10. agent-workspace-actions.ts has no test. It's 26 lines, but it's the entry point that grants canEdit: true on a folder the user picks, i.e. the thing that widens the agent's editable roots. A test pinning that grant is cheap insurance.

---

Nothing above is structural. The parts I looked at closely are careful work: every unwrap() in pty.rs and openai_client.rs is inside a #[cfg(test)] module, store.rs sets 0o600 on OpenOptions rather than chmod-after-create, no token crosses the IPC boundary, the connector secret input is type="password", and the new capability grant is a single atomic-audio:default line. The ChatGPT ADR recording the client-id decision before any code was written is exactly the right way to have handled that one 🚀

---

Generated by Claude Code