@morshoto/framekit 0.1.5 → 0.1.10

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 (40) hide show
  1. package/bin/framekit.mjs +2 -1
  2. package/dist-package/adapters/final-cut/typescript/src/assets.js +223 -15
  3. package/dist-package/adapters/final-cut/typescript/src/background-export.js +384 -0
  4. package/dist-package/adapters/final-cut/typescript/src/canonical.js +588 -0
  5. package/dist-package/adapters/final-cut/typescript/src/connection.js +20 -5
  6. package/dist-package/adapters/final-cut/typescript/src/disposable-native.js +33 -7
  7. package/dist-package/adapters/final-cut/typescript/src/fcpxml.js +805 -51
  8. package/dist-package/adapters/final-cut/typescript/src/index.js +5 -0
  9. package/dist-package/adapters/final-cut/typescript/src/library-inspection.js +390 -0
  10. package/dist-package/adapters/final-cut/typescript/src/live.js +6 -3
  11. package/dist-package/adapters/final-cut/typescript/src/media.js +151 -0
  12. package/dist-package/adapters/final-cut/typescript/src/native-session.js +412 -0
  13. package/dist-package/adapters/final-cut/typescript/src/native.js +2271 -424
  14. package/dist-package/adapters/final-cut/typescript/src/publisher.js +225 -32
  15. package/dist-package/adapters/final-cut/typescript/src/session.js +145 -17
  16. package/dist-package/apps/mcp-server/src/main.js +73 -17
  17. package/dist-package/apps/mcp-server/src/routing.js +242 -39
  18. package/dist-package/apps/mcp-server/src/server.js +677 -89
  19. package/dist-package/apps/mcp-server/src/version.js +109 -1
  20. package/dist-package/packages/runtime/src/application/media-analysis-service.js +3 -4
  21. package/dist-package/packages/runtime/src/application/project-service.js +46 -7
  22. package/dist-package/packages/runtime/src/audio/dialogue-normalization.js +9 -0
  23. package/dist-package/packages/runtime/src/capabilities.js +62 -9
  24. package/dist-package/packages/runtime/src/context/project-catalog.js +159 -0
  25. package/dist-package/packages/runtime/src/domain/capabilities.js +33 -0
  26. package/dist-package/packages/runtime/src/domain/context.js +14 -1
  27. package/dist-package/packages/runtime/src/domain/editing.js +27 -1
  28. package/dist-package/packages/runtime/src/domain/index.js +1 -0
  29. package/dist-package/packages/runtime/src/domain/skills.js +2 -0
  30. package/dist-package/packages/runtime/src/domain/timeline-target.js +217 -0
  31. package/dist-package/packages/runtime/src/editing/edit-service.js +57 -1
  32. package/dist-package/packages/runtime/src/editing/intent.js +178 -2
  33. package/dist-package/packages/runtime/src/index.js +1 -0
  34. package/dist-package/packages/runtime/src/runtime.js +2 -2
  35. package/dist-package/packages/runtime/src/skills/builtin.js +314 -39
  36. package/dist-package/packages/runtime/src/skills/requirements.js +1 -0
  37. package/dist-package/packages/runtime/src/skills/runtime.js +33 -8
  38. package/dist-package/packages/runtime/src/verification/verification.js +81 -4
  39. package/dist-package/packages/testkit/src/in-memory-editor.js +130 -4
  40. package/package.json +12 -2
@@ -1,9 +1,11 @@
1
1
  import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
