From 1d2c244c7e18a92fb013266e5d402ae735d0ce34 Mon Sep 17 00:00:00 2001 From: scuttletoby <123843277+scuttletoby@users.noreply.github.com> Date: Sun, 22 Nov 2026 12:05:19 +0000 Subject: [PATCH 1/3] Fork: assistant setup (switch, built-in assistant profile, Make assistant) 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 --- FORK_CHANGES.md | 1 + apps/server/src/fork/mcpProfile.test.ts | 15 +- apps/server/src/golive/forkReport.test.ts | 1 + apps/server/src/policy/forkManagedSettings.ts | 1 + .../settings/fork/AssistantSettings.tsx | 163 ++++++++++++++++++ .../settings/fork/ForkSettingsPanel.tsx | 2 + .../fork/assistantSetup.logic.test.ts | 82 +++++++++ .../settings/fork/assistantSetup.logic.ts | 85 +++++++++ .../settings/fork/mcpProfileSettings.logic.ts | 10 +- .../settings/forkSettingsSearchItems.ts | 16 ++ docs/fork/README.md | 18 +- docs/fork/assistant.md | 55 ++++++ packages/contracts/src/assistant.test.ts | 26 +++ packages/contracts/src/assistant.ts | 37 ++++ packages/contracts/src/forkDefaults.ts | 8 + packages/contracts/src/forkSettings.ts | 7 + packages/contracts/src/mcpProfile.ts | 15 +- packages/contracts/src/mcpProfileResolve.ts | 13 +- packages/shared/src/forkSettingsPatch.test.ts | 1 + 19 files changed, 539 insertions(+), 17 deletions(-) create mode 100644 apps/web/src/components/settings/fork/AssistantSettings.tsx create mode 100644 apps/web/src/components/settings/fork/assistantSetup.logic.test.ts create mode 100644 apps/web/src/components/settings/fork/assistantSetup.logic.ts create mode 100644 docs/fork/assistant.md create mode 100644 packages/contracts/src/assistant.test.ts create mode 100644 packages/contracts/src/assistant.ts diff --git a/FORK_CHANGES.md b/FORK_CHANGES.md index 9c9fc3317b840..d2cc6440bec42 100644 --- a/FORK_CHANGES.md +++ b/FORK_CHANGES.md @@ -49,6 +49,7 @@ setting is missing here or a setting named here does not exist. | Model policy: the setting for which models (and efforts) agents may pick, per provider driver: off, advise or enforce, and the allowed rows. The server checks an agent's pick (`delegate_task`, `create_threads`, `t3_thread_launch`, `t3_thread_configure`, here, and both before and after it goes to linked machines): a model in no row, a call that names no model, or an effort off its row is refused in enforce, only noted in advise. A person's own pick is never refused; Settings marks one outside the rows. A bad hand edit, or a settings file that does not parse, refuses every agent pick (a warning if the value says advise). Settings offers the fork's start rows (Opus 5.5 and Fable 5.2) while none are saved. While it is on, a child whose call names its model keeps only the options it names. | Agents should use the models the person chose for each kind of work. | `server.modelPolicy` | off | [#268](https://github.com/scuttletoby/t3code/pull/268), [#731](https://github.com/scuttletoby/t3code/issues/731) | | Placement, part 1: the settings only. `placement` (off, advise or enforce; this machine's labels, an optional facts command, label groups that must never meet on one machine, and a weight per linked machine) and `placementNeeds` (labels a project's work needs). Person-only; a bad `placement` reads as off and a bad `placementNeeds` fits no machine, each kept as written. Nothing reads them yet. | Delegated work should go to a machine that has what it needs, and never where it must not run. | `server.placement`, `server.placementNeeds`, `projectOverride.placementNeeds` | off | [#134](https://github.com/scuttletoby/t3code/issues/134) | | Calm sidebar, part 1: the settings. `threadRoles` names the assistant thread and one orchestrator per project; the server refuses a role for a thread that is missing, deleted, a sub-agent, a side chat, delegated from a linked machine or in another project. `calmSidebarEnabled` is the per-device switch. Nothing shows them yet. | A short sidebar: the threads that matter on top, the rest folded. | `server.threadRoles`, `client.calmSidebarEnabled` | off | [#928](https://github.com/scuttletoby/t3code/pull/928) | +| Assistant setup: the switch `assistant.enabled` (off) offers **Make assistant** in Settings, which makes a thread in the Scratch project, names it `threadRoles.assistant` and picks for it the new built-in MCP profile `assistant` (no outside servers, no shell, file or web tools; T3 tool groups `orchestration`, `threads` and `projects`). Claude only. | ## Repository, CI and releases diff --git a/apps/server/src/fork/mcpProfile.test.ts b/apps/server/src/fork/mcpProfile.test.ts index b6c41f96d0252..31c2515bfd56e 100644 --- a/apps/server/src/fork/mcpProfile.test.ts +++ b/apps/server/src/fork/mcpProfile.test.ts @@ -79,7 +79,7 @@ describe("MCP profile resolver: old and empty state", () => { }); }); - it.each(["all", "t3-only"])( + it.each(["all", "t3-only", "assistant"])( "refuses %s when a hand edit put a profile of that name in the file", (name) => { const file = { @@ -662,6 +662,19 @@ describe('builtinTools "none" (assistant)', () => { ); }); + it("the built-in assistant: no servers or built-in tools, three groups; a child keeps it", () => { + const picked = fromFile({ mcpThreadProfiles: { a1: "assistant" } }); + const own = resolved(resolveMcpProfile(picked, [top("a1")])); + expect([own.name, own.source]).toEqual(["assistant", "thread-pick"]); + expect(own.profile).toEqual({ + servers: [], + t3Tools: ["orchestration", "threads", "projects"], + builtinTools: "none", + }); + const sub = resolved(resolveMcpProfile(picked, [child("c1"), top("a1")])); + expect(sub.profile).toEqual(own.profile); + }); + it.each([["some"], [false], [["Bash"]]])("refuses, never widens, builtinTools %j", (value) => { const broken = fromFile({ mcpProfiles: { odd: { servers: "all", t3Tools: "all", builtinTools: value } }, diff --git a/apps/server/src/golive/forkReport.test.ts b/apps/server/src/golive/forkReport.test.ts index 2723fa4902fdd..a7734bc4ed989 100644 --- a/apps/server/src/golive/forkReport.test.ts +++ b/apps/server/src/golive/forkReport.test.ts @@ -1127,6 +1127,7 @@ describe("__fork-report settings", () => { placementNeeds: "placement: settings only so far; nothing reads them yet (later placement rows)", threadRoles: "calm sidebar: settings only so far; nothing reads them yet", + assistant: "only offers Make assistant; the assistant is the threadRoles.assistant thread", }; it("counts every fork setting as a feature or names why it is not a switch", () => { diff --git a/apps/server/src/policy/forkManagedSettings.ts b/apps/server/src/policy/forkManagedSettings.ts index fd2202bcd2904..c4fab57507451 100644 --- a/apps/server/src/policy/forkManagedSettings.ts +++ b/apps/server/src/policy/forkManagedSettings.ts @@ -6,6 +6,7 @@ import type { ForkServerSettingKey } from "@t3tools/contracts"; const WHOLE_ONLY = [ + "assistant", "handoff", "mcpCarriedProfiles", "mcpProfile", diff --git a/apps/web/src/components/settings/fork/AssistantSettings.tsx b/apps/web/src/components/settings/fork/AssistantSettings.tsx new file mode 100644 index 0000000000000..53228c6fc008a --- /dev/null +++ b/apps/web/src/components/settings/fork/AssistantSettings.tsx @@ -0,0 +1,163 @@ +/** + * Fork (assistant): the switch `assistant.enabled` and "Make assistant", which makes a thread in the + * Scratch project and names it the assistant (`threadRoles.assistant`) with the built-in profile + * `assistant`. Server-wide, so a project screen does not show it. Every write is an ordinary settings + * save from the person at the screen; agents cannot change these keys. Docs: docs/fork/assistant.md. + */ +/* oxlint-disable t3code/no-untranslated-copy -- Fork: this panel is the fork's own and its text is English only; upstream's translation catalogs hold no fork keys. */ +import { + DEFAULT_PROVIDER_INTERACTION_MODE, + DEFAULT_RUNTIME_MODE, + type EnvironmentId, +} from "@t3tools/contracts"; +import { scopeThreadRef } from "@t3tools/client-runtime/environment"; +import { useNavigate } from "@tanstack/react-router"; +import { useState } from "react"; + +import { newThreadId } from "~/lib/utils"; +import { useScratchProject } from "../../../hooks/useScratchProject"; +import { useThreadShells, waitForThreadShell } from "../../../state/entities"; +import { useEnvironmentProviders } from "../../../state/environments"; +import { threadEnvironment } from "../../../state/threads"; +import { useAtomCommand } from "../../../state/use-atom-command"; +import { buildThreadRouteParams } from "../../../threadRoutes"; +import { Button } from "../../ui/button"; +import { Switch } from "../../ui/switch"; +import { useSettingsScope } from "../SettingsScopeContext"; +import { SettingsSection } from "../settingsLayout"; +import { useSearchableSetting } from "../settingsSearch"; +import { useUpdateScopedSettings } from "../useScopedSettings"; +import { ForkRow } from "./ForkRow"; +import { + assistantModelSelection, + assistantThreadState, + assistantThreadText, + makeAssistantPatch, +} from "./assistantSetup.logic"; + +export function AssistantSettings() { + const searchableSetting = useSearchableSetting(); + const updateSettings = useUpdateScopedSettings(); + const { targets } = useSettingsScope(); + const { openScratchProject } = useScratchProject(); + const createThread = useAtomCommand(threadEnvironment.create, { reportFailure: false }); + const deleteThread = useAtomCommand(threadEnvironment.delete, { reportFailure: false }); + const providers = useEnvironmentProviders(); + const shells = useThreadShells(); + const navigate = useNavigate(); + const [busy, setBusy] = useState(false); + const [error, setError] = useState(null); + + const target = targets.length === 1 ? targets[0]! : null; + if (target === null) { + return ( + + + + ); + } + const environmentId: EnvironmentId = target.environmentId; + const enabled = target.settings.assistant.enabled; + const state = assistantThreadState( + target.settings.threadRoles.assistant, + shells.filter((thread) => thread.environmentId === environmentId), + ); + const modelSelection = assistantModelSelection(providers.get(environmentId) ?? []); + + const makeAssistant = async () => { + if (modelSelection === null) return; + setBusy(true); + setError(null); + try { + const project = await openScratchProject(environmentId); + if (project === null) return; + const threadId = newThreadId(); + const created = await createThread({ + environmentId, + input: { + threadId, + projectId: project.id, + title: "Assistant", + modelSelection, + runtimeMode: DEFAULT_RUNTIME_MODE, + interactionMode: DEFAULT_PROVIDER_INTERACTION_MODE, + branch: null, + worktreePath: null, + }, + }); + if (created._tag === "Failure") { + setError("Could not make the assistant's thread. Try again."); + return; + } + // An empty thread the save did not name is removed; one that got a message stays. + const discard = () => + void deleteThread({ environmentId, input: { threadId, onlyIfUnused: true } }); + const ref = scopeThreadRef(environmentId, threadId); + if (!(await waitForThreadShell(ref))) { + setError("The assistant's thread was made, but it did not reach this client. Try again."); + discard(); + return; + } + updateSettings(makeAssistantPatch(threadId), { + onFailed: () => { + setError("The server refused to name the new thread the assistant. Nothing was changed."); + discard(); + }, + onSaved: () => + void navigate({ to: "/$environmentId/$threadId", params: buildThreadRouteParams(ref) }), + }); + } finally { + setBusy(false); + } + }; + + return ( + + + updateSettings({ assistant: { enabled: Boolean(checked) } }) + } + aria-label="Offer Make assistant" + /> + } + /> + {enabled ? ( + void makeAssistant()} + > + Make assistant + + } + /> + ) : null} + + ); +} diff --git a/apps/web/src/components/settings/fork/ForkSettingsPanel.tsx b/apps/web/src/components/settings/fork/ForkSettingsPanel.tsx index 5699f051206cf..b87255f52caf6 100644 --- a/apps/web/src/components/settings/fork/ForkSettingsPanel.tsx +++ b/apps/web/src/components/settings/fork/ForkSettingsPanel.tsx @@ -11,6 +11,7 @@ import { useSettingsScope } from "../SettingsScopeContext"; import { SettingsPageContainer, SettingsRow, SettingsSection } from "../settingsLayout"; import { useSearchableSetting } from "../settingsSearch"; import { WaitsAndSlotsSettings } from "../WaitsAndSlotsSettings"; +import { AssistantSettings } from "./AssistantSettings"; import { forkFeatureStatuses } from "./forkStatus.logic"; import { HandoffSettings } from "./HandoffSettings"; import { McpProfileSettings } from "./McpProfileSettings"; @@ -49,6 +50,7 @@ export function ForkSettingsPanel() { + {isProjectScope ? null : } ); } diff --git a/apps/web/src/components/settings/fork/assistantSetup.logic.test.ts b/apps/web/src/components/settings/fork/assistantSetup.logic.test.ts new file mode 100644 index 0000000000000..d1c38ff0bd717 --- /dev/null +++ b/apps/web/src/components/settings/fork/assistantSetup.logic.test.ts @@ -0,0 +1,82 @@ +import { + ProviderDriverKind, + ProviderInstanceId, + ServerSettings, + ThreadId, + resolveMcpProfile, + type ServerProvider, +} from "@t3tools/contracts"; +import { forkSettingsWriteProblem } from "@t3tools/shared/forkSettingsPatch"; +import { applyServerSettingsPatch } from "@t3tools/shared/serverSettings"; +import * as Schema from "effect/Schema"; +import { describe, expect, it } from "vite-plus/test"; + +import { + assistantModelSelection, + assistantThreadState, + makeAssistantPatch, +} from "./assistantSetup.logic"; + +const provider = ( + instanceId: string, + driver: string, + models: ReadonlyArray<{ slug: string; isDefault?: boolean }>, + extra: Partial = {}, +): ServerProvider => + ({ + instanceId: ProviderInstanceId.make(instanceId), + driver: ProviderDriverKind.make(driver), + enabled: true, + availability: "available", + models: models.map((model) => ({ ...model, name: model.slug, isCustom: false })), + ...extra, + }) as unknown as ServerProvider; + +describe("Make assistant", () => { + it("picks an on, available Claude instance (the default first) and Claude's default model", () => { + const providers = [ + provider("codex", "codex", [{ slug: "gpt" }]), + provider("claudeWork", "claudeAgent", [{ slug: "claude-x", isDefault: true }]), + provider("claudeAgent", "claudeAgent", [{ slug: "claude-x" }, { slug: "claude-opus-5-5" }]), + ]; + expect(assistantModelSelection(providers)).toEqual({ + instanceId: "claudeAgent", + model: "claude-opus-5-5", + }); + expect(assistantModelSelection(providers.slice(0, 2))).toEqual({ + instanceId: "claudeWork", + model: "claude-x", + }); + }); + + it("offers nothing without a usable Claude: no other provider can drop built-in tools", () => { + expect(assistantModelSelection([provider("codex", "codex", [{ slug: "gpt" }])])).toBeNull(); + const off = provider("claudeAgent", "claudeAgent", [{ slug: "c" }], { enabled: false }); + const gone = provider("claudeAgent", "claudeAgent", [{ slug: "c" }], { + availability: "unavailable", + } as Partial); + expect(assistantModelSelection([off, gone])).toBeNull(); + }); + + it("one save names the thread the assistant and gives it the assistant profile", () => { + const decode = Schema.decodeUnknownSync(ServerSettings); + const before = decode({ mcpThreadProfiles: { old: "t3-only" } }); + const thread = ThreadId.make("thread-new"); + const after = applyServerSettingsPatch(before, makeAssistantPatch(thread)); + expect(after.threadRoles.assistant).toBe("thread-new"); + expect(after.mcpThreadProfiles).toEqual({ old: "t3-only", "thread-new": "assistant" }); + expect(forkSettingsWriteProblem(before, after)).toBeUndefined(); + const resolved = resolveMcpProfile(after, [{ threadId: thread, delegated: false }]); + expect(resolved._tag === "Resolved" && resolved.profile.builtinTools).toBe("none"); + }); + + it("shows a deleted or archived assistant thread as gone or archived", () => { + const threads = [{ id: "a", title: "Assistant", archivedAt: null }]; + expect(assistantThreadState(null, threads)).toEqual({ kind: "none" }); + expect(assistantThreadState("a", threads)).toMatchObject({ kind: "ok", title: "Assistant" }); + expect(assistantThreadState("b", threads)).toEqual({ kind: "gone", threadId: "b" }); + expect( + assistantThreadState("a", [{ ...threads[0]!, archivedAt: "2026-01-01T00:00:00Z" }]).kind, + ).toBe("archived"); + }); +}); diff --git a/apps/web/src/components/settings/fork/assistantSetup.logic.ts b/apps/web/src/components/settings/fork/assistantSetup.logic.ts new file mode 100644 index 0000000000000..bc13edcf37c0f --- /dev/null +++ b/apps/web/src/components/settings/fork/assistantSetup.logic.ts @@ -0,0 +1,85 @@ +/** + * Fork (assistant): the pure parts of "Make assistant". The thread is made in the Scratch project and + * named the assistant by one settings save from the person at the screen; the server's role check + * (apps/server/src/fork/threadRoleTargets.ts) refuses a thread that cannot hold the role. + */ +/* oxlint-disable t3code/no-untranslated-copy -- Fork: the fork's own settings are English only; upstream's translation catalogs hold no fork keys. */ +import { + DEFAULT_MODEL_BY_PROVIDER, + MCP_PROFILE_ASSISTANT, + ProviderDriverKind, + type ModelSelection, + type ServerProvider, + type ServerSettingsPatch, + type ThreadId, +} from "@t3tools/contracts"; +import { createModelSelection } from "@t3tools/shared/model"; + +const CLAUDE = ProviderDriverKind.make("claudeAgent"); + +/** + * The assistant's model: a Claude instance that is on and available (the default one first), with + * Claude's default model when it offers it. Null when there is none: the assistant's profile has no + * built-in tools, which only Claude can apply, so any other provider would refuse its turns. + */ +export function assistantModelSelection( + providers: ReadonlyArray, + defaultInstanceId: string = CLAUDE, +): ModelSelection | null { + const usable = providers.filter( + (provider) => + provider.driver === CLAUDE && provider.enabled && provider.availability !== "unavailable", + ); + const pick = usable.find((provider) => provider.instanceId === defaultInstanceId) ?? usable[0]; + if (pick === undefined) return null; + const wanted = DEFAULT_MODEL_BY_PROVIDER[CLAUDE]; + const model = + pick.models.find((entry) => entry.slug === wanted) ?? + pick.models.find((entry) => entry.isDefault === true) ?? + pick.models[0]; + return model === undefined ? null : createModelSelection(pick.instanceId, model.slug); +} + +/** The one save that makes `threadId` the assistant: its profile pick and the role pointer. */ +export const makeAssistantPatch = (threadId: ThreadId): ServerSettingsPatch => ({ + mcpThreadProfiles: { [threadId]: MCP_PROFILE_ASSISTANT }, + threadRoles: { assistant: threadId }, +}); + +/** The thread `threadRoles.assistant` names, as Settings shows it. */ +export type AssistantThreadState = + | { readonly kind: "none" } + | { readonly kind: "gone"; readonly threadId: string } + | { readonly kind: "archived" | "ok"; readonly threadId: string; readonly title: string }; + +/** Readers treat a deleted or archived assistant thread as no assistant (threadRoles docs). */ +export function assistantThreadState( + assistant: string | null, + threads: ReadonlyArray<{ + readonly id: string; + readonly title: string; + readonly archivedAt: string | null; + }>, +): AssistantThreadState { + if (assistant === null) return { kind: "none" }; + const thread = threads.find((candidate) => candidate.id === assistant); + if (thread === undefined) return { kind: "gone", threadId: assistant }; + return { + kind: thread.archivedAt === null ? "ok" : "archived", + threadId: assistant, + title: thread.title, + }; +} + +export function assistantThreadText(state: AssistantThreadState): string { + switch (state.kind) { + case "none": + return "No thread is the assistant yet."; + case "gone": + return `The assistant was thread ${state.threadId}, which is deleted or not on this server. Make a new one.`; + case "archived": + return `The assistant is "${state.title}", which is archived, so it counts as none. Unarchive it or make a new one.`; + case "ok": + return `The assistant is "${state.title}".`; + } +} diff --git a/apps/web/src/components/settings/fork/mcpProfileSettings.logic.ts b/apps/web/src/components/settings/fork/mcpProfileSettings.logic.ts index 8926de4803abe..a7f2b6dcfc577 100644 --- a/apps/web/src/components/settings/fork/mcpProfileSettings.logic.ts +++ b/apps/web/src/components/settings/fork/mcpProfileSettings.logic.ts @@ -6,8 +6,7 @@ /* oxlint-disable t3code/no-untranslated-copy -- Fork: the fork's own settings are English only; upstream's translation catalogs hold no fork keys. */ import { MCP_BUILTIN_TOOLS_NONE, - MCP_PROFILE_ALL, - MCP_PROFILE_T3_ONLY, + MCP_BUILT_IN_PROFILES, MCP_SUBAGENT_INHERIT, MCP_T3_TOOL_GROUPS, MCP_T3_UNGROUPED_TOOLS, @@ -66,11 +65,6 @@ export type McpProfileRow = readonly removable: boolean; }; -const BUILT_IN_SETS: ReadonlyArray = [ - [MCP_PROFILE_ALL, { servers: "all", t3Tools: "all" }], - [MCP_PROFILE_T3_ONLY, { servers: [], t3Tools: "all" }], -]; - const entriesOf = (profiles: unknown): ReadonlyArray => typeof profiles === "object" && profiles !== null && !Array.isArray(profiles) ? Object.entries(profiles) @@ -97,7 +91,7 @@ export function mcpProfileRows( knownServers: ReadonlyArray | null, ): ReadonlyArray { const entries = entriesOf(settings.mcpProfiles); - const builtIns = BUILT_IN_SETS.map(([name, profile]): McpProfileRow => { + const builtIns = Object.entries(MCP_BUILT_IN_PROFILES).map(([name, profile]): McpProfileRow => { // A save never writes one: a hand edit, and the resolver refuses the built-in while it stays. if (entries.some(([entryName]) => entryName === name)) { return { diff --git a/apps/web/src/components/settings/forkSettingsSearchItems.ts b/apps/web/src/components/settings/forkSettingsSearchItems.ts index c26248bdf259c..7fda6e457ff90 100644 --- a/apps/web/src/components/settings/forkSettingsSearchItems.ts +++ b/apps/web/src/components/settings/forkSettingsSearchItems.ts @@ -249,4 +249,20 @@ export const FORK_SETTINGS_SEARCH_ITEMS = [ environmentOnly: true, scope: "environment-defaults", }, + { + id: "assistant", + title: "Assistant", + to: FORK_PAGE, + searchTerms: ["assistant personal one thread across projects"], + environmentOnly: true, + scope: "environment-defaults", + }, + { + id: "assistant-thread", + title: "Make assistant", + to: FORK_PAGE, + searchTerms: ["assistant thread role scratch make"], + environmentOnly: true, + scope: "environment-defaults", + }, ] as const; diff --git a/docs/fork/README.md b/docs/fork/README.md index 3b100bc4b3ca9..c33e1fb4a0a66 100644 --- a/docs/fork/README.md +++ b/docs/fork/README.md @@ -67,6 +67,7 @@ no section below. "Off" means the default leaves the machine as upstream's would | [`server.mcpCarriedProfiles`](#servermcpcarriedprofiles) | `"apply"` | yes | [#640](https://github.com/scuttletoby/t3code/issues/640) | | [`server.handoff`](#serverhandoff) | `{"mode":"off"}` | yes | [#215](https://github.com/scuttletoby/t3code/issues/215) | | [`server.threadRoles`](#serverthreadroles) | `{"assistant":null,"orchestrators":{}}` | yes | [#138](https://github.com/scuttletoby/t3code/issues/138) | +| [`server.assistant`](#serverassistant) | `{"enabled":false}` | yes | [#879](https://github.com/scuttletoby/t3code/issues/879) | | [`projectOverride.waitChecks`](#projectoverridewaitchecks) | not set | yes | [#84](https://github.com/scuttletoby/t3code/issues/84) | | [`projectOverride.playtest`](#projectoverrideplaytest) | not set | yes | [#260](https://github.com/scuttletoby/t3code/issues/260) | | [`projectOverride.reviewRules`](#projectoverridereviewrules) | not set | yes | [#291](https://github.com/scuttletoby/t3code/issues/291) | @@ -770,8 +771,9 @@ Switch off in `settings.json`: `"headlessUsageRefreshInterval": 0`. ### `server.mcpProfiles` Named MCP profiles. A profile says which outside MCP servers (`servers`) and which groups of T3's -own tools (`t3Tools`) a thread gets; each is `"all"` or a list. Two profiles are built in: `all` -(everything, today's behaviour) and `t3-only` (no outside servers, every T3 tool); a profile cannot +own tools (`t3Tools`) a thread gets; each is `"all"` or a list. Three profiles are built in: `all` +(everything, today's behaviour), `t3-only` (no outside servers, every T3 tool) and `assistant` (see +[assistant.md](assistant.md): no outside servers or built-in tools, three T3 tool groups); a profile cannot take their names, and one written in by hand makes that built-in refuse threads until it is removed (a save may send `null` under a built-in name to remove it) or renamed. @@ -1029,7 +1031,7 @@ the owner set up so. { "mcpProfiles": { "lean": { "servers": [], "t3Tools": ["orchestration", "threads"] } } } ``` -In the app: **Settings → Fork**, section MCP profiles. It lists `all` and `t3-only` (read-only) +In the app: **Settings → Fork**, section MCP profiles. It lists the built-ins (read-only) and each named profile, and adds, edits and deletes named ones: `servers` is all or a list of names (the editor offers the names other profiles use and takes any other; no list of the machine's servers reaches the app yet), `t3Tools` all or a list of groups, and a "No built-in tools" box sets `builtinTools: "none"`. `request_secret`, @@ -1183,6 +1185,15 @@ file after the next save of any setting, since the save writes the settings as r } ``` +### `server.assistant` + +`enabled` offers **Make assistant** in **Settings → Fork**, section Assistant: it makes a thread in +the Scratch project, picks the built-in MCP profile `assistant` for it and points +`threadRoles.assistant` at it, in one save from the person. Off (the default): no such button; a +thread already named the assistant stays as it is. Only the person can change it. Anything but +`{"enabled": true}` in the file reads as off; a save with a bad value is refused. More in +[assistant.md](assistant.md). + ### `projectOverride.waitChecks` A project's own list of wait checks. It replaces the server's list for that project as a whole (a @@ -1345,6 +1356,7 @@ switch. - [host-tools.md](host-tools.md): design for agents on a person's own computer (no code yet). - [playtest.md](playtest.md): the playtest adapter contract (steps, environment, exit codes). - [handoff.md](handoff.md): handoff instead of compaction (when, the quiet rule, the message). +- [assistant.md](assistant.md): the assistant thread (setup, its profile, what it cannot do yet). - [run-records.md](run-records.md): one record per agent run (usage, time, labels) and the weekly summary. - [`.github/fork-fleet.md`](../../.github/fork-fleet.md): the fleet runners and `CI_RUNNERS`. diff --git a/docs/fork/assistant.md b/docs/fork/assistant.md new file mode 100644 index 0000000000000..869e965306e13 --- /dev/null +++ b/docs/fork/assistant.md @@ -0,0 +1,55 @@ +# The assistant + +Fork only. The assistant is one long thread you talk to across projects. It can read threads, and +start and message work in your projects. It has no shell, no file tools and no web. Later pull +requests let it find each project's orchestrator by itself; mail and calendar come later as +simple tools ([#879](https://github.com/scuttletoby/t3code/issues/879)). + +## Making it + +1. **Settings → Fork**, section Assistant: switch on **Offer Make assistant** (`assistant.enabled`). +2. Press **Make assistant**. T3 makes a thread named "Assistant" in the Scratch project (the project + with no folder), then in one settings save picks the MCP profile `assistant` for it + (`mcpThreadProfiles`) and names it the assistant (`threadRoles.assistant`). The app opens it. + +The button needs exactly one environment selected at the top and a Claude provider that is on and +available. The thread gets Claude's default model; change it in the thread as usual. + +Only you can do this: both keys are person-only, so no agent's tool can name a thread the assistant +or give it a profile. The server checks the role as for any `threadRoles` save: the thread must +exist and be a top-level thread. If that save is refused, the new thread is removed again while it +is still empty. + +## The profile `assistant` + +A built-in MCP profile, like `all` and `t3-only`: + +- `servers: []`: no outside MCP servers. +- `builtinTools: "none"`: no shell, file or web tools of the provider. Only Claude can apply this, so + a turn on any other provider is refused and says why. +- `t3Tools`: the groups `orchestration`, `threads` and `projects`, plus the tools every profile + keeps (`send_to_user`, `request_secret`, `tool_search`). + +Any thread can pick it, not only the assistant. A sub-agent of the assistant gets at most the same. +A profile you write into `mcpProfiles` under the name `assistant` makes the built-in refuse its +threads until you remove it (the rule for every built-in name). + +Not yet: the assistant cannot launch a thread into a project whose profile is wider than its own +(the launch check refuses a narrower thread starting a wider one). It can message threads there. +A later pull request settles how the assistant starts work. + +## When things change + +- **Made twice:** the second press makes a new thread and moves the pointer to it. The old thread + keeps its `assistant` profile pick and stays as it is; delete or archive it if you like. +- **Its thread archived or deleted:** Settings shows it as archived or gone, and readers treat it as + no assistant. The pointer and the profile pick stay in the file until a new Make assistant (or a + settings save) replaces them. +- **Profile edited by hand:** an entry `mcpProfiles.assistant` makes the assistant's turns refused + (fail closed) until it is removed; the switch and pointer are not touched. +- **Settings unreadable:** a bad `assistant` value reads as off; a bad `threadRoles` as no roles; a + thread whose profile cannot be read is refused, never given every tool. +- **An older client or server:** an older fork server does not know the profile `assistant`, so + it refuses the save (the empty thread is removed) and refuses the turns of a thread already set + to it, never giving it more. An older client has no Assistant section and shows the pick as a + profile it does not know. diff --git a/packages/contracts/src/assistant.test.ts b/packages/contracts/src/assistant.test.ts new file mode 100644 index 0000000000000..5b5450d1fd458 --- /dev/null +++ b/packages/contracts/src/assistant.test.ts @@ -0,0 +1,26 @@ +// Fork (assistant): the `assistant` settings block. Off in an old or bad file; a save is strict. +import * as Schema from "effect/Schema"; +import { describe, expect, it } from "vite-plus/test"; + +import { FORK_PERSON_ONLY_KEYS } from "./forkSettings.ts"; +import { ServerSettings, ServerSettingsPatch } from "./settings.ts"; + +const decodeServer = Schema.decodeUnknownSync(ServerSettings); +const decodePatch = Schema.decodeUnknownSync(ServerSettingsPatch); + +describe("assistant settings", () => { + it("reads an old file, or anything but enabled: true, as off; keeps the other settings", () => { + for (const assistant of [undefined, null, {}, { enabled: "yes" }, [true], true]) { + const settings = decodeServer({ assistant, enableAgentBrowserAccess: false }); + expect(settings.assistant).toEqual({ enabled: false }); + expect(settings.enableAgentBrowserAccess).toBe(false); + } + expect(decodeServer({ assistant: { enabled: true } }).assistant).toEqual({ enabled: true }); + }); + + it("takes a good save, refuses a bad one, and is person-only", () => { + expect(decodePatch({ assistant: { enabled: true } }).assistant).toEqual({ enabled: true }); + expect(() => decodePatch({ assistant: { enabled: "yes" } })).toThrow(); + expect(FORK_PERSON_ONLY_KEYS).toContain("assistant"); + }); +}); diff --git a/packages/contracts/src/assistant.ts b/packages/contracts/src/assistant.ts new file mode 100644 index 0000000000000..7b9e756dfafef --- /dev/null +++ b/packages/contracts/src/assistant.ts @@ -0,0 +1,37 @@ +/** + * Fork (assistant): the `assistant` settings block. `enabled` offers "Make assistant" in Settings; + * the assistant itself is the thread `threadRoles.assistant` names, run with the built-in MCP + * profile `assistant`. Off by default. Docs: docs/fork/assistant.md. + */ +import * as Effect from "effect/Effect"; +import * as Schema from "effect/Schema"; +import * as SchemaTransformation from "effect/SchemaTransformation"; + +export const AssistantSettings = Schema.Struct({ + enabled: Schema.Boolean.pipe(Schema.withDecodingDefault(Effect.succeed(false))), +}); +export type AssistantSettings = typeof AssistantSettings.Type; + +const DEFAULT_ASSISTANT_SETTINGS: AssistantSettings = { enabled: false }; + +/** The settings file's `assistant`, read leniently: anything but `enabled: true` reads as off. */ +export const AssistantSettingsFromSettingsFile = Schema.Unknown.pipe( + Schema.decodeTo( + AssistantSettings, + SchemaTransformation.transform({ + decode: (raw: unknown): typeof AssistantSettings.Encoded => ({ + enabled: + typeof raw === "object" && + raw !== null && + (raw as { enabled?: unknown }).enabled === true, + }), + encode: (settings: typeof AssistantSettings.Encoded): unknown => settings, + }), + ), + Schema.withDecodingDefault(Effect.succeed(DEFAULT_ASSISTANT_SETTINGS)), +); + +/** A save's change: strict, so a bad value is refused; a field left out keeps its value. */ +export const AssistantSettingsPatch = Schema.Struct({ + enabled: Schema.optionalKey(Schema.Boolean), +}); diff --git a/packages/contracts/src/forkDefaults.ts b/packages/contracts/src/forkDefaults.ts index 75915a307c719..00a44d967c56f 100644 --- a/packages/contracts/src/forkDefaults.ts +++ b/packages/contracts/src/forkDefaults.ts @@ -220,6 +220,14 @@ export const FORK_SETTING_DEFAULTS: ReadonlyArray = [ reason: "No thread holds a role, so every thread is shown as upstream shows it.", decidedIn: "#138", }, + { + scope: "server", + key: "assistant", + default: { enabled: false }, + off: true, + reason: 'Settings offers no "Make assistant"; no thread is made.', + decidedIn: "#879", + }, { scope: "projectOverride", key: "mcpProfile", diff --git a/packages/contracts/src/forkSettings.ts b/packages/contracts/src/forkSettings.ts index ee1d4b6338ca5..0a5410ba4802b 100644 --- a/packages/contracts/src/forkSettings.ts +++ b/packages/contracts/src/forkSettings.ts @@ -43,6 +43,7 @@ import { ReviewRulesProjectPatch, } from "./reviewRules.ts"; import { ThreadRolesFromSettingsFile, ThreadRolesPatch } from "./threadRoles.ts"; +import { AssistantSettingsFromSettingsFile, AssistantSettingsPatch } from "./assistant.ts"; import { DEFAULT_USAGE_PACING_INSTANCE_SETTINGS, UsagePacingGateMode, @@ -59,6 +60,7 @@ import { WaitForSettingsPatch, } from "./waitFor.ts"; +export * from "./assistant.ts"; export * from "./forkFeatures.ts"; export * from "./handoff.ts"; export * from "./mcpProfile.ts"; @@ -138,6 +140,8 @@ export const ForkServerSettingsFields = { ), /** Which thread is the assistant and each project's orchestrator; none. A bad entry drops alone. */ threadRoles: ThreadRolesFromSettingsFile, + /** Offers "Make assistant"; off. A bad value reads as off. */ + assistant: AssistantSettingsFromSettingsFile, }; /** A key of {@link ForkServerSettingsFields}. */ @@ -183,6 +187,8 @@ export const ForkServerSettingsPatchFields = { placementNeeds: Schema.optionalKey(PlacementNeedsPatch), /** Strict ids; the server also refuses a pointer to a thread that cannot hold the role. */ threadRoles: Schema.optionalKey(ThreadRolesPatch), + /** Strict: a save refuses a bad value or an unknown field. */ + assistant: Schema.optionalKey(AssistantSettingsPatch), } satisfies Record; /** @@ -234,6 +240,7 @@ export const FORK_PATCH_RULES: { readonly [K in ForkServerSettingKey]: ForkPatch // One orchestrator per project entry, so two people setting different projects keep both; two // saves of the same project, the last one wins. threadRoles: { fields: { assistant: "replace", orchestrators: { replaceEntries: {} } } }, + assistant: "merge-fields", }; /** diff --git a/packages/contracts/src/mcpProfile.ts b/packages/contracts/src/mcpProfile.ts index 9d2eef040ca5a..ca716e3ae2a9e 100644 --- a/packages/contracts/src/mcpProfile.ts +++ b/packages/contracts/src/mcpProfile.ts @@ -13,8 +13,17 @@ import { TrimmedString } from "./baseSchemas.ts"; export const MCP_PROFILE_ALL = "all"; /** No outside servers, every T3 tool. */ export const MCP_PROFILE_T3_ONLY = "t3-only"; -/** The two profiles every build knows; `mcpProfiles` cannot redefine them. */ -const MCP_BUILT_IN_PROFILE_NAMES: ReadonlyArray = [MCP_PROFILE_ALL, MCP_PROFILE_T3_ONLY]; +/** + * The assistant's: no outside servers, no built-in tools, and only the T3 tools that find, start + * and message threads and projects (docs/fork/assistant.md). + */ +export const MCP_PROFILE_ASSISTANT = "assistant"; +/** The profiles every build knows; `mcpProfiles` cannot redefine them. */ +const MCP_BUILT_IN_PROFILE_NAMES: ReadonlyArray = [ + MCP_PROFILE_ALL, + MCP_PROFILE_T3_ONLY, + MCP_PROFILE_ASSISTANT, +]; /** * A profile's `builtinTools`: `none` starts the thread with no built-in tools of the provider (no * shell, files or web; only MCP tools). Only Claude applies it; a turn on any other driver is @@ -31,7 +40,7 @@ const MCP_PROFILE_NAME_PATTERN = /^[a-z0-9][a-z0-9-]{0,39}$/u; export const McpProfileName = Schema.String.check(Schema.isPattern(MCP_PROFILE_NAME_PATTERN)); export type McpProfileName = typeof McpProfileName.Type; -/** True for `all` and `t3-only`. */ +/** True for a built-in profile's name: `all`, `t3-only` and `assistant`. */ export const isBuiltInMcpProfileName = (name: string): boolean => MCP_BUILT_IN_PROFILE_NAMES.includes(name); diff --git a/packages/contracts/src/mcpProfileResolve.ts b/packages/contracts/src/mcpProfileResolve.ts index 17f6336416a00..e5852b8fde5db 100644 --- a/packages/contracts/src/mcpProfileResolve.ts +++ b/packages/contracts/src/mcpProfileResolve.ts @@ -8,6 +8,7 @@ import { MCP_BUILTIN_TOOLS_NONE, MCP_CARRIED_PROFILES_REFUSE, MCP_PROFILE_ALL, + MCP_PROFILE_ASSISTANT, MCP_PROFILE_T3_ONLY, MCP_SUBAGENT_INHERIT, MCP_T3_TOOL_GROUPS, @@ -108,9 +109,15 @@ export type McpProfileResolution = McpProfileResolved | McpProfileCannotApply; /** Longer lineages are refused; real delegation chains are a few threads deep. */ export const MCP_PROFILE_MAX_LINEAGE = 64; -const BUILT_IN_PROFILES: Readonly> = { +/** What each built-in profile gives; Settings lists them from here. */ +export const MCP_BUILT_IN_PROFILES: Readonly> = { [MCP_PROFILE_ALL]: { servers: "all", t3Tools: "all" }, [MCP_PROFILE_T3_ONLY]: { servers: [], t3Tools: "all" }, + [MCP_PROFILE_ASSISTANT]: { + servers: [], + t3Tools: ["orchestration", "threads", "projects"], + builtinTools: MCP_BUILTIN_TOOLS_NONE, + }, }; const KNOWN_GROUPS: ReadonlySet = new Set(MCP_T3_TOOL_GROUPS); @@ -181,7 +188,9 @@ type Lookup = /** A named profile: a built-in, or an entry of `mcpProfiles` checked now. */ function lookUp(settings: McpProfileSettings, name: string): Lookup { const profiles: unknown = settings.mcpProfiles; - const builtIn = Object.hasOwn(BUILT_IN_PROFILES, name) ? BUILT_IN_PROFILES[name] : undefined; + const builtIn = Object.hasOwn(MCP_BUILT_IN_PROFILES, name) + ? MCP_BUILT_IN_PROFILES[name] + : undefined; if (builtIn !== undefined) { // A save never writes an entry under a built-in's name, so one is a hand edit. Which of the // two the owner meant is unknown, so neither is used. diff --git a/packages/shared/src/forkSettingsPatch.test.ts b/packages/shared/src/forkSettingsPatch.test.ts index 709be547c98bc..98550aafd0f00 100644 --- a/packages/shared/src/forkSettingsPatch.test.ts +++ b/packages/shared/src/forkSettingsPatch.test.ts @@ -303,6 +303,7 @@ describe("fork settings save check (MCP profile references)", () => { ["a built-in default", { mcpProfile: "t3-only" }], ["inherit as the sub-agent rule", { mcpSubagentProfile: "inherit" }], ["a pick of a built-in", { mcpThreadProfiles: { "thread-1": "all" } }], + ["a pick of the assistant's built-in", { mcpThreadProfiles: { "thread-1": "assistant" } }], [ "a default added in the same save", { mcpProfiles: { docs: { servers: ["docs"], t3Tools: "all" } }, mcpProfile: "docs" }, From cfa6854103ecefeb6dd28c259e415b14d75c32f8 Mon Sep 17 00:00:00 2001 From: scuttletoby <123843277+scuttletoby@users.noreply.github.com> Date: Sun, 22 Nov 2026 12:11:14 +0000 Subject: [PATCH 2/3] Fork: the MCP profile list test counts the assistant built-in Co-Authored-By: Claude Opus 5.5 --- .../settings/fork/mcpProfileSettings.logic.test.ts | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/apps/web/src/components/settings/fork/mcpProfileSettings.logic.test.ts b/apps/web/src/components/settings/fork/mcpProfileSettings.logic.test.ts index d070433cc7fdb..991e9aecd776a 100644 --- a/apps/web/src/components/settings/fork/mcpProfileSettings.logic.test.ts +++ b/apps/web/src/components/settings/fork/mcpProfileSettings.logic.test.ts @@ -35,14 +35,15 @@ function serverSave(settings: ServerSettings, patch: unknown): ServerSettings { const LEAN = { servers: ["docs"], t3Tools: ["threads", "orchestration"] }; describe("MCP profile list", () => { - it("shows all and t3-only read-only from an old settings file, and nothing else", () => { + it("shows the built-ins read-only from an old settings file, and nothing else", () => { const old = fromFile({}); const rows = mcpProfileRows(old, null); expect(rows.map((row) => [row.name, row.kind, row.state])).toEqual([ ["all", "built-in", "ok"], ["t3-only", "built-in", "ok"], + ["assistant", "built-in", "ok"], ]); - expect(mcpProfileChoices(old)).toEqual(["all", "t3-only"]); + expect(mcpProfileChoices(old)).toEqual(["all", "t3-only", "assistant"]); // The default and the rule show as their defaults; nothing to write. expect(shownProfileRef(old.mcpProfile, "all")).toBe("all"); expect(shownProfileRef(old.mcpSubagentProfile, "inherit")).toBe("inherit"); @@ -144,7 +145,7 @@ describe("saving and deleting a profile", () => { it("refuses built-in names, inherit, bad names and a name taken", () => { const settings = fromFile({ mcpProfiles: { lean: LEAN } }); const draft = { servers: [] as string[], t3Tools: "all" as const }; - for (const name of ["all", "t3-only"]) { + for (const name of ["all", "t3-only", "assistant"]) { expect(saveMcpProfilePatch(settings, null, { ...draft, name })).toEqual({ problem: `"${name}" is a built-in profile; pick another name.`, }); From b1a7658bf6b5a21f23aff5bd229e94003eddbb3b Mon Sep 17 00:00:00 2001 From: scuttletoby <123843277+scuttletoby@users.noreply.github.com> Date: Sun, 22 Nov 2026 12:20:42 +0000 Subject: [PATCH 3/3] Fork: assistant setup review fixes - 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 --- FORK_CHANGES.md | 2 +- .../settings/fork/AssistantSettings.tsx | 42 +++++++++++----- .../fork/assistantSetup.logic.test.ts | 32 ++++++------ .../settings/fork/assistantSetup.logic.ts | 43 ++++++++-------- docs/fork/README.md | 3 +- docs/fork/assistant.md | 50 +++++++++++++------ packages/contracts/src/mcpProfile.ts | 4 +- 7 files changed, 109 insertions(+), 67 deletions(-) diff --git a/FORK_CHANGES.md b/FORK_CHANGES.md index d2cc6440bec42..56f533ca1d653 100644 --- a/FORK_CHANGES.md +++ b/FORK_CHANGES.md @@ -49,7 +49,7 @@ setting is missing here or a setting named here does not exist. | Model policy: the setting for which models (and efforts) agents may pick, per provider driver: off, advise or enforce, and the allowed rows. The server checks an agent's pick (`delegate_task`, `create_threads`, `t3_thread_launch`, `t3_thread_configure`, here, and both before and after it goes to linked machines): a model in no row, a call that names no model, or an effort off its row is refused in enforce, only noted in advise. A person's own pick is never refused; Settings marks one outside the rows. A bad hand edit, or a settings file that does not parse, refuses every agent pick (a warning if the value says advise). Settings offers the fork's start rows (Opus 5.5 and Fable 5.2) while none are saved. While it is on, a child whose call names its model keeps only the options it names. | Agents should use the models the person chose for each kind of work. | `server.modelPolicy` | off | [#268](https://github.com/scuttletoby/t3code/pull/268), [#731](https://github.com/scuttletoby/t3code/issues/731) | | Placement, part 1: the settings only. `placement` (off, advise or enforce; this machine's labels, an optional facts command, label groups that must never meet on one machine, and a weight per linked machine) and `placementNeeds` (labels a project's work needs). Person-only; a bad `placement` reads as off and a bad `placementNeeds` fits no machine, each kept as written. Nothing reads them yet. | Delegated work should go to a machine that has what it needs, and never where it must not run. | `server.placement`, `server.placementNeeds`, `projectOverride.placementNeeds` | off | [#134](https://github.com/scuttletoby/t3code/issues/134) | | Calm sidebar, part 1: the settings. `threadRoles` names the assistant thread and one orchestrator per project; the server refuses a role for a thread that is missing, deleted, a sub-agent, a side chat, delegated from a linked machine or in another project. `calmSidebarEnabled` is the per-device switch. Nothing shows them yet. | A short sidebar: the threads that matter on top, the rest folded. | `server.threadRoles`, `client.calmSidebarEnabled` | off | [#928](https://github.com/scuttletoby/t3code/pull/928) | -| Assistant setup: the switch `assistant.enabled` (off) offers **Make assistant** in Settings, which makes a thread in the Scratch project, names it `threadRoles.assistant` and picks for it the new built-in MCP profile `assistant` (no outside servers, no shell, file or web tools; T3 tool groups `orchestration`, `threads` and `projects`). Claude only. | +| Assistant setup: the switch `assistant.enabled` (off) offers **Make assistant** in Settings, which makes a thread in the Scratch project, names it `threadRoles.assistant` and picks for it the new built-in MCP profile `assistant` (no outside servers, no shell, file or web tools; T3 tool groups `orchestration`, `threads` and `projects`). Claude only. | One thread you talk to across projects, with only T3's tools. | `server.assistant`, `server.mcpProfiles` | off | [#953](https://github.com/scuttletoby/t3code/pull/953) | ## Repository, CI and releases diff --git a/apps/web/src/components/settings/fork/AssistantSettings.tsx b/apps/web/src/components/settings/fork/AssistantSettings.tsx index 53228c6fc008a..574d8d4a4367c 100644 --- a/apps/web/src/components/settings/fork/AssistantSettings.tsx +++ b/apps/web/src/components/settings/fork/AssistantSettings.tsx @@ -9,10 +9,11 @@ import { DEFAULT_PROVIDER_INTERACTION_MODE, DEFAULT_RUNTIME_MODE, type EnvironmentId, + type ServerSettingsPatch, } from "@t3tools/contracts"; import { scopeThreadRef } from "@t3tools/client-runtime/environment"; import { useNavigate } from "@tanstack/react-router"; -import { useState } from "react"; +import { useRef, useState } from "react"; import { newThreadId } from "~/lib/utils"; import { useScratchProject } from "../../../hooks/useScratchProject"; @@ -30,9 +31,10 @@ import { useUpdateScopedSettings } from "../useScopedSettings"; import { ForkRow } from "./ForkRow"; import { assistantModelSelection, + assistantProfilePatch, + assistantRolePatch, assistantThreadState, assistantThreadText, - makeAssistantPatch, } from "./assistantSetup.logic"; export function AssistantSettings() { @@ -46,6 +48,7 @@ export function AssistantSettings() { const shells = useThreadShells(); const navigate = useNavigate(); const [busy, setBusy] = useState(false); + const running = useRef(false); const [error, setError] = useState(null); const target = targets.length === 1 ? targets[0]! : null; @@ -71,14 +74,28 @@ export function AssistantSettings() { ); const modelSelection = assistantModelSelection(providers.get(environmentId) ?? []); + // Resolves once the save settled: true when every target saved it. + const save = (patch: ServerSettingsPatch) => + new Promise((resolve) => + updateSettings(patch, { onFailed: () => resolve(false), onSaved: () => resolve(true) }), + ); + const makeAssistant = async () => { - if (modelSelection === null) return; + // A ref, not only the state: a double click arrives before the disabled button re-renders. + if (modelSelection === null || running.current) return; + running.current = true; setBusy(true); setError(null); try { const project = await openScratchProject(environmentId); if (project === null) return; const threadId = newThreadId(); + // The pick first: a stop at any later point leaves no thread, or a thread already narrowed. + // A pick for a thread that never gets made does nothing. + if (!(await save(assistantProfilePatch(threadId)))) { + setError("The server refused the assistant profile. Nothing was made."); + return; + } const created = await createThread({ environmentId, input: { @@ -96,7 +113,7 @@ export function AssistantSettings() { setError("Could not make the assistant's thread. Try again."); return; } - // An empty thread the save did not name is removed; one that got a message stays. + // An empty thread the role save did not name is removed; one that got a message stays. const discard = () => void deleteThread({ environmentId, input: { threadId, onlyIfUnused: true } }); const ref = scopeThreadRef(environmentId, threadId); @@ -105,15 +122,14 @@ export function AssistantSettings() { discard(); return; } - updateSettings(makeAssistantPatch(threadId), { - onFailed: () => { - setError("The server refused to name the new thread the assistant. Nothing was changed."); - discard(); - }, - onSaved: () => - void navigate({ to: "/$environmentId/$threadId", params: buildThreadRouteParams(ref) }), - }); + if (!(await save(assistantRolePatch(threadId)))) { + setError("The server refused to name the new thread the assistant. It was removed."); + discard(); + return; + } + void navigate({ to: "/$environmentId/$threadId", params: buildThreadRouteParams(ref) }); } finally { + running.current = false; setBusy(false); } }; @@ -141,7 +157,7 @@ export function AssistantSettings() { serverScoped {...searchableSetting("assistant-thread")} settingKeys={["threadRoles"]} - lockPaths={["threadRoles"]} + lockPaths={["threadRoles", "mcpThreadProfiles"]} status={error} description={`${assistantThreadText(state)} Make assistant makes a new thread in the Scratch project and names it the assistant; an earlier one stays as it is.${ modelSelection === null ? " It needs a Claude provider that is on and available." : "" diff --git a/apps/web/src/components/settings/fork/assistantSetup.logic.test.ts b/apps/web/src/components/settings/fork/assistantSetup.logic.test.ts index d1c38ff0bd717..9daa8f1b38b58 100644 --- a/apps/web/src/components/settings/fork/assistantSetup.logic.test.ts +++ b/apps/web/src/components/settings/fork/assistantSetup.logic.test.ts @@ -13,8 +13,9 @@ import { describe, expect, it } from "vite-plus/test"; import { assistantModelSelection, + assistantProfilePatch, + assistantRolePatch, assistantThreadState, - makeAssistantPatch, } from "./assistantSetup.logic"; const provider = ( @@ -58,25 +59,26 @@ describe("Make assistant", () => { expect(assistantModelSelection([off, gone])).toBeNull(); }); - it("one save names the thread the assistant and gives it the assistant profile", () => { + it("picks the profile first, before the thread exists, then names the assistant", () => { const decode = Schema.decodeUnknownSync(ServerSettings); const before = decode({ mcpThreadProfiles: { old: "t3-only" } }); const thread = ThreadId.make("thread-new"); - const after = applyServerSettingsPatch(before, makeAssistantPatch(thread)); - expect(after.threadRoles.assistant).toBe("thread-new"); - expect(after.mcpThreadProfiles).toEqual({ old: "t3-only", "thread-new": "assistant" }); - expect(forkSettingsWriteProblem(before, after)).toBeUndefined(); - const resolved = resolveMcpProfile(after, [{ threadId: thread, delegated: false }]); + // Saved before the thread is made: if setup stops here, no wide "Assistant" thread exists. + const picked = applyServerSettingsPatch(before, assistantProfilePatch(thread)); + expect(forkSettingsWriteProblem(before, picked)).toBeUndefined(); + expect(picked.threadRoles.assistant).toBeNull(); + const resolved = resolveMcpProfile(picked, [{ threadId: thread, delegated: false }]); expect(resolved._tag === "Resolved" && resolved.profile.builtinTools).toBe("none"); + const named = applyServerSettingsPatch(picked, assistantRolePatch(thread)); + expect(forkSettingsWriteProblem(picked, named)).toBeUndefined(); + expect(named.threadRoles.assistant).toBe("thread-new"); + expect(named.mcpThreadProfiles).toEqual({ old: "t3-only", "thread-new": "assistant" }); }); - it("shows a deleted or archived assistant thread as gone or archived", () => { - const threads = [{ id: "a", title: "Assistant", archivedAt: null }]; - expect(assistantThreadState(null, threads)).toEqual({ kind: "none" }); - expect(assistantThreadState("a", threads)).toMatchObject({ kind: "ok", title: "Assistant" }); - expect(assistantThreadState("b", threads)).toEqual({ kind: "gone", threadId: "b" }); - expect( - assistantThreadState("a", [{ ...threads[0]!, archivedAt: "2026-01-01T00:00:00Z" }]).kind, - ).toBe("archived"); + it("shows an assistant thread that is not active (archived or deleted) as none", () => { + const active = [{ id: "a", title: "Assistant" }]; + expect(assistantThreadState(null, active)).toEqual({ kind: "none" }); + expect(assistantThreadState("a", active)).toMatchObject({ kind: "ok", title: "Assistant" }); + expect(assistantThreadState("b", active)).toEqual({ kind: "inactive", threadId: "b" }); }); }); diff --git a/apps/web/src/components/settings/fork/assistantSetup.logic.ts b/apps/web/src/components/settings/fork/assistantSetup.logic.ts index bc13edcf37c0f..a4870c0db1c23 100644 --- a/apps/web/src/components/settings/fork/assistantSetup.logic.ts +++ b/apps/web/src/components/settings/fork/assistantSetup.logic.ts @@ -40,45 +40,46 @@ export function assistantModelSelection( return model === undefined ? null : createModelSelection(pick.instanceId, model.slug); } -/** The one save that makes `threadId` the assistant: its profile pick and the role pointer. */ -export const makeAssistantPatch = (threadId: ThreadId): ServerSettingsPatch => ({ +/** + * The first save: the thread's profile pick, made before the thread exists, so a thread named + * "Assistant" never runs with a wider profile, even when the setup stops half-way. + */ +export const assistantProfilePatch = (threadId: ThreadId): ServerSettingsPatch => ({ mcpThreadProfiles: { [threadId]: MCP_PROFILE_ASSISTANT }, +}); + +/** The second save, once the thread exists: the role pointer (the server's role check decides). */ +export const assistantRolePatch = (threadId: ThreadId): ServerSettingsPatch => ({ threadRoles: { assistant: threadId }, }); -/** The thread `threadRoles.assistant` names, as Settings shows it. */ +/** + * The thread `threadRoles.assistant` names, as Settings shows it. The client's thread list holds + * active threads only, so an archived one reads as not active, like a deleted one. + */ export type AssistantThreadState = | { readonly kind: "none" } - | { readonly kind: "gone"; readonly threadId: string } - | { readonly kind: "archived" | "ok"; readonly threadId: string; readonly title: string }; + | { readonly kind: "inactive"; readonly threadId: string } + | { readonly kind: "ok"; readonly threadId: string; readonly title: string }; /** Readers treat a deleted or archived assistant thread as no assistant (threadRoles docs). */ export function assistantThreadState( assistant: string | null, - threads: ReadonlyArray<{ - readonly id: string; - readonly title: string; - readonly archivedAt: string | null; - }>, + activeThreads: ReadonlyArray<{ readonly id: string; readonly title: string }>, ): AssistantThreadState { if (assistant === null) return { kind: "none" }; - const thread = threads.find((candidate) => candidate.id === assistant); - if (thread === undefined) return { kind: "gone", threadId: assistant }; - return { - kind: thread.archivedAt === null ? "ok" : "archived", - threadId: assistant, - title: thread.title, - }; + const thread = activeThreads.find((candidate) => candidate.id === assistant); + return thread === undefined + ? { kind: "inactive", threadId: assistant } + : { kind: "ok", threadId: assistant, title: thread.title }; } export function assistantThreadText(state: AssistantThreadState): string { switch (state.kind) { case "none": return "No thread is the assistant yet."; - case "gone": - return `The assistant was thread ${state.threadId}, which is deleted or not on this server. Make a new one.`; - case "archived": - return `The assistant is "${state.title}", which is archived, so it counts as none. Unarchive it or make a new one.`; + case "inactive": + return `The assistant was thread ${state.threadId}, which is archived, deleted or not on this server, so there is none. Unarchive it or make a new one.`; case "ok": return `The assistant is "${state.title}".`; } diff --git a/docs/fork/README.md b/docs/fork/README.md index c33e1fb4a0a66..03419afbdea04 100644 --- a/docs/fork/README.md +++ b/docs/fork/README.md @@ -1189,7 +1189,8 @@ file after the next save of any setting, since the save writes the settings as r `enabled` offers **Make assistant** in **Settings → Fork**, section Assistant: it makes a thread in the Scratch project, picks the built-in MCP profile `assistant` for it and points -`threadRoles.assistant` at it, in one save from the person. Off (the default): no such button; a +`threadRoles.assistant` at it, in two saves from the person (the pick first, before the thread +exists). Off (the default): no such button; a thread already named the assistant stays as it is. Only the person can change it. Anything but `{"enabled": true}` in the file reads as off; a save with a bad value is refused. More in [assistant.md](assistant.md). diff --git a/docs/fork/assistant.md b/docs/fork/assistant.md index 869e965306e13..c3dbdb3929d70 100644 --- a/docs/fork/assistant.md +++ b/docs/fork/assistant.md @@ -1,16 +1,18 @@ # The assistant Fork only. The assistant is one long thread you talk to across projects. It can read threads, and -start and message work in your projects. It has no shell, no file tools and no web. Later pull +start and message work in your projects. It has no shell, no file tools and no web of its own. Later pull requests let it find each project's orchestrator by itself; mail and calendar come later as simple tools ([#879](https://github.com/scuttletoby/t3code/issues/879)). ## Making it 1. **Settings → Fork**, section Assistant: switch on **Offer Make assistant** (`assistant.enabled`). -2. Press **Make assistant**. T3 makes a thread named "Assistant" in the Scratch project (the project - with no folder), then in one settings save picks the MCP profile `assistant` for it - (`mcpThreadProfiles`) and names it the assistant (`threadRoles.assistant`). The app opens it. +2. Press **Make assistant**. T3 first saves the MCP profile pick `assistant` for a new thread id + (`mcpThreadProfiles`), then makes a thread named "Assistant" with that id in the Scratch project + (the project with no folder), then names it the assistant (`threadRoles.assistant`). The app + opens it. The pick comes first so a thread called "Assistant" never runs with a wider profile, + even if setup stops half-way. The button needs exactly one environment selected at the top and a Claude provider that is on and available. The thread gets Claude's default model; change it in the thread as usual. @@ -18,7 +20,8 @@ available. The thread gets Claude's default model; change it in the thread as us Only you can do this: both keys are person-only, so no agent's tool can name a thread the assistant or give it a profile. The server checks the role as for any `threadRoles` save: the thread must exist and be a top-level thread. If that save is refused, the new thread is removed again while it -is still empty. +is still empty. The button is locked while a managed policy owns `threadRoles` or +`mcpThreadProfiles`. ## The profile `assistant` @@ -28,11 +31,26 @@ A built-in MCP profile, like `all` and `t3-only`: - `builtinTools: "none"`: no shell, file or web tools of the provider. Only Claude can apply this, so a turn on any other provider is refused and says why. - `t3Tools`: the groups `orchestration`, `threads` and `projects`, plus the tools every profile - keeps (`send_to_user`, `request_secret`, `tool_search`). + keeps (`send_to_user`, `request_secret`, `tool_search`). These are more than reading and + messaging: + - `orchestration`: list, read, message, wait for, interrupt and update threads; delegate tasks + and launch threads (`delegate_task`, `create_threads`); schedule tasks; link and unlink + environments. + - `threads`: launch, configure (model and settings of another thread), transfer, search and + organize threads. + - `projects`: list and read projects, and also create, clone (a repository onto disk), update and + delete them. + + Each of these keeps its own server checks (model policy, launch limits, person-only settings). Any thread can pick it, not only the assistant. A sub-agent of the assistant gets at most the same. -A profile you write into `mcpProfiles` under the name `assistant` makes the built-in refuse its -threads until you remove it (the rule for every built-in name). +A profile in `mcpProfiles` under the name `assistant` makes the built-in refuse its threads until +you remove it (the rule for every built-in name). + +**Upgrading with your own profile called `assistant`:** before this version that was an ordinary +name. After it, every thread that picks it is refused until the entry is removed or renamed. When +you remove it, those threads get the built-in `assistant` instead, which may differ from yours, so +rename it and move their picks first. Not yet: the assistant cannot launch a thread into a project whose profile is wider than its own (the launch check refuses a narrower thread starting a wider one). It can message threads there. @@ -41,15 +59,19 @@ A later pull request settles how the assistant starts work. ## When things change - **Made twice:** the second press makes a new thread and moves the pointer to it. The old thread - keeps its `assistant` profile pick and stays as it is; delete or archive it if you like. -- **Its thread archived or deleted:** Settings shows it as archived or gone, and readers treat it as - no assistant. The pointer and the profile pick stay in the file until a new Make assistant (or a - settings save) replaces them. + keeps its `assistant` profile pick and stays as it is; delete or archive it if you like. The + button is off while a setup runs, so a double click makes one thread. +- **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 with the `assistant` profile and no role; Settings still says there is no assistant. +- **Its thread archived or deleted:** Settings says it is archived, deleted or not on this server + (the app's thread list holds active threads only), and readers treat it as no assistant. The + pointer and the profile pick stay in the file until a new Make assistant replaces the pointer. - **Profile edited by hand:** an entry `mcpProfiles.assistant` makes the assistant's turns refused (fail closed) until it is removed; the switch and pointer are not touched. - **Settings unreadable:** a bad `assistant` value reads as off; a bad `threadRoles` as no roles; a thread whose profile cannot be read is refused, never given every tool. - **An older client or server:** an older fork server does not know the profile `assistant`, so - it refuses the save (the empty thread is removed) and refuses the turns of a thread already set - to it, never giving it more. An older client has no Assistant section and shows the pick as a + it refuses the first save (the pick) and nothing is made, and it refuses the turns of a thread + already set to it, never giving it more. An older client has no Assistant section and shows the pick as a profile it does not know. diff --git a/packages/contracts/src/mcpProfile.ts b/packages/contracts/src/mcpProfile.ts index ca716e3ae2a9e..43c0899d1e01d 100644 --- a/packages/contracts/src/mcpProfile.ts +++ b/packages/contracts/src/mcpProfile.ts @@ -14,8 +14,8 @@ export const MCP_PROFILE_ALL = "all"; /** No outside servers, every T3 tool. */ export const MCP_PROFILE_T3_ONLY = "t3-only"; /** - * The assistant's: no outside servers, no built-in tools, and only the T3 tools that find, start - * and message threads and projects (docs/fork/assistant.md). + * The assistant's: no outside servers, no built-in tools, and the T3 groups `orchestration`, + * `threads` and `projects` (docs/fork/assistant.md lists what they can do). */ export const MCP_PROFILE_ASSISTANT = "assistant"; /** The profiles every build knows; `mcpProfiles` cannot redefine them. */