Skip to content

Commit 9e37f0c

Browse files
authored
fix(preview): transfer recordings to the agent environment (#10572)
1 parent 15193df commit 9e37f0c

11 files changed

Lines changed: 517 additions & 17 deletions

File tree

‎apps/server/src/mcp/PreviewAutomationBroker.test.ts‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -404,6 +404,49 @@ it.effect("classifies a remote non-editable target without collapsing it to exec
404404
);
405405
});
406406

407+
it.effect.each([
408+
"PreviewAutomationRecordingTransferError",
409+
"PreviewAutomationRecordingDesktopUpdateRequiredError",
410+
"PreviewAutomationRecordingTooLargeError",
411+
"PreviewAutomationRecordingDeadlineExpiredError",
412+
] as const)("preserves recording failure %s", (tag) =>
413+
Effect.scoped(
414+
Effect.gen(function* () {
415+
const broker = yield* makeBroker;
416+
const remoteError = {
417+
_tag: tag,
418+
message: "remote recording details",
419+
detail: { reason: "untrusted-reason", threadId: "untrusted-thread" },
420+
};
421+
const requests = requestsFrom(yield* broker.connect(makeHost()));
422+
yield* Stream.runForEach(requests, (request) =>
423+
broker.respond({
424+
clientId: "client-1",
425+
connectionId: request.connectionId,
426+
requestId: request.requestId,
427+
ok: false,
428+
error: remoteError,
429+
}),
430+
).pipe(Effect.forkScoped);
431+
yield* Effect.yieldNow;
432+
const error = yield* broker
433+
.invoke<void>({
434+
scope,
435+
operation: "recordingStop",
436+
input: {},
437+
})
438+
.pipe(Effect.flip);
439+
expect(error).toMatchObject({
440+
_tag: tag,
441+
threadId: scope.threadId,
442+
});
443+
expect(error.cause).toBe(remoteError);
444+
expect(error.message).toContain("remains on the desktop");
445+
expect(error.message).not.toContain("remote recording details");
446+
}),
447+
),
448+
);
449+
407450
it.effect("distinguishes malformed remote failures", () =>
408451
Effect.scoped(
409452
Effect.gen(function* () {

‎apps/server/src/mcp/PreviewAutomationBroker.ts‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,10 @@ import {
77
PreviewAutomationMalformedResponseError,
88
PreviewAutomationNoAvailableHostError,
99
PreviewAutomationRemoteUnavailableError,
10+
PreviewAutomationRecordingTransferError,
11+
PreviewAutomationRecordingDesktopUpdateRequiredError,
12+
PreviewAutomationRecordingTooLargeError,
13+
PreviewAutomationRecordingDeadlineExpiredError,
1014
PreviewAutomationRequestQueueClosedError,
1115
PreviewAutomationResultTooLargeError,
1216
PreviewAutomationTabNotFoundError,
@@ -194,6 +198,26 @@ const classifyResponseError = (
194198
cause: error,
195199
};
196200
switch (error._tag) {
201+
case "PreviewAutomationRecordingDesktopUpdateRequiredError":
202+
return new PreviewAutomationRecordingDesktopUpdateRequiredError({
203+
threadId: context.threadId,
204+
cause: error,
205+
});
206+
case "PreviewAutomationRecordingTooLargeError":
207+
return new PreviewAutomationRecordingTooLargeError({
208+
threadId: context.threadId,
209+
cause: error,
210+
});
211+
case "PreviewAutomationRecordingDeadlineExpiredError":
212+
return new PreviewAutomationRecordingDeadlineExpiredError({
213+
threadId: context.threadId,
214+
cause: error,
215+
});
216+
case "PreviewAutomationRecordingTransferError":
217+
return new PreviewAutomationRecordingTransferError({
218+
threadId: context.threadId,
219+
cause: error,
220+
});
197221
case "PreviewAutomationNoAvailableHostError":
198222
return new PreviewAutomationNoAvailableHostError({
199223
...context,

‎apps/server/src/mcp/toolkits/preview/handlers.test.ts‎

Lines changed: 125 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,17 @@
1-
import { describe, expect, it } from "vite-plus/test";
1+
import { describe, expect, it } from "@effect/vitest";
2+
import * as NodeServices from "@effect/platform-node/NodeServices";
3+
import { ThreadId } from "@t3tools/contracts";
4+
import * as Effect from "effect/Effect";
5+
import * as FileSystem from "effect/FileSystem";
6+
import * as Layer from "effect/Layer";
7+
import * as Path from "effect/Path";
28

3-
import { normalizePreviewOpenInput } from "./handlers.ts";
9+
import {
10+
createPendingAttachmentId,
11+
parseThreadSegmentFromAttachmentId,
12+
} from "../../../attachmentStore.ts";
13+
import * as ServerConfig from "../../../config.ts";
14+
import { claimPreviewRecording, normalizePreviewOpenInput } from "./handlers.ts";
415

516
describe("normalizePreviewOpenInput", () => {
617
it("leaves an unstated visibility for the client preference to decide", () => {
@@ -30,3 +41,115 @@ describe("normalizePreviewOpenInput", () => {
3041
});
3142
});
3243
});
44+
45+
describe("claimPreviewRecording", () => {
46+
it.effect("overlapping and repeated claims return the same retained recording", () =>
47+
Effect.gen(function* () {
48+
const config = yield* ServerConfig.ServerConfig;
49+
const fileSystem = yield* FileSystem.FileSystem;
50+
const path = yield* Path.Path;
51+
const uploadedAttachmentId = createPendingAttachmentId(".webm");
52+
const pendingPath = path.join(config.attachmentsDir, `${uploadedAttachmentId}.webm`);
53+
yield* fileSystem.makeDirectory(config.attachmentsDir, { recursive: true });
54+
yield* fileSystem.writeFileString(pendingPath, "video!");
55+
const response = {
56+
id: "desktop-recording",
57+
tabId: "tab-1",
58+
path: "/desktop/recording.webm",
59+
mimeType: "video/webm",
60+
sizeBytes: 6,
61+
createdAt: "2026-09-07T00:00:00.000Z",
62+
uploadedAttachmentId,
63+
};
64+
const claim = claimPreviewRecording(ThreadId.make("thread-1"), response);
65+
const [first, second] = yield* Effect.all([claim, claim], { concurrency: "unbounded" });
66+
expect(first).toEqual(second);
67+
expect(yield* claim).toEqual(first);
68+
expect(yield* fileSystem.readFileString(first.path)).toBe("video!");
69+
expect(yield* fileSystem.exists(pendingPath)).toBe(false);
70+
const wrongThread = yield* claimPreviewRecording(ThreadId.make("thread-2"), response).pipe(
71+
Effect.result,
72+
);
73+
expect(wrongThread._tag).toBe("Failure");
74+
const wrongPath = yield* claimPreviewRecording(ThreadId.make("thread-1"), {
75+
...response,
76+
uploadedAttachmentId: `../${uploadedAttachmentId}`,
77+
}).pipe(Effect.result);
78+
expect(wrongPath._tag).toBe("Failure");
79+
}).pipe(
80+
Effect.provide(
81+
ServerConfig.layerTest(process.cwd(), { prefix: "t3-preview-recording-" }).pipe(
82+
Layer.provideMerge(NodeServices.layer),
83+
),
84+
),
85+
),
86+
);
87+
88+
it.effect.each([6, 5])(
89+
"claims only a complete uploaded recording (reported bytes: %s)",
90+
(sizeBytes) =>
91+
Effect.gen(function* () {
92+
const config = yield* ServerConfig.ServerConfig;
93+
const fileSystem = yield* FileSystem.FileSystem;
94+
const path = yield* Path.Path;
95+
const uploadedAttachmentId = createPendingAttachmentId(".webm");
96+
const pendingPath = path.join(config.attachmentsDir, `${uploadedAttachmentId}.webm`);
97+
yield* fileSystem.makeDirectory(config.attachmentsDir, { recursive: true });
98+
yield* fileSystem.writeFileString(pendingPath, "video!");
99+
const response = {
100+
id: "desktop-recording",
101+
tabId: "tab-1",
102+
path: "/desktop/recording.webm",
103+
mimeType: "video/webm",
104+
sizeBytes,
105+
createdAt: "2026-09-07T00:00:00.000Z",
106+
uploadedAttachmentId,
107+
};
108+
const result = yield* claimPreviewRecording(ThreadId.make("thread-1"), response).pipe(
109+
Effect.result,
110+
);
111+
if (sizeBytes === 6) {
112+
expect(result._tag).toBe("Success");
113+
if (result._tag !== "Success") return;
114+
expect(result.success.path).not.toBe(response.path);
115+
expect(parseThreadSegmentFromAttachmentId(result.success.id)).toBe("thread-1");
116+
expect(yield* fileSystem.readFileString(result.success.path)).toBe("video!");
117+
expect(yield* fileSystem.exists(pendingPath)).toBe(false);
118+
} else {
119+
expect(result._tag).toBe("Failure");
120+
if (result._tag !== "Failure") return;
121+
expect(result.failure._tag).toBe("PreviewAutomationRecordingTransferError");
122+
expect(yield* fileSystem.exists(pendingPath)).toBe(true);
123+
}
124+
}).pipe(
125+
Effect.provide(
126+
ServerConfig.layerTest(process.cwd(), { prefix: "t3-preview-recording-" }).pipe(
127+
Layer.provideMerge(NodeServices.layer),
128+
),
129+
),
130+
),
131+
);
132+
133+
it.effect("reports an older desktop without returning its inaccessible path", () =>
134+
Effect.gen(function* () {
135+
const result = yield* claimPreviewRecording(ThreadId.make("thread-1"), {
136+
id: "desktop-recording",
137+
tabId: "tab-1",
138+
path: "/desktop/recording.webm",
139+
mimeType: "video/webm",
140+
sizeBytes: 6,
141+
createdAt: "2026-09-07T00:00:00.000Z",
142+
}).pipe(Effect.result);
143+
expect(result._tag).toBe("Failure");
144+
if (result._tag !== "Failure") return;
145+
expect(result.failure._tag).toBe("PreviewAutomationRecordingDesktopUpdateRequiredError");
146+
expect(result.failure.message).toContain("Update the desktop app");
147+
}).pipe(
148+
Effect.provide(
149+
ServerConfig.layerTest(process.cwd(), { prefix: "t3-preview-recording-" }).pipe(
150+
Layer.provideMerge(NodeServices.layer),
151+
),
152+
),
153+
),
154+
);
155+
});

‎apps/server/src/mcp/toolkits/preview/handlers.ts‎

Lines changed: 106 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,31 @@
11
import * as Effect from "effect/Effect";
2-
import type {
3-
PreviewAutomationOperation,
4-
PreviewAutomationOpenInput,
2+
import * as FileSystem from "effect/FileSystem";
3+
import * as Schema from "effect/Schema";
4+
import {
5+
PROVIDER_SEND_TURN_MAX_FILE_BYTES,
6+
PREVIEW_RECORDING_STOP_TIMEOUT_MS,
7+
PreviewAutomationRecordingTransferError,
8+
PreviewAutomationRecordingDesktopUpdateRequiredError,
59
PreviewAutomationRecordingArtifact,
6-
PreviewAutomationRecordingStatus,
7-
PreviewAutomationResizeResult,
8-
PreviewAutomationSetColorSchemeResult,
9-
PreviewAutomationSnapshot,
10-
PreviewAutomationStatus,
11-
PreviewTabId,
10+
type ThreadId,
11+
type PreviewAutomationOperation,
12+
type PreviewAutomationOpenInput,
13+
type PreviewAutomationRecordingStatus,
14+
type PreviewAutomationResizeResult,
15+
type PreviewAutomationSetColorSchemeResult,
16+
type PreviewAutomationSnapshot,
17+
type PreviewAutomationStatus,
18+
type PreviewTabId,
1219
} from "@t3tools/contracts";
1320

21+
import {
22+
parseAttachmentUuid,
23+
parseAttachmentFileExtension,
24+
PENDING_ATTACHMENT_THREAD_SEGMENT,
25+
toSafeThreadAttachmentSegment,
26+
} from "../../../attachmentStore.ts";
27+
import { resolveAttachmentRelativePath } from "../../../attachmentPaths.ts";
28+
import * as ServerConfig from "../../../config.ts";
1429
import * as McpInvocationContext from "../../McpInvocationContext.ts";
1530
import * as PreviewAutomationBroker from "../../PreviewAutomationBroker.ts";
1631
import { PreviewSnapshotToolkit, PreviewStandardToolkit, PreviewToolkit } from "./tools.ts";
@@ -67,6 +82,79 @@ const invokeTargeted = <A>(
6782
return invoke<A>(operation, operationInput, timeoutMs, tabId);
6883
};
6984

85+
const UploadedRecordingArtifact = Schema.Struct({
86+
...PreviewAutomationRecordingArtifact.fields,
87+
uploadedAttachmentId: Schema.optional(Schema.String),
88+
});
89+
const decodeUploadedRecordingArtifact = Schema.decodeUnknownEffect(UploadedRecordingArtifact);
90+
91+
export const claimPreviewRecording = Effect.fn("PreviewToolkit.claimRecording")(function* (
92+
threadId: ThreadId,
93+
response: unknown,
94+
) {
95+
const artifact = yield* decodeUploadedRecordingArtifact(response).pipe(
96+
Effect.mapError(
97+
(cause) =>
98+
new PreviewAutomationRecordingTransferError({
99+
threadId,
100+
cause,
101+
}),
102+
),
103+
);
104+
if (!artifact.uploadedAttachmentId) {
105+
return yield* new PreviewAutomationRecordingDesktopUpdateRequiredError({ threadId });
106+
}
107+
const config = yield* ServerConfig.ServerConfig;
108+
const uuid = parseAttachmentUuid(artifact.uploadedAttachmentId);
109+
const extension = parseAttachmentFileExtension(artifact.uploadedAttachmentId);
110+
const threadSegment = toSafeThreadAttachmentSegment(threadId);
111+
const pendingId = `${PENDING_ATTACHMENT_THREAD_SEGMENT}-${uuid}-${extension}`;
112+
if (!uuid || !extension || !threadSegment || artifact.uploadedAttachmentId !== pendingId) {
113+
return yield* new PreviewAutomationRecordingTransferError({
114+
threadId,
115+
});
116+
}
117+
// The same completed upload can be returned to overlapping stop requests.
118+
const finalId = `${threadSegment}-${uuid}-${extension}`;
119+
const currentPath = resolveAttachmentRelativePath({
120+
attachmentsDir: config.attachmentsDir,
121+
relativePath: `${pendingId}.${extension}`,
122+
});
123+
const finalPath = resolveAttachmentRelativePath({
124+
attachmentsDir: config.attachmentsDir,
125+
relativePath: `${finalId}.${extension}`,
126+
});
127+
if (!currentPath || !finalPath) {
128+
return yield* new PreviewAutomationRecordingTransferError({ threadId });
129+
}
130+
const fileSystem = yield* FileSystem.FileSystem;
131+
const validateFile = (filePath: string) =>
132+
fileSystem.stat(filePath).pipe(
133+
Effect.filterOrFail(
134+
(stat) =>
135+
stat.type === "File" &&
136+
Number(stat.size) === artifact.sizeBytes &&
137+
artifact.sizeBytes > 0 &&
138+
artifact.sizeBytes <= PROVIDER_SEND_TURN_MAX_FILE_BYTES,
139+
() => new PreviewAutomationRecordingTransferError({ threadId }),
140+
),
141+
);
142+
yield* Effect.gen(function* () {
143+
yield* validateFile(currentPath);
144+
yield* fileSystem.rename(currentPath, finalPath);
145+
}).pipe(
146+
// Another stop may already have claimed this exact upload for this thread.
147+
Effect.catch((cause) =>
148+
cause._tag !== "PreviewAutomationRecordingTransferError" && cause.reason._tag === "NotFound"
149+
? validateFile(finalPath)
150+
: Effect.fail(cause),
151+
),
152+
Effect.mapError((cause) => new PreviewAutomationRecordingTransferError({ threadId, cause })),
153+
);
154+
const { uploadedAttachmentId: _uploadedAttachmentId, ...recording } = artifact;
155+
return { ...recording, id: finalId, path: finalPath };
156+
});
157+
70158
const handlers = {
71159
preview_status: (input) => invokeTargeted<PreviewAutomationStatus>("status", input ?? {}),
72160
preview_open: (input) =>
@@ -94,7 +182,15 @@ const handlers = {
94182
preview_recording_start: (input) =>
95183
invokeTargeted<PreviewAutomationRecordingStatus>("recordingStart", input ?? {}),
96184
preview_recording_stop: (input) =>
97-
invokeTargeted<PreviewAutomationRecordingArtifact>("recordingStop", input ?? {}),
185+
Effect.gen(function* () {
186+
const scope = yield* McpInvocationContext.requireMcpCapability("preview");
187+
const response = yield* invokeTargeted<unknown>(
188+
"recordingStop",
189+
{ ...input, transferToEnvironment: true },
190+
PREVIEW_RECORDING_STOP_TIMEOUT_MS,
191+
);
192+
return yield* claimPreviewRecording(scope.threadId, response);
193+
}),
98194
} satisfies Parameters<typeof PreviewToolkit.toLayer>[0];
99195

100196
const { preview_snapshot, ...standardHandlers } = handlers;

‎apps/server/src/mcp/toolkits/preview/tools.ts‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -19,10 +19,12 @@ import {
1919
PreviewAutomationWaitForInput,
2020
} from "@t3tools/contracts";
2121
import * as Schema from "effect/Schema";
22+
import * as FileSystem from "effect/FileSystem";
2223
import { Tool, Toolkit } from "effect/unstable/ai";
2324

2425
import * as McpInvocationContext from "../../McpInvocationContext.ts";
2526
import * as PreviewAutomationBroker from "../../PreviewAutomationBroker.ts";
27+
import * as ServerConfig from "../../../config.ts";
2628

2729
const dependencies = [
2830
McpInvocationContext.McpInvocationContext,
@@ -207,11 +209,11 @@ export const PreviewRecordingStartTool = safeBrowserTool(
207209
export const PreviewRecordingStopTool = safeBrowserTool(
208210
Tool.make("preview_recording_stop", {
209211
description:
210-
"Stop recording the collaborative browser tab selected by tabId, or this agent session's current tab when omitted, and save it as a local evidence artifact.",
212+
"Stop recording the collaborative browser tab selected by tabId, or this agent session's current tab when omitted, and transfer the compressed recording once (up to 50 MiB) to an evidence file readable in this agent's environment. Returns its environment-local path after transfer succeeds.",
211213
parameters: PreviewAutomationTabTargetInput,
212214
success: PreviewAutomationRecordingArtifact,
213215
failure: PreviewAutomationError,
214-
dependencies,
216+
dependencies: [...dependencies, FileSystem.FileSystem, ServerConfig.ServerConfig],
215217
}).annotate(Tool.Title, "Stop browser recording"),
216218
);
217219

0 commit comments

Comments
 (0)