2
2
  import { ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
3
+ import { resolve as resolvePath } from "node:path";
3
4
  import { z } from "zod";
4
- import { createCapabilityPreflight, resolveEditingIntent, withCapabilityFamilies, } from "../../../packages/runtime/src/index.js";
5
- import { EDITOR_FIRST_MCP_INSTRUCTIONS, resolveEditingRoute, } from "./routing.js";
6
- import { FRAMEKIT_VERSION } from "./version.js";
5
+ import { createCapabilityPreflight, resolveEditingIntent, serializeCapabilityUnavailableError, withCanonicalTimelineMode, withCapabilityFamilies, } from "../../../packages/runtime/src/index.js";
6
+ import { NATIVE_MEDIA_IMPORT_DIRECTORY_ERROR_CODE, serializeFinalCutLibraryInspectionError, serializeNativeFinalCutMediaImportError, } from "../../../adapters/final-cut/typescript/src/index.js";
7
+ import { BACKGROUND_ARTIFACT_WORKFLOW, EDITOR_FIRST_MCP_INSTRUCTIONS, resolveEditingRoute, } from "./routing.js";
8
+ import { FRAMEKIT_BUILD_FINGERPRINT, FRAMEKIT_VERSION, } from "./version.js";
7
9
  const revisionValueSchema = z.object({
8
10
  id: z.string(),
9
11
  sequence: z.number().int().nonnegative(),
@@ -62,6 +64,39 @@ const markerSchema = z.object({
62
64
  duration: z.number().nonnegative(),
63
65
  name: z.string().min(1),
64
66
  });
67
+ const maskBoundsSchema = z.object({
68
+ x: z.number().finite().min(0).max(1),
69
+ y: z.number().finite().min(0).max(1),
70
+ width: z.number().finite().positive().max(1),
71
+ height: z.number().finite().positive().max(1),
72
+ }).strict().superRefine((bounds, context) => {
73
+ if (bounds.x + bounds.width > 1) {
74
+ context.addIssue({ code: z.ZodIssueCode.custom, path: ["width"], message: "x plus width must fit within the frame" });
75
+ }
76
+ if (bounds.y + bounds.height > 1) {
77
+ context.addIssue({ code: z.ZodIssueCode.custom, path: ["height"], message: "y plus height must fit within the frame" });
78
+ }
79
+ });
80
+ const maskSchema = z.discriminatedUnion("mode", [
81
+ z.object({
82
+ mode: z.literal("rectangle"),
83
+ bounds: maskBoundsSchema,
84
+ inverted: z.boolean().optional(),
85
+ }).strict(),
86
+ z.object({
87
+ mode: z.literal("supplied-alpha"),
88
+ alphaMediaId: z.string().trim().min(1),
89
+ bounds: maskBoundsSchema.optional(),
90
+ inverted: z.boolean().optional(),
91
+ }).strict(),
92
+ z.object({
93
+ mode: z.literal("person-cutout"),
94
+ }).strict(),
95
+ ]);
96
+ const nativeMaskSchema = z.object({
97
+ mode: z.literal("rectangle"),
98
+ bounds: maskBoundsSchema,
99
+ }).strict();
65
100
  const renameClipSchema = z.object({ type: z.literal("rename-clip"), clipId: z.string().min(1), name: z.string().min(1), baseRevision: revisionSchema });
66
101
  const trimClipSchema = z.object({
67
102
  type: z.literal("trim-clip"),
@@ -265,6 +300,10 @@ const artifactPublishInputSchema = z.object({
265
300
  transactionId: z.string().min(1),
266
301
  confirm: z.boolean(),
267
302
  }).strict();
303
+ const artifactTransactionInputSchema = z.object({
304
+ artifactPath: z.string().trim().min(1),
305
+ transactionId: z.string().min(1),
306
+ }).strict();
268
307
  const workflowOperationSchema = z.discriminatedUnion("type", [
269
308
  renameClipSchema,
270
309
  trimClipSchema,
@@ -290,6 +329,28 @@ const workflowOperationSchema = z.discriminatedUnion("type", [
290
329
  duration: z.number().positive(),
291
330
  targetLane: z.union([z.literal("primary"), z.number().int()]).optional(),
292
331
  }),
332
+ z.object({
333
+ type: z.literal("timeline.picture-in-picture.add"),
334
+ occurrenceId: z.string().min(1),
335
+ mediaId: z.string().min(1),
336
+ attachedTo: z.string().min(1),
337
+ start: z.number().finite().nonnegative(),
338
+ duration: z.number().finite().positive(),
339
+ targetLane: z.number().int().refine((lane) => lane !== 0, "PIP requires a connected non-primary lane"),
340
+ position: z.object({ x: z.number().finite(), y: z.number().finite() }),
341
+ scale: z.number().finite().positive(),
342
+ crop: z.object({
343
+ top: z.number().finite().min(0).lt(1),
344
+ right: z.number().finite().min(0).lt(1),
345
+ bottom: z.number().finite().min(0).lt(1),
346
+ left: z.number().finite().min(0).lt(1),
347
+ }).optional(),
348
+ frame: z.object({
349
+ style: z.literal("solid"),
350
+ color: z.string().regex(/^#[0-9a-f]{6}$/i),
351
+ width: z.number().finite().nonnegative(),
352
+ }).optional(),
353
+ }),
293
354
  z.object({
294
355
  type: z.literal("timeline.audio.fades"),
295
356
  clipId: z.string().min(1),
@@ -344,6 +405,11 @@ const workflowOperationSchema = z.discriminatedUnion("type", [
344
405
  fadeIn: z.number().nonnegative().optional(),
345
406
  fadeOut: z.number().nonnegative().optional(),
346
407
  }),
408
+ z.object({
409
+ type: z.literal("timeline.mask.add"),
410
+ occurrenceId: z.string().min(1),
411
+ mask: maskSchema,
412
+ }),
347
413
  ]);
348
414
  const workflowOperationsSchema = z.array(workflowOperationSchema).min(1).superRefine((operations, context) => {
349
415
  operations.forEach((operation, index) => {
@@ -359,6 +425,11 @@ const workflowOperationsSchema = z.array(workflowOperationSchema).min(1).superRe
359
425
  && (typeof operation.targetLane !== "number" || operation.targetLane === 0)) {
360
426
  context.addIssue({ code: z.ZodIssueCode.custom, path: [index, "targetLane"], message: "audio requires an explicit non-primary lane" });
361
427
  }
428
+ if (operation.type === "timeline.picture-in-picture.add"
429
+ && operation.crop
430
+ && (operation.crop.left + operation.crop.right >= 1 || operation.crop.top + operation.crop.bottom >= 1)) {
431
+ context.addIssue({ code: z.ZodIssueCode.custom, path: [index, "crop"], message: "PIP crop must leave a positive source rectangle" });
432
+ }
362
433
  if (operation.type === "timeline.audio.mix"
363
434
  && operation.gainDb === undefined && operation.fadeIn === undefined && operation.fadeOut === undefined) {
364
435
  context.addIssue({ code: z.ZodIssueCode.custom, path: [index], message: "audio mix requires a gain or fade change" });
@@ -470,6 +541,37 @@ const nativeTransitionPreviewSchema = {
470
541
  afterOccurrenceHandle: z.string().min(1),
471
542
  duration: rationalTimeSchema,
472
543
  };
544
+ const nativePictureInPicturePreviewSchema = {
545
+ mediaHandle: z.string().min(1),
546
+ anchorOccurrenceHandle: z.string().min(1),
547
+ start: rationalTimeSchema,
548
+ duration: rationalTimeSchema,
549
+ position: z.object({ x: z.number().finite(), y: z.number().finite() }),
550
+ scale: z.number().finite().positive(),
551
+ crop: z.object({
552
+ top: z.number().finite().min(0).lt(1),
553
+ right: z.number().finite().min(0).lt(1),
554
+ bottom: z.number().finite().min(0).lt(1),
555
+ left: z.number().finite().min(0).lt(1),
556
+ }).optional(),
557
+ frame: z.object({
558
+ style: z.literal("solid"),
559
+ color: z.string().regex(/^#[0-9a-f]{6}$/i),
560
+ width: z.number().finite().nonnegative(),
561
+ }).optional(),
562
+ };
563
+ const nativeMaskPreviewSchema = {
564
+ occurrenceHandle: z.string().trim().min(1),
565
+ mask: nativeMaskSchema,
566
+ };
567
+ const timelineMaskInputSchema = {
568
+ projectId: z.string().trim().min(1),
569
+ sequenceId: z.string().trim().min(1),
570
+ baseRevision: revisionValueSchema,
571
+ occurrenceId: z.string().trim().min(1),
572
+ mask: maskSchema,
573
+ verification: verificationPolicySchema.optional(),
574
+ };
473
575
  const exportAssertionSchema = z.discriminatedUnion("type", [
474
576
  z.object({
475
577
  type: z.literal("audio-audibility"),
@@ -526,11 +628,83 @@ const nativeEditToolInputSchema = z.object({
526
628
  gainDb: z.number().finite().optional(),
527
629
  duration: z.number().nonnegative().optional(),
528
630
  }).strict();
631
+ const nativeOperationSessionSubmitSchema = z.object({
632
+ operation: z.literal("disposable.rename-clip"),
633
+ previewToken: z.string().trim().min(1),
634
+ projectId: z.string().trim().min(1),
635
+ sequenceId: z.string().trim().min(1),
636
+ targetIdentity: z.string().trim().min(1),
637
+ baseRevision: revisionValueSchema,
638
+ idempotencyKey: z.string().trim().min(1),
639
+ }).strict();
640
+ const nativeOperationSessionJobSchema = {
641
+ jobId: z.string().trim().min(1),
642
+ };
529
643
  function jsonResult(value) {
530
644
  return {
531
645
  content: [{ type: "text", text: JSON.stringify(value) }],
532
646
  };
533
647
  }
648
+ function capabilityErrorResult(operation, capabilityName, capability) {
649
+ return {
650
+ isError: true,
651
+ content: [{
652
+ type: "text",
653
+ text: JSON.stringify({
654
+ code: "CAPABILITY_UNAVAILABLE",
655
+ message: `${operation} requires ${capabilityName}`,
656
+ operation,
657
+ capability: capabilityName,
658
+ available: false,
659
+ backend: capability.backend,
660
+ guarantee: capability.guarantee,
661
+ unavailableReason: capability.unavailableReason,
662
+ }),
663
+ }],
664
+ };
665
+ }
666
+ function nativeMediaImportErrorResult(error) {
667
+ const serialized = serializeNativeFinalCutMediaImportError(error);
668
+ if (serialized) {
669
+ return {
670
+ isError: true,
671
+ content: [{ type: "text", text: JSON.stringify(serialized) }],
672
+ };
673
+ }
674
+ if (!isDirectoryMediaImportError(error))
675
+ throw error;
676
+ return {
677
+ isError: true,
678
+ content: [{
679
+ type: "text",
680
+ text: JSON.stringify({
681
+ code: error.code,
682
+ message: error.message,
683
+ guidance: error.guidance,
684
+ }),
685
+ }],
686
+ };
687
+ }
688
+ function capabilityUnavailableErrorResult(error) {
689
+ const serialized = serializeCapabilityUnavailableError(error);
690
+ if (!serialized)
691
+ throw error;
692
+ return {
693
+ isError: true,
694
+ content: [{ type: "text", text: JSON.stringify(serialized) }],
695
+ };
696
+ }
697
+ function isDirectoryMediaImportError(error) {
698
+ if (!error || typeof error !== "object")
699
+ return false;
700
+ const value = error;
701
+ const guidance = value.guidance;
702
+ return value.code === NATIVE_MEDIA_IMPORT_DIRECTORY_ERROR_CODE
703
+ && Boolean(guidance)
704
+ && typeof guidance === "object"
705
+ && typeof guidance.previewTool === "string"
706
+ && typeof guidance.executeTool === "string";
707
+ }
534
708
  function skillErrorResult(error) {
535
709
  const value = error && typeof error === "object" ? error : {};
536
710
  const message = error instanceof Error ? error.message : String(error);
@@ -569,10 +743,20 @@ function normalizeConnectionStatus(value) {
569
743
  const backend = typeof identity?.backend === "string" ? identity.backend : undefined;
570
744
  return {
571
745
  ...status,
572
- capabilities: withCapabilityFamilies(status.capabilities, {
746
+ capabilities: withCanonicalTimelineMode(withCapabilityFamilies(status.capabilities, {
573
747
  ...(backend ? { backend, connectionBackend: backend } : {}),
574
748
  connection: status.state === "ready",
575
- }),
749
+ })),
750
+ };
751
+ }
752
+ function nativeMediaIntentCapabilities(nativeEditor) {
753
+ const capabilities = nativeEditor?.capabilities();
754
+ return {
755
+ "native.mediaImport": Boolean(capabilities?.mediaImport),
756
+ "native.mediaSelection": Boolean(capabilities?.mediaSelection),
757
+ "native.mediaAppendSelected": Boolean(capabilities?.mediaAppendSelected),
758
+ "native.mediaAppend": Boolean(capabilities?.mediaAppend),
759
+ "native.mediaInsert": Boolean(capabilities?.mediaInsert),
576
760
  };
577
761
  }
578
762
  function isRuntimeCapabilities(value) {
@@ -606,7 +790,7 @@ export function createMcpServer(runtime, options = {}) {
606
790
  server.registerTool("connection.status", {
607
791
  description: "Read Framekit's Final Cut connection state before editor-first capability discovery.",
608
792
  inputSchema: {},
609
- }, async () => jsonResult(normalizeConnectionStatus(await connectionStatus(options))));
793
+ }, async () => jsonResult(await effectiveConnectionStatus(runtime, options)));
610
794
  server.registerTool("skill.list", {
611
795
  description: "List registered versioned Framekit Skills with current capability availability.",
612
796
  inputSchema: {},
@@ -670,22 +854,55 @@ export function createMcpServer(runtime, options = {}) {
670
854
  });
671
855
  server.registerTool("project.inspect", {
672
856
  description: "Read the current canonical project snapshot before editing.route selects a capability-checked path.",
673
- }, async () => jsonResult(await runtime.inspectProject()));
857
+ }, async () => {
858
+ const inspected = await inspectMcpEditor(runtime, options);
859
+ const capability = inspected.capabilities.families.canonicalDocument.read;
860
+ if (!capability.available) {
861
+ return capabilityErrorResult("project.inspect", "canonicalDocument.read", capability);
862
+ }
863
+ try {
864
+ return jsonResult(await runtime.inspectProject());
865
+ }
866
+ catch (error) {
867
+ return capabilityUnavailableErrorResult(error);
868
+ }
869
+ });
674
870
  server.registerTool("artifact.inspect", {
675
- description: "Identify the managed FCPXML artifact used by artifact.edit and artifact.publish.",
871
+ description: "Identify the managed FCPXML artifact used by the background artifact.edit and artifact.publish workflows.",
676
872
  inputSchema: {},
677
873
  }, async () => jsonResult(await runtime.inspectArtifact()));
678
874
  server.registerTool("project.list", {
679
875
  description: "List projects and their stable Final Cut sequence identities, including the active target.",
680
876
  inputSchema: {},
681
- }, async () => jsonResult(await runtime.listProjects()));
877
+ }, async () => {
878
+ try {
879
+ return jsonResult(await runtime.listProjects());
880
+ }
881
+ catch (error) {
882
+ const inspectionError = serializeFinalCutLibraryInspectionError(error);
883
+ if (inspectionError) {
884
+ return {
885
+ isError: true,
886
+ content: [{ type: "text", text: JSON.stringify(inspectionError) }],
887
+ };
888
+ }
889
+ return capabilityUnavailableErrorResult(error);
890
+ }
891
+ });
682
892
  server.registerTool("project.select", {
683
893
  description: "Select one project and, when it has multiple sequences, one explicit sequence; ambiguous targets fail closed.",
684
894
  inputSchema: {
685
895
  projectId: z.string().min(1),
686
896
  sequenceId: z.string().min(1).optional(),
687
897
  },
688
- }, async ({ projectId, sequenceId }) => jsonResult(await runtime.selectProject({ projectId, sequenceId })));
898
+ }, async ({ projectId, sequenceId }) => {
899
+ try {
900
+ return jsonResult(await runtime.selectProject({ projectId, sequenceId }));
901
+ }
902
+ catch (error) {
903
+ return capabilityUnavailableErrorResult(error);
904
+ }
905
+ });
689
906
  server.registerTool("editor.inspect", {
690
907
  description: "Read editor identity and machine-readable capabilities before selecting an editing path.",
691
908
  }, async () => {
@@ -705,13 +922,23 @@ export function createMcpServer(runtime, options = {}) {
705
922
  server.registerTool("editing.intent.resolve", {
706
923
  description: "Map a supported natural-language editing request to one explicit operation without executing it.",
707
924
  inputSchema: { request: z.string().trim().min(1) },
708
- }, async ({ request }) => jsonResult(resolveEditingIntent(request)));
925
+ }, async ({ request }) => jsonResult(resolveEditingIntent(request, {
926
+ availableCapabilities: nativeMediaIntentCapabilities(options.nativeEditor),
927
+ })));
709
928
  server.registerTool("editing.route", {
710
929
  description: "Resolve an editor-first path after capability checks; never bypass a connected editor, and require explicit external fallback selection.",
711
930
  inputSchema: {
712
931
  operation: z.enum([
932
+ "project.list",
933
+ "project.select",
934
+ "project.inspect",
935
+ "timeline.inspect",
936
+ "editor.live.inspect",
713
937
  "timeline.edit",
938
+ "artifact.edit",
939
+ "timeline.mask.add",
714
940
  "editor.native.edit",
941
+ "editor.native.picture-in-picture",
715
942
  "timeline.publish.new-project",
716
943
  "timeline.export",
717
944
  ]),
@@ -728,31 +955,52 @@ export function createMcpServer(runtime, options = {}) {
728
955
  server.registerTool("editor.native.inspect", {
729
956
  description: "Inspect the active Final Cut selection/playhead before a native UI edit.",
730
957
  inputSchema: {},
731
- }, async () => jsonResult(options.nativeEditor
732
- ? await options.nativeEditor.inspect()
958
+ }, async (_args, extra) => jsonResult(options.nativeEditor
959
+ ? await options.nativeEditor.inspect({ signal: extra.signal })
733
960
  : { available: false, error: { code: "CAPABILITY_UNAVAILABLE", message: "Final Cut native writes are not configured" } }));
734
961
  server.registerTool("editor.native.focus", {
735
962
  description: "Activate Final Cut Pro and focus its timeline without changing project or timeline content.",
736
963
  inputSchema: {},
737
- }, async () => jsonResult(options.nativeEditor
738
- ? await options.nativeEditor.focusTimeline()
964
+ }, async (_args, extra) => jsonResult(options.nativeEditor
965
+ ? await options.nativeEditor.focusTimeline({ signal: extra.signal })
739
966
  : { available: false, error: { code: "CAPABILITY_UNAVAILABLE", message: "Final Cut native writes are not configured" } }));
740
967
  server.registerTool("editor.native.media.import", {
741
968
  description: "Import one local video or audio file into the active Final Cut Browser and wait for a stable media handle.",
742
969
  inputSchema: { path: z.string().min(1) },
743
- }, async ({ path }) => {
970
+ }, async ({ path }, extra) => {
971
+ if (!options.nativeEditor)
972
+ throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native media import is not configured");
973
+ try {
974
+ return jsonResult(await options.nativeEditor.importMedia(path, { signal: extra.signal }));
975
+ }
976
+ catch (error) {
977
+ return nativeMediaImportErrorResult(error);
978
+ }
979
+ });
980
+ server.registerTool("editor.native.media.directory.preview", {
981
+ description: "Enumerate supported top-level video files in a local directory without mutating Final Cut and return an expiring import preview.",
982
+ inputSchema: { path: z.string().trim().min(1) },
983
+ }, async ({ path }, extra) => {
984
+ if (!options.nativeEditor)
985
+ throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native media import is not configured");
986
+ return jsonResult(await options.nativeEditor.previewImportMediaDirectory(path, { signal: extra.signal }));
987
+ });
988
+ server.registerTool("editor.native.media.directory.execute", {
989
+ description: "Import every file from a directory preview after explicit confirmation and return per-file stable media handles or failures.",
990
+ inputSchema: { previewToken: z.string().min(1), confirm: z.literal(true) },
991
+ }, async ({ previewToken, confirm }, extra) => {
744
992
  if (!options.nativeEditor)
745
993
  throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native media import is not configured");
746
- return jsonResult(await options.nativeEditor.importMedia(path));
994
+ return jsonResult(await options.nativeEditor.executeImportMediaDirectory(previewToken, confirm, { signal: extra.signal }));
747
995
  });
748
996
  server.registerTool("editor.native.edit", {
749
997
  description: "Apply a guarded native Final Cut UI edit to the active selection or playhead.",
750
998
  inputSchema: nativeEditToolInputSchema,
751
- }, async (input) => {
999
+ }, async (input, extra) => {
752
1000
  if (!options.nativeEditor)
753
1001
  throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native writes are not configured");
754
1002
  const operation = nativeEditSchema.parse(input);
755
- return jsonResult(await options.nativeEditor.edit(operation));
1003
+ return jsonResult(await options.nativeEditor.edit(operation, { signal: extra.signal }));
756
1004
  });
757
1005
  server.registerTool("editor.native.disposable.preview", {
758
1006
  description: "Preview a disposable native Final Cut rename after canonical target, revision, and native preflight checks.",
@@ -765,7 +1013,7 @@ export function createMcpServer(runtime, options = {}) {
765
1013
  server.registerTool("editor.native.disposable.execute", {
766
1014
  description: "Execute a disposable native Final Cut edit and return canonical diff, verification, and rollback state.",
767
1015
  inputSchema: { previewToken: z.string().min(1) },
768
- }, async ({ previewToken }) => {
1016
+ }, async ({ previewToken }, extra) => {
769
1017
  if (!options.disposableNative)
770
1018
  throw new Error("CAPABILITY_UNAVAILABLE: disposable native edit is not configured");
771
1019
  return jsonResult(await options.disposableNative.execute(previewToken));
@@ -778,30 +1026,80 @@ export function createMcpServer(runtime, options = {}) {
778
1026
  throw new Error("CAPABILITY_UNAVAILABLE: disposable native edit is not configured");
779
1027
  return jsonResult(await options.disposableNative.undo(operationId));
780
1028
  });
1029
+ server.registerTool("editor.native.operation.submit", {
1030
+ description: "Accept a previewed native Final Cut operation as a resumable job without waiting for headed readiness.",
1031
+ inputSchema: nativeOperationSessionSubmitSchema,
1032
+ }, async (request) => {
1033
+ if (!options.nativeOperationSession)
1034
+ throw new Error("CAPABILITY_UNAVAILABLE: native operation session is not configured");
1035
+ return jsonResult(await options.nativeOperationSession.submit(request));
1036
+ });
1037
+ server.registerTool("editor.native.operation.status", {
1038
+ description: "Poll a resumable native Final Cut operation for readiness, completion, verification, and restoration evidence.",
1039
+ inputSchema: nativeOperationSessionJobSchema,
1040
+ }, async ({ jobId }) => {
1041
+ if (!options.nativeOperationSession)
1042
+ throw new Error("CAPABILITY_UNAVAILABLE: native operation session is not configured");
1043
+ return jsonResult(options.nativeOperationSession.status(jobId));
1044
+ });
1045
+ server.registerTool("editor.native.operation.retry", {
1046
+ description: "Retry a waiting native Final Cut operation after the required headed session becomes ready.",
1047
+ inputSchema: nativeOperationSessionJobSchema,
1048
+ }, async ({ jobId }) => {
1049
+ if (!options.nativeOperationSession)
1050
+ throw new Error("CAPABILITY_UNAVAILABLE: native operation session is not configured");
1051
+ return jsonResult(await options.nativeOperationSession.retry(jobId));
1052
+ });
1053
+ server.registerTool("editor.native.operation.cancel", {
1054
+ description: "Cancel a pending native Final Cut operation or report recovery when mutation has already started.",
1055
+ inputSchema: nativeOperationSessionJobSchema,
1056
+ }, async ({ jobId }) => {
1057
+ if (!options.nativeOperationSession)
1058
+ throw new Error("CAPABILITY_UNAVAILABLE: native operation session is not configured");
1059
+ return jsonResult(await options.nativeOperationSession.cancel(jobId));
1060
+ });
781
1061
  server.registerTool("editor.native.title.add.preview", {
782
1062
  description: "Preview adding an installed Final Cut title at the live playhead or an explicit timeline range.",
783
1063
  inputSchema: nativeTitlePreviewSchema,
784
- }, async ({ assetId, text, start, duration }) => {
1064
+ }, async ({ assetId, text, start, duration }, extra) => {
785
1065
  if (!options.nativeEditor)
786
1066
  throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native title placement is not configured");
787
1067
  const asset = await resolveNativeTitleAsset(runtime, assetId);
788
- return jsonResult(await options.nativeEditor.previewTitleAdd({ asset, text, start, duration }));
1068
+ return jsonResult(await options.nativeEditor.previewTitleAdd({ asset, text, start, duration }, { signal: extra.signal }));
789
1069
  });
790
1070
  server.registerTool("editor.native.title.add.execute", {
791
1071
  description: "Execute a previously previewed native Final Cut title placement and return its verification and Undo handle.",
792
1072
  inputSchema: { previewToken: z.string().min(1) },
793
- }, async ({ previewToken }) => {
1073
+ }, async ({ previewToken }, extra) => {
794
1074
  if (!options.nativeEditor)
795
1075
  throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native title placement is not configured");
796
- return jsonResult(await options.nativeEditor.executeTitleAdd(previewToken));
1076
+ return jsonResult(await options.nativeEditor.executeTitleAdd(previewToken, { signal: extra.signal }));
1077
+ });
1078
+ server.registerTool("editor.native.picture-in-picture.preview", {
1079
+ description: "Preview connecting selected Final Cut Browser video to a stable timeline occurrence with verified transform properties.",
1080
+ inputSchema: nativePictureInPicturePreviewSchema,
1081
+ }, async (request, extra) => {
1082
+ if (!options.nativeEditor)
1083
+ throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native picture-in-picture placement is not configured");
1084
+ await requireEditingRoute(runtime, options, "editor.native.picture-in-picture");
1085
+ return jsonResult(await options.nativeEditor.previewPictureInPicture(request, { signal: extra.signal }));
1086
+ });
1087
+ server.registerTool("editor.native.picture-in-picture.execute", {
1088
+ description: "Execute a native Final Cut picture-in-picture preview and return transform readback, revision, and Undo verification.",
1089
+ inputSchema: { previewToken: z.string().min(1) },
1090
+ }, async ({ previewToken }, extra) => {
1091
+ if (!options.nativeEditor)
1092
+ throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native picture-in-picture placement is not configured");
1093
+ await requireEditingRoute(runtime, options, "editor.native.picture-in-picture");
1094
+ return jsonResult(await options.nativeEditor.executePictureInPicture(previewToken, { signal: extra.signal }));
797
1095
  });
798
1096
  server.registerTool("editor.native.transition.search", {
799
1097
  description: "Search the visible Final Cut Transitions browser and return only transitions with stable native identities.",
800
1098
  inputSchema: { query: z.string().trim().min(1) },
801
- }, async ({ query }) => {
1099
+ }, async ({ query }, extra) => {
802
1100
  if (!options.nativeEditor)
803
1101
  throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native transition discovery is not configured");
804
- const matches = await options.nativeEditor.searchTransitions(query);
1102
+ const matches = await options.nativeEditor.searchTransitions(query, { signal: extra.signal });
805
1103
  for (const match of matches) {
806
1104
  nativeTransitionAssets.set(match.id, match);
807
1105
  nativeTransitionAssets.set(`final-cut:transition:${match.identity}`, match);
@@ -811,160 +1109,220 @@ export function createMcpServer(runtime, options = {}) {
811
1109
  server.registerTool("editor.native.transition.add.preview", {
812
1110
  description: "Preview adding a discovered native transition between two adjacent occurrence handles at an exact duration.",
813
1111
  inputSchema: nativeTransitionPreviewSchema,
814
- }, async ({ assetId, beforeOccurrenceHandle, afterOccurrenceHandle, duration }) => {
1112
+ }, async ({ assetId, beforeOccurrenceHandle, afterOccurrenceHandle, duration }, extra) => {
815
1113
  if (!options.nativeEditor)
816
1114
  throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native transition placement is not configured");
817
- const asset = await resolveNativeTransitionAsset(runtime, options.nativeEditor, assetId, nativeTransitionAssets);
1115
+ const asset = await resolveNativeTransitionAsset(runtime, options.nativeEditor, assetId, nativeTransitionAssets, extra.signal);
818
1116
  return jsonResult(await options.nativeEditor.previewTransitionAdd({
819
1117
  asset,
820
1118
  beforeOccurrenceHandle,
821
1119
  afterOccurrenceHandle,
822
1120
  duration,
823
- }));
1121
+ }, { signal: extra.signal }));
824
1122
  });
825
1123
  server.registerTool("editor.native.transition.add.execute", {
826
1124
  description: "Execute a previously previewed native transition placement and return verified revision and Undo state.",
827
1125
  inputSchema: { previewToken: z.string().min(1) },
828
- }, async ({ previewToken }) => {
1126
+ }, async ({ previewToken }, extra) => {
829
1127
  if (!options.nativeEditor)
830
1128
  throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native transition placement is not configured");
831
- return jsonResult(await options.nativeEditor.executeTransitionAdd(previewToken));
1129
+ return jsonResult(await options.nativeEditor.executeTransitionAdd(previewToken, { signal: extra.signal }));
1130
+ });
1131
+ server.registerTool("editor.native.mask.preview", {
1132
+ description: "Preview adding a bounded native Final Cut Draw Mask to one located occurrence without mutating the timeline.",
1133
+ inputSchema: nativeMaskPreviewSchema,
1134
+ }, async ({ occurrenceHandle, mask }, extra) => {
1135
+ if (!options.nativeEditor)
1136
+ throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native masking is not configured");
1137
+ return jsonResult(await options.nativeEditor.previewMask({ occurrenceHandle, mask }, { signal: extra.signal }));
1138
+ });
1139
+ server.registerTool("editor.native.mask.execute", {
1140
+ description: "Execute a previously previewed native Draw Mask and return readback verification and native Undo state.",
1141
+ inputSchema: { previewToken: z.string().trim().min(1) },
1142
+ }, async ({ previewToken }, extra) => {
1143
+ if (!options.nativeEditor)
1144
+ throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native masking is not configured");
1145
+ return jsonResult(await options.nativeEditor.executeMask(previewToken, { signal: extra.signal }));
832
1146
  });
833
1147
  server.registerTool("editor.native.undo", {
834
1148
  description: "Undo a previously accepted native Final Cut UI edit using Final Cut's native Undo command.",
835
1149
  inputSchema: { operationId: z.string().min(1) },
836
- }, async ({ operationId }) => {
1150
+ }, async ({ operationId }, extra) => {
837
1151
  if (!options.nativeEditor)
838
1152
  throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native writes are not configured");
839
- return jsonResult(await options.nativeEditor.undo(operationId));
1153
+ return jsonResult(await options.nativeEditor.undo(operationId, { signal: extra.signal }));
840
1154
  });
841
1155
  server.registerTool("editor.native.media.search", {
842
1156
  description: "Search the active Final Cut Browser for live media and return short-lived media handles.",
843
1157
  inputSchema: { query: z.string().min(1) },
844
- }, async ({ query }) => {
1158
+ }, async ({ query }, extra) => {
845
1159
  if (!options.nativeEditor)
846
1160
  throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native media search is not configured");
847
- return jsonResult(await options.nativeEditor.searchMedia(query));
1161
+ return jsonResult(await options.nativeEditor.searchMedia(query, { signal: extra.signal }));
848
1162
  });
849
1163
  server.registerTool("editor.native.media.select", {
850
1164
  description: "Select one live Final Cut Browser media result using its short-lived handle.",
851
1165
  inputSchema: { mediaHandle: z.string().min(1) },
852
- }, async ({ mediaHandle }) => {
1166
+ }, async ({ mediaHandle }, extra) => {
853
1167
  if (!options.nativeEditor)
854
1168
  throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native media selection is not configured");
855
- return jsonResult(await options.nativeEditor.selectMedia(mediaHandle));
1169
+ return jsonResult(await options.nativeEditor.selectMedia(mediaHandle, { signal: extra.signal }));
856
1170
  });
857
1171
  server.registerTool("editor.native.media.append.preview", {
858
1172
  description: "Preview appending the selected Final Cut Browser media to the end of the active timeline.",
859
1173
  inputSchema: { mediaHandle: z.string().min(1) },
860
- }, async ({ mediaHandle }) => {
1174
+ }, async ({ mediaHandle }, extra) => {
861
1175
  if (!options.nativeEditor)
862
1176
  throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native media append is not configured");
863
- return jsonResult(await options.nativeEditor.previewAppendMedia(mediaHandle));
1177
+ return jsonResult(await options.nativeEditor.previewAppendMedia(mediaHandle, { signal: extra.signal }));
864
1178
  });
865
1179
  server.registerTool("editor.native.media.append.execute", {
866
1180
  description: "Execute a previously previewed append of selected Final Cut Browser media.",
867
1181
  inputSchema: { previewToken: z.string().min(1) },
868
- }, async ({ previewToken }) => {
1182
+ }, async ({ previewToken }, extra) => {
869
1183
  if (!options.nativeEditor)
870
1184
  throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native media append is not configured");
871
- return jsonResult(await options.nativeEditor.executeAppendMedia(previewToken));
1185
+ return jsonResult(await options.nativeEditor.executeAppendMedia(previewToken, { signal: extra.signal }));
872
1186
  });
873
1187
  server.registerTool("editor.native.media.append.selected.preview", {
874
1188
  description: "Preview appending the currently selected Final Cut Browser media to the end of the active timeline.",
875
1189
  inputSchema: {},
876
- }, async () => {
1190
+ }, async (_args, extra) => {
877
1191
  if (!options.nativeEditor)
878
1192
  throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native selected-media append is not configured");
879
- return jsonResult(await options.nativeEditor.previewAppendSelectedMedia());
1193
+ return jsonResult(await options.nativeEditor.previewAppendSelectedMedia({ signal: extra.signal }));
880
1194
  });
881
1195
  server.registerTool("editor.native.media.append.selected.execute", {
882
1196
  description: "Execute a previously previewed append of the currently selected Final Cut Browser media.",
883
1197
  inputSchema: { previewToken: z.string().min(1) },
884
- }, async ({ previewToken }) => {
1198
+ }, async ({ previewToken }, extra) => {
885
1199
  if (!options.nativeEditor)
886
1200
  throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native selected-media append is not configured");
887
- return jsonResult(await options.nativeEditor.executeAppendSelectedMedia(previewToken));
1201
+ return jsonResult(await options.nativeEditor.executeAppendSelectedMedia(previewToken, { signal: extra.signal }));
888
1202
  });
889
1203
  server.registerTool("editor.native.media.insert.preview", {
890
1204
  description: "Preview inserting the selected Final Cut Browser media at the current playhead.",
891
1205
  inputSchema: { mediaHandle: z.string().min(1) },
892
- }, async ({ mediaHandle }) => {
1206
+ }, async ({ mediaHandle }, extra) => {
893
1207
  if (!options.nativeEditor)
894
1208
  throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native media insert is not configured");
895
- return jsonResult(await options.nativeEditor.previewInsertMedia(mediaHandle));
1209
+ return jsonResult(await options.nativeEditor.previewInsertMedia(mediaHandle, { signal: extra.signal }));
896
1210
  });
897
1211
  server.registerTool("editor.native.media.insert.execute", {
898
1212
  description: "Execute a previously previewed insertion of selected Final Cut Browser media at the playhead.",
899
1213
  inputSchema: { previewToken: z.string().min(1) },
900
- }, async ({ previewToken }) => {
1214
+ }, async ({ previewToken }, extra) => {
901
1215
  if (!options.nativeEditor)
902
1216
  throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native media insert is not configured");
903
- return jsonResult(await options.nativeEditor.executeInsertMedia(previewToken));
1217
+ return jsonResult(await options.nativeEditor.executeInsertMedia(previewToken, { signal: extra.signal }));
904
1218
  });
905
1219
  server.registerTool("editor.native.timeline.locate", {
906
1220
  description: "Locate matching occurrences of a live Browser media result in the active Final Cut timeline.",
907
1221
  inputSchema: { mediaHandle: z.string().min(1) },
908
- }, async ({ mediaHandle }) => {
1222
+ }, async ({ mediaHandle }, extra) => {
909
1223
  if (!options.nativeEditor)
910
1224
  throw new Error("CAPABILITY_UNAVAILABLE: Final Cut timeline occurrence location is not configured");
911
- return jsonResult(await options.nativeEditor.locateOccurrence(mediaHandle));
1225
+ return jsonResult(await options.nativeEditor.locateOccurrence(mediaHandle, { signal: extra.signal }));
912
1226
  });
913
1227
  server.registerTool("editor.native.media.target", {
914
1228
  description: "Search Final Cut's Browser and target exactly one timeline occurrence with a deterministic live playhead.",
915
1229
  inputSchema: { query: z.string().min(1) },
916
- }, async ({ query }) => {
1230
+ }, async ({ query }, extra) => {
917
1231
  if (!options.nativeEditor)
918
1232
  throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native media targeting is not configured");
919
- return jsonResult(await options.nativeEditor.targetMedia(query));
1233
+ return jsonResult(await options.nativeEditor.targetMedia(query, { signal: extra.signal }));
920
1234
  });
921
1235
  server.registerTool("editor.native.blade.preview", {
922
1236
  description: "Prepare a short-lived confirmation token for a Blade-at-playhead operation.",
923
1237
  inputSchema: { occurrenceHandle: z.string().min(1) },
924
- }, async ({ occurrenceHandle }) => {
1238
+ }, async ({ occurrenceHandle }, extra) => {
925
1239
  if (!options.nativeEditor)
926
1240
  throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native Blade is not configured");
927
- return jsonResult(await options.nativeEditor.previewBlade(occurrenceHandle));
1241
+ return jsonResult(await options.nativeEditor.previewBlade(occurrenceHandle, { signal: extra.signal }));
928
1242
  });
929
1243
  server.registerTool("editor.native.blade.execute", {
930
1244
  description: "Execute a previously previewed Blade-at-playhead operation in Final Cut Pro.",
931
1245
  inputSchema: { previewToken: z.string().min(1) },
932
- }, async ({ previewToken }) => {
1246
+ }, async ({ previewToken }, extra) => {
933
1247
  if (!options.nativeEditor)
934
1248
  throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native Blade is not configured");
935
- return jsonResult(await options.nativeEditor.executeBlade(previewToken));
1249
+ return jsonResult(await options.nativeEditor.executeBlade(previewToken, { signal: extra.signal }));
936
1250
  });
937
1251
  server.registerTool("editor.native.delete-range.preview", {
938
1252
  description: "Preview a destructive ripple-delete of an explicit rational time range from the Final Cut primary storyline.",
939
1253
  inputSchema: { start: rationalTimeSchema, end: rationalTimeSchema },
940
- }, async ({ start, end }) => {
1254
+ }, async ({ start, end }, extra) => {
941
1255
  if (!options.nativeEditor)
942
1256
  throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native range deletion is not configured");
943
- return jsonResult(await options.nativeEditor.previewDeleteRange({ start, end }));
1257
+ return jsonResult(await options.nativeEditor.previewDeleteRange({ start, end }, { signal: extra.signal }));
944
1258
  });
945
1259
  server.registerTool("editor.native.delete-range.execute", {
946
1260
  description: "Execute a previously previewed primary-storyline ripple-delete range operation in Final Cut Pro.",
947
1261
  inputSchema: { previewToken: z.string().min(1) },
948
- }, async ({ previewToken }) => {
1262
+ }, async ({ previewToken }, extra) => {
949
1263
  if (!options.nativeEditor)
950
1264
  throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native range deletion is not configured");
951
- return jsonResult(await options.nativeEditor.executeDeleteRange(previewToken));
1265
+ return jsonResult(await options.nativeEditor.executeDeleteRange(previewToken, { signal: extra.signal }));
952
1266
  });
953
1267
  server.registerTool("editor.native.trim-to-duration.preview", {
954
1268
  description: "Preview a destructive operation that preserves the beginning of the Final Cut sequence and removes everything after the requested rational duration.",
955
1269
  inputSchema: { duration: rationalTimeSchema },
956
- }, async ({ duration }) => {
1270
+ }, async ({ duration }, extra) => {
957
1271
  if (!options.nativeEditor)
958
1272
  throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native duration trimming is not configured");
959
- return jsonResult(await options.nativeEditor.previewTrimToDuration(duration));
1273
+ return jsonResult(await options.nativeEditor.previewTrimToDuration(duration, { signal: extra.signal }));
960
1274
  });
961
1275
  server.registerTool("editor.native.trim-to-duration.execute", {
962
1276
  description: "Execute a previously previewed trim-to-duration operation in Final Cut Pro.",
963
1277
  inputSchema: { previewToken: z.string().min(1) },
964
- }, async ({ previewToken }) => {
1278
+ }, async ({ previewToken }, extra) => {
965
1279
  if (!options.nativeEditor)
966
1280
  throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native duration trimming is not configured");
967
- return jsonResult(await options.nativeEditor.executeTrimToDuration(previewToken));
1281
+ return jsonResult(await options.nativeEditor.executeTrimToDuration(previewToken, { signal: extra.signal }));
1282
+ });
1283
+ server.registerTool("artifact.publish.preview", {
1284
+ description: "Prepare a headed-only publish handoff for a verified FCPXML artifact without opening Final Cut.",
1285
+ inputSchema: {
1286
+ artifactPath: z.string().trim().min(1),
1287
+ transactionId: z.string().min(1),
1288
+ },
1289
+ }, async ({ artifactPath, transactionId }) => {
1290
+ if (!options.projectPublisher)
1291
+ throw new Error("CAPABILITY_UNAVAILABLE: Final Cut project publishing requires FRAMEKIT_FCPXML_PATH and native writes");
1292
+ const transaction = runtime.getTransaction(transactionId);
1293
+ if (transaction.target?.kind !== "artifact" || transaction.target.artifactPath !== artifactPath) {
1294
+ throw new Error(`PUBLISH_TARGET_MISMATCH: transaction ${transactionId} is not verified for artifact ${artifactPath}`);
1295
+ }
1296
+ if (!transaction.artifactDigest) {
1297
+ throw new Error(`PUBLISH_SOURCE_CHANGED: transaction ${transactionId} has no immutable artifact digest`);
1298
+ }
1299
+ const verification = await runtime.verifyTransaction(transactionId);
1300
+ if (!verification.passed)
1301
+ throw new Error(`FINAL_CUT_PUBLISH_VALIDATION_FAILED: source transaction ${transactionId} did not pass verification`);
1302
+ return jsonResult(await options.projectPublisher.preparePublish({
1303
+ sourceTransactionId: transactionId,
1304
+ artifactPath,
1305
+ artifactDigest: transaction.artifactDigest,
1306
+ }));
1307
+ });
1308
+ server.registerTool("artifact.publish.execute", {
1309
+ description: "Execute a prepared artifact publish job after explicit confirmation and return only a verified or resumable state.",
1310
+ inputSchema: {
1311
+ jobId: z.string().trim().min(1),
1312
+ confirm: z.literal(true),
1313
+ },
1314
+ }, async ({ jobId, confirm }) => {
1315
+ if (!options.projectPublisher)
1316
+ throw new Error("CAPABILITY_UNAVAILABLE: Final Cut project publishing requires FRAMEKIT_FCPXML_PATH and native writes");
1317
+ return jsonResult(await options.projectPublisher.executePublishJob(jobId, confirm));
1318
+ });
1319
+ server.registerTool("artifact.publish.status", {
1320
+ description: "Read the current state of a prepared artifact publish job without opening Final Cut or retrying it.",
1321
+ inputSchema: { jobId: z.string().trim().min(1) },
1322
+ }, async ({ jobId }) => {
1323
+ if (!options.projectPublisher)
1324
+ throw new Error("CAPABILITY_UNAVAILABLE: Final Cut project publishing requires FRAMEKIT_FCPXML_PATH and native writes");
1325
+ return jsonResult(options.projectPublisher.getPublishJob(jobId));
968
1326
  });
969
1327
  server.registerTool("artifact.publish", {
970
1328
  description: "Import the validated FCPXML artifact as a new Final Cut project without replacing the active project; requires explicit confirmation.",
@@ -1089,9 +1447,21 @@ export function createMcpServer(runtime, options = {}) {
1089
1447
  timestamp: new Date(sequence).toISOString(),
1090
1448
  }, waitMs ?? 0)));
1091
1449
  server.registerTool("editor.live.inspect", {
1092
- description: "Read live Final Cut Workflow Extension state: project, active sequence, playhead, and selected range.",
1450
+ description: "Read observed live Final Cut state without requiring canonical timeline snapshot capability.",
1093
1451
  inputSchema: {},
1094
- }, async () => jsonResult(await runtime.inspectLiveEditor()));
1452
+ }, async () => {
1453
+ const inspected = await inspectMcpEditor(runtime, options);
1454
+ const capability = inspected.capabilities.families.observation.timeline;
1455
+ if (!capability.available) {
1456
+ return capabilityErrorResult("editor.live.inspect", "observation.timeline", capability);
1457
+ }
1458
+ try {
1459
+ return jsonResult(await runtime.inspectLiveEditor());
1460
+ }
1461
+ catch (error) {
1462
+ return capabilityUnavailableErrorResult(error);
1463
+ }
1464
+ });
1095
1465
  server.registerTool("editor.live.changes", {
1096
1466
  description: "Read live Final Cut timeline change events after a revision; optionally wait for new events.",
1097
1467
  inputSchema: {
@@ -1104,8 +1474,20 @@ export function createMcpServer(runtime, options = {}) {
1104
1474
  timestamp: new Date(sequence).toISOString(),
1105
1475
  }, waitMs ?? 0)));
1106
1476
  server.registerTool("timeline.inspect", {
1107
- description: "Read the current canonical timeline snapshot.",
1108
- }, async () => jsonResult(await runtime.inspectTimeline()));
1477
+ description: "Read the current canonical timeline snapshot after canonical capability checks.",
1478
+ }, async () => {
1479
+ const inspected = await inspectMcpEditor(runtime, options);
1480
+ const capability = inspected.capabilities.families.canonicalDocument.read;
1481
+ if (!capability.available) {
1482
+ return capabilityErrorResult("timeline.inspect", "canonicalDocument.read", capability);
1483
+ }
1484
+ try {
1485
+ return jsonResult(await runtime.inspectTimeline());
1486
+ }
1487
+ catch (error) {
1488
+ return capabilityUnavailableErrorResult(error);
1489
+ }
1490
+ });
1109
1491
  server.registerTool("timeline.frame.capture", {
1110
1492
  description: "Capture an image at an exact timeline position with project, sequence, clip, and optional visual-analysis metadata.",
1111
1493
  inputSchema: {
@@ -1120,7 +1502,19 @@ export function createMcpServer(runtime, options = {}) {
1120
1502
  server.registerTool("media.search", {
1121
1503
  description: "Search normalized media references by id or source path.",
1122
1504
  inputSchema: { query: z.string() },
1123
- }, async ({ query }) => jsonResult(await runtime.searchMedia(query)));
1505
+ }, async ({ query }) => {
1506
+ const inspected = await inspectMcpEditor(runtime, options);
1507
+ const capability = inspected.capabilities.families.observation.media;
1508
+ if (!capability.available) {
1509
+ return capabilityErrorResult("media.search", "observation.media", capability);
1510
+ }
1511
+ try {
1512
+ return jsonResult(await runtime.searchMedia(query));
1513
+ }
1514
+ catch (error) {
1515
+ return capabilityUnavailableErrorResult(error);
1516
+ }
1517
+ });
1124
1518
  server.registerTool("media.index", {
1125
1519
  description: "Query analyzed media by semantic properties, source identity, capabilities, and usable ranges.",
1126
1520
  inputSchema: mediaIndexQuerySchema.shape,
@@ -1141,11 +1535,12 @@ export function createMcpServer(runtime, options = {}) {
1141
1535
  inputSchema: roughCutPlanSchema.shape,
1142
1536
  }, async (request) => jsonResult(await runtime.planRoughCut(request)));
1143
1537
  server.registerTool("editor.assets", {
1144
- description: "Search editor-native transitions, effects, titles, generators, and templates.",
1538
+ description: "Search installed transitions, effects, titles, generators, and templates; filesystem discovery is the default and native Browser discovery is explicit.",
1145
1539
  inputSchema: {
1146
1540
  query: z.string().optional(),
1147
1541
  kind: z.enum(["transition", "effect", "title", "generator", "audio-effect", "template"]).optional(),
1148
1542
  vendor: z.string().optional(),
1543
+ discovery: z.enum(["background", "native", "all"]).optional().default("background"),
1149
1544
  },
1150
1545
  }, async (query) => jsonResult(await runtime.listAssets(query)));
1151
1546
  server.registerTool("timeline.changes", {
@@ -1175,16 +1570,19 @@ export function createMcpServer(runtime, options = {}) {
1175
1570
  inputSchema: roughCutConstructionPlanInputSchema,
1176
1571
  }, async (request) => jsonResult(await runtime.previewRoughCutConstruction(request)));
1177
1572
  server.registerTool("artifact.edit", {
1178
- description: "Edit the identified managed FCPXML artifact and return its artifact target, new revision, read-after-write, and diff.",
1573
+ description: "Edit the identified managed FCPXML artifact in the background and return its artifact target, new revision, read-after-write, and diff.",
1179
1574
  inputSchema: artifactEditToolInputSchema,
1180
1575
  }, async (input) => {
1576
+ await requireEditingRoute(runtime, options, "artifact.edit");
1181
1577
  const { artifactPath, verification, ...operation } = input;
1182
- return jsonResult(await runtime.editArtifact(artifactPath, editOperationSchema.parse(operation), verification ?? {}));
1578
+ const transaction = await runtime.editArtifact(artifactPath, editOperationSchema.parse(operation), verification ?? {});
1579
+ return jsonResult({ ...transaction, ...withTransactionProvenance(transaction) });
1183
1580
  });
1184
1581
  server.registerTool("editor.timeline.edit", {
1185
1582
  description: "Edit the active Final Cut project and sequence identified by IDs and base revision; return the live timeline target, read-after-write, and diff.",
1186
1583
  inputSchema: editorTimelineEditToolInputSchema,
1187
1584
  }, async (input) => {
1585
+ await requireEditingRoute(runtime, options, "timeline.edit");
1188
1586
  const { projectId, sequenceId, verification, ...operation } = input;
1189
1587
  return jsonResult(await runtime.editTimeline({ projectId, sequenceId }, editOperationSchema.parse(operation), verification ?? {}));
1190
1588
  });
@@ -1211,15 +1609,29 @@ export function createMcpServer(runtime, options = {}) {
1211
1609
  await requireEditingRoute(runtime, options, "timeline.edit");
1212
1610
  return jsonResult(await runtime.previewEdit(request));
1213
1611
  });
1612
+ server.registerTool("timeline.mask.add.preview", {
1613
+ description: "Preview a bounded or supplied-alpha mask against an explicit project, sequence, revision, and occurrence without mutation.",
1614
+ inputSchema: timelineMaskInputSchema,
1615
+ }, async ({ projectId, sequenceId, baseRevision, occurrenceId, mask, verification }) => {
1616
+ await requireEditingRoute(runtime, options, "timeline.mask.add");
1617
+ return jsonResult(await runtime.previewTimelineEdit({ projectId, sequenceId }, {
1618
+ baseRevision,
1619
+ operations: [{ type: "timeline.mask.add", occurrenceId, mask }],
1620
+ ...(verification ? { verification } : {}),
1621
+ }));
1622
+ });
1214
1623
  server.registerTool("artifact.edit.preview", {
1215
- description: "Validate and preview an ordered artifact edit against the identified FCPXML artifact without mutating it.",
1624
+ description: "Validate and preview an ordered background FCPXML artifact edit without mutating it or the open Final Cut timeline.",
1216
1625
  inputSchema: {
1217
1626
  artifactPath: z.string().trim().min(1),
1218
1627
  baseRevision: revisionValueSchema,
1219
1628
  operations: workflowOperationsSchema,
1220
1629
  verification: verificationPolicySchema.optional(),
1221
1630
  },
1222
- }, async ({ artifactPath, baseRevision, operations, verification }) => jsonResult(await runtime.previewArtifactEdit(artifactPath, { baseRevision, operations, ...(verification ? { verification } : {}) })));
1631
+ }, async ({ artifactPath, baseRevision, operations, verification }) => {
1632
+ await requireEditingRoute(runtime, options, "artifact.edit");
1633
+ return jsonResult(await runtime.previewArtifactEdit(artifactPath, { baseRevision, operations, ...(verification ? { verification } : {}) }).then(withArtifactPreviewProvenance));
1634
+ });
1223
1635
  server.registerTool("editor.timeline.edit.preview", {
1224
1636
  description: "Validate and preview an ordered live timeline edit against the identified active project and sequence without mutating it.",
1225
1637
  inputSchema: {
@@ -1229,15 +1641,51 @@ export function createMcpServer(runtime, options = {}) {
1229
1641
  operations: workflowOperationsSchema,
1230
1642
  verification: verificationPolicySchema.optional(),
1231
1643
  },
1232
- }, async ({ projectId, sequenceId, baseRevision, operations, verification }) => jsonResult(await runtime.previewTimelineEdit({ projectId, sequenceId }, { baseRevision, operations, ...(verification ? { verification } : {}) })));
1644
+ }, async ({ projectId, sequenceId, baseRevision, operations, verification }) => {
1645
+ await requireEditingRoute(runtime, options, "timeline.edit");
1646
+ return jsonResult(await runtime.previewTimelineEdit({ projectId, sequenceId }, { baseRevision, operations, ...(verification ? { verification } : {}) }));
1647
+ });
1233
1648
  server.registerTool("artifact.edit.execute", {
1234
- description: "Execute one short-lived artifact edit preview token exactly once and verify the artifact transaction.",
1649
+ description: "Execute one short-lived background artifact edit preview token exactly once and verify the FCPXML artifact transaction.",
1235
1650
  inputSchema: { previewToken: z.string().min(1) },
1236
- }, async ({ previewToken }) => jsonResult(await runtime.executeEdit(previewToken)));
1651
+ }, async ({ previewToken }) => {
1652
+ await requireEditingRoute(runtime, options, "artifact.edit");
1653
+ const transaction = await runtime.executeEdit(previewToken);
1654
+ return jsonResult({ ...transaction, ...withTransactionProvenance(transaction) });
1655
+ });
1656
+ server.registerTool("artifact.edit.diff", {
1657
+ description: "Read the deterministic diff for a background FCPXML artifact transaction.",
1658
+ inputSchema: artifactTransactionInputSchema,
1659
+ }, async ({ artifactPath, transactionId }) => {
1660
+ const transaction = requireArtifactTransaction(runtime, transactionId, artifactPath);
1661
+ return jsonResult({ ...runtime.getDiff(transactionId), ...withTransactionProvenance(transaction) });
1662
+ });
1663
+ server.registerTool("artifact.edit.verify", {
1664
+ description: "Read verification checks for a background FCPXML artifact transaction.",
1665
+ inputSchema: artifactTransactionInputSchema,
1666
+ }, async ({ artifactPath, transactionId }) => {
1667
+ const transaction = requireArtifactTransaction(runtime, transactionId, artifactPath);
1668
+ return jsonResult({ ...(await runtime.verifyTransaction(transactionId)), ...withTransactionProvenance(transaction) });
1669
+ });
1670
+ server.registerTool("artifact.edit.undo", {
1671
+ description: "Restore a background FCPXML artifact transaction without changing the open Final Cut timeline.",
1672
+ inputSchema: artifactTransactionInputSchema,
1673
+ }, async ({ artifactPath, transactionId }) => {
1674
+ const transaction = requireArtifactTransaction(runtime, transactionId, artifactPath);
1675
+ const restored = await runtime.undo(transactionId);
1676
+ const artifact = await runtime.inspectArtifact();
1677
+ return jsonResult({
1678
+ ...restored,
1679
+ ...withTransactionProvenance(transaction, restored.revision, artifact.digest),
1680
+ });
1681
+ });
1237
1682
  server.registerTool("editor.timeline.edit.execute", {
1238
1683
  description: "Execute one short-lived live timeline edit preview token exactly once and verify the timeline transaction.",
1239
1684
  inputSchema: { previewToken: z.string().min(1) },
1240
- }, async ({ previewToken }) => jsonResult(await runtime.executeEdit(previewToken)));
1685
+ }, async ({ previewToken }) => {
1686
+ await requireEditingRoute(runtime, options, "timeline.edit");
1687
+ return jsonResult(await runtime.executeEdit(previewToken));
1688
+ });
1241
1689
  server.registerTool("timeline.edit.execute", {
1242
1690
  description: "Execute one short-lived composite edit preview token exactly once after editing.route capability checks, then verify the transaction.",
1243
1691
  inputSchema: { previewToken: z.string().min(1) },
@@ -1245,6 +1693,13 @@ export function createMcpServer(runtime, options = {}) {
1245
1693
  await requireEditingRoute(runtime, options, "timeline.edit");
1246
1694
  return jsonResult(await runtime.executeEdit(previewToken));
1247
1695
  });
1696
+ server.registerTool("timeline.mask.add.execute", {
1697
+ description: "Execute one short-lived mask preview token after capability and revision checks, then verify the mask state.",
1698
+ inputSchema: { previewToken: z.string().trim().min(1) },
1699
+ }, async ({ previewToken }) => {
1700
+ await requireEditingRoute(runtime, options, "timeline.mask.add");
1701
+ return jsonResult(await runtime.executeEdit(previewToken));
1702
+ });
1248
1703
  server.registerTool("speech.analyze", {
1249
1704
  description: "Analyze speech words, filler markers, and optional VAD for one media item or source range.",
1250
1705
  inputSchema: { mediaId: z.string().min(1), range: rangeSchema.optional() },
@@ -1298,18 +1753,81 @@ export function createMcpServer(runtime, options = {}) {
1298
1753
  server.registerTool("edit.diff", {
1299
1754
  description: "Read the deterministic diff for a completed edit transaction.",
1300
1755
  inputSchema: { transactionId: z.string().min(1) },
1301
- }, async ({ transactionId }) => jsonResult(runtime.getDiff(transactionId)));
1756
+ }, async ({ transactionId }) => {
1757
+ const transaction = runtime.getTransaction(transactionId);
1758
+ return jsonResult({ ...runtime.getDiff(transactionId), ...withTransactionProvenance(transaction) });
1759
+ });
1302
1760
  server.registerTool("edit.verify", {
1303
1761
  description: "Read verification checks for a completed transaction.",
1304
1762
  inputSchema: { transactionId: z.string().min(1) },
1305
- }, async ({ transactionId }) => jsonResult(await runtime.verifyTransaction(transactionId)));
1763
+ }, async ({ transactionId }) => {
1764
+ const transaction = runtime.getTransaction(transactionId);
1765
+ return jsonResult({ ...(await runtime.verifyTransaction(transactionId)), ...withTransactionProvenance(transaction) });
1766
+ });
1306
1767
  server.registerTool("edit.undo", {
1307
1768
  description: "Restore the pre-edit snapshot for a completed transaction.",
1308
1769
  inputSchema: { transactionId: z.string().min(1) },
1309
- }, async ({ transactionId }) => jsonResult(await runtime.undo(transactionId)));
1770
+ }, async ({ transactionId }) => {
1771
+ const transaction = runtime.getTransaction(transactionId);
1772
+ const restored = await runtime.undo(transactionId);
1773
+ const artifact = transaction.target?.kind === "artifact" ? await runtime.inspectArtifact() : undefined;
1774
+ return jsonResult({
1775
+ ...restored,
1776
+ ...withTransactionProvenance(transaction, restored.revision, artifact?.digest),
1777
+ });
1778
+ });
1310
1779
  installMcpSchemaCompatibility(server);
1311
1780
  return server;
1312
1781
  }
1782
+ function withTransactionProvenance(transaction, revision = transaction.after.revision, digest = transaction.artifactDigest) {
1783
+ const target = transaction.target;
1784
+ const artifact = target?.kind === "artifact"
1785
+ ? {
1786
+ mode: "background-artifact",
1787
+ path: target.artifactPath,
1788
+ revisionScope: "artifact",
1789
+ revision: structuredClone(revision),
1790
+ ...(digest ? { digest } : {}),
1791
+ mutatesOpenTimeline: false,
1792
+ }
1793
+ : undefined;
1794
+ return {
1795
+ ...(target ? { target: structuredClone(target) } : {}),
1796
+ ...(artifact ? { artifact } : {}),
1797
+ provenance: {
1798
+ surface: target?.kind === "artifact" ? "artifact" : "live-timeline",
1799
+ revisionScope: target?.kind === "artifact" ? "artifact" : "live-timeline",
1800
+ revision: structuredClone(revision),
1801
+ ...(target?.kind === "artifact" && digest ? { digest } : {}),
1802
+ mutatesOpenTimeline: target?.kind !== "artifact",
1803
+ },
1804
+ };
1805
+ }
1806
+ function withArtifactPreviewProvenance(preview) {
1807
+ const target = preview.target;
1808
+ if (target.kind !== "artifact") {
1809
+ throw new Error("INVALID_ARTIFACT_TARGET: preview is not bound to an artifact");
1810
+ }
1811
+ const artifact = {
1812
+ mode: "background-artifact",
1813
+ path: target.artifactPath,
1814
+ revisionScope: "artifact",
1815
+ revision: structuredClone(preview.baseRevision),
1816
+ ...(preview.artifactDigest ? { digest: preview.artifactDigest } : {}),
1817
+ mutatesOpenTimeline: false,
1818
+ };
1819
+ return {
1820
+ ...preview,
1821
+ artifact,
1822
+ provenance: {
1823
+ surface: "artifact",
1824
+ revisionScope: "artifact",
1825
+ revision: structuredClone(preview.baseRevision),
1826
+ ...(preview.artifactDigest ? { digest: preview.artifactDigest } : {}),
1827
+ mutatesOpenTimeline: false,
1828
+ },
1829
+ };
1830
+ }
1313
1831
  async function resolveNativeTitleAsset(runtime, assetId) {
1314
1832
  const assets = await runtime.listAssets();
1315
1833
  const asset = assets.find((candidate) => candidate.id === assetId);
@@ -1319,7 +1837,7 @@ async function resolveNativeTitleAsset(runtime, assetId) {
1319
1837
  throw new Error(`TITLE_ASSET_INCOMPATIBLE: ${assetId} is not an installed Final Cut title asset`);
1320
1838
  return asset;
1321
1839
  }
1322
- async function resolveNativeTransitionAsset(runtime, nativeEditor, assetId, nativeTransitionAssets = new Map()) {
1840
+ async function resolveNativeTransitionAsset(runtime, nativeEditor, assetId, nativeTransitionAssets = new Map(), signal) {
1323
1841
  const cachedAsset = nativeTransitionAssets.get(assetId);
1324
1842
  if (cachedAsset)
1325
1843
  return cachedAsset;
@@ -1336,7 +1854,7 @@ async function resolveNativeTransitionAsset(runtime, nativeEditor, assetId, nati
1336
1854
  // transition placement must use the stable identity returned by Final Cut's
1337
1855
  // Transitions browser. Resolve registry assets back through native discovery
1338
1856
  // instead of fabricating a native identity from the registry id.
1339
- const nativeMatches = await nativeEditor.searchTransitions(asset?.name ?? assetId);
1857
+ const nativeMatches = await nativeEditor.searchTransitions(asset?.name ?? assetId, { signal });
1340
1858
  const matchingNativeMatches = asset
1341
1859
  ? nativeMatches.filter((candidate) => candidate.name === asset.name)
1342
1860
  : nativeMatches.filter((candidate) => candidate.id === assetId || candidate.identity === assetId);
@@ -1357,18 +1875,52 @@ async function connectionStatus(options) {
1357
1875
  capabilities: null,
1358
1876
  };
1359
1877
  }
1878
+ async function effectiveConnectionStatus(runtime, options) {
1879
+ const status = await connectionStatus(options);
1880
+ const hasConnectionCapabilities = isRuntimeCapabilities(status.capabilities);
1881
+ if (status.state !== "ready" || (options.connectionStatus && !hasConnectionCapabilities)) {
1882
+ return normalizeConnectionStatus(status);
1883
+ }
1884
+ try {
1885
+ const inspected = await inspectMcpEditor(runtime, options);
1886
+ return {
1887
+ ...status,
1888
+ identity: inspected.identity,
1889
+ capabilities: inspected.capabilities,
1890
+ preflight: inspected.preflight,
1891
+ };
1892
+ }
1893
+ catch (error) {
1894
+ const message = error instanceof Error ? error.message : String(error);
1895
+ return normalizeConnectionStatus({
1896
+ ...status,
1897
+ state: "unavailable",
1898
+ lastError: {
1899
+ code: "CAPABILITY_UNAVAILABLE",
1900
+ message: `effective runtime capability inspection failed: ${message}`,
1901
+ },
1902
+ identity: undefined,
1903
+ capabilities: undefined,
1904
+ preflight: undefined,
1905
+ });
1906
+ }
1907
+ }
1360
1908
  async function inspectMcpEditor(runtime, options) {
1361
1909
  const inspected = await runtime.inspectEditor();
1362
1910
  const native = options.nativeEditor?.capabilities();
1363
1911
  const publishingAvailable = Boolean(options.projectPublisher && (typeof options.projectPublisher.isAvailable !== "function" || options.projectPublisher.isAvailable()));
1364
1912
  const exportAvailable = Boolean(options.videoExporter?.isAvailable());
1913
+ const backgroundExportAvailable = Boolean(options.backgroundRenderer?.isAvailable());
1365
1914
  const capabilities = withCapabilityFamilies({
1366
1915
  ...inspected.capabilities,
1367
1916
  editor: {
1368
1917
  ...inspected.capabilities.editor,
1369
1918
  artifactPublish: publishingAvailable,
1919
+ artifactPublishMode: publishingAvailable ? "headed-only" : "unavailable",
1370
1920
  ...(publishingAvailable ? {} : { timelinePublishNewProject: false }),
1371
1921
  videoExport: exportAvailable,
1922
+ backgroundRender: backgroundExportAvailable,
1923
+ externalRender: false,
1372
1924
  },
1373
1925
  }, {
1374
1926
  backend: inspected.identity.backend,
@@ -1387,8 +1939,11 @@ async function inspectMcpEditor(runtime, options) {
1387
1939
  mediaAppend: Boolean(native?.mediaAppend),
1388
1940
  mediaInsert: Boolean(native?.mediaInsert),
1389
1941
  titlePlacement: Boolean(native?.titlePlacement),
1942
+ titleDiscovery: Boolean(native?.titleDiscovery),
1943
+ pictureInPicture: Boolean(native?.pictureInPicture),
1390
1944
  transitionDiscovery: Boolean(native?.transitionDiscovery),
1391
1945
  transitionPlacement: Boolean(native?.transitionPlacement),
1946
+ masking: Boolean(native?.masking),
1392
1947
  timelineFocus: Boolean(native?.timelineFocus),
1393
1948
  projectCreation: false,
1394
1949
  clipInsertion: false,
@@ -1398,17 +1953,50 @@ async function inspectMcpEditor(runtime, options) {
1398
1953
  publishingBackend: "fcpxml-publisher",
1399
1954
  export: exportAvailable,
1400
1955
  exportBackend: "final-cut-native-export",
1956
+ backgroundExport: {
1957
+ available: backgroundExportAvailable,
1958
+ backend: "external-renderer",
1959
+ guarantee: backgroundExportAvailable ? "verified" : "none",
1960
+ ...(backgroundExportAvailable ? { evidenceTier: "artifact-rendered" } : { unavailableReason: "background rendering is unavailable" }),
1961
+ },
1962
+ backgroundExportBackend: "external-renderer",
1963
+ externalExport: {
1964
+ available: false,
1965
+ backend: "external-renderer",
1966
+ guarantee: "none",
1967
+ unavailableReason: "external rendering is unavailable",
1968
+ },
1969
+ externalExportBackend: "external-renderer",
1401
1970
  });
1402
1971
  return {
1403
1972
  ...inspected,
1404
1973
  capabilities,
1405
- preflight: createCapabilityPreflight(inspected.identity, capabilities, {
1406
- processMode: options.processMode ?? (native ? "headed" : "headless"),
1407
- nativeWrite: Boolean(native?.selectionEdit),
1408
- }),
1974
+ workflows: {
1975
+ artifact: {
1976
+ mode: "background-artifact",
1977
+ tools: [...BACKGROUND_ARTIFACT_WORKFLOW],
1978
+ requiresFinalCutFrontmost: false,
1979
+ changesOpenTimeline: false,
1980
+ },
1981
+ },
1982
+ preflight: {
1983
+ ...createCapabilityPreflight(inspected.identity, capabilities, {
1984
+ processMode: options.processMode ?? (native ? "headed" : "headless"),
1985
+ nativeWrite: Boolean(native?.selectionEdit),
1986
+ }),
1987
+ fingerprint: options.buildFingerprint ?? FRAMEKIT_BUILD_FINGERPRINT,
1988
+ },
1409
1989
  ...(native ? { native } : {}),
1410
1990
  };
1411
1991
  }
1992
+ function requireArtifactTransaction(runtime, transactionId, artifactPath) {
1993
+ const transaction = runtime.getTransaction(transactionId);
1994
+ const target = transaction.target;
1995
+ if (target?.kind !== "artifact" || resolvePath(target.artifactPath) !== resolvePath(artifactPath.trim())) {
1996
+ throw new Error(`TARGET_MISMATCH: transaction ${transactionId} is not bound to artifact ${artifactPath}`);
1997
+ }
1998
+ return transaction;
1999
+ }
1412
2000
  async function requireEditingRoute(runtime, options, operation) {
1413
2001
  const route = resolveEditingRoute({ operation }, await editingRouteContext(runtime, options));
1414
2002
  if (route.status !== "editor-selected") {
@@ -1416,7 +2004,7 @@ async function requireEditingRoute(runtime, options, operation) {
1416
2004
  }
1417
2005
  }
1418
2006
  async function editingRouteContext(runtime, options) {
1419
- const connection = await connectionStatus(options);
2007
+ const connection = await effectiveConnectionStatus(runtime, options);
1420
2008
  let editor;
1421
2009
  try {
1422
2010
  editor = await inspectMcpEditor(runtime, options);