Skip to content

Fork: assistant setup (switch, built-in assistant profile, Make assistant) - #953

Open
scuttletoby wants to merge 3 commits into
mainfrom
fork/assistant-setup
Open

scuttletoby wants to merge 3 commits into
mainfrom
fork/assistant-setup

Conversation

@scuttletoby

@scuttletoby scuttletoby commented Nov 22, 2026 •

Copy link
Copy Markdown
Owner

Assistant PR 2 of 18 (#879). Builds on #927 (builtinTools: "none") and #928 (threadRoles).

What and why

The assistant is one long thread you talk to across projects. This PR lets you set it up. It is off by default.

  • Settings block assistant (server, person-only, whole-managed). assistant.enabled is off by default. When it is off, Settings shows no Make assistant button. A bad or missing value reads as off.

  • Built-in MCP profile assistant:

    • servers: []
    • builtinTools: "none" (no shell, file or web tools; Claude only, as in fork: MCP profile builtinTools "none" (assistant PR 1) #927)
    • t3Tools: orchestration, threads, projects, plus the tools every profile keeps.
    • It sits next to all and t3-only in the one built-in table in contracts. The web list of built-ins now reads that table instead of keeping its own copy.
  • Settings → Fork → Assistant: a switch, then a row with Make assistant. The button makes two settings saves from the person at the screen:

    1. saves mcpThreadProfiles[id] = "assistant" for a new thread id, before the thread exists;
    2. makes a thread "Assistant" with that id in the Scratch project, with Claude's default model;
    3. saves threadRoles.assistant = id;
    4. opens the thread.

    Because the pick comes first, a thread called "Assistant" never runs with a wider profile, even if setup stops half-way. The role goes through the existing threadRoles server guard (thread exists, top-level, own project; person-only key). No agent path writes a role or a profile pick. If the role save is refused, the new thread is deleted while it is still empty (onlyIfUnused). The button stays busy until the saves settle, and a ref stops a double click. The row is locked when a managed policy owns threadRoles or mcpThreadProfiles, and it shows whether the assistant thread is active or not.

  • Docs: new docs/fork/assistant.md, including what the three T3 tool groups can really do (projects can also create, clone, update and delete projects; threads can configure other threads). In docs/fork/README.md: a table row and section for server.assistant, and the built-ins text now lists three. A FORK_CHANGES.md line.

Owner answers used (#153–#158, all yes): the assistant may start work without a tap (#158), so it runs full-access with no built-in tools.

Size

The plan said at most 400 changed lines. This PR is 585+ / 20−: 361 code, 130 test, 94 docs. I did not split it. Without its tests and docs it is under 400, and none of the parts is useful on its own: the setting, the profile and the button only make sense together. #927 grew the same way (531+ against a plan of 250).

Upstream fit

  • No upstream file changes. The seam check is 0. The Settings section mounts in the fork's own ForkSettingsPanel.
  • No Scratch or sidebar button: that would need new upstream lines. The button lives in the fork's Settings and uses upstream's own pieces: useScratchProject, threadEnvironment.create/delete, waitForThreadShell and the settings save.
  • The profile and role use mechanisms that are already merged (the MCP profile resolver, threadRoles), with no new server path.

General vs project

All general. There are no project names, paths or facts. The profile is a general least-privilege set; any thread can pick it. Which provider and model to use comes from the environment's providers.

State question

  • Assistant made twice: the second press makes a new thread and moves threadRoles.assistant to it. The old thread keeps its assistant pick and is not touched. Nothing is lost. A double click makes one thread, because a ref guards the run and the button stays busy until the saves settle.
  • Its thread archived or deleted: the client's thread list holds active threads only, so Settings says it is "archived, deleted or not on this server", and readers treat it as no assistant (the threadRoles rule). The pointer and pick stay until the next Make assistant replaces the pointer.
  • Profile edited by hand, or an own profile called assistant saved before this version: the entry makes the built-in "broken", so every thread that picks it is refused (fail closed) until it is removed. This uses the same rule as all and t3-only, and the test is extended to cover assistant. The docs carry an upgrade note: rename your own profile and move its picks first, because after removal those picks get the built-in.
  • Settings unreadable: assistant is read leniently: anything but enabled: true is off, and other settings are kept (tested). A bad threadRoles reads as no roles (Calm sidebar part 1: threadRoles and calmSidebarEnabled settings #928). A thread whose profile cannot be read is refused, never widened.
  • Stops half-way: after the pick only, nothing is made; a pick for a thread that does not exist does nothing. After the thread is made but before the role, an "Assistant" thread is left in Scratch that already has the narrow assistant profile and no role; Settings still says there is no assistant. If the role save fails or the thread does not reach the client, the empty thread is deleted and the pick stays, which is harmless.
  • An older client: it has no Assistant section. It shows the thread's pick as a profile it does not know, and it cannot change assistant.
  • An older server with a newer client: the first save (the pick naming assistant) is refused as an unknown profile, nothing is made, and nothing is widened.

Known limits (later PRs)

  • The assistant cannot yet launch a thread into a project whose profile is wider than its own, because the launch check refuses that. It can message threads there. This is documented in docs/fork/assistant.md and left for PR 3.
  • The thread gets Claude's default model, with no model pin. The model policy turn check still applies.

Tests (each fails without the change)

I ran the new and changed tests against origin/main's source files with this PR's tests in place:

  • packages/contracts/src/assistant.test.ts: 2 fail (no assistant key).
  • packages/shared/src/forkSettingsPatch.test.ts "takes a pick of the assistant's built-in": fails (the pick is refused as unknown).
  • packages/shared/src/forkDocs.test.ts: 3 fail (README row and section with no setting).
  • .github/scripts/fork-changes-list.test.cjs: fails with the first version of the FORK_CHANGES.md row (no server.assistant named), and passes now.
  • apps/server/src/fork/mcpProfile.test.ts: 2 fail. A hand-written assistant entry is accepted, and the built-in is "not set up".
  • apps/server/src/golive/forkReport.test.ts: 1 fails.
  • apps/web/.../assistantSetup.logic.test.ts: fails (the module is missing). It checks that the pick save passes the save check before the thread exists, that the pick alone already resolves to builtinTools: "none", and then the role save. mcpProfileSettings.logic.test.ts: 2 fail (only two built-ins; assistant can be saved as a custom profile).

The tests use real behaviour: the patch goes through applyServerSettingsPatch and forkSettingsWriteProblem, and its pick through the real resolver. No mocks.

Checks run

  • Typecheck: contracts, shared, server and web all pass.
  • Vitest: contracts 85, shared 109, server 493, web unit 72 and browser McpProfileSettings 9, all passing.
  • .github/scripts/*.test.cjs: 368 passing.
  • Lint passes, and knip passes in pre-commit.
  • vp fmt --check on the touched files passes.
  • node .github/scripts/fork-seam-check.cjs --config-ref origin/main origin/main HEAD returns 0.

Review

One Opus lens (high effort, read-only, asked the state question). It found:

  • Blocking, fixed: the FORK_CHANGES.md row had one cell, not five, and did not name server.assistant.
  • Minor, fixed:
    • Archived and deleted threads now show as one state.
    • The button stays busy until the saves settle.
    • The pick is saved first, so there is no wide half-made thread.
    • The row also locks on mcpThreadProfiles.
    • The docs now cover an own profile called assistant and what the tool groups can do.
  • Owner-facing note (not changed): the projects and threads groups give the assistant more than starting and messaging work: it can delete or clone projects and configure other threads. This PR documents it; a finer split of the groups is a later decision.

🤖 Generated with Claude Code

scuttletoby and others added 3 commits November 22, 2026 12:05
…tant)

The switch assistant.enabled (off by default) offers "Make assistant" in
Settings. It makes a thread in the Scratch project and names it the
assistant in one person-path settings save: threadRoles.assistant (the
server's role guard decides) and the thread's MCP profile pick
"assistant". The new built-in profile "assistant" has no outside
servers, no built-in tools (builtinTools "none", Claude only) and the
T3 groups orchestration, threads and projects. The web list of
built-ins now reads the one table in contracts.

Assistant PR 2 of 18. Docs: docs/fork/assistant.md.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- FORK_CHANGES row: all five cells, naming server.assistant (the
  fork-changes-list test failed without it).
- Make assistant saves the profile pick before it makes the thread, so a
  setup that stops half-way never leaves a wider "Assistant" thread; the
  role is a second save once the thread exists.
- The button stays busy until the saves settle; a ref stops a double
  click from making two threads.
- An archived assistant reads as not active (the client's thread list
  holds active threads only), not as deleted.
- The button row is locked when a policy owns mcpThreadProfiles.
- Docs: what the three T3 tool groups can do, the upgrade note for an
  own profile called "assistant", and the half-way states.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@scuttletoby

Copy link
Copy Markdown
Owner Author

lens: code · reviewer: lens agent (Opus, read-only) · read at: b1a7658
verdict: not safe to merge
covered: the full diff (20 files), the MCP profile resolver and launch check (launchMcpProfile.ts, scheduledTaskMcpProfile.ts), the orchestrator, thread and project toolkits the profile keeps, ProjectService delete, the person-only key list, the managed-policy whole-only list, useScopedSettings, the assistant design (section 5 and owner question 6) and the owner decisions on #153 to #158 and #879
checks: ran the 7 changed vitest files (276 tests pass): contracts assistant, shared forkSettingsPatch and forkDocs, server mcpProfile and forkReport, web assistantSetup.logic and mcpProfileSettings.logic; ran .github/scripts/fork-changes-list.test.cjs (10 pass); traced each way the "Assistant" thread could run with more than the profile: pick saved after start, retry, double click, two tabs, managed policy, a user profile named assistant, t3_thread_transfer fork, create_threads, t3_thread_launch, delegate_task, schedule_task, t3_thread_configure to another provider
state: runs again: each press makes a new thread and moves the pointer, the old thread keeps its narrow pick, nothing lost; stopped half-way: the pick is saved before the thread exists, so a half-made "Assistant" thread is never wider than the profile (a pick alone does nothing; a refused role save deletes the empty thread with onlyIfUnused); old settings without assistant read as off, threadRoles as no roles; a hand-written mcpProfiles.assistant makes the built-in refuse (fail closed); an older server refuses the first save, so nothing is made
blocker: none
major: the assistant profile's tool scope was never decided by the owner. The design (section 5) and #879 name the groups orchestration, threads and projects; #158 allows starting and messaging work without a tap. Nobody decided that the assistant may also, with no tap (the thread runs full-access): delete any project except Scratch with force: true, which deletes every thread of that project, archived ones too (ProjectService.ts:723-738; transcripts are lost); clone any repository onto disk and register or create folders (t3_project_clone, t3_project_create); change another thread's model (t3_thread_configure); interrupt threads and stop workflows; link and unlink environments. The design said starting work without a tap "is safe only with a yes on question 1" (cards only, no mail text); #153 answered the other way (the assistant may read mail text), so a hostile mail could later steer a thread that holds these tools. Single tools cannot be dropped today (profiles keep whole groups; dropping projects also drops t3_thread_launch). Needs an owner answer before merge: keep the three whole groups, or split projects (and threads) into read/start versus destructive tools before the assistant is offered (recommended: split before any mail PR lands).
minor: the Settings text says "no shell, files, web or outside servers; it can read, start and message threads" (AssistantSettings.tsx:144), but the profile can also delete projects with their threads, clone repositories from the network onto disk and reconfigure other threads; this is the text the owner reads when switching it on
minor: docs/fork/assistant.md puts "launch" under threads, but t3_thread_launch is in the project toolkit (group projects); and "delete them" should say a forced delete removes every thread of the project
minor: a managed policy that later owns mcpThreadProfiles (whole-only, forkManagedSettings.ts:15) without the assistant's id drops its pick, so the thread that still holds threadRoles.assistant resolves to the Scratch or server profile (by default all, with shell); the lock only stops a new Make assistant
minor: save() in AssistantSettings.tsx:78-81 waits for onSaved/onFailed, but useScopedSettings.ts:120 calls neither when writeScopedSettings rejects (a thrown persistServer error), so the button stays busy until the page remounts (nothing is made, so this is safe, only stuck)
minor: every refused or abandoned run leaves its mcpThreadProfiles pick for a thread id that never exists or was deleted; harmless, but entries pile up on retries
minor: AssistantSettingsFromSettingsFile encodes only enabled, so a downgrade that saves drops any field a newer build adds to assistant (other fork keys such as mcpProfiles keep entries as written)

@scuttletoby

Copy link
Copy Markdown
Owner Author

lens: code · reviewer: lens agent (Opus, read-only), replaces my report above (it missed two CI failures) · read at: b1a7658
verdict: not safe to merge
covered: the full diff (20 files), the MCP profile resolver and launch check (launchMcpProfile.ts, scheduledTaskMcpProfile.ts), the orchestrator, thread and project toolkits the profile keeps, ProjectService delete, the person-only key list, the managed-policy whole-only list, useScopedSettings, the assistant design (section 5 and owner question 6) and the owner decisions on #153 to #158 and #879
checks: ran the 7 changed vitest files (276 tests pass): contracts assistant, shared forkSettingsPatch and forkDocs, server mcpProfile and forkReport, web assistantSetup.logic and mcpProfileSettings.logic; ran .github/scripts/fork-changes-list.test.cjs (10 pass); traced each way the "Assistant" thread could run with more than the profile: pick saved after start, retry, double click, two tabs, managed policy, a user profile named assistant, t3_thread_transfer fork, create_threads, t3_thread_launch, delegate_task, schedule_task, t3_thread_configure to another provider
state: runs again: each press makes a new thread and moves the pointer, the old thread keeps its narrow pick, nothing lost; stopped half-way: the pick is saved before the thread exists, so a half-made "Assistant" thread is never wider than the profile (a pick alone does nothing; a refused role save deletes the empty thread with onlyIfUnused); old settings without assistant read as off, threadRoles as no roles; a hand-written mcpProfiles.assistant makes the built-in refuse (fail closed); an older server refuses the first save, so nothing is made
blocker: CI is red on this head: Test Web 1 fails apps/web/src/reactCompilerCoverage.test.ts:32, because React Compiler refuses the try/finally without catch in makeAssistant (AssistantSettings.tsx:89), so the new component is not compiled; use try/catch/finally or move the steps into a helper the finally does not wrap
blocker: CI is red on this head: Test Web 3 fails apps/web/src/components/fork/mcpProfile/threadMcpProfile.logic.test.ts:119, which expects 5 profile picks in the thread menu and now gets 6 (mcp-profile:pick:assistant); the PR body's "web unit 72 passing" did not include this file. Update the test, and check that the new built-in in every thread's menu is wanted
major: the assistant profile's tool scope was never decided by the owner. The design (section 5) and #879 name the groups orchestration, threads and projects; #158 allows starting and messaging work without a tap. Nobody decided that the assistant may also, with no tap (the thread runs full-access): delete any project except Scratch with force: true, which deletes every thread of that project, archived ones too (ProjectService.ts:723-738; transcripts are lost); clone any repository onto disk and register or create folders (t3_project_clone, t3_project_create); change another thread's model (t3_thread_configure); interrupt threads and stop workflows; link and unlink environments. The design said starting work without a tap "is safe only with a yes on question 1" (cards only, no mail text); #153 answered the other way (the assistant may read mail text), so a hostile mail could later steer a thread that holds these tools. Single tools cannot be dropped today (profiles keep whole groups; dropping projects also drops t3_thread_launch). Needs an owner answer before merge: keep the three whole groups, or split projects (and threads) into read/start versus destructive tools before the assistant is offered (recommended: split before any mail PR lands).
minor: the Settings text says "no shell, files, web or outside servers; it can read, start and message threads" (AssistantSettings.tsx:144), but the profile can also delete projects with their threads, clone repositories from the network onto disk and reconfigure other threads; this is the text the owner reads when switching it on
minor: docs/fork/assistant.md puts "launch" under threads, but t3_thread_launch is in the project toolkit (group projects); and "delete them" should say a forced delete removes every thread of the project
minor: a managed policy that later owns mcpThreadProfiles (whole-only, forkManagedSettings.ts:15) without the assistant's id drops its pick, so the thread that still holds threadRoles.assistant resolves to the Scratch or server profile (by default all, with shell); the lock only stops a new Make assistant
minor: save() in AssistantSettings.tsx:78-81 waits for onSaved/onFailed, but useScopedSettings.ts:120 calls neither when writeScopedSettings rejects (a thrown persistServer error), so the button stays busy until the page remounts (nothing is made, so this is safe, only stuck)
minor: every refused or abandoned run leaves its mcpThreadProfiles pick for a thread id that never exists or was deleted; harmless, but entries pile up on retries
minor: AssistantSettingsFromSettingsFile encodes only enabled, so a downgrade that saves drops any field a newer build adds to assistant (other fork keys such as mcpProfiles keep entries as written)

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant