@morshoto/framekit 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (31) hide show
  1. package/README.md +67 -0
  2. package/bin/framekit.mjs +26 -0
  3. package/dist-package/adapters/final-cut/typescript/src/analyzers.js +116 -0
  4. package/dist-package/adapters/final-cut/typescript/src/assets.js +112 -0
  5. package/dist-package/adapters/final-cut/typescript/src/connection.js +379 -0
  6. package/dist-package/adapters/final-cut/typescript/src/disposable-native.js +282 -0
  7. package/dist-package/adapters/final-cut/typescript/src/export.js +382 -0
  8. package/dist-package/adapters/final-cut/typescript/src/fcpxml.js +503 -0
  9. package/dist-package/adapters/final-cut/typescript/src/index.js +11 -0
  10. package/dist-package/adapters/final-cut/typescript/src/live.js +415 -0
  11. package/dist-package/adapters/final-cut/typescript/src/native-operation.js +18 -0
  12. package/dist-package/adapters/final-cut/typescript/src/native.js +3134 -0
  13. package/dist-package/adapters/final-cut/typescript/src/publisher.js +102 -0
  14. package/dist-package/adapters/final-cut/typescript/src/session.js +171 -0
  15. package/dist-package/apps/cli/src/main.js +130 -0
  16. package/dist-package/apps/mcp-server/src/main.js +146 -0
  17. package/dist-package/apps/mcp-server/src/server.js +617 -0
  18. package/dist-package/packages/runtime/src/capabilities.js +24 -0
  19. package/dist-package/packages/runtime/src/context/context-engine.js +142 -0
  20. package/dist-package/packages/runtime/src/diff/diff.js +145 -0
  21. package/dist-package/packages/runtime/src/domain/types.js +1 -0
  22. package/dist-package/packages/runtime/src/editing/intent.js +83 -0
  23. package/dist-package/packages/runtime/src/index.js +8 -0
  24. package/dist-package/packages/runtime/src/runtime.js +890 -0
  25. package/dist-package/packages/runtime/src/snapshot-digest.js +24 -0
  26. package/dist-package/packages/runtime/src/speech/filler-removal.js +87 -0
  27. package/dist-package/packages/runtime/src/verification/verification.js +113 -0
  28. package/dist-package/packages/testkit/src/fixture-analyzers.js +39 -0
  29. package/dist-package/packages/testkit/src/in-memory-editor.js +520 -0
  30. package/dist-package/packages/testkit/src/index.js +2 -0
  31. package/package.json +64 -0
