diff --git a/apps/server/src/orchestration-v2/Adapters/ClaudeAdapterV2.test.ts b/apps/server/src/orchestration-v2/Adapters/ClaudeAdapterV2.test.ts index cb9aadef97ad0..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"; @@ -794,6 +797,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 +815,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); @@ -21042,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, @@ -21088,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", @@ -21138,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 1539b054c6e7c..7ce127f4b41ce 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; @@ -2276,7 +2277,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* ( ], { 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) { @@ -12632,6 +12636,7 @@ export const makeClaudeAdapterV2 = Effect.fn("makeClaudeAdapterV2")(function* ( const shouldResume = resumeSessionAt !== undefined || openedWithResume || hasPersistedProviderTurn; const queryOptions = makeClaudeQueryOptions({ + 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 4af8bdb574404..5411209eb6f01 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"; @@ -265,6 +267,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 +278,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 +291,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.", + ); }), ); }); @@ -1678,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 fe0e5dc17f40b..e4cd81f49200b 100644 --- a/apps/server/src/orchestration-v2/Adapters/CodexAdapterV2.ts +++ b/apps/server/src/orchestration-v2/Adapters/CodexAdapterV2.ts @@ -111,6 +111,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, @@ -785,6 +786,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; @@ -837,6 +839,7 @@ export const buildCodexTurnStartParams = Effect.fn("CodexAdapterV2.buildCodexTur browser: input.browserToolsAvailable ?? true, device: input.deviceToolsAvailable ?? false, }, + input.visualInstructions, ) : undefined; const additionalContext = @@ -1891,6 +1894,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); @@ -7514,6 +7518,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).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..a1690680e2ca4 100644 --- a/docs/user/html-renders.md +++ b/docs/user/html-renders.md @@ -10,6 +10,25 @@ 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 and forks may retain the instructions +from their original thread. + +```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..80b397df5ce7a 100644 --- a/packages/contracts/src/settings.test.ts +++ b/packages/contracts/src/settings.test.ts @@ -544,3 +544,28 @@ 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(); + for (const decode of [decodeServerSettings, decodeServerSettingsPatch]) { + 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 7bbb03595d4bb..fa99c03fde9f9 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) && !value.includes("\0") + ? true + : "Visual instructions must contain well-formed Unicode without NUL characters.", + ), + ), +); + 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))), @@ -1536,6 +1548,8 @@ export const ServerSettings = Schema.Struct({ }), ), ), + // Leaves room for browser guidance inside Codex's 4,000-byte context entry. + 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)), @@ -1929,6 +1943,7 @@ export const ServerSettingsPatch = Schema.Struct({ addProjectBaseDirectory: Schema.optionalKey(TrimmedString), ghqCloneLayout: Schema.optionalKey(Schema.Boolean), textGenerationModelSelection: Schema.optionalKey(ModelSelectionPatch), + visualInstructions: Schema.optionalKey(VisualInstructions), 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 e0fb9d0f61ae2..da282b7850aa2 100644 --- a/packages/provider-acp/src/server/adapter.ts +++ b/packages/provider-acp/src/server/adapter.ts @@ -8400,11 +8400,13 @@ export const makeAcpAdapterV2 = Effect.fn("makeAcpAdapterV2")(function* ( ); attachmentBlocks.push(...blocks); } + 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); 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.test.ts b/packages/provider-cursor/src/server/adapter.test.ts index a4cb1a5aa7c63..fe1ade27bd3f3 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, @@ -757,6 +758,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; @@ -809,14 +811,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, @@ -846,7 +854,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; @@ -883,8 +891,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 90c55675af296..056b47d76208b 100644 --- a/packages/provider-cursor/src/server/adapter.ts +++ b/packages/provider-cursor/src/server/adapter.ts @@ -2621,6 +2621,7 @@ export const makeCursorAdapterV2 = Effect.fn("makeCursorAdapterV2")(function* ( return { message: "/compress", prompt: undefined }; } const newText = t3OrchestrationPrompt({ + visualInstructions: (yield* host.settings.get).visualInstructions, prompt: yield* providerMessageTextWithAttachmentPaths({ text: yield* resolveCursorSkillText( rawText, @@ -2994,6 +2995,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, 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..d2c11e9e903a4 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).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 3a83c81557d5a..63648cf8c6cc3 100644 --- a/packages/provider-opencode/src/server/v2/adapter.ts +++ b/packages/provider-opencode/src/server/v2/adapter.ts @@ -4269,7 +4269,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).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 ff7725191e621..3cc62a0d0bf2f 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"; @@ -517,8 +519,14 @@ export const makePiAdapterV2 = Effect.fn("makePiAdapterV2")(function* ( return yield* Effect.gen(function* () { const launch = buildPiRpcLaunch({ launchArgs: resolvedLaunchArgs.args, - // PortScanner.AGENT_THREAD_ENV, as a literal because this package cannot reach apps/server. - environment: { ...options.environment, T3CODE_THREAD_ID: input.threadId }, + environment: { + ...options.environment, + // PortScanner.AGENT_THREAD_ENV, as a literal because this package cannot reach apps/server. + T3CODE_THREAD_ID: input.threadId, + [T3_PI_ORCHESTRATION_INSTRUCTIONS_ENV]: t3OrchestrationInstructions( + (yield* host.settings.get).visualInstructions, + ).trim(), + }, mcpSession, extensionPath, sessionPath, 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 6a909f4e374f9..173b0adc58ed7 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 0f137d0f4d4d0..d1266422391b6 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"]);