From cb4f75befc17ec3420676d49dd1b5b87ea051294 Mon Sep 17 00:00:00 2001 From: Noah Schenk Date: Thu, 12 Nov 2026 11:20:58 +0100 Subject: [PATCH 1/5] feat(settings): let users override visual delivery guidance --- .../Adapters/ClaudeAdapterV2.test.ts | 3 ++ .../Adapters/ClaudeAdapterV2.ts | 8 +++- .../Adapters/CodexAdapterV2.test.ts | 6 +++ .../Adapters/CodexAdapterV2.ts | 7 ++++ .../CodexDeveloperInstructions.test.ts | 2 +- .../provider/CodexDeveloperInstructions.ts | 5 ++- apps/server/src/serverSettings.test.ts | 21 ++++++++++ docs/user/html-renders.md | 18 +++++++++ packages/contracts/src/settings.test.ts | 15 +++++++ packages/contracts/src/settings.ts | 7 ++++ packages/provider-acp/src/server/adapter.ts | 3 ++ .../server/orchestrationInstructions.test.ts | 40 +++++++++++++++++++ .../src/server/orchestrationInstructions.ts | 39 +++++++++++++----- .../provider-cursor/src/server/adapter.ts | 1 + .../src/server/adapter.test.ts | 4 ++ .../provider-opencode/src/server/adapter.ts | 1 + .../src/server/v2/adapter.ts | 6 ++- packages/provider-pi/src/server/adapter.ts | 9 ++++- .../src/server/mcpBridge.testkit.ts | 2 + .../src/server/mcpExtensionSource.test.ts | 16 ++++++++ .../src/server/mcpExtensionSource.ts | 4 +- 21 files changed, 200 insertions(+), 17 deletions(-) diff --git a/apps/server/src/orchestration-v2/Adapters/ClaudeAdapterV2.test.ts b/apps/server/src/orchestration-v2/Adapters/ClaudeAdapterV2.test.ts index 043f3b8a756d9..c5e910b26f08a 100644 --- a/apps/server/src/orchestration-v2/Adapters/ClaudeAdapterV2.test.ts +++ b/apps/server/src/orchestration-v2/Adapters/ClaudeAdapterV2.test.ts @@ -794,6 +794,7 @@ describe("ClaudeAdapterV2 native protocol logging", () => { instanceId: ProviderInstanceId.make("claudeAgent"), model: "claude-sonnet-4-6", }, + visualInstructions: "Publish reports using my publishing skill.", nativeThreadId: "native-thread-claude-mcp", resume: false, cwd: "/workspace", @@ -811,6 +812,8 @@ describe("ClaudeAdapterV2 native protocol logging", () => { assert.equal(systemPrompt.preset, "claude_code"); assert.include(systemPrompt.append ?? "", "Use `delegate_task`"); assert.include(systemPrompt.append ?? "", "call `t3_background_wait`"); + assert.include(systemPrompt.append ?? "", "Publish reports using my publishing skill."); + assert.notInclude(systemPrompt.append ?? "", "Answer data with a trend"); assert.notInclude(systemPrompt.append ?? "", "## T3 Code devices"); const logged = ClaudeAdapterV2.loggedClaudeQueryOptions(options); assert.equal(logged.hasMcpServers, true); diff --git a/apps/server/src/orchestration-v2/Adapters/ClaudeAdapterV2.ts b/apps/server/src/orchestration-v2/Adapters/ClaudeAdapterV2.ts index 7590a2c950bc7..41e33ec322002 100644 --- a/apps/server/src/orchestration-v2/Adapters/ClaudeAdapterV2.ts +++ b/apps/server/src/orchestration-v2/Adapters/ClaudeAdapterV2.ts @@ -215,7 +215,7 @@ import { import type { ManagedServerProvider } from "@t3tools/provider-core/server/snapshot"; import { T3_CODE_DEVICE_TOOL_INSTRUCTIONS_WITH_TOOL_SEARCH, - T3_CODE_ORCHESTRATION_INSTRUCTIONS, + t3OrchestrationInstructions, } from "@t3tools/provider-core/server/orchestrationInstructions"; import { buildRuntimeInstructions } from "@t3tools/provider-core/server/runtimeInstructions"; import { @@ -2119,6 +2119,7 @@ export function makeClaudeQueryOptions(input: { readonly cwd: string | null; readonly attachmentsDir?: string; readonly settings?: ClaudeSettings; + readonly visualInstructions?: string | null; readonly promptSuggestions?: boolean; readonly sdkSettings?: string | ClaudeSdkSettings; readonly environment?: NodeJS.ProcessEnv; @@ -2275,7 +2276,7 @@ export function makeClaudeQueryOptions(input: { buildRuntimeInstructions({ harness: "Claude Code" }) + (input.mcpServers === undefined ? "" - : T3_CODE_ORCHESTRATION_INSTRUCTIONS + + : t3OrchestrationInstructions(input.visualInstructions) + CLAUDE_BACKGROUND_WAIT_INSTRUCTIONS + CLAUDE_SEND_TO_USER_INSTRUCTIONS + (deviceInstructions @@ -12613,6 +12614,9 @@ export const makeClaudeAdapterV2 = Effect.fn("makeClaudeAdapterV2")(function* ( const shouldResume = resumeSessionAt !== undefined || openedWithResume || hasPersistedProviderTurn; const queryOptions = makeClaudeQueryOptions({ + visualInstructions: Option.isSome(serverSettings) + ? (yield* serverSettings.value.getSettings.pipe(Effect.orDie)).visualInstructions + : null, modelSelection: turnInput.modelSelection, modelCatalog: catalog, nativeThreadId, diff --git a/apps/server/src/orchestration-v2/Adapters/CodexAdapterV2.test.ts b/apps/server/src/orchestration-v2/Adapters/CodexAdapterV2.test.ts index b41e6e0c13345..2f2d83be1ecb9 100644 --- a/apps/server/src/orchestration-v2/Adapters/CodexAdapterV2.test.ts +++ b/apps/server/src/orchestration-v2/Adapters/CodexAdapterV2.test.ts @@ -265,6 +265,7 @@ describe("CodexAdapterV2 runtime policy", () => { const modelSelection = { instanceId: ProviderInstanceId.make("codex"), model: "gpt-5.4" }; const appContext = [{ key: "mcp_app_todos_list_todos_item-1", text: "Filtered to overdue" }]; const alone = yield* CodexAdapterV2.buildCodexTurnStartParams({ + visualInstructions: "Publish reports using my publishing skill.", nativeThreadId: "native-app-context", codexInput: [{ type: "text", text: "what's on my list?" }], runtimePolicy: policy, @@ -275,6 +276,7 @@ describe("CodexAdapterV2 runtime policy", () => { "mcp_app_todos_list_todos_item-1": { kind: "untrusted", value: "Filtered to overdue" }, }); const withT3 = yield* CodexAdapterV2.buildCodexTurnStartParams({ + visualInstructions: "Publish reports using my publishing skill.", nativeThreadId: "native-app-context", codexInput: [{ type: "text", text: "what's on my list?" }], runtimePolicy: policy, @@ -287,6 +289,10 @@ describe("CodexAdapterV2 runtime policy", () => { value: "Filtered to overdue", }); assert.isDefined(withT3.additionalContext?.["t3_code_runtime"]); + assert.include( + withT3.additionalContext?.["t3_code_orchestration_03"]?.value ?? "", + "Publish reports using my publishing skill.", + ); }), ); }); diff --git a/apps/server/src/orchestration-v2/Adapters/CodexAdapterV2.ts b/apps/server/src/orchestration-v2/Adapters/CodexAdapterV2.ts index c340645bb9f52..90d3c4b5cc9be 100644 --- a/apps/server/src/orchestration-v2/Adapters/CodexAdapterV2.ts +++ b/apps/server/src/orchestration-v2/Adapters/CodexAdapterV2.ts @@ -109,6 +109,7 @@ import * as PortScanner from "../../preview/PortScanner.ts"; import { getCodexServiceTierOptionValue } from "../../codexModelOptions.ts"; import { ServerConfig } from "../../config.ts"; import { expandHomePath } from "@t3tools/provider-core/server/pathExpansion"; +import * as ServerSettings from "../../serverSettings.ts"; import { buildCodexAdditionalContext } from "../../provider/CodexDeveloperInstructions.ts"; import { describeMcpElicitation, @@ -783,6 +784,7 @@ export const buildCodexTurnStartParams = Effect.fn("CodexAdapterV2.buildCodexTur readonly codexInput: ReadonlyArray; readonly runtimePolicy: ProviderAdapter.ProviderAdapterV2RuntimePolicy; readonly modelSelection: ModelSelection; + readonly visualInstructions?: string | null; readonly hasT3Mcp?: boolean; readonly browserToolsAvailable?: boolean; readonly deviceToolsAvailable?: boolean; @@ -835,6 +837,7 @@ export const buildCodexTurnStartParams = Effect.fn("CodexAdapterV2.buildCodexTur browser: input.browserToolsAvailable ?? true, device: input.deviceToolsAvailable ?? false, }, + input.visualInstructions, ) : undefined; const additionalContext = @@ -1852,6 +1855,7 @@ export interface CodexAdapterV2Options { export const makeCodexAdapterV2 = Effect.fn("makeCodexAdapterV2")(function* ( adapterOptions: CodexAdapterV2Options, ) { + const serverSettings = yield* Effect.serviceOption(ServerSettings.ServerSettingsService); const mcpSessions = yield* McpProviderSessions.McpProviderSessions; const readMcpSession = (threadId: ThreadId | null) => threadId === null ? Effect.undefined : mcpSessions.read(threadId); @@ -7410,6 +7414,9 @@ export const makeCodexAdapterV2 = Effect.fn("makeCodexAdapterV2")(function* ( cyberAccess: codexCyberAccess(models, turnInput.modelSelection.model), nativeThreadId: threadId, codexInput, + visualInstructions: Option.isSome(serverSettings) + ? (yield* serverSettings.value.getSettings.pipe(Effect.orDie)).visualInstructions + : null, runtimePolicy: turnInput.runtimePolicy, modelSelection: turnInput.modelSelection, hasT3Mcp: mcpSession !== undefined, diff --git a/apps/server/src/provider/CodexDeveloperInstructions.test.ts b/apps/server/src/provider/CodexDeveloperInstructions.test.ts index 445174281dd41..aba17797c96a2 100644 --- a/apps/server/src/provider/CodexDeveloperInstructions.test.ts +++ b/apps/server/src/provider/CodexDeveloperInstructions.test.ts @@ -15,7 +15,7 @@ describe("buildCodexAdditionalContext", () => { it.each([undefined, { browser: true, device: true }])( "keeps every entry within Codex's per-entry cap with tools %j", (availability) => { - const context = buildCodexAdditionalContext(runtime, availability); + const context = buildCodexAdditionalContext(runtime, availability, "界".repeat(1_000)); for (const [key, entry] of Object.entries(context)) { // Codex counts ceil(UTF-8 bytes / 4) tokens, excluding keys and wrappers. diff --git a/apps/server/src/provider/CodexDeveloperInstructions.ts b/apps/server/src/provider/CodexDeveloperInstructions.ts index cbfd514eb11a6..3aac9a670639d 100644 --- a/apps/server/src/provider/CodexDeveloperInstructions.ts +++ b/apps/server/src/provider/CodexDeveloperInstructions.ts @@ -4,7 +4,7 @@ import { buildRuntimeInstructions } from "@t3tools/provider-core/server/runtimeI import { T3_CODE_BROWSER_TOOL_INSTRUCTIONS, T3_CODE_DEVICE_TOOL_INSTRUCTIONS, - T3_CODE_ORCHESTRATION_SECTIONS, + t3OrchestrationSections, } from "@t3tools/provider-core/server/orchestrationInstructions"; /** Codex silently truncates additionalContext values over 1,000 tokens, counted as UTF-8 bytes / 4. */ @@ -41,12 +41,13 @@ export interface CodexRuntimeInfo { export function buildCodexAdditionalContext( runtime: CodexRuntimeInfo, toolsAvailable: boolean | T3CodeToolAvailability = true, + visualInstructions?: string | null, ): Record { const tools = toolInstructions(toolsAvailable); // Split values to fit per-entry caps; number keys because Codex emits them in key order. return { ...Object.fromEntries( - T3_CODE_ORCHESTRATION_SECTIONS.map((section, index) => [ + t3OrchestrationSections(visualInstructions).map((section, index) => [ `t3_code_orchestration_${String(index + 1).padStart(2, "0")}`, { kind: "application" as const, value: section }, ]), diff --git a/apps/server/src/serverSettings.test.ts b/apps/server/src/serverSettings.test.ts index 873649cb168f5..9af4a32dfaf00 100644 --- a/apps/server/src/serverSettings.test.ts +++ b/apps/server/src/serverSettings.test.ts @@ -3099,3 +3099,24 @@ it.layer(Layer.mergeAll(NodeServices.layer, NodeCrypto.layer))( ); }, ); + +it.layer(Layer.mergeAll(NodeServices.layer, NodeCrypto.layer))("visual delivery settings", (it) => { + it.effect( + "persists visual delivery replacements, empty guidance, and restoration of defaults", + () => + Effect.gen(function* () { + const config = yield* ServerConfig.ServerConfig; + const fs = yield* FileSystem.FileSystem; + const service = yield* ServerSettingsModule.ServerSettingsService; + assert.isNull((yield* service.getSettings).visualInstructions); + for (const visualInstructions of ["Use html_render only for inline delivery.", "", null]) { + yield* service.updateSettings({ visualInstructions }); + const saved = yield* decodeServerSettingsJson( + yield* fs.readFileString(config.settingsPath), + ); + assert.equal(saved.visualInstructions, visualInstructions); + assert.equal((yield* service.getSettings).visualInstructions, visualInstructions); + } + }).pipe(Effect.provide(layerServerSettings())), + ); +}); diff --git a/docs/user/html-renders.md b/docs/user/html-renders.md index 3a1c3de9474d1..61ce321f98ad4 100644 --- a/docs/user/html-renders.md +++ b/docs/user/html-renders.md @@ -10,6 +10,24 @@ Before publishing, agents check their work with screenshots from a small headles Previews can load public resources such as CDN scripts, but nothing on your local network. The machine running the environment looks up each name, and previews block names that resolve to private or reserved addresses. Clash or Mihomo in fake-IP DNS mode can return these addresses, so external resources can fail there. The preview's console messages can identify affected hostnames. Inline the resource, add its host to `fake-ip-filter`, or switch that machine's proxy DNS to `redir-host`. +## Customize visual delivery + +To use your own publishing workflow, set `visualInstructions` in the environment's +`settings.json` under its userdata directory. This setting survives app updates and +replaces T3's visual-delivery guidance for every provider receiving it. Start a new +thread after changing it; existing threads may retain earlier instructions. + +```json +{ + "visualInstructions": "Use html_render only to display HTML inside the chat. For standalone reports, follow my publishing skill and return its link." +} +``` + +The limit is 1,000 characters. An empty string omits the visual-delivery guidance; +`null` or removing the setting restores the shipped default. Browser-use guidance +and tool permissions remain in effect. For a remote environment, change the file +on the machine running that environment. + ## MCP apps Some MCP servers return an interactive app with their tool results, following the [MCP Apps](https://github.com/modelcontextprotocol/ext-apps) standard. When an agent calls one of those tools, the app appears in the thread below the tool call, on web, desktop, and mobile. The tool call keeps its input and result, so you can still read them when an app shows nothing. Codex and Claude support this today, for any MCP server you have configured for them. Claude needs Claude Code 2.1.301 or newer; older versions and other providers show these calls as ordinary tool calls. diff --git a/packages/contracts/src/settings.test.ts b/packages/contracts/src/settings.test.ts index 1db913e38ba3b..570daa1566bf7 100644 --- a/packages/contracts/src/settings.test.ts +++ b/packages/contracts/src/settings.test.ts @@ -544,3 +544,18 @@ describe("server model preferences", () => { expect(decodeServerSettingsPatch(input)).toEqual(input); }); }); + +describe("visual delivery settings", () => { + it("distinguishes default, omitted, and custom guidance and bounds Codex context size", () => { + expect(decodeServerSettings({}).visualInstructions).toBeNull(); + for (const visualInstructions of [ + null, + "", + "Use the requested publishing destination.", + "界".repeat(1_000), + ]) { + expect(decodeServerSettingsPatch({ visualInstructions })).toEqual({ visualInstructions }); + } + expect(() => decodeServerSettingsPatch({ visualInstructions: "x".repeat(1_001) })).toThrow(); + }); +}); diff --git a/packages/contracts/src/settings.ts b/packages/contracts/src/settings.ts index 7bbb03595d4bb..d90ffcc12fd89 100644 --- a/packages/contracts/src/settings.ts +++ b/packages/contracts/src/settings.ts @@ -1536,6 +1536,10 @@ export const ServerSettings = Schema.Struct({ }), ), ), + // Leaves room for browser guidance inside Codex's 4,000-byte context entry. + visualInstructions: Schema.NullOr(Schema.String.check(Schema.isMaxLength(1_000))).pipe( + Schema.withDecodingDefault(Effect.succeed(null)), + ), threadTitleInstructions: TrimmedString.pipe(Schema.withDecodingDefault(Effect.succeed(""))), branchNamingMode: BranchNamingMode.pipe( Schema.withDecodingDefault(Effect.succeed("static" as const)), @@ -1929,6 +1933,9 @@ export const ServerSettingsPatch = Schema.Struct({ addProjectBaseDirectory: Schema.optionalKey(TrimmedString), ghqCloneLayout: Schema.optionalKey(Schema.Boolean), textGenerationModelSelection: Schema.optionalKey(ModelSelectionPatch), + visualInstructions: Schema.optionalKey( + Schema.NullOr(Schema.String.check(Schema.isMaxLength(1_000))), + ), threadTitleInstructions: Schema.optionalKey(TrimmedString), branchNamingMode: Schema.optionalKey(BranchNamingMode), branchNamePrefix: Schema.optionalKey(TrimmedString), diff --git a/packages/provider-acp/src/server/adapter.ts b/packages/provider-acp/src/server/adapter.ts index 0875b039d79eb..82aff56cfcafc 100644 --- a/packages/provider-acp/src/server/adapter.ts +++ b/packages/provider-acp/src/server/adapter.ts @@ -8306,11 +8306,14 @@ export const makeAcpAdapterV2 = Effect.fn("makeAcpAdapterV2")(function* ( ); attachmentBlocks.push(...blocks); } + const visualInstructions = (yield* host.settings.get.pipe(Effect.orDie)) + .visualInstructions; // Read delivery state after the awaits above, so a compaction that lands // while the prompt is prepared still resends the notes in this prompt. const previousInstructionState = (yield* Ref.get(promptInstructionStates)).get(sessionId); const compactionMarker = (yield* Ref.get(compactionMarkers)).get(sessionId); const text = t3AcpPromptWithInstructions({ + visualInstructions, prompt: messageText, state: instructionState, ...(previousInstructionState === undefined || compactionMarker !== undefined diff --git a/packages/provider-core/src/server/orchestrationInstructions.test.ts b/packages/provider-core/src/server/orchestrationInstructions.test.ts index c8dd21cc02634..2102c8760c216 100644 --- a/packages/provider-core/src/server/orchestrationInstructions.test.ts +++ b/packages/provider-core/src/server/orchestrationInstructions.test.ts @@ -4,6 +4,8 @@ import { T3_CODE_DEVICE_TOOL_INSTRUCTIONS, T3_CODE_DEVICE_TOOL_INSTRUCTIONS_WITH_TOOL_SEARCH, T3_CODE_ORCHESTRATION_INSTRUCTIONS, + t3OrchestrationInstructions, + t3OrchestrationSections, t3AcpPromptWithInstructions, t3OrchestrationPrompt, t3OrchestrationSystemPrompt, @@ -83,3 +85,41 @@ describe("T3 device instructions", () => { assert.notInclude(t3AcpPromptWithInstructions({ prompt: "Hi.", state }), "## T3 Code devices"); }); }); + +describe("visual delivery overrides", () => { + it("restores defaults and replaces or omits only the visual guidance", () => { + assert.equal(t3OrchestrationInstructions(), T3_CODE_ORCHESTRATION_INSTRUCTIONS); + assert.equal(t3OrchestrationInstructions(null), T3_CODE_ORCHESTRATION_INSTRUCTIONS); + const state = { interactionMode: "default", hasT3Mcp: true, hasDeviceTools: true } as const; + for (const visualInstructions of [ + "Publish standalone reports with the user's publishing skill.", + "", + ]) { + const instructions = t3OrchestrationInstructions(visualInstructions); + assert.include(instructions, visualInstructions); + assert.notInclude(instructions, "Answer data with a trend"); + assert.include(instructions, "Never use `preview_*` unasked"); + assert.include(instructions, "orchestrator_capabilities"); + assert.equal( + t3OrchestrationSections(visualInstructions).slice(0, -1).join("\n"), + t3OrchestrationSections().slice(0, -1).join("\n"), + ); + assert.include(t3OrchestrationSystemPrompt(true, true, visualInstructions), instructions); + assert.include( + t3AcpPromptWithInstructions({ prompt: "Report.", state, visualInstructions }), + instructions.trim(), + ); + assert.include( + t3OrchestrationPrompt({ + prompt: "Report.", + hasT3Mcp: true, + hasDeviceTools: true, + orchestrationDelivered: false, + deviceInstructionsDelivered: false, + visualInstructions, + }), + instructions.trim(), + ); + } + }); +}); diff --git a/packages/provider-core/src/server/orchestrationInstructions.ts b/packages/provider-core/src/server/orchestrationInstructions.ts index 4ce08d71119fe..670f84e9b04b1 100644 --- a/packages/provider-core/src/server/orchestrationInstructions.ts +++ b/packages/provider-core/src/server/orchestrationInstructions.ts @@ -1,7 +1,11 @@ import type { ProviderInteractionMode } from "@t3tools/contracts"; +const DEFAULT_VISUAL_INSTRUCTIONS = `- Answer data with a trend or comparison with a chart and show any visual the user asks for here: pass an HTML file path or inline HTML to \`html_preview\`, then \`html_render\`. A screenshot on disk or a text description doesn't show it. Never start a server for it. Page tools write only on user request. Never use them to show results. Asked for an image to post, send or use elsewhere: a \`.png\` file and its path, never \`html_render\`.`; + +const T3_CODE_PREVIEW_INSTRUCTIONS = `- Never use \`preview_*\` unasked to verify or show your own edit. Use them when the current request asks for browser work, including recording edits, or names a page or tab. Don't repeat preview calls from an earlier turn. Public pages: web fetch or search unless browser work was asked; then preview tools only, no web fetch. Close a tab you opened before you reply, unless the user asked for it or uses it.`; + // Codex truncates entries over 4,000 bytes; keep each section self-contained and below that limit. -export const T3_CODE_ORCHESTRATION_SECTIONS: ReadonlyArray = [ +const T3_CODE_ORCHESTRATION_SECTIONS: ReadonlyArray = [ `## T3 Code orchestration Ordinary coding tasks need no T3 tools. @@ -20,8 +24,8 @@ Ordinary coding tasks need no T3 tools. - T3 tools may load late. Try the name once before you call it absent.`, `### Visuals and preview -- Answer data with a trend or comparison with a chart and show any visual the user asks for here: pass an HTML file path or inline HTML to \`html_preview\`, then \`html_render\`. A screenshot on disk or a text description doesn't show it. Never start a server for it. Page tools write only on user request. Never use them to show results. Asked for an image to post, send or use elsewhere: a \`.png\` file and its path, never \`html_render\`. -- Never use \`preview_*\` unasked to verify or show your own edit. Use them when the current request asks for browser work, including recording edits, or names a page or tab. Don't repeat preview calls from an earlier turn. Public pages: web fetch or search unless browser work was asked; then preview tools only, no web fetch. Close a tab you opened before you reply, unless the user asked for it or uses it.`, +${DEFAULT_VISUAL_INSTRUCTIONS} +${T3_CODE_PREVIEW_INSTRUCTIONS}`, ]; export const T3_CODE_ORCHESTRATION_INSTRUCTIONS = ` @@ -29,6 +33,20 @@ export const T3_CODE_ORCHESTRATION_INSTRUCTIONS = ` ${T3_CODE_ORCHESTRATION_SECTIONS.join("\n\n")} `; +/** Replace only visual delivery guidance; browser restrictions and orchestration stay in place. */ +export function t3OrchestrationSections(visualInstructions?: string | null): ReadonlyArray { + return visualInstructions == null + ? T3_CODE_ORCHESTRATION_SECTIONS + : [ + ...T3_CODE_ORCHESTRATION_SECTIONS.slice(0, -1), + `### Visuals and preview\n\n${visualInstructions}\n${T3_CODE_PREVIEW_INSTRUCTIONS}`, + ]; +} + +export function t3OrchestrationInstructions(visualInstructions?: string | null): string { + return `\n\n${t3OrchestrationSections(visualInstructions).join("\n\n")}\n`; +} + export const T3_CODE_BROWSER_TOOL_INSTRUCTIONS = ` ## T3 Code browser @@ -76,6 +94,7 @@ export interface T3AcpInstructionState { /** ACP lacks system/developer fields; inject context on first prompt and tool/mode changes. */ export function t3AcpPromptWithInstructions(input: { readonly prompt: string; + readonly visualInstructions?: string | null; readonly state: T3AcpInstructionState; readonly previousState?: T3AcpInstructionState; }): string { @@ -96,7 +115,7 @@ export function t3AcpPromptWithInstructions(input: { ? [ T3_CODE_BROWSER_TOOL_INSTRUCTIONS.trim(), ...(input.state.hasDeviceTools ? [T3_CODE_DEVICE_TOOL_INSTRUCTIONS] : []), - T3_CODE_ORCHESTRATION_INSTRUCTIONS.trim(), + t3OrchestrationInstructions(input.visualInstructions).trim(), T3_CODE_ACP_MCP_FALLBACK_INSTRUCTIONS, ] : []), @@ -104,10 +123,10 @@ export function t3AcpPromptWithInstructions(input: { return `\n${instructions.join("\n\n")}\n\n\n\n${input.prompt}\n`; } -const orchestrationInstructions = (hasDeviceTools: boolean) => +const orchestrationInstructions = (hasDeviceTools: boolean, visualInstructions?: string | null) => hasDeviceTools - ? `${T3_CODE_ORCHESTRATION_INSTRUCTIONS}\n${T3_CODE_DEVICE_TOOL_INSTRUCTIONS}\n` - : T3_CODE_ORCHESTRATION_INSTRUCTIONS; + ? `${t3OrchestrationInstructions(visualInstructions)}\n${T3_CODE_DEVICE_TOOL_INSTRUCTIONS}\n` + : t3OrchestrationInstructions(visualInstructions); function prependT3OrchestrationInstructions(prompt: string, instructions: string): string { return `${instructions.trim()}\n\n\n${prompt}\n`; @@ -116,6 +135,7 @@ function prependT3OrchestrationInstructions(prompt: string, instructions: string /** For providers whose instructions ride on the prompt, so a compacted conversation loses them. */ export function t3OrchestrationPrompt(input: { readonly prompt: string; + readonly visualInstructions?: string | null; readonly hasT3Mcp: boolean; readonly hasDeviceTools: boolean; readonly orchestrationDelivered: boolean; @@ -125,7 +145,7 @@ export function t3OrchestrationPrompt(input: { if (!input.orchestrationDelivered) { return prependT3OrchestrationInstructions( input.prompt, - orchestrationInstructions(input.hasDeviceTools), + orchestrationInstructions(input.hasDeviceTools, input.visualInstructions), ); } return input.hasDeviceTools && !input.deviceInstructionsDelivered @@ -136,6 +156,7 @@ export function t3OrchestrationPrompt(input: { export function t3OrchestrationSystemPrompt( hasT3Mcp: boolean, hasDeviceTools: boolean, + visualInstructions?: string | null, ): string | undefined { - return hasT3Mcp ? orchestrationInstructions(hasDeviceTools) : undefined; + return hasT3Mcp ? orchestrationInstructions(hasDeviceTools, visualInstructions) : undefined; } diff --git a/packages/provider-cursor/src/server/adapter.ts b/packages/provider-cursor/src/server/adapter.ts index 496a2bd5460e8..afbbb2bea4cfa 100644 --- a/packages/provider-cursor/src/server/adapter.ts +++ b/packages/provider-cursor/src/server/adapter.ts @@ -2452,6 +2452,7 @@ export const makeCursorAdapterV2 = Effect.fn("makeCursorAdapterV2")(function* ( return { message: "/compress", prompt: undefined }; } const newText = t3OrchestrationPrompt({ + visualInstructions: (yield* host.settings.get.pipe(Effect.orDie)).visualInstructions, prompt: yield* providerMessageTextWithAttachmentPaths({ text: yield* resolveCursorSkillText( rawText, diff --git a/packages/provider-opencode/src/server/adapter.test.ts b/packages/provider-opencode/src/server/adapter.test.ts index c28e6ff52b34b..1f59533e9c898 100644 --- a/packages/provider-opencode/src/server/adapter.test.ts +++ b/packages/provider-opencode/src/server/adapter.test.ts @@ -8,6 +8,7 @@ import * as NodeServices from "@effect/platform-node/NodeServices"; import type { OpencodeClient, ToolPart } from "@opencode-ai/sdk/v2"; import { toolOutputImages } from "@t3tools/shared/toolOutput"; import { + DEFAULT_SERVER_SETTINGS, CheckpointId, NodeId, ProjectId, @@ -190,6 +191,7 @@ const makeOpenCodeRuntimeHarness = Effect.fn("makeOpenCodeRuntimeHarness")(funct } as unknown as OpenCodeRuntime.OpenCodeRuntime["Service"]), Effect.provideService(ProviderHost.ProviderHost, { paths: { cwd: "/workspace" }, + settings: { get: Effect.succeed(DEFAULT_SERVER_SETTINGS) }, resolveAttachmentPath: () => null, ...host, } as unknown as ProviderHost.ProviderHost["Service"]), @@ -3734,6 +3736,7 @@ describe("OpenCodeAdapterV2", () => { } as unknown as OpenCodeRuntime.OpenCodeRuntime["Service"]), Effect.provideService(ProviderHost.ProviderHost, { paths: { cwd: "/workspace" }, + settings: { get: Effect.succeed(DEFAULT_SERVER_SETTINGS) }, resolveAttachmentPath: () => null, } as unknown as ProviderHost.ProviderHost["Service"]), ); @@ -4378,6 +4381,7 @@ describe("OpenCodeAdapterV2", () => { } as unknown as OpenCodeRuntime.OpenCodeRuntime["Service"]), Effect.provideService(ProviderHost.ProviderHost, { paths: { cwd: "/workspace" }, + settings: { get: Effect.succeed(DEFAULT_SERVER_SETTINGS) }, resolveAttachmentPath: () => null, } as unknown as ProviderHost.ProviderHost["Service"]), ); diff --git a/packages/provider-opencode/src/server/adapter.ts b/packages/provider-opencode/src/server/adapter.ts index 2f645c58ae7c8..6c94054751635 100644 --- a/packages/provider-opencode/src/server/adapter.ts +++ b/packages/provider-opencode/src/server/adapter.ts @@ -1063,6 +1063,7 @@ export const makeOpenCodeAdapterV2 = Effect.fn("makeOpenCodeAdapterV2")(function const orchestrationSystemPrompt = t3OrchestrationSystemPrompt( hasT3Mcp, mcpSession?.capabilities?.has("device") === true, + (yield* host.settings.get.pipe(Effect.orDie)).visualInstructions, ); if (hasT3Mcp) { yield* OpenCodeRuntime.runOpenCodeSdk("mcp.add", () => diff --git a/packages/provider-opencode/src/server/v2/adapter.ts b/packages/provider-opencode/src/server/v2/adapter.ts index 6604f84eb289e..2176dc5222d02 100644 --- a/packages/provider-opencode/src/server/v2/adapter.ts +++ b/packages/provider-opencode/src/server/v2/adapter.ts @@ -4236,7 +4236,11 @@ export const make = Effect.fn("OpenCode2Adapter.make")(function* (instanceId: Pr } const instructions = [ buildRuntimeInstructions({ harness: "OpenCode", model: turnInput.modelSelection.model }), - t3OrchestrationSystemPrompt(mcpAvailable, mcpSession?.capabilities?.has("device") === true), + t3OrchestrationSystemPrompt( + mcpAvailable, + mcpSession?.capabilities?.has("device") === true, + (yield* host.settings.get.pipe(Effect.orDie)).visualInstructions, + ), mcpAvailable ? "To wait for a background shell you started (tests, a build), call `t3_background_wait` with its shell ID before you end your turn. Do not mark work you leave running, or PRs." : undefined, diff --git a/packages/provider-pi/src/server/adapter.ts b/packages/provider-pi/src/server/adapter.ts index b41e31c778199..8838133f6a086 100644 --- a/packages/provider-pi/src/server/adapter.ts +++ b/packages/provider-pi/src/server/adapter.ts @@ -25,6 +25,8 @@ import { type MessageId, type OrchestrationV2ProviderTurnTokenUsage, } from "@t3tools/contracts"; +import { t3OrchestrationInstructions } from "@t3tools/provider-core/server/orchestrationInstructions"; +import { T3_PI_ORCHESTRATION_INSTRUCTIONS_ENV } from "./mcpExtensionSource.ts"; import { PiSettings } from "../settings.ts"; import * as Cause from "effect/Cause"; import * as DateTime from "effect/DateTime"; @@ -488,7 +490,12 @@ export const makePiAdapterV2 = Effect.fn("makePiAdapterV2")(function* ( } const launch = buildPiRpcLaunch({ launchArgs: resolvedLaunchArgs.args, - environment: options.environment, + environment: { + ...options.environment, + [T3_PI_ORCHESTRATION_INSTRUCTIONS_ENV]: t3OrchestrationInstructions( + (yield* host.settings.get.pipe(Effect.orDie)).visualInstructions, + ).trim(), + }, mcpSession, extensionPath, runtimeMode: input.runtimePolicy.runtimeMode, diff --git a/packages/provider-pi/src/server/mcpBridge.testkit.ts b/packages/provider-pi/src/server/mcpBridge.testkit.ts index 98ef74bb862cc..7f543b9e7f236 100644 --- a/packages/provider-pi/src/server/mcpBridge.testkit.ts +++ b/packages/provider-pi/src/server/mcpBridge.testkit.ts @@ -48,6 +48,7 @@ export async function loadMcpBridge( readonly toolSearchDisabled?: boolean; readonly allowsTool?: (name: string) => boolean; readonly runtimeMode?: string; + readonly orchestrationInstructions?: string; readonly inputSchema?: Record; } = {}, ) { @@ -89,6 +90,7 @@ export async function loadMcpBridge( await NodeVM.runInNewContext(`${source}\nt3McpExtension(pi)`, { process: { env: { + T3_PI_ORCHESTRATION_INSTRUCTIONS: options.orchestrationInstructions, T3_MCP_URL: "http://fixture.invalid/mcp", T3_MCP_BEARER_TOKEN: "fixture-token", T3_PI_MCP_EXTENSION_PATH: "/fixture/pi-t3-extension.ts", diff --git a/packages/provider-pi/src/server/mcpExtensionSource.test.ts b/packages/provider-pi/src/server/mcpExtensionSource.test.ts index c4119157a0175..69ca5234117e7 100644 --- a/packages/provider-pi/src/server/mcpExtensionSource.test.ts +++ b/packages/provider-pi/src/server/mcpExtensionSource.test.ts @@ -53,6 +53,22 @@ async function loadHooks( } describe("Pi orchestration prompt section", () => { + it("isolates visual overrides between Pi processes sharing an extension file", async () => { + const first = await loadMcpBridge({ + orchestrationInstructions: "Publish with the report skill.", + }); + const second = await loadMcpBridge({ orchestrationInstructions: "Render inside the chat." }); + const event = { systemPrompt: "base" }; + const ctx = { ui: { notify: assert.fail } }; + assert.equal( + (await first.handlers.get("before_agent_start")!(event, ctx))?.systemPrompt, + "base\n\nPublish with the report skill.", + ); + assert.equal( + (await second.handlers.get("before_agent_start")!(event, ctx))?.systemPrompt, + "base\n\nRender inside the chat.", + ); + }); it.each([ { name: "on Pi builds without prompt sections", diff --git a/packages/provider-pi/src/server/mcpExtensionSource.ts b/packages/provider-pi/src/server/mcpExtensionSource.ts index 48aeff24370de..8d1285b7e2939 100644 --- a/packages/provider-pi/src/server/mcpExtensionSource.ts +++ b/packages/provider-pi/src/server/mcpExtensionSource.ts @@ -3,6 +3,8 @@ import { T3_CODE_ORCHESTRATION_INSTRUCTIONS } from "@t3tools/provider-core/serve export const PI_T3_MCP_EXTENSION_FILENAME = "pi-t3-mcp-extension.ts"; +export const T3_PI_ORCHESTRATION_INSTRUCTIONS_ENV = "T3_PI_ORCHESTRATION_INSTRUCTIONS"; + export const T3_MCP_URL_ENV = "T3_MCP_URL"; export const T3_MCP_BEARER_ENV = "T3_MCP_BEARER_TOKEN"; export const T3_PI_RUNTIME_MODE_ENV = "T3_PI_RUNTIME_MODE"; @@ -23,7 +25,7 @@ const URL_ENV = ${JSON.stringify(T3_MCP_URL_ENV)}; const TOKEN_ENV = ${JSON.stringify(T3_MCP_BEARER_ENV)}; const RUNTIME_MODE_ENV = ${JSON.stringify(T3_PI_RUNTIME_MODE_ENV)}; const EXTENSION_PATH_ENV = ${JSON.stringify(T3_PI_MCP_EXTENSION_PATH_ENV)}; -const ORCHESTRATION_INSTRUCTIONS = ${JSON.stringify(T3_CODE_ORCHESTRATION_INSTRUCTIONS.trim())}; +const ORCHESTRATION_INSTRUCTIONS = process.env[${JSON.stringify(T3_PI_ORCHESTRATION_INSTRUCTIONS_ENV)}] ?? ${JSON.stringify(T3_CODE_ORCHESTRATION_INSTRUCTIONS.trim())}; const SERVICE_TIER_COMMAND = ${JSON.stringify(PI_T3_SERVICE_TIER_COMMAND)}; const PROTOCOL = "2025-06-18"; const READ_ONLY_TOOLS = new Set(["read", "grep", "find", "ls"]); From 1c3d3fb5568e4d029059491e88bb4aee9481286e Mon Sep 17 00:00:00 2001 From: Noah Schenk Date: Thu, 12 Nov 2026 11:35:33 +0100 Subject: [PATCH 2/5] fix(settings): reject malformed Unicode in visual instructions --- packages/contracts/src/settings.test.ts | 7 ++++++- packages/contracts/src/settings.ts | 20 ++++++++++++++------ 2 files changed, 20 insertions(+), 7 deletions(-) diff --git a/packages/contracts/src/settings.test.ts b/packages/contracts/src/settings.test.ts index 570daa1566bf7..e4d238dabc89a 100644 --- a/packages/contracts/src/settings.test.ts +++ b/packages/contracts/src/settings.test.ts @@ -551,11 +551,16 @@ describe("visual delivery settings", () => { for (const visualInstructions of [ null, "", - "Use the requested publishing destination.", + "Use the requested publishing destination. 🦊", "界".repeat(1_000), ]) { expect(decodeServerSettingsPatch({ visualInstructions })).toEqual({ visualInstructions }); } expect(() => decodeServerSettingsPatch({ visualInstructions: "x".repeat(1_001) })).toThrow(); + for (const decode of [decodeServerSettings, decodeServerSettingsPatch]) { + for (const visualInstructions of ["\ud800", "\udfff", "prefix\ud800suffix"]) { + expect(() => decode({ visualInstructions })).toThrow(); + } + } }); }); diff --git a/packages/contracts/src/settings.ts b/packages/contracts/src/settings.ts index d90ffcc12fd89..f7809681d6ed5 100644 --- a/packages/contracts/src/settings.ts +++ b/packages/contracts/src/settings.ts @@ -54,6 +54,7 @@ import { ProviderDriverKind, } from "./providerInstance.ts"; import { PullRequestMergeMethod } from "./pullRequest.ts"; +import { hasOnlyPairedSurrogates } from "./threadMetadataMcp.ts"; import { CloudSpeechModelId, SpeechAcceleration, @@ -1356,6 +1357,17 @@ export const CloudSpeechCredentials = Schema.Struct({ openrouter: CloudSpeechCredential, }); +const VisualInstructions = Schema.NullOr( + Schema.String.check( + Schema.isMaxLength(1_000), + Schema.makeFilter((value) => + hasOnlyPairedSurrogates(value) + ? true + : "Visual instructions must contain well-formed Unicode.", + ), + ), +); + export const ServerSettings = Schema.Struct({ // Null means unmigrated; empty is authoritative and must not resurrect cleared preferences. favorites: Schema.NullOr(ModelFavorites).pipe(Schema.withDecodingDefault(Effect.succeed(null))), @@ -1537,9 +1549,7 @@ export const ServerSettings = Schema.Struct({ ), ), // Leaves room for browser guidance inside Codex's 4,000-byte context entry. - visualInstructions: Schema.NullOr(Schema.String.check(Schema.isMaxLength(1_000))).pipe( - Schema.withDecodingDefault(Effect.succeed(null)), - ), + visualInstructions: VisualInstructions.pipe(Schema.withDecodingDefault(Effect.succeed(null))), threadTitleInstructions: TrimmedString.pipe(Schema.withDecodingDefault(Effect.succeed(""))), branchNamingMode: BranchNamingMode.pipe( Schema.withDecodingDefault(Effect.succeed("static" as const)), @@ -1933,9 +1943,7 @@ export const ServerSettingsPatch = Schema.Struct({ addProjectBaseDirectory: Schema.optionalKey(TrimmedString), ghqCloneLayout: Schema.optionalKey(Schema.Boolean), textGenerationModelSelection: Schema.optionalKey(ModelSelectionPatch), - visualInstructions: Schema.optionalKey( - Schema.NullOr(Schema.String.check(Schema.isMaxLength(1_000))), - ), + visualInstructions: Schema.optionalKey(VisualInstructions), threadTitleInstructions: Schema.optionalKey(TrimmedString), branchNamingMode: Schema.optionalKey(BranchNamingMode), branchNamePrefix: Schema.optionalKey(TrimmedString), From 0836aa7558911f60efe369c0fdb7a90efd454532 Mon Sep 17 00:00:00 2001 From: Noah Schenk Date: Sun, 15 Nov 2026 00:01:37 +0100 Subject: [PATCH 3/5] fix(providers): handle Cursor recovery and invalid visual guidance --- packages/contracts/src/settings.test.ts | 7 ++++- packages/contracts/src/settings.ts | 4 +-- .../src/server/adapter.test.ts | 27 +++++++++++++++---- .../provider-cursor/src/server/adapter.ts | 5 ++++ 4 files changed, 35 insertions(+), 8 deletions(-) diff --git a/packages/contracts/src/settings.test.ts b/packages/contracts/src/settings.test.ts index e4d238dabc89a..80b397df5ce7a 100644 --- a/packages/contracts/src/settings.test.ts +++ b/packages/contracts/src/settings.test.ts @@ -558,7 +558,12 @@ describe("visual delivery settings", () => { } expect(() => decodeServerSettingsPatch({ visualInstructions: "x".repeat(1_001) })).toThrow(); for (const decode of [decodeServerSettings, decodeServerSettingsPatch]) { - for (const visualInstructions of ["\ud800", "\udfff", "prefix\ud800suffix"]) { + for (const visualInstructions of [ + "\ud800", + "\udfff", + "prefix\ud800suffix", + "prefix\0suffix", + ]) { expect(() => decode({ visualInstructions })).toThrow(); } } diff --git a/packages/contracts/src/settings.ts b/packages/contracts/src/settings.ts index f7809681d6ed5..fa99c03fde9f9 100644 --- a/packages/contracts/src/settings.ts +++ b/packages/contracts/src/settings.ts @@ -1361,9 +1361,9 @@ const VisualInstructions = Schema.NullOr( Schema.String.check( Schema.isMaxLength(1_000), Schema.makeFilter((value) => - hasOnlyPairedSurrogates(value) + hasOnlyPairedSurrogates(value) && !value.includes("\0") ? true - : "Visual instructions must contain well-formed Unicode.", + : "Visual instructions must contain well-formed Unicode without NUL characters.", ), ), ); diff --git a/packages/provider-cursor/src/server/adapter.test.ts b/packages/provider-cursor/src/server/adapter.test.ts index 38c4119ad94ac..9f41579c49a23 100644 --- a/packages/provider-cursor/src/server/adapter.test.ts +++ b/packages/provider-cursor/src/server/adapter.test.ts @@ -6,6 +6,7 @@ import { assert, describe, it } from "@effect/vitest"; import type { InteractionUpdate } from "@cursor/sdk"; import { toolOutputImages } from "@t3tools/shared/toolOutput"; import { + DEFAULT_SERVER_SETTINGS, EnvironmentId, MessageId, NodeId, @@ -754,6 +755,7 @@ describe("CursorAdapterV2", () => { const fileSystem = yield* FileSystem.FileSystem; const workspace = yield* fileSystem.makeTempDirectoryScoped({ prefix: "cursor-v2-device-" }); const sentMessages: Array = []; + const visualInstructions = "Use my publishing skill for standalone reports."; const instanceId = ProviderInstanceId.make("cursor"); const threadId = ThreadId.make("cursor-device-thread"); const mcpSessions = yield* McpProviderSessions.McpProviderSessions; @@ -806,14 +808,20 @@ describe("CursorAdapterV2", () => { }), }), }), - Effect.provide(TestProviderHost.layer({ cwd: workspace })), + Effect.provide( + TestProviderHost.layer({ + cwd: workspace, + settings: { ...DEFAULT_SERVER_SETTINGS, visualInstructions }, + }), + ), ); - const runtime = yield* adapter.openSession({ + const sessionInput = { threadId, providerSessionId: ProviderSessionId.make("cursor-device-session"), modelSelection, runtimePolicy, - }); + }; + let runtime = yield* adapter.openSession(sessionInput); const providerThread = yield* runtime.ensureThread({ threadId, modelSelection, @@ -843,7 +851,7 @@ describe("CursorAdapterV2", () => { lastVisitedAt: null, deletedAt: null, }; - // Starts at run 5: a conversation from before device instructions existed, now resumed. + // Recovery can create a new native agent after earlier app turns. let runOrdinal = 4; const send = Effect.fnUntraced(function* (compact = false) { runOrdinal += 1; @@ -880,8 +888,17 @@ describe("CursorAdapterV2", () => { const told = (orchestration: boolean, devices: boolean) => ({ orchestration, devices }); yield* setDeviceAccess(true); - assert.deepEqual(yield* send(), told(false, true)); + assert.deepEqual(yield* send(), told(true, true)); + assert.include(sentMessages.at(-1)!, visualInstructions); assert.deepEqual(yield* send(), told(false, false)); + runtime = yield* adapter.openSession(sessionInput); + yield* runtime.resumeThread({ providerThread }); + assert.deepEqual( + yield* send(), + told(false, true), + "an existing agent stays told after restart", + ); + assert.notInclude(sentMessages.at(-1)!, visualInstructions); yield* send(true); assert.deepEqual( yield* send(), diff --git a/packages/provider-cursor/src/server/adapter.ts b/packages/provider-cursor/src/server/adapter.ts index afbbb2bea4cfa..35309f2b64276 100644 --- a/packages/provider-cursor/src/server/adapter.ts +++ b/packages/provider-cursor/src/server/adapter.ts @@ -2788,6 +2788,11 @@ export const makeCursorAdapterV2 = Effect.fn("makeCursorAdapterV2")(function* ( modelSelection: threadInput.modelSelection, runtimePolicy: threadInput.runtimePolicy, }); + yield* Ref.set(told, { + agent: opened.nativeThreadId, + orchestration: false, + device: false, + }); const now = yield* DateTime.now; return makeProviderThread({ idAllocator, From e31eae575209452d68ec04c249558726f654a940 Mon Sep 17 00:00:00 2001 From: maria-rcks Date: Sun, 15 Nov 2026 04:24:55 +0000 Subject: [PATCH 4/5] fix(providers): preserve turn-start errors for visual settings --- .../Adapters/ClaudeAdapterV2.test.ts | 55 +++++++++++++------ .../Adapters/ClaudeAdapterV2.ts | 7 ++- .../Adapters/CodexAdapterV2.test.ts | 48 ++++++++++++++++ .../Adapters/CodexAdapterV2.ts | 2 +- docs/user/html-renders.md | 3 +- 5 files changed, 94 insertions(+), 21 deletions(-) diff --git a/apps/server/src/orchestration-v2/Adapters/ClaudeAdapterV2.test.ts b/apps/server/src/orchestration-v2/Adapters/ClaudeAdapterV2.test.ts index 65a6e87715ca6..23c8126a260a0 100644 --- a/apps/server/src/orchestration-v2/Adapters/ClaudeAdapterV2.test.ts +++ b/apps/server/src/orchestration-v2/Adapters/ClaudeAdapterV2.test.ts @@ -35,6 +35,8 @@ import { ChatImageAttachment, CheckpointId, ClaudeSettings, + DEFAULT_SERVER_SETTINGS, + ServerSettingsError, EnvironmentId, MessageId, type ModelSelection, @@ -116,6 +118,7 @@ import * as ProviderAdapter from "@t3tools/provider-core/server/ProviderAdapter" import type * as ProviderContinuationRequests from "@t3tools/provider-core/server/ProviderContinuationRequests"; import { makeProviderFailure } from "@t3tools/provider-core/server/failure"; import * as ClaudeAdapterV2 from "./ClaudeAdapterV2.ts"; +import { ServerSettingsService } from "../../serverSettings.ts"; import * as IdAllocator from "@t3tools/provider-core/server/IdAllocator"; import * as ProviderInstallationGate from "../../provider/ProviderInstallationGate.ts"; import { ClaudeOrchestratorReplayHarness } from "./ClaudeAdapterV2.testkit.ts"; @@ -21045,6 +21048,11 @@ describe("ClaudeAdapterV2 background wake turns", () => { yield* fileSystem.writeFileString(appendFile, "File sentinel\n"); const processQueues: Array> = []; let closes = 0; + let settingsFail = false; + const settingsError = new ServerSettingsError({ + settingsPath: "settings.json", + operation: "read-secret", + }); const firstTurnTerminal = yield* Deferred.make(); const adapter = yield* ClaudeAdapterV2.makeClaudeAdapterV2({ instanceId: ClaudeAdapterV2.CLAUDE_DEFAULT_INSTANCE_ID, @@ -21091,7 +21099,15 @@ describe("ClaudeAdapterV2 background wake turns", () => { subagentModel: () => Effect.succeed(null), assertComplete: Effect.void, }, - }); + }).pipe( + Effect.provide( + Layer.mock(ServerSettingsService)({ + getSettings: Effect.suspend(() => + settingsFail ? Effect.fail(settingsError) : Effect.succeed(DEFAULT_SERVER_SETTINGS), + ), + }), + ), + ); const runtimePolicy = ProviderAdapter.ProviderAdapterV2RuntimePolicy.make({ runtimeMode: "full-access", interactionMode: "default", @@ -21141,27 +21157,34 @@ describe("ClaudeAdapterV2 background wake turns", () => { yield* fileSystem.remove(appendFile); // A thinking change cannot apply live, so this turn must replace the process. - const refused = yield* runtime - .startTurn( - makeClaudeTestTurnInput({ - threadId, - providerThread: { ...providerThread, status: "active" }, - now, - attemptId: RunAttemptId.make("attempt-claude-append-replacement-b"), - text: "Switch model.", - attachments: [], - providerTurnOrdinal: 2, - modelSelection: CLAUDE_TEST_RESTART_MODEL_SELECTION, - runtimePolicy, - }), - ) - .pipe(Effect.flip); + const replacement = runtime.startTurn( + makeClaudeTestTurnInput({ + threadId, + providerThread: { ...providerThread, status: "active" }, + now, + attemptId: RunAttemptId.make("attempt-claude-append-replacement-b"), + text: "Switch model.", + attachments: [], + providerTurnOrdinal: 2, + modelSelection: CLAUDE_TEST_RESTART_MODEL_SELECTION, + runtimePolicy, + }), + ); + const refused = yield* replacement.pipe(Effect.flip); assert.equal( makeProviderFailure({ cause: refused, class: "provider_error" }).message, new ClaudeAdapterV2.ClaudeAppendSystemPromptFileError({ path: appendFile }).message, ); assert.lengthOf(processQueues, 1); assert.equal(closes, 0); + + yield* fileSystem.writeFileString(appendFile, "File sentinel\n"); + settingsFail = true; + const settingsFailure = yield* replacement.pipe(Effect.flip); + assert.instanceOf(settingsFailure, ProviderAdapter.ProviderAdapterTurnStartError); + assert.strictEqual(settingsFailure.cause, settingsError); + assert.lengthOf(processQueues, 1); + assert.equal(closes, 0); }).pipe( Effect.provide( Layer.mergeAll( diff --git a/apps/server/src/orchestration-v2/Adapters/ClaudeAdapterV2.ts b/apps/server/src/orchestration-v2/Adapters/ClaudeAdapterV2.ts index 0399c3a7e229d..7ce127f4b41ce 100644 --- a/apps/server/src/orchestration-v2/Adapters/ClaudeAdapterV2.ts +++ b/apps/server/src/orchestration-v2/Adapters/ClaudeAdapterV2.ts @@ -12614,6 +12614,9 @@ export const makeClaudeAdapterV2 = Effect.fn("makeClaudeAdapterV2")(function* ( ], { concurrency: "unbounded" }, ); + const visualInstructions = Option.isSome(serverSettings) + ? (yield* serverSettings.value.getSettings).visualInstructions + : null; const closedExistingNativeThreadId = existing !== null ? existing.nativeThreadId : null; clearedNativeSessions.delete(nativeThreadId); if (existing !== null) { @@ -12633,9 +12636,7 @@ export const makeClaudeAdapterV2 = Effect.fn("makeClaudeAdapterV2")(function* ( const shouldResume = resumeSessionAt !== undefined || openedWithResume || hasPersistedProviderTurn; const queryOptions = makeClaudeQueryOptions({ - visualInstructions: Option.isSome(serverSettings) - ? (yield* serverSettings.value.getSettings.pipe(Effect.orDie)).visualInstructions - : null, + visualInstructions, modelSelection: turnInput.modelSelection, modelCatalog: catalog, nativeThreadId, diff --git a/apps/server/src/orchestration-v2/Adapters/CodexAdapterV2.test.ts b/apps/server/src/orchestration-v2/Adapters/CodexAdapterV2.test.ts index 55a88734dfc93..048fb67fde654 100644 --- a/apps/server/src/orchestration-v2/Adapters/CodexAdapterV2.test.ts +++ b/apps/server/src/orchestration-v2/Adapters/CodexAdapterV2.test.ts @@ -29,6 +29,7 @@ import { ProviderTurnId, RunAttemptId, RunId, + ServerSettingsError, ThreadId, TurnItemId, type ServerProviderModel, @@ -78,6 +79,7 @@ import * as ModelManifest from "../../provider/ModelManifest.ts"; import * as PortScanner from "../../preview/PortScanner.ts"; import { resolveProviderCompatibility } from "../../provider/providerCompatibility.ts"; import * as CodexAdapterV2 from "./CodexAdapterV2.ts"; +import { ServerSettingsService } from "../../serverSettings.ts"; import { withCodexReplayChildMetadata } from "./CodexAdapterV2.testkit.ts"; import * as CodexAdapterV2Testkit from "./CodexAdapterV2.testkit.ts"; @@ -1684,6 +1686,52 @@ describe("CodexAdapterV2 post-settle continuation", () => { ), ); + it.effect("reports unreadable visual settings as a turn-start failure", () => + Effect.gen(function* () { + const settingsError = new ServerSettingsError({ + settingsPath: "settings.json", + operation: "read-secret", + }); + const harness = yield* makeCodexReplayHarness( + makeCodexReplayTranscript({ + scenario: "visual-settings-error", + entries: codexReplayPreamble({ + nativeThreadId: "visual-settings-thread", + nativeTurnId: "visual-settings-turn", + prompt: "work", + }).slice(0, 5), + }), + ).pipe( + Effect.provide( + Layer.mock(ServerSettingsService)({ getSettings: Effect.fail(settingsError) }), + ), + ); + const failure = yield* harness.runtime + .startTurn( + makeCodexTestTurnInput({ + threadId: harness.threadId, + providerThread: harness.providerThread, + now: yield* DateTime.now, + attemptId: RunAttemptId.make("visual-settings-attempt"), + text: "work", + }), + ) + .pipe(Effect.flip); + assert.instanceOf(failure, ProviderAdapter.ProviderAdapterTurnStartError); + assert.strictEqual(failure.cause, settingsError); + }).pipe( + Effect.scoped, + Effect.provide( + Layer.mergeAll( + IdAllocator.layer, + McpProviderSessions.layer, + NodeServices.layer, + NodeCrypto.layer, + ), + ), + ), + ); + it.effect("keeps native image views available to the clients", () => Effect.gen(function* () { const nativeThreadId = "image-view-thread"; diff --git a/apps/server/src/orchestration-v2/Adapters/CodexAdapterV2.ts b/apps/server/src/orchestration-v2/Adapters/CodexAdapterV2.ts index fdcd986d5b058..fbbe6614fe18d 100644 --- a/apps/server/src/orchestration-v2/Adapters/CodexAdapterV2.ts +++ b/apps/server/src/orchestration-v2/Adapters/CodexAdapterV2.ts @@ -7480,7 +7480,7 @@ export const makeCodexAdapterV2 = Effect.fn("makeCodexAdapterV2")(function* ( nativeThreadId: threadId, codexInput, visualInstructions: Option.isSome(serverSettings) - ? (yield* serverSettings.value.getSettings.pipe(Effect.orDie)).visualInstructions + ? (yield* serverSettings.value.getSettings).visualInstructions : null, runtimePolicy: turnInput.runtimePolicy, modelSelection: turnInput.modelSelection, diff --git a/docs/user/html-renders.md b/docs/user/html-renders.md index 61ce321f98ad4..a1690680e2ca4 100644 --- a/docs/user/html-renders.md +++ b/docs/user/html-renders.md @@ -15,7 +15,8 @@ Previews can load public resources such as CDN scripts, but nothing on your loca To use your own publishing workflow, set `visualInstructions` in the environment's `settings.json` under its userdata directory. This setting survives app updates and replaces T3's visual-delivery guidance for every provider receiving it. Start a new -thread after changing it; existing threads may retain earlier instructions. +thread after changing it. Existing threads and forks may retain the instructions +from their original thread. ```json { From 076f954457f06cb1600c43db0da0b744caf25e0d Mon Sep 17 00:00:00 2001 From: maria-rcks Date: Sun, 15 Nov 2026 04:32:05 +0000 Subject: [PATCH 5/5] fix(providers): keep visual settings errors typed across adapters --- packages/provider-acp/src/server/adapter.ts | 3 +-- packages/provider-cursor/src/server/adapter.ts | 2 +- packages/provider-opencode/src/server/adapter.ts | 2 +- packages/provider-opencode/src/server/v2/adapter.ts | 2 +- packages/provider-pi/src/server/adapter.ts | 2 +- 5 files changed, 5 insertions(+), 6 deletions(-) diff --git a/packages/provider-acp/src/server/adapter.ts b/packages/provider-acp/src/server/adapter.ts index 1e634c75f8786..da282b7850aa2 100644 --- a/packages/provider-acp/src/server/adapter.ts +++ b/packages/provider-acp/src/server/adapter.ts @@ -8400,8 +8400,7 @@ export const makeAcpAdapterV2 = Effect.fn("makeAcpAdapterV2")(function* ( ); attachmentBlocks.push(...blocks); } - const visualInstructions = (yield* host.settings.get.pipe(Effect.orDie)) - .visualInstructions; + const visualInstructions = (yield* host.settings.get).visualInstructions; // Read delivery state after the awaits above, so a compaction that lands // while the prompt is prepared still resends the notes in this prompt. const previousInstructionState = (yield* Ref.get(promptInstructionStates)).get(sessionId); diff --git a/packages/provider-cursor/src/server/adapter.ts b/packages/provider-cursor/src/server/adapter.ts index 34c13c001b696..056b47d76208b 100644 --- a/packages/provider-cursor/src/server/adapter.ts +++ b/packages/provider-cursor/src/server/adapter.ts @@ -2621,7 +2621,7 @@ export const makeCursorAdapterV2 = Effect.fn("makeCursorAdapterV2")(function* ( return { message: "/compress", prompt: undefined }; } const newText = t3OrchestrationPrompt({ - visualInstructions: (yield* host.settings.get.pipe(Effect.orDie)).visualInstructions, + visualInstructions: (yield* host.settings.get).visualInstructions, prompt: yield* providerMessageTextWithAttachmentPaths({ text: yield* resolveCursorSkillText( rawText, diff --git a/packages/provider-opencode/src/server/adapter.ts b/packages/provider-opencode/src/server/adapter.ts index 6c94054751635..d2c11e9e903a4 100644 --- a/packages/provider-opencode/src/server/adapter.ts +++ b/packages/provider-opencode/src/server/adapter.ts @@ -1063,7 +1063,7 @@ export const makeOpenCodeAdapterV2 = Effect.fn("makeOpenCodeAdapterV2")(function const orchestrationSystemPrompt = t3OrchestrationSystemPrompt( hasT3Mcp, mcpSession?.capabilities?.has("device") === true, - (yield* host.settings.get.pipe(Effect.orDie)).visualInstructions, + (yield* host.settings.get).visualInstructions, ); if (hasT3Mcp) { yield* OpenCodeRuntime.runOpenCodeSdk("mcp.add", () => diff --git a/packages/provider-opencode/src/server/v2/adapter.ts b/packages/provider-opencode/src/server/v2/adapter.ts index a2723a1f84e4c..63648cf8c6cc3 100644 --- a/packages/provider-opencode/src/server/v2/adapter.ts +++ b/packages/provider-opencode/src/server/v2/adapter.ts @@ -4272,7 +4272,7 @@ export const make = Effect.fn("OpenCode2Adapter.make")(function* (instanceId: Pr t3OrchestrationSystemPrompt( mcpAvailable, mcpSession?.capabilities?.has("device") === true, - (yield* host.settings.get.pipe(Effect.orDie)).visualInstructions, + (yield* host.settings.get).visualInstructions, ), mcpAvailable ? "To wait for a background shell you started (tests, a build), call `t3_background_wait` with its shell ID before you end your turn. Do not mark work you leave running, or PRs." diff --git a/packages/provider-pi/src/server/adapter.ts b/packages/provider-pi/src/server/adapter.ts index 1431333790cda..89ee3b9b344f3 100644 --- a/packages/provider-pi/src/server/adapter.ts +++ b/packages/provider-pi/src/server/adapter.ts @@ -522,7 +522,7 @@ export const makePiAdapterV2 = Effect.fn("makePiAdapterV2")(function* ( environment: { ...options.environment, [T3_PI_ORCHESTRATION_INSTRUCTIONS_ENV]: t3OrchestrationInstructions( - (yield* host.settings.get.pipe(Effect.orDie)).visualInstructions, + (yield* host.settings.get).visualInstructions, ).trim(), }, mcpSession,