@@ -0,0 +1,617 @@
1
+ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
2
+ import { z } from "zod";
3
+ import { resolveEditingIntent } from "../../../packages/runtime/src/index.js";
4
+ const revisionValueSchema = z.object({
5
+ id: z.string(),
6
+ sequence: z.number().int().nonnegative(),
7
+ timestamp: z.string(),
8
+ });
9
+ const revisionSchema = revisionValueSchema.optional();
10
+ const rationalTimeSchema = z.object({
11
+ value: z.string().regex(/^-?\d+$/),
12
+ timescale: z.string().regex(/^\d+$/).refine((value) => Number(value) > 0),
13
+ });
14
+ const rangeSchema = z.object({
15
+ start: z.number().nonnegative(),
16
+ end: z.number().positive(),
17
+ });
18
+ const markerSchema = z.object({
19
+ id: z.string().min(1),
20
+ start: z.number().nonnegative(),
21
+ duration: z.number().nonnegative(),
22
+ name: z.string().min(1),
23
+ });
24
+ const renameClipSchema = z.object({ type: z.literal("rename-clip"), clipId: z.string().min(1), name: z.string().min(1), baseRevision: revisionSchema });
25
+ const trimClipSchema = z.object({
26
+ type: z.literal("trim-clip"),
27
+ clipId: z.string().min(1),
28
+ duration: z.number().positive(),
29
+ durationTime: rationalTimeSchema.optional(),
30
+ baseRevision: revisionSchema,
31
+ });
32
+ const setGainSchema = z.object({ type: z.literal("set-gain"), clipId: z.string().min(1), gainDb: z.number().finite(), baseRevision: revisionSchema });
33
+ const rippleDeleteSchema = z.object({ type: z.literal("ripple-delete"), timelineId: z.string().min(1), range: rangeSchema, reason: z.string().optional(), baseRevision: revisionSchema });
34
+ const addMarkerSchema = z.object({ type: z.literal("add-marker"), timelineId: z.string().min(1), marker: markerSchema, baseRevision: revisionSchema });
35
+ const editOperationSchema = z.discriminatedUnion("type", [
36
+ renameClipSchema,
37
+ trimClipSchema,
38
+ setGainSchema,
39
+ rippleDeleteSchema,
40
+ addMarkerSchema,
41
+ ]);
42
+ const editToolInputSchema = z.object({
43
+ type: z.enum(["rename-clip", "trim-clip", "set-gain", "ripple-delete", "add-marker"]),
44
+ clipId: z.string().min(1).optional(),
45
+ name: z.string().min(1).optional(),
46
+ duration: z.number().positive().optional(),
47
+ durationTime: rationalTimeSchema.optional(),
48
+ gainDb: z.number().finite().optional(),
49
+ timelineId: z.string().min(1).optional(),
50
+ range: rangeSchema.optional(),
51
+ reason: z.string().optional(),
52
+ marker: markerSchema.optional(),
53
+ baseRevision: revisionSchema,
54
+ }).strict();
55
+ const workflowOperationSchema = z.discriminatedUnion("type", [
56
+ renameClipSchema,
57
+ trimClipSchema,
58
+ setGainSchema,
59
+ rippleDeleteSchema,
60
+ addMarkerSchema,
61
+ z.object({
62
+ type: z.literal("media.import"),
63
+ mediaId: z.string().min(1),
64
+ source: z.string().min(1),
65
+ mediaKind: z.enum(["video", "audio"]),
66
+ duration: z.number().positive(),
67
+ sourceDigest: z.string().min(1),
68
+ }),
69
+ z.object({
70
+ type: z.literal("timeline.media.add"),
71
+ occurrenceId: z.string().min(1),
72
+ mediaId: z.string().min(1),
73
+ role: z.enum(["video", "music"]),
74
+ start: z.number().nonnegative(),
75
+ duration: z.number().positive(),
76
+ targetLane: z.union([z.literal("primary"), z.number().int()]).optional(),
77
+ }),
78
+ z.object({
79
+ type: z.literal("timeline.audio.fades"),
80
+ clipId: z.string().min(1),
81
+ fadeIn: z.number().nonnegative(),
82
+ fadeOut: z.number().nonnegative(),
83
+ }),
84
+ z.object({
85
+ type: z.literal("timeline.title.add"),
86
+ occurrenceId: z.string().min(1),
87
+ assetId: z.string().min(1),
88
+ text: z.string().min(1),
89
+ start: z.number().nonnegative(),
90
+ duration: z.number().positive(),
91
+ targetLane: z.number().int().refine((lane) => lane !== 0, "title requires a non-primary lane"),
92
+ }),
93
+ ]);
94
+ const workflowOperationsSchema = z.array(workflowOperationSchema).min(1).superRefine((operations, context) => {
95
+ operations.forEach((operation, index) => {
96
+ if (operation.type === "timeline.media.add" && operation.role === "video"
97
+ && operation.targetLane !== undefined && operation.targetLane !== "primary") {
98
+ context.addIssue({ code: z.ZodIssueCode.custom, path: [index, "targetLane"], message: "video must target the primary storyline" });
99
+ }
100
+ if (operation.type === "timeline.media.add" && operation.role === "music"
101
+ && (typeof operation.targetLane !== "number" || operation.targetLane === 0)) {
102
+ context.addIssue({ code: z.ZodIssueCode.custom, path: [index, "targetLane"], message: "music requires an explicit non-primary lane" });
103
+ }
104
+ });
105
+ });
106
+ const musicImportSchema = z.object({
107
+ mediaId: z.string().min(1),
108
+ source: z.string().min(1),
109
+ duration: z.number().positive(),
110
+ sourceDigest: z.string().min(1),
111
+ });
112
+ const musicDuckingSchema = z.object({
113
+ enabled: z.boolean(),
114
+ dialogueClipIds: z.array(z.string().min(1)).optional(),
115
+ reductionDb: z.number().finite().optional(),
116
+ });
117
+ const musicAddInputSchema = {
118
+ baseRevision: revisionValueSchema,
119
+ occurrenceId: z.string().min(1),
120
+ mediaId: z.string().min(1).optional(),
121
+ import: musicImportSchema.optional(),
122
+ placement: z.enum(["append", "insert"]),
123
+ start: z.number().nonnegative().optional(),
124
+ duration: z.number().positive().optional(),
125
+ targetLane: z.number().int().refine((lane) => lane !== 0, "music requires a non-primary lane"),
126
+ gainDb: z.number().finite().optional(),
127
+ fadeIn: z.number().nonnegative().optional(),
128
+ fadeOut: z.number().nonnegative().optional(),
129
+ ducking: musicDuckingSchema.optional(),
130
+ };
131
+ const fillerRemovalInputSchema = {
132
+ baseRevision: revisionValueSchema,
133
+ range: rangeSchema,
134
+ confidenceThreshold: z.number().finite().min(0).max(1).optional(),
135
+ preservePauseMs: z.number().finite().nonnegative().optional(),
136
+ targetPauseMs: z.number().finite().nonnegative().optional(),
137
+ };
138
+ const nativeEditSchema = z.discriminatedUnion("type", [
139
+ z.object({ type: z.literal("rename-selected-clip"), name: z.string().min(1) }),
140
+ z.object({ type: z.literal("trim-selected-clip-to-playhead"), edge: z.enum(["start", "end"]) }),
141
+ z.object({ type: z.literal("set-selected-clip-gain"), gainDb: z.number().finite() }),
142
+ z.object({ type: z.literal("add-marker-at-playhead"), name: z.string().min(1), duration: z.number().nonnegative().optional() }),
143
+ ]);
144
+ const disposableNativePreviewSchema = {
145
+ clipId: z.string().min(1),
146
+ name: z.string().min(1),
147
+ baseRevision: revisionValueSchema.optional(),
148
+ };
149
+ const nativeTitlePreviewSchema = {
150
+ assetId: z.string().min(1),
151
+ text: z.string().trim().min(1),
152
+ start: rationalTimeSchema.optional(),
153
+ duration: rationalTimeSchema,
154
+ };
155
+ const exportExpectationSchema = z.object({
156
+ durationSeconds: z.number().positive().optional(),
157
+ durationToleranceSeconds: z.number().nonnegative().optional(),
158
+ width: z.number().int().positive().optional(),
159
+ height: z.number().int().positive().optional(),
160
+ frameRate: z.number().positive().optional(),
161
+ frameRateTolerance: z.number().nonnegative().optional(),
162
+ hasAudio: z.boolean().optional(),
163
+ }).optional();
164
+ const nativeEditToolInputSchema = z.object({
165
+ type: z.enum([
166
+ "rename-selected-clip",
167
+ "trim-selected-clip-to-playhead",
168
+ "set-selected-clip-gain",
169
+ "add-marker-at-playhead",
170
+ ]),
171
+ name: z.string().min(1).optional(),
172
+ edge: z.enum(["start", "end"]).optional(),
173
+ gainDb: z.number().finite().optional(),
174
+ duration: z.number().nonnegative().optional(),
175
+ }).strict();
176
+ function jsonResult(value) {
177
+ return {
178
+ content: [{ type: "text", text: JSON.stringify(value) }],
179
+ };
180
+ }
181
+ function frameResult(value) {
182
+ const { data, mimeType, ...imageMetadata } = value.image;
183
+ return {
184
+ content: [
185
+ { type: "image", data, mimeType },
186
+ {
187
+ type: "text",
188
+ text: JSON.stringify({
189
+ ...value,
190
+ image: { mimeType, ...imageMetadata },
191
+ }),
192
+ },
193
+ ],
194
+ };
195
+ }
196
+ export function createMcpServer(runtime, options = {}) {
197
+ const server = new McpServer({ name: "framekit", version: "0.1.0" });
198
+ server.registerTool("connection.status", {
199
+ description: "Read Framekit's Final Cut connection state, setup progress, and live capabilities.",
200
+ inputSchema: {},
201
+ }, async () => jsonResult(options.connectionStatus?.() ?? {
202
+ state: "ready",
203
+ editorDetected: false,
204
+ extensionInstalled: false,
205
+ socketPath: null,
206
+ capabilities: null,
207
+ lastError: null,
208
+ }));
209
+ server.registerTool("project.inspect", {
210
+ description: "Read the current canonical project snapshot.",
211
+ }, async () => jsonResult(await runtime.inspectProject()));
212
+ server.registerTool("project.list", {
213
+ description: "List projects and their stable Final Cut sequence identities, including the active target.",
214
+ inputSchema: {},
215
+ }, async () => jsonResult(await runtime.listProjects()));
216
+ server.registerTool("project.select", {
217
+ description: "Select one project and, when it has multiple sequences, one explicit sequence; ambiguous targets fail closed.",
218
+ inputSchema: {
219
+ projectId: z.string().min(1),
220
+ sequenceId: z.string().min(1).optional(),
221
+ },
222
+ }, async ({ projectId, sequenceId }) => jsonResult(await runtime.selectProject({ projectId, sequenceId })));
223
+ server.registerTool("editor.inspect", {
224
+ description: "Read editor identity and machine-readable Phase 2 capabilities.",
225
+ }, async () => {
226
+ const inspected = await runtime.inspectEditor();
227
+ return jsonResult({
228
+ ...inspected,
229
+ capabilities: {
230
+ ...inspected.capabilities,
231
+ editor: {
232
+ ...inspected.capabilities.editor,
233
+ timelinePublishNewProject: Boolean(options.projectPublisher),
234
+ videoExport: Boolean(options.videoExporter?.isAvailable()),
235
+ },
236
+ },
237
+ ...(options.nativeEditor ? { native: options.nativeEditor.capabilities() } : {}),
238
+ });
239
+ });
240
+ server.registerTool("editing.intent.resolve", {
241
+ description: "Map a supported natural-language editing request to one explicit operation without executing it.",
242
+ inputSchema: { request: z.string().trim().min(1) },
243
+ }, async ({ request }) => jsonResult(resolveEditingIntent(request)));
244
+ server.registerTool("editor.native.inspect", {
245
+ description: "Inspect the active Final Cut selection/playhead before a native UI edit.",
246
+ inputSchema: {},
247
+ }, async () => jsonResult(options.nativeEditor
248
+ ? await options.nativeEditor.inspect()
249
+ : { available: false, error: { code: "CAPABILITY_UNAVAILABLE", message: "Final Cut native writes are not configured" } }));
250
+ server.registerTool("editor.native.focus", {
251
+ description: "Activate Final Cut Pro and focus its timeline without changing project or timeline content.",
252
+ inputSchema: {},
253
+ }, async () => jsonResult(options.nativeEditor
254
+ ? await options.nativeEditor.focusTimeline()
255
+ : { available: false, error: { code: "CAPABILITY_UNAVAILABLE", message: "Final Cut native writes are not configured" } }));
256
+ server.registerTool("editor.native.media.import", {
257
+ description: "Import one local video or audio file into the active Final Cut Browser and wait for a stable media handle.",
258
+ inputSchema: { path: z.string().min(1) },
259
+ }, async ({ path }) => {
260
+ if (!options.nativeEditor)
261
+ throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native media import is not configured");
262
+ return jsonResult(await options.nativeEditor.importMedia(path));
263
+ });
264
+ server.registerTool("editor.native.edit", {
265
+ description: "Apply a guarded native Final Cut UI edit to the active selection or playhead.",
266
+ inputSchema: nativeEditToolInputSchema,
267
+ }, async (input) => {
268
+ if (!options.nativeEditor)
269
+ throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native writes are not configured");
270
+ const operation = nativeEditSchema.parse(input);
271
+ return jsonResult(await options.nativeEditor.edit(operation));
272
+ });
273
+ server.registerTool("editor.native.disposable.preview", {
274
+ description: "Preview a disposable native Final Cut rename after canonical target, revision, and native preflight checks.",
275
+ inputSchema: disposableNativePreviewSchema,
276
+ }, async ({ clipId, name, baseRevision }) => {
277
+ if (!options.disposableNative)
278
+ throw new Error("CAPABILITY_UNAVAILABLE: disposable native edit is not configured");
279
+ return jsonResult(await options.disposableNative.preview({ clipId, name, baseRevision }));
280
+ });
281
+ server.registerTool("editor.native.disposable.execute", {
282
+ description: "Execute a disposable native Final Cut edit and return canonical diff, verification, and rollback state.",
283
+ inputSchema: { previewToken: z.string().min(1) },
284
+ }, async ({ previewToken }) => {
285
+ if (!options.disposableNative)
286
+ throw new Error("CAPABILITY_UNAVAILABLE: disposable native edit is not configured");
287
+ return jsonResult(await options.disposableNative.execute(previewToken));
288
+ });
289
+ server.registerTool("editor.native.disposable.undo", {
290
+ description: "Undo a verified disposable native Final Cut edit and verify canonical restoration.",
291
+ inputSchema: { operationId: z.string().min(1) },
292
+ }, async ({ operationId }) => {
293
+ if (!options.disposableNative)
294
+ throw new Error("CAPABILITY_UNAVAILABLE: disposable native edit is not configured");
295
+ return jsonResult(await options.disposableNative.undo(operationId));
296
+ });
297
+ server.registerTool("editor.native.title.add.preview", {
298
+ description: "Preview adding an installed Final Cut title at the live playhead or an explicit timeline range.",
299
+ inputSchema: nativeTitlePreviewSchema,
300
+ }, async ({ assetId, text, start, duration }) => {
301
+ if (!options.nativeEditor)
302
+ throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native title placement is not configured");
303
+ const asset = await resolveNativeTitleAsset(runtime, assetId);
304
+ return jsonResult(await options.nativeEditor.previewTitleAdd({ asset, text, start, duration }));
305
+ });
306
+ server.registerTool("editor.native.title.add.execute", {
307
+ description: "Execute a previously previewed native Final Cut title placement and return its verification and Undo handle.",
308
+ inputSchema: { previewToken: z.string().min(1) },
309
+ }, async ({ previewToken }) => {
310
+ if (!options.nativeEditor)
311
+ throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native title placement is not configured");
312
+ return jsonResult(await options.nativeEditor.executeTitleAdd(previewToken));
313
+ });
314
+ server.registerTool("editor.native.undo", {
315
+ description: "Undo a previously accepted native Final Cut UI edit using Final Cut's native Undo command.",
316
+ inputSchema: { operationId: z.string().min(1) },
317
+ }, async ({ operationId }) => {
318
+ if (!options.nativeEditor)
319
+ throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native writes are not configured");
320
+ return jsonResult(await options.nativeEditor.undo(operationId));
321
+ });
322
+ server.registerTool("editor.native.media.search", {
323
+ description: "Search the active Final Cut Browser for live media and return short-lived media handles.",
324
+ inputSchema: { query: z.string().min(1) },
325
+ }, async ({ query }) => {
326
+ if (!options.nativeEditor)
327
+ throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native media search is not configured");
328
+ return jsonResult(await options.nativeEditor.searchMedia(query));
329
+ });
330
+ server.registerTool("editor.native.media.select", {
331
+ description: "Select one live Final Cut Browser media result using its short-lived handle.",
332
+ inputSchema: { mediaHandle: z.string().min(1) },
333
+ }, async ({ mediaHandle }) => {
334
+ if (!options.nativeEditor)
335
+ throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native media selection is not configured");
336
+ return jsonResult(await options.nativeEditor.selectMedia(mediaHandle));
337
+ });
338
+ server.registerTool("editor.native.media.append.preview", {
339
+ description: "Preview appending the selected Final Cut Browser media to the end of the active timeline.",
340
+ inputSchema: { mediaHandle: z.string().min(1) },
341
+ }, async ({ mediaHandle }) => {
342
+ if (!options.nativeEditor)
343
+ throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native media append is not configured");
344
+ return jsonResult(await options.nativeEditor.previewAppendMedia(mediaHandle));
345
+ });
346
+ server.registerTool("editor.native.media.append.execute", {
347
+ description: "Execute a previously previewed append of selected Final Cut Browser media.",
348
+ inputSchema: { previewToken: z.string().min(1) },
349
+ }, async ({ previewToken }) => {
350
+ if (!options.nativeEditor)
351
+ throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native media append is not configured");
352
+ return jsonResult(await options.nativeEditor.executeAppendMedia(previewToken));
353
+ });
354
+ server.registerTool("editor.native.media.append.selected.preview", {
355
+ description: "Preview appending the currently selected Final Cut Browser media to the end of the active timeline.",
356
+ inputSchema: {},
357
+ }, async () => {
358
+ if (!options.nativeEditor)
359
+ throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native selected-media append is not configured");
360
+ return jsonResult(await options.nativeEditor.previewAppendSelectedMedia());
361
+ });
362
+ server.registerTool("editor.native.media.append.selected.execute", {
363
+ description: "Execute a previously previewed append of the currently selected Final Cut Browser media.",
364
+ inputSchema: { previewToken: z.string().min(1) },
365
+ }, async ({ previewToken }) => {
366
+ if (!options.nativeEditor)
367
+ throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native selected-media append is not configured");
368
+ return jsonResult(await options.nativeEditor.executeAppendSelectedMedia(previewToken));
369
+ });
370
+ server.registerTool("editor.native.media.insert.preview", {
371
+ description: "Preview inserting the selected Final Cut Browser media at the current playhead.",
372
+ inputSchema: { mediaHandle: z.string().min(1) },
373
+ }, async ({ mediaHandle }) => {
374
+ if (!options.nativeEditor)
375
+ throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native media insert is not configured");
376
+ return jsonResult(await options.nativeEditor.previewInsertMedia(mediaHandle));
377
+ });
378
+ server.registerTool("editor.native.media.insert.execute", {
379
+ description: "Execute a previously previewed insertion of selected Final Cut Browser media at the playhead.",
380
+ inputSchema: { previewToken: z.string().min(1) },
381
+ }, async ({ previewToken }) => {
382
+ if (!options.nativeEditor)
383
+ throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native media insert is not configured");
384
+ return jsonResult(await options.nativeEditor.executeInsertMedia(previewToken));
385
+ });
386
+ server.registerTool("editor.native.timeline.locate", {
387
+ description: "Locate matching occurrences of a live Browser media result in the active Final Cut timeline.",
388
+ inputSchema: { mediaHandle: z.string().min(1) },
389
+ }, async ({ mediaHandle }) => {
390
+ if (!options.nativeEditor)
391
+ throw new Error("CAPABILITY_UNAVAILABLE: Final Cut timeline occurrence location is not configured");
392
+ return jsonResult(await options.nativeEditor.locateOccurrence(mediaHandle));
393
+ });
394
+ server.registerTool("editor.native.media.target", {
395
+ description: "Search Final Cut's Browser and target exactly one timeline occurrence with a deterministic live playhead.",
396
+ inputSchema: { query: z.string().min(1) },
397
+ }, async ({ query }) => {
398
+ if (!options.nativeEditor)
399
+ throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native media targeting is not configured");
400
+ return jsonResult(await options.nativeEditor.targetMedia(query));
401
+ });
402
+ server.registerTool("editor.native.blade.preview", {
403
+ description: "Prepare a short-lived confirmation token for a Blade-at-playhead operation.",
404
+ inputSchema: { occurrenceHandle: z.string().min(1) },
405
+ }, async ({ occurrenceHandle }) => {
406
+ if (!options.nativeEditor)
407
+ throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native Blade is not configured");
408
+ return jsonResult(await options.nativeEditor.previewBlade(occurrenceHandle));
409
+ });
410
+ server.registerTool("editor.native.blade.execute", {
411
+ description: "Execute a previously previewed Blade-at-playhead operation in Final Cut Pro.",
412
+ inputSchema: { previewToken: z.string().min(1) },
413
+ }, async ({ previewToken }) => {
414
+ if (!options.nativeEditor)
415
+ throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native Blade is not configured");
416
+ return jsonResult(await options.nativeEditor.executeBlade(previewToken));
417
+ });
418
+ server.registerTool("editor.native.delete-range.preview", {
419
+ description: "Preview a destructive ripple-delete of an explicit rational time range from the Final Cut primary storyline.",
420
+ inputSchema: { start: rationalTimeSchema, end: rationalTimeSchema },
421
+ }, async ({ start, end }) => {
422
+ if (!options.nativeEditor)
423
+ throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native range deletion is not configured");
424
+ return jsonResult(await options.nativeEditor.previewDeleteRange({ start, end }));
425
+ });
426
+ server.registerTool("editor.native.delete-range.execute", {
427
+ description: "Execute a previously previewed primary-storyline ripple-delete range operation in Final Cut Pro.",
428
+ inputSchema: { previewToken: z.string().min(1) },
429
+ }, async ({ previewToken }) => {
430
+ if (!options.nativeEditor)
431
+ throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native range deletion is not configured");
432
+ return jsonResult(await options.nativeEditor.executeDeleteRange(previewToken));
433
+ });
434
+ server.registerTool("editor.native.trim-to-duration.preview", {
435
+ description: "Preview a destructive operation that preserves the beginning of the Final Cut sequence and removes everything after the requested rational duration.",
436
+ inputSchema: { duration: rationalTimeSchema },
437
+ }, async ({ duration }) => {
438
+ if (!options.nativeEditor)
439
+ throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native duration trimming is not configured");
440
+ return jsonResult(await options.nativeEditor.previewTrimToDuration(duration));
441
+ });
442
+ server.registerTool("editor.native.trim-to-duration.execute", {
443
+ description: "Execute a previously previewed trim-to-duration operation in Final Cut Pro.",
444
+ inputSchema: { previewToken: z.string().min(1) },
445
+ }, async ({ previewToken }) => {
446
+ if (!options.nativeEditor)
447
+ throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native duration trimming is not configured");
448
+ return jsonResult(await options.nativeEditor.executeTrimToDuration(previewToken));
449
+ });
450
+ server.registerTool("timeline.publish.new-project", {
451
+ description: "Import the validated FCPXML artifact as a new Final Cut project without replacing the active project.",
452
+ inputSchema: { transactionId: z.string().min(1) },
453
+ }, async ({ transactionId }) => {
454
+ if (!options.projectPublisher)
455
+ throw new Error("CAPABILITY_UNAVAILABLE: Final Cut project publishing requires FRAMEKIT_FCPXML_PATH and native writes");
456
+ const verification = await runtime.verifyTransaction(transactionId);
457
+ if (!verification.passed)
458
+ throw new Error(`FINAL_CUT_PUBLISH_VALIDATION_FAILED: source transaction ${transactionId} did not pass verification`);
459
+ return jsonResult(await options.projectPublisher.publishNewProject(transactionId));
460
+ });
461
+ server.registerTool("timeline.export", {
462
+ description: "Export the active Final Cut timeline to a local video file, wait for completion, and verify its media metadata.",
463
+ inputSchema: {
464
+ outputPath: z.string().trim().min(1),
465
+ preset: z.enum(["master", "web"]),
466
+ overwrite: z.boolean().optional(),
467
+ expected: exportExpectationSchema,
468
+ },
469
+ }, async ({ outputPath, preset, overwrite, expected }) => {
470
+ if (!options.videoExporter?.isAvailable())
471
+ throw new Error("CAPABILITY_UNAVAILABLE: Final Cut video export is not configured");
472
+ return jsonResult(await options.videoExporter.exportVideo({ outputPath, preset, overwrite, expected }));
473
+ });
474
+ server.registerTool("context.inspect", {
475
+ description: "Read the queryable agent editing context and its current revision.",
476
+ inputSchema: {},
477
+ }, async () => jsonResult(await runtime.inspectContext()));
478
+ server.registerTool("context.changes", {
479
+ description: "Read incremental timeline, live-state, and native-asset changes after a context revision.",
480
+ inputSchema: {
481
+ sequence: z.number().int().nonnegative(),
482
+ waitMs: z.number().int().min(0).max(30_000).optional(),
483
+ },
484
+ }, async ({ sequence, waitMs }) => jsonResult(await runtime.contextChangesSince({
485
+ id: `rev-${sequence}`,
486
+ sequence,
487
+ timestamp: new Date(sequence).toISOString(),
488
+ }, waitMs ?? 0)));
489
+ server.registerTool("editor.live.inspect", {
490
+ description: "Read live Final Cut Workflow Extension state: project, active sequence, playhead, and selected range.",
491
+ inputSchema: {},
492
+ }, async () => jsonResult(await runtime.inspectLiveEditor()));
493
+ server.registerTool("editor.live.changes", {
494
+ description: "Read live Final Cut timeline change events after a revision; optionally wait for new events.",
495
+ inputSchema: {
496
+ sequence: z.number().int().nonnegative(),
497
+ waitMs: z.number().int().min(0).max(30_000).optional(),
498
+ },
499
+ }, async ({ sequence, waitMs }) => jsonResult(await runtime.liveChangesSince({
500
+ id: `rev-${sequence}`,
501
+ sequence,
502
+ timestamp: new Date(sequence).toISOString(),
503
+ }, waitMs ?? 0)));
504
+ server.registerTool("timeline.inspect", {
505
+ description: "Read the current canonical timeline snapshot.",
506
+ }, async () => jsonResult(await runtime.inspectTimeline()));
507
+ server.registerTool("timeline.frame.capture", {
508
+ description: "Capture an image at an exact timeline position with project, sequence, clip, and optional visual-analysis metadata.",
509
+ inputSchema: {
510
+ position: rationalTimeSchema,
511
+ analyze: z.boolean().optional(),
512
+ },
513
+ }, async ({ position, analyze }) => frameResult(await runtime.captureFrame(position, { analyze })));
514
+ server.registerTool("media.inspect", {
515
+ description: "Read normalized context and available analysis for one media item.",
516
+ inputSchema: { mediaId: z.string().min(1) },
517
+ }, async ({ mediaId }) => jsonResult(await runtime.inspectMedia(mediaId)));
518
+ server.registerTool("media.search", {
519
+ description: "Search normalized media references by id or source path.",
520
+ inputSchema: { query: z.string() },
521
+ }, async ({ query }) => jsonResult(await runtime.searchMedia(query)));
522
+ server.registerTool("visual.analyze", {
523
+ description: "Analyze scenes, subjects, motion, and keyframes for one media item.",
524
+ inputSchema: {
525
+ mediaId: z.string().min(1),
526
+ range: rangeSchema.optional(),
527
+ },
528
+ }, async ({ mediaId, range }) => jsonResult(await runtime.analyzeVisual(mediaId, range)));
529
+ server.registerTool("media.understand", {
530
+ description: "Return combined speech, audio, and visual understanding for one media item.",
531
+ inputSchema: { mediaId: z.string().min(1) },
532
+ }, async ({ mediaId }) => jsonResult(await runtime.understandMedia(mediaId)));
533
+ server.registerTool("editor.assets", {
534
+ description: "Search editor-native transitions, effects, titles, generators, and templates.",
535
+ inputSchema: {
536
+ query: z.string().optional(),
537
+ kind: z.enum(["transition", "effect", "title", "generator", "audio-effect", "template"]).optional(),
538
+ vendor: z.string().optional(),
539
+ },
540
+ }, async (query) => jsonResult(await runtime.listAssets(query)));
541
+ server.registerTool("timeline.changes", {
542
+ description: "Return the canonical timeline diff since a previously observed revision.",
543
+ inputSchema: { sequence: z.number().int().nonnegative() },
544
+ }, async ({ sequence }) => {
545
+ const project = await runtime.inspectProject();
546
+ return jsonResult(await runtime.changesSince({
547
+ id: `rev-${sequence}`,
548
+ sequence,
549
+ timestamp: new Date(0 + sequence).toISOString(),
550
+ }));
551
+ });
552
+ server.registerTool("timeline.edit", {
553
+ description: "Apply one supported edit and return read-after-write plus its diff.",
554
+ inputSchema: editToolInputSchema,
555
+ }, async (input) => jsonResult(await runtime.edit(editOperationSchema.parse(input))));
556
+ server.registerTool("music.add", {
557
+ description: "Preview adding a searched or imported music bed with placement, gain, and fades; execute the returned token with music.add.execute.",
558
+ inputSchema: musicAddInputSchema,
559
+ }, async (request) => jsonResult(await runtime.previewMusic(request)));
560
+ server.registerTool("music.add.preview", {
561
+ description: "Preview adding a searched or imported music bed without mutating the timeline.",
562
+ inputSchema: musicAddInputSchema,
563
+ }, async (request) => jsonResult(await runtime.previewMusic(request)));
564
+ server.registerTool("music.add.execute", {
565
+ description: "Execute a previously previewed music add and return verified placement and audio state.",
566
+ inputSchema: { previewToken: z.string().min(1) },
567
+ }, async ({ previewToken }) => jsonResult(await runtime.executeEdit(previewToken)));
568
+ server.registerTool("timeline.edit.preview", {
569
+ description: "Validate and preview one ordered, atomic Basic Editing MVP workflow without mutating the project.",
570
+ inputSchema: {
571
+ baseRevision: revisionValueSchema,
572
+ operations: workflowOperationsSchema,
573
+ },
574
+ }, async (request) => jsonResult(await runtime.previewEdit(request)));
575
+ server.registerTool("timeline.edit.execute", {
576
+ description: "Execute one short-lived composite edit preview token exactly once and verify the transaction.",
577
+ inputSchema: { previewToken: z.string().min(1) },
578
+ }, async ({ previewToken }) => jsonResult(await runtime.executeEdit(previewToken)));
579
+ server.registerTool("speech.analyze", {
580
+ description: "Analyze speech words and filler markers for one media item.",
581
+ inputSchema: { mediaId: z.string().min(1) },
582
+ }, async ({ mediaId }) => jsonResult(await runtime.analyzeSpeech(mediaId)));
583
+ server.registerTool("speech.filler.remove.preview", {
584
+ description: "Analyze a selected canonical timeline range and preview removal of high-confidence filler words with safe rational delete ranges.",
585
+ inputSchema: fillerRemovalInputSchema,
586
+ }, async (request) => jsonResult(await runtime.previewFillerRemoval(request)));
587
+ server.registerTool("speech.filler.remove.execute", {
588
+ description: "Execute a previously previewed filler removal, re-analyze adjacent speech, and return the verified or rolled-back transaction.",
589
+ inputSchema: { previewToken: z.string().min(1) },
590
+ }, async ({ previewToken }) => jsonResult(await runtime.executeFillerRemoval(previewToken)));
591
+ server.registerTool("audio.analyze", {
592
+ description: "Analyze loudness, true peak, and silence for one media item.",
593
+ inputSchema: { mediaId: z.string().min(1) },
594
+ }, async ({ mediaId }) => jsonResult(await runtime.analyzeAudio(mediaId)));
595
+ server.registerTool("edit.diff", {
596
+ description: "Read the deterministic diff for a completed edit transaction.",
597
+ inputSchema: { transactionId: z.string().min(1) },
598
+ }, async ({ transactionId }) => jsonResult(runtime.getDiff(transactionId)));
599
+ server.registerTool("edit.verify", {
600
+ description: "Read verification checks for a completed transaction.",
601
+ inputSchema: { transactionId: z.string().min(1) },
602
+ }, async ({ transactionId }) => jsonResult(await runtime.verifyTransaction(transactionId)));
603
+ server.registerTool("edit.undo", {
604
+ description: "Restore the pre-edit snapshot for a completed transaction.",
605
+ inputSchema: { transactionId: z.string().min(1) },
606
+ }, async ({ transactionId }) => jsonResult(await runtime.undo(transactionId)));
607
+ return server;
608
+ }
609
+ async function resolveNativeTitleAsset(runtime, assetId) {
610
+ const assets = await runtime.listAssets();
611
+ const asset = assets.find((candidate) => candidate.id === assetId);
612
+ if (!asset)
613
+ throw new Error(`TITLE_ASSET_NOT_FOUND: installed title asset ${assetId} was not discovered`);
614
+ if (asset.kind !== "title")
615
+ throw new Error(`TITLE_ASSET_INCOMPATIBLE: ${assetId} is not an installed Final Cut title asset`);
616
+ return asset;
617
+ }
@@ -0,0 +1,24 @@
1
+ export function canonicalTimelineMode(capabilities) {
2
+ const editor = capabilities.editor;
3
+ const hasExplicitTargeting = Boolean(editor.projectCatalogRead && editor.projectSelection);
4
+ if (editor.projectRead
5
+ && editor.timelineSnapshotRead
6
+ && hasExplicitTargeting
7
+ && editor.timelineWrite
8
+ && editor.readAfterWrite
9
+ && editor.rollback) {
10
+ return "canonical-write";
11
+ }
12
+ if (editor.projectRead && editor.timelineSnapshotRead && hasExplicitTargeting)
13
+ return "canonical-read";
14
+ return "metadata-only";
15
+ }
16
+ export function withCanonicalTimelineMode(capabilities) {
17
+ return {
18
+ ...capabilities,
19
+ editor: {
20
+ ...capabilities.editor,
21
+ canonicalTimelineMode: canonicalTimelineMode(capabilities),
22
+ },
23
+ };
24
+ }