@morshoto/framekit 0.1.6 → 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 (33) hide show
  1. package/bin/framekit.mjs +2 -1
  2. package/dist-package/adapters/final-cut/typescript/src/assets.js +157 -35
  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 +189 -32
  5. package/dist-package/adapters/final-cut/typescript/src/connection.js +3 -3
  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 +615 -49
  8. package/dist-package/adapters/final-cut/typescript/src/index.js +4 -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 +1192 -364
  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 +26 -7
  17. package/dist-package/apps/mcp-server/src/routing.js +227 -39
  18. package/dist-package/apps/mcp-server/src/server.js +532 -97
  19. package/dist-package/apps/mcp-server/src/version.js +109 -1
  20. package/dist-package/packages/runtime/src/application/media-analysis-service.js +1 -3
  21. package/dist-package/packages/runtime/src/application/project-service.js +46 -7
  22. package/dist-package/packages/runtime/src/capabilities.js +55 -7
  23. package/dist-package/packages/runtime/src/context/project-catalog.js +159 -0
  24. package/dist-package/packages/runtime/src/domain/capabilities.js +33 -0
  25. package/dist-package/packages/runtime/src/domain/context.js +14 -1
  26. package/dist-package/packages/runtime/src/domain/index.js +1 -0
  27. package/dist-package/packages/runtime/src/domain/timeline-target.js +217 -0
  28. package/dist-package/packages/runtime/src/editing/edit-service.js +15 -1
  29. package/dist-package/packages/runtime/src/editing/intent.js +178 -2
  30. package/dist-package/packages/runtime/src/index.js +1 -0
  31. package/dist-package/packages/runtime/src/runtime.js +2 -2
  32. package/dist-package/packages/testkit/src/in-memory-editor.js +5 -4
  33. package/package.json +7 -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(),
@@ -298,6 +300,10 @@ const artifactPublishInputSchema = z.object({
298
300
  transactionId: z.string().min(1),
299
301
  confirm: z.boolean(),
300
302
  }).strict();
303
+ const artifactTransactionInputSchema = z.object({
304
+ artifactPath: z.string().trim().min(1),
305
+ transactionId: z.string().min(1),
306
+ }).strict();
301
307
  const workflowOperationSchema = z.discriminatedUnion("type", [
302
308
  renameClipSchema,
303
309
  trimClipSchema,
@@ -622,11 +628,83 @@ const nativeEditToolInputSchema = z.object({
622
628
  gainDb: z.number().finite().optional(),
623
629
  duration: z.number().nonnegative().optional(),
624
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
+ };
625
643
  function jsonResult(value) {
626
644
  return {
627
645
  content: [{ type: "text", text: JSON.stringify(value) }],
628
646
  };
629
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
+ }
630
708
  function skillErrorResult(error) {
631
709
  const value = error && typeof error === "object" ? error : {};
632
710
  const message = error instanceof Error ? error.message : String(error);
@@ -665,10 +743,20 @@ function normalizeConnectionStatus(value) {
665
743
  const backend = typeof identity?.backend === "string" ? identity.backend : undefined;
666
744
  return {
667
745
  ...status,
668
- capabilities: withCapabilityFamilies(status.capabilities, {
746
+ capabilities: withCanonicalTimelineMode(withCapabilityFamilies(status.capabilities, {
669
747
  ...(backend ? { backend, connectionBackend: backend } : {}),
670
748
  connection: status.state === "ready",
671
- }),
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),
672
760
  };
673
761
  }
674
762
  function isRuntimeCapabilities(value) {
@@ -702,7 +790,7 @@ export function createMcpServer(runtime, options = {}) {
702
790
  server.registerTool("connection.status", {
703
791
  description: "Read Framekit's Final Cut connection state before editor-first capability discovery.",
704
792
  inputSchema: {},
705
- }, async () => jsonResult(normalizeConnectionStatus(await connectionStatus(options))));
793
+ }, async () => jsonResult(await effectiveConnectionStatus(runtime, options)));
706
794
  server.registerTool("skill.list", {
707
795
  description: "List registered versioned Framekit Skills with current capability availability.",
708
796
  inputSchema: {},
@@ -766,22 +854,55 @@ export function createMcpServer(runtime, options = {}) {
766
854
  });
767
855
  server.registerTool("project.inspect", {
768
856
  description: "Read the current canonical project snapshot before editing.route selects a capability-checked path.",
769
- }, 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
+ });
770
870
  server.registerTool("artifact.inspect", {
771
- 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.",
772
872
  inputSchema: {},
773
873
  }, async () => jsonResult(await runtime.inspectArtifact()));
774
874
  server.registerTool("project.list", {
775
875
  description: "List projects and their stable Final Cut sequence identities, including the active target.",
776
876
  inputSchema: {},
777
- }, 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
+ });
778
892
  server.registerTool("project.select", {
779
893
  description: "Select one project and, when it has multiple sequences, one explicit sequence; ambiguous targets fail closed.",
780
894
  inputSchema: {
781
895
  projectId: z.string().min(1),
782
896
  sequenceId: z.string().min(1).optional(),
783
897
  },
784
- }, 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
+ });
785
906
  server.registerTool("editor.inspect", {
786
907
  description: "Read editor identity and machine-readable capabilities before selecting an editing path.",
787
908
  }, async () => {
@@ -801,12 +922,20 @@ export function createMcpServer(runtime, options = {}) {
801
922
  server.registerTool("editing.intent.resolve", {
802
923
  description: "Map a supported natural-language editing request to one explicit operation without executing it.",
803
924
  inputSchema: { request: z.string().trim().min(1) },
804
- }, async ({ request }) => jsonResult(resolveEditingIntent(request)));
925
+ }, async ({ request }) => jsonResult(resolveEditingIntent(request, {
926
+ availableCapabilities: nativeMediaIntentCapabilities(options.nativeEditor),
927
+ })));
805
928
  server.registerTool("editing.route", {
806
929
  description: "Resolve an editor-first path after capability checks; never bypass a connected editor, and require explicit external fallback selection.",
807
930
  inputSchema: {
808
931
  operation: z.enum([
932
+ "project.list",
933
+ "project.select",
934
+ "project.inspect",
935
+ "timeline.inspect",
936
+ "editor.live.inspect",
809
937
  "timeline.edit",
938
+ "artifact.edit",
810
939
  "timeline.mask.add",
811
940
  "editor.native.edit",
812
941
  "editor.native.picture-in-picture",
@@ -826,31 +955,52 @@ export function createMcpServer(runtime, options = {}) {
826
955
  server.registerTool("editor.native.inspect", {
827
956
  description: "Inspect the active Final Cut selection/playhead before a native UI edit.",
828
957
  inputSchema: {},
829
- }, async () => jsonResult(options.nativeEditor
830
- ? await options.nativeEditor.inspect()
958
+ }, async (_args, extra) => jsonResult(options.nativeEditor
959
+ ? await options.nativeEditor.inspect({ signal: extra.signal })
831
960
  : { available: false, error: { code: "CAPABILITY_UNAVAILABLE", message: "Final Cut native writes are not configured" } }));
832
961
  server.registerTool("editor.native.focus", {
833
962
  description: "Activate Final Cut Pro and focus its timeline without changing project or timeline content.",
834
963
  inputSchema: {},
835
- }, async () => jsonResult(options.nativeEditor
836
- ? await options.nativeEditor.focusTimeline()
964
+ }, async (_args, extra) => jsonResult(options.nativeEditor
965
+ ? await options.nativeEditor.focusTimeline({ signal: extra.signal })
837
966
  : { available: false, error: { code: "CAPABILITY_UNAVAILABLE", message: "Final Cut native writes are not configured" } }));
838
967
  server.registerTool("editor.native.media.import", {
839
968
  description: "Import one local video or audio file into the active Final Cut Browser and wait for a stable media handle.",
840
969
  inputSchema: { path: z.string().min(1) },
841
- }, 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) => {
842
984
  if (!options.nativeEditor)
843
985
  throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native media import is not configured");
844
- return jsonResult(await options.nativeEditor.importMedia(path));
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) => {
992
+ if (!options.nativeEditor)
993
+ throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native media import is not configured");
994
+ return jsonResult(await options.nativeEditor.executeImportMediaDirectory(previewToken, confirm, { signal: extra.signal }));
845
995
  });
846
996
  server.registerTool("editor.native.edit", {
847
997
  description: "Apply a guarded native Final Cut UI edit to the active selection or playhead.",
848
998
  inputSchema: nativeEditToolInputSchema,
849
- }, async (input) => {
999
+ }, async (input, extra) => {
850
1000
  if (!options.nativeEditor)
851
1001
  throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native writes are not configured");
852
1002
  const operation = nativeEditSchema.parse(input);
853
- return jsonResult(await options.nativeEditor.edit(operation));
1003
+ return jsonResult(await options.nativeEditor.edit(operation, { signal: extra.signal }));
854
1004
  });
855
1005
  server.registerTool("editor.native.disposable.preview", {
856
1006
  description: "Preview a disposable native Final Cut rename after canonical target, revision, and native preflight checks.",
@@ -863,7 +1013,7 @@ export function createMcpServer(runtime, options = {}) {
863
1013
  server.registerTool("editor.native.disposable.execute", {
864
1014
  description: "Execute a disposable native Final Cut edit and return canonical diff, verification, and rollback state.",
865
1015
  inputSchema: { previewToken: z.string().min(1) },
866
- }, async ({ previewToken }) => {
1016
+ }, async ({ previewToken }, extra) => {
867
1017
  if (!options.disposableNative)
868
1018
  throw new Error("CAPABILITY_UNAVAILABLE: disposable native edit is not configured");
869
1019
  return jsonResult(await options.disposableNative.execute(previewToken));
@@ -876,48 +1026,80 @@ export function createMcpServer(runtime, options = {}) {
876
1026
  throw new Error("CAPABILITY_UNAVAILABLE: disposable native edit is not configured");
877
1027
  return jsonResult(await options.disposableNative.undo(operationId));
878
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
+ });
879
1061
  server.registerTool("editor.native.title.add.preview", {
880
1062
  description: "Preview adding an installed Final Cut title at the live playhead or an explicit timeline range.",
881
1063
  inputSchema: nativeTitlePreviewSchema,
882
- }, async ({ assetId, text, start, duration }) => {
1064
+ }, async ({ assetId, text, start, duration }, extra) => {
883
1065
  if (!options.nativeEditor)
884
1066
  throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native title placement is not configured");
885
1067
  const asset = await resolveNativeTitleAsset(runtime, assetId);
886
- return jsonResult(await options.nativeEditor.previewTitleAdd({ asset, text, start, duration }));
1068
+ return jsonResult(await options.nativeEditor.previewTitleAdd({ asset, text, start, duration }, { signal: extra.signal }));
887
1069
  });
888
1070
  server.registerTool("editor.native.title.add.execute", {
889
1071
  description: "Execute a previously previewed native Final Cut title placement and return its verification and Undo handle.",
890
1072
  inputSchema: { previewToken: z.string().min(1) },
891
- }, async ({ previewToken }) => {
1073
+ }, async ({ previewToken }, extra) => {
892
1074
  if (!options.nativeEditor)
893
1075
  throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native title placement is not configured");
894
- return jsonResult(await options.nativeEditor.executeTitleAdd(previewToken));
1076
+ return jsonResult(await options.nativeEditor.executeTitleAdd(previewToken, { signal: extra.signal }));
895
1077
  });
896
1078
  server.registerTool("editor.native.picture-in-picture.preview", {
897
1079
  description: "Preview connecting selected Final Cut Browser video to a stable timeline occurrence with verified transform properties.",
898
1080
  inputSchema: nativePictureInPicturePreviewSchema,
899
- }, async (request) => {
1081
+ }, async (request, extra) => {
900
1082
  if (!options.nativeEditor)
901
1083
  throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native picture-in-picture placement is not configured");
902
1084
  await requireEditingRoute(runtime, options, "editor.native.picture-in-picture");
903
- return jsonResult(await options.nativeEditor.previewPictureInPicture(request));
1085
+ return jsonResult(await options.nativeEditor.previewPictureInPicture(request, { signal: extra.signal }));
904
1086
  });
905
1087
  server.registerTool("editor.native.picture-in-picture.execute", {
906
1088
  description: "Execute a native Final Cut picture-in-picture preview and return transform readback, revision, and Undo verification.",
907
1089
  inputSchema: { previewToken: z.string().min(1) },
908
- }, async ({ previewToken }) => {
1090
+ }, async ({ previewToken }, extra) => {
909
1091
  if (!options.nativeEditor)
910
1092
  throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native picture-in-picture placement is not configured");
911
1093
  await requireEditingRoute(runtime, options, "editor.native.picture-in-picture");
912
- return jsonResult(await options.nativeEditor.executePictureInPicture(previewToken));
1094
+ return jsonResult(await options.nativeEditor.executePictureInPicture(previewToken, { signal: extra.signal }));
913
1095
  });
914
1096
  server.registerTool("editor.native.transition.search", {
915
1097
  description: "Search the visible Final Cut Transitions browser and return only transitions with stable native identities.",
916
1098
  inputSchema: { query: z.string().trim().min(1) },
917
- }, async ({ query }) => {
1099
+ }, async ({ query }, extra) => {
918
1100
  if (!options.nativeEditor)
919
1101
  throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native transition discovery is not configured");
920
- const matches = await options.nativeEditor.searchTransitions(query);
1102
+ const matches = await options.nativeEditor.searchTransitions(query, { signal: extra.signal });
921
1103
  for (const match of matches) {
922
1104
  nativeTransitionAssets.set(match.id, match);
923
1105
  nativeTransitionAssets.set(`final-cut:transition:${match.identity}`, match);
@@ -927,176 +1109,220 @@ export function createMcpServer(runtime, options = {}) {
927
1109
  server.registerTool("editor.native.transition.add.preview", {
928
1110
  description: "Preview adding a discovered native transition between two adjacent occurrence handles at an exact duration.",
929
1111
  inputSchema: nativeTransitionPreviewSchema,
930
- }, async ({ assetId, beforeOccurrenceHandle, afterOccurrenceHandle, duration }) => {
1112
+ }, async ({ assetId, beforeOccurrenceHandle, afterOccurrenceHandle, duration }, extra) => {
931
1113
  if (!options.nativeEditor)
932
1114
  throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native transition placement is not configured");
933
- const asset = await resolveNativeTransitionAsset(runtime, options.nativeEditor, assetId, nativeTransitionAssets);
1115
+ const asset = await resolveNativeTransitionAsset(runtime, options.nativeEditor, assetId, nativeTransitionAssets, extra.signal);
934
1116
  return jsonResult(await options.nativeEditor.previewTransitionAdd({
935
1117
  asset,
936
1118
  beforeOccurrenceHandle,
937
1119
  afterOccurrenceHandle,
938
1120
  duration,
939
- }));
1121
+ }, { signal: extra.signal }));
940
1122
  });
941
1123
  server.registerTool("editor.native.transition.add.execute", {
942
1124
  description: "Execute a previously previewed native transition placement and return verified revision and Undo state.",
943
1125
  inputSchema: { previewToken: z.string().min(1) },
944
- }, async ({ previewToken }) => {
1126
+ }, async ({ previewToken }, extra) => {
945
1127
  if (!options.nativeEditor)
946
1128
  throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native transition placement is not configured");
947
- return jsonResult(await options.nativeEditor.executeTransitionAdd(previewToken));
1129
+ return jsonResult(await options.nativeEditor.executeTransitionAdd(previewToken, { signal: extra.signal }));
948
1130
  });
949
1131
  server.registerTool("editor.native.mask.preview", {
950
1132
  description: "Preview adding a bounded native Final Cut Draw Mask to one located occurrence without mutating the timeline.",
951
1133
  inputSchema: nativeMaskPreviewSchema,
952
- }, async ({ occurrenceHandle, mask }) => {
1134
+ }, async ({ occurrenceHandle, mask }, extra) => {
953
1135
  if (!options.nativeEditor)
954
1136
  throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native masking is not configured");
955
- return jsonResult(await options.nativeEditor.previewMask({ occurrenceHandle, mask }));
1137
+ return jsonResult(await options.nativeEditor.previewMask({ occurrenceHandle, mask }, { signal: extra.signal }));
956
1138
  });
957
1139
  server.registerTool("editor.native.mask.execute", {
958
1140
  description: "Execute a previously previewed native Draw Mask and return readback verification and native Undo state.",
959
1141
  inputSchema: { previewToken: z.string().trim().min(1) },
960
- }, async ({ previewToken }) => {
1142
+ }, async ({ previewToken }, extra) => {
961
1143
  if (!options.nativeEditor)
962
1144
  throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native masking is not configured");
963
- return jsonResult(await options.nativeEditor.executeMask(previewToken));
1145
+ return jsonResult(await options.nativeEditor.executeMask(previewToken, { signal: extra.signal }));
964
1146
  });
965
1147
  server.registerTool("editor.native.undo", {
966
1148
  description: "Undo a previously accepted native Final Cut UI edit using Final Cut's native Undo command.",
967
1149
  inputSchema: { operationId: z.string().min(1) },
968
- }, async ({ operationId }) => {
1150
+ }, async ({ operationId }, extra) => {
969
1151
  if (!options.nativeEditor)
970
1152
  throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native writes are not configured");
971
- return jsonResult(await options.nativeEditor.undo(operationId));
1153
+ return jsonResult(await options.nativeEditor.undo(operationId, { signal: extra.signal }));
972
1154
  });
973
1155
  server.registerTool("editor.native.media.search", {
974
1156
  description: "Search the active Final Cut Browser for live media and return short-lived media handles.",
975
1157
  inputSchema: { query: z.string().min(1) },
976
- }, async ({ query }) => {
1158
+ }, async ({ query }, extra) => {
977
1159
  if (!options.nativeEditor)
978
1160
  throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native media search is not configured");
979
- return jsonResult(await options.nativeEditor.searchMedia(query));
1161
+ return jsonResult(await options.nativeEditor.searchMedia(query, { signal: extra.signal }));
980
1162
  });
981
1163
  server.registerTool("editor.native.media.select", {
982
1164
  description: "Select one live Final Cut Browser media result using its short-lived handle.",
983
1165
  inputSchema: { mediaHandle: z.string().min(1) },
984
- }, async ({ mediaHandle }) => {
1166
+ }, async ({ mediaHandle }, extra) => {
985
1167
  if (!options.nativeEditor)
986
1168
  throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native media selection is not configured");
987
- return jsonResult(await options.nativeEditor.selectMedia(mediaHandle));
1169
+ return jsonResult(await options.nativeEditor.selectMedia(mediaHandle, { signal: extra.signal }));
988
1170
  });
989
1171
  server.registerTool("editor.native.media.append.preview", {
990
1172
  description: "Preview appending the selected Final Cut Browser media to the end of the active timeline.",
991
1173
  inputSchema: { mediaHandle: z.string().min(1) },
992
- }, async ({ mediaHandle }) => {
1174
+ }, async ({ mediaHandle }, extra) => {
993
1175
  if (!options.nativeEditor)
994
1176
  throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native media append is not configured");
995
- return jsonResult(await options.nativeEditor.previewAppendMedia(mediaHandle));
1177
+ return jsonResult(await options.nativeEditor.previewAppendMedia(mediaHandle, { signal: extra.signal }));
996
1178
  });
997
1179
  server.registerTool("editor.native.media.append.execute", {
998
1180
  description: "Execute a previously previewed append of selected Final Cut Browser media.",
999
1181
  inputSchema: { previewToken: z.string().min(1) },
1000
- }, async ({ previewToken }) => {
1182
+ }, async ({ previewToken }, extra) => {
1001
1183
  if (!options.nativeEditor)
1002
1184
  throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native media append is not configured");
1003
- return jsonResult(await options.nativeEditor.executeAppendMedia(previewToken));
1185
+ return jsonResult(await options.nativeEditor.executeAppendMedia(previewToken, { signal: extra.signal }));
1004
1186
  });
1005
1187
  server.registerTool("editor.native.media.append.selected.preview", {
1006
1188
  description: "Preview appending the currently selected Final Cut Browser media to the end of the active timeline.",
1007
1189
  inputSchema: {},
1008
- }, async () => {
1190
+ }, async (_args, extra) => {
1009
1191
  if (!options.nativeEditor)
1010
1192
  throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native selected-media append is not configured");
1011
- return jsonResult(await options.nativeEditor.previewAppendSelectedMedia());
1193
+ return jsonResult(await options.nativeEditor.previewAppendSelectedMedia({ signal: extra.signal }));
1012
1194
  });
1013
1195
  server.registerTool("editor.native.media.append.selected.execute", {
1014
1196
  description: "Execute a previously previewed append of the currently selected Final Cut Browser media.",
1015
1197
  inputSchema: { previewToken: z.string().min(1) },
1016
- }, async ({ previewToken }) => {
1198
+ }, async ({ previewToken }, extra) => {
1017
1199
  if (!options.nativeEditor)
1018
1200
  throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native selected-media append is not configured");
1019
- return jsonResult(await options.nativeEditor.executeAppendSelectedMedia(previewToken));
1201
+ return jsonResult(await options.nativeEditor.executeAppendSelectedMedia(previewToken, { signal: extra.signal }));
1020
1202
  });
1021
1203
  server.registerTool("editor.native.media.insert.preview", {
1022
1204
  description: "Preview inserting the selected Final Cut Browser media at the current playhead.",
1023
1205
  inputSchema: { mediaHandle: z.string().min(1) },
1024
- }, async ({ mediaHandle }) => {
1206
+ }, async ({ mediaHandle }, extra) => {
1025
1207
  if (!options.nativeEditor)
1026
1208
  throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native media insert is not configured");
1027
- return jsonResult(await options.nativeEditor.previewInsertMedia(mediaHandle));
1209
+ return jsonResult(await options.nativeEditor.previewInsertMedia(mediaHandle, { signal: extra.signal }));
1028
1210
  });
1029
1211
  server.registerTool("editor.native.media.insert.execute", {
1030
1212
  description: "Execute a previously previewed insertion of selected Final Cut Browser media at the playhead.",
1031
1213
  inputSchema: { previewToken: z.string().min(1) },
1032
- }, async ({ previewToken }) => {
1214
+ }, async ({ previewToken }, extra) => {
1033
1215
  if (!options.nativeEditor)
1034
1216
  throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native media insert is not configured");
1035
- return jsonResult(await options.nativeEditor.executeInsertMedia(previewToken));
1217
+ return jsonResult(await options.nativeEditor.executeInsertMedia(previewToken, { signal: extra.signal }));
1036
1218
  });
1037
1219
  server.registerTool("editor.native.timeline.locate", {
1038
1220
  description: "Locate matching occurrences of a live Browser media result in the active Final Cut timeline.",
1039
1221
  inputSchema: { mediaHandle: z.string().min(1) },
1040
- }, async ({ mediaHandle }) => {
1222
+ }, async ({ mediaHandle }, extra) => {
1041
1223
  if (!options.nativeEditor)
1042
1224
  throw new Error("CAPABILITY_UNAVAILABLE: Final Cut timeline occurrence location is not configured");
1043
- return jsonResult(await options.nativeEditor.locateOccurrence(mediaHandle));
1225
+ return jsonResult(await options.nativeEditor.locateOccurrence(mediaHandle, { signal: extra.signal }));
1044
1226
  });
1045
1227
  server.registerTool("editor.native.media.target", {
1046
1228
  description: "Search Final Cut's Browser and target exactly one timeline occurrence with a deterministic live playhead.",
1047
1229
  inputSchema: { query: z.string().min(1) },
1048
- }, async ({ query }) => {
1230
+ }, async ({ query }, extra) => {
1049
1231
  if (!options.nativeEditor)
1050
1232
  throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native media targeting is not configured");
1051
- return jsonResult(await options.nativeEditor.targetMedia(query));
1233
+ return jsonResult(await options.nativeEditor.targetMedia(query, { signal: extra.signal }));
1052
1234
  });
1053
1235
  server.registerTool("editor.native.blade.preview", {
1054
1236
  description: "Prepare a short-lived confirmation token for a Blade-at-playhead operation.",
1055
1237
  inputSchema: { occurrenceHandle: z.string().min(1) },
1056
- }, async ({ occurrenceHandle }) => {
1238
+ }, async ({ occurrenceHandle }, extra) => {
1057
1239
  if (!options.nativeEditor)
1058
1240
  throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native Blade is not configured");
1059
- return jsonResult(await options.nativeEditor.previewBlade(occurrenceHandle));
1241
+ return jsonResult(await options.nativeEditor.previewBlade(occurrenceHandle, { signal: extra.signal }));
1060
1242
  });
1061
1243
  server.registerTool("editor.native.blade.execute", {
1062
1244
  description: "Execute a previously previewed Blade-at-playhead operation in Final Cut Pro.",
1063
1245
  inputSchema: { previewToken: z.string().min(1) },
1064
- }, async ({ previewToken }) => {
1246
+ }, async ({ previewToken }, extra) => {
1065
1247
  if (!options.nativeEditor)
1066
1248
  throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native Blade is not configured");
1067
- return jsonResult(await options.nativeEditor.executeBlade(previewToken));
1249
+ return jsonResult(await options.nativeEditor.executeBlade(previewToken, { signal: extra.signal }));
1068
1250
  });
1069
1251
  server.registerTool("editor.native.delete-range.preview", {
1070
1252
  description: "Preview a destructive ripple-delete of an explicit rational time range from the Final Cut primary storyline.",
1071
1253
  inputSchema: { start: rationalTimeSchema, end: rationalTimeSchema },
1072
- }, async ({ start, end }) => {
1254
+ }, async ({ start, end }, extra) => {
1073
1255
  if (!options.nativeEditor)
1074
1256
  throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native range deletion is not configured");
1075
- return jsonResult(await options.nativeEditor.previewDeleteRange({ start, end }));
1257
+ return jsonResult(await options.nativeEditor.previewDeleteRange({ start, end }, { signal: extra.signal }));
1076
1258
  });
1077
1259
  server.registerTool("editor.native.delete-range.execute", {
1078
1260
  description: "Execute a previously previewed primary-storyline ripple-delete range operation in Final Cut Pro.",
1079
1261
  inputSchema: { previewToken: z.string().min(1) },
1080
- }, async ({ previewToken }) => {
1262
+ }, async ({ previewToken }, extra) => {
1081
1263
  if (!options.nativeEditor)
1082
1264
  throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native range deletion is not configured");
1083
- return jsonResult(await options.nativeEditor.executeDeleteRange(previewToken));
1265
+ return jsonResult(await options.nativeEditor.executeDeleteRange(previewToken, { signal: extra.signal }));
1084
1266
  });
1085
1267
  server.registerTool("editor.native.trim-to-duration.preview", {
1086
1268
  description: "Preview a destructive operation that preserves the beginning of the Final Cut sequence and removes everything after the requested rational duration.",
1087
1269
  inputSchema: { duration: rationalTimeSchema },
1088
- }, async ({ duration }) => {
1270
+ }, async ({ duration }, extra) => {
1089
1271
  if (!options.nativeEditor)
1090
1272
  throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native duration trimming is not configured");
1091
- return jsonResult(await options.nativeEditor.previewTrimToDuration(duration));
1273
+ return jsonResult(await options.nativeEditor.previewTrimToDuration(duration, { signal: extra.signal }));
1092
1274
  });
1093
1275
  server.registerTool("editor.native.trim-to-duration.execute", {
1094
1276
  description: "Execute a previously previewed trim-to-duration operation in Final Cut Pro.",
1095
1277
  inputSchema: { previewToken: z.string().min(1) },
1096
- }, async ({ previewToken }) => {
1278
+ }, async ({ previewToken }, extra) => {
1097
1279
  if (!options.nativeEditor)
1098
1280
  throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native duration trimming is not configured");
1099
- 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));
1100
1326
  });
1101
1327
  server.registerTool("artifact.publish", {
1102
1328
  description: "Import the validated FCPXML artifact as a new Final Cut project without replacing the active project; requires explicit confirmation.",
@@ -1221,9 +1447,21 @@ export function createMcpServer(runtime, options = {}) {
1221
1447
  timestamp: new Date(sequence).toISOString(),
1222
1448
  }, waitMs ?? 0)));
1223
1449
  server.registerTool("editor.live.inspect", {
1224
- 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.",
1225
1451
  inputSchema: {},
1226
- }, 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
+ });
1227
1465
  server.registerTool("editor.live.changes", {
1228
1466
  description: "Read live Final Cut timeline change events after a revision; optionally wait for new events.",
1229
1467
  inputSchema: {
@@ -1236,8 +1474,20 @@ export function createMcpServer(runtime, options = {}) {
1236
1474
  timestamp: new Date(sequence).toISOString(),
1237
1475
  }, waitMs ?? 0)));
1238
1476
  server.registerTool("timeline.inspect", {
1239
- description: "Read the current canonical timeline snapshot.",
1240
- }, 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
+ });
1241
1491
  server.registerTool("timeline.frame.capture", {
1242
1492
  description: "Capture an image at an exact timeline position with project, sequence, clip, and optional visual-analysis metadata.",
1243
1493
  inputSchema: {
@@ -1252,7 +1502,19 @@ export function createMcpServer(runtime, options = {}) {
1252
1502
  server.registerTool("media.search", {
1253
1503
  description: "Search normalized media references by id or source path.",
1254
1504
  inputSchema: { query: z.string() },
1255
- }, 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
+ });
1256
1518
  server.registerTool("media.index", {
1257
1519
  description: "Query analyzed media by semantic properties, source identity, capabilities, and usable ranges.",
1258
1520
  inputSchema: mediaIndexQuerySchema.shape,
@@ -1273,11 +1535,12 @@ export function createMcpServer(runtime, options = {}) {
1273
1535
  inputSchema: roughCutPlanSchema.shape,
1274
1536
  }, async (request) => jsonResult(await runtime.planRoughCut(request)));
1275
1537
  server.registerTool("editor.assets", {
1276
- 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.",
1277
1539
  inputSchema: {
1278
1540
  query: z.string().optional(),
1279
1541
  kind: z.enum(["transition", "effect", "title", "generator", "audio-effect", "template"]).optional(),
1280
1542
  vendor: z.string().optional(),
1543
+ discovery: z.enum(["background", "native", "all"]).optional().default("background"),
1281
1544
  },
1282
1545
  }, async (query) => jsonResult(await runtime.listAssets(query)));
1283
1546
  server.registerTool("timeline.changes", {
@@ -1307,16 +1570,19 @@ export function createMcpServer(runtime, options = {}) {
1307
1570
  inputSchema: roughCutConstructionPlanInputSchema,
1308
1571
  }, async (request) => jsonResult(await runtime.previewRoughCutConstruction(request)));
1309
1572
  server.registerTool("artifact.edit", {
1310
- 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.",
1311
1574
  inputSchema: artifactEditToolInputSchema,
1312
1575
  }, async (input) => {
1576
+ await requireEditingRoute(runtime, options, "artifact.edit");
1313
1577
  const { artifactPath, verification, ...operation } = input;
1314
- 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) });
1315
1580
  });
1316
1581
  server.registerTool("editor.timeline.edit", {
1317
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.",
1318
1583
  inputSchema: editorTimelineEditToolInputSchema,
1319
1584
  }, async (input) => {
1585
+ await requireEditingRoute(runtime, options, "timeline.edit");
1320
1586
  const { projectId, sequenceId, verification, ...operation } = input;
1321
1587
  return jsonResult(await runtime.editTimeline({ projectId, sequenceId }, editOperationSchema.parse(operation), verification ?? {}));
1322
1588
  });
@@ -1355,14 +1621,17 @@ export function createMcpServer(runtime, options = {}) {
1355
1621
  }));
1356
1622
  });
1357
1623
  server.registerTool("artifact.edit.preview", {
1358
- 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.",
1359
1625
  inputSchema: {
1360
1626
  artifactPath: z.string().trim().min(1),
1361
1627
  baseRevision: revisionValueSchema,
1362
1628
  operations: workflowOperationsSchema,
1363
1629
  verification: verificationPolicySchema.optional(),
1364
1630
  },
1365
- }, 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
+ });
1366
1635
  server.registerTool("editor.timeline.edit.preview", {
1367
1636
  description: "Validate and preview an ordered live timeline edit against the identified active project and sequence without mutating it.",
1368
1637
  inputSchema: {
@@ -1372,15 +1641,51 @@ export function createMcpServer(runtime, options = {}) {
1372
1641
  operations: workflowOperationsSchema,
1373
1642
  verification: verificationPolicySchema.optional(),
1374
1643
  },
1375
- }, 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
+ });
1376
1648
  server.registerTool("artifact.edit.execute", {
1377
- 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.",
1378
1650
  inputSchema: { previewToken: z.string().min(1) },
1379
- }, 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
+ });
1380
1682
  server.registerTool("editor.timeline.edit.execute", {
1381
1683
  description: "Execute one short-lived live timeline edit preview token exactly once and verify the timeline transaction.",
1382
1684
  inputSchema: { previewToken: z.string().min(1) },
1383
- }, 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
+ });
1384
1689
  server.registerTool("timeline.edit.execute", {
1385
1690
  description: "Execute one short-lived composite edit preview token exactly once after editing.route capability checks, then verify the transaction.",
1386
1691
  inputSchema: { previewToken: z.string().min(1) },
@@ -1448,18 +1753,81 @@ export function createMcpServer(runtime, options = {}) {
1448
1753
  server.registerTool("edit.diff", {
1449
1754
  description: "Read the deterministic diff for a completed edit transaction.",
1450
1755
  inputSchema: { transactionId: z.string().min(1) },
1451
- }, async ({ transactionId }) => jsonResult(runtime.getDiff(transactionId)));
1756
+ }, async ({ transactionId }) => {
1757
+ const transaction = runtime.getTransaction(transactionId);
1758
+ return jsonResult({ ...runtime.getDiff(transactionId), ...withTransactionProvenance(transaction) });
1759
+ });
1452
1760
  server.registerTool("edit.verify", {
1453
1761
  description: "Read verification checks for a completed transaction.",
1454
1762
  inputSchema: { transactionId: z.string().min(1) },
1455
- }, 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
+ });
1456
1767
  server.registerTool("edit.undo", {
1457
1768
  description: "Restore the pre-edit snapshot for a completed transaction.",
1458
1769
  inputSchema: { transactionId: z.string().min(1) },
1459
- }, 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
+ });
1460
1779
  installMcpSchemaCompatibility(server);
1461
1780
  return server;
1462
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
+ }
1463
1831
  async function resolveNativeTitleAsset(runtime, assetId) {
1464
1832
  const assets = await runtime.listAssets();
1465
1833
  const asset = assets.find((candidate) => candidate.id === assetId);
@@ -1469,7 +1837,7 @@ async function resolveNativeTitleAsset(runtime, assetId) {
1469
1837
  throw new Error(`TITLE_ASSET_INCOMPATIBLE: ${assetId} is not an installed Final Cut title asset`);
1470
1838
  return asset;
1471
1839
  }
1472
- async function resolveNativeTransitionAsset(runtime, nativeEditor, assetId, nativeTransitionAssets = new Map()) {
1840
+ async function resolveNativeTransitionAsset(runtime, nativeEditor, assetId, nativeTransitionAssets = new Map(), signal) {
1473
1841
  const cachedAsset = nativeTransitionAssets.get(assetId);
1474
1842
  if (cachedAsset)
1475
1843
  return cachedAsset;
@@ -1486,7 +1854,7 @@ async function resolveNativeTransitionAsset(runtime, nativeEditor, assetId, nati
1486
1854
  // transition placement must use the stable identity returned by Final Cut's
1487
1855
  // Transitions browser. Resolve registry assets back through native discovery
1488
1856
  // instead of fabricating a native identity from the registry id.
1489
- const nativeMatches = await nativeEditor.searchTransitions(asset?.name ?? assetId);
1857
+ const nativeMatches = await nativeEditor.searchTransitions(asset?.name ?? assetId, { signal });
1490
1858
  const matchingNativeMatches = asset
1491
1859
  ? nativeMatches.filter((candidate) => candidate.name === asset.name)
1492
1860
  : nativeMatches.filter((candidate) => candidate.id === assetId || candidate.identity === assetId);
@@ -1507,18 +1875,52 @@ async function connectionStatus(options) {
1507
1875
  capabilities: null,
1508
1876
  };
1509
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
+ }
1510
1908
  async function inspectMcpEditor(runtime, options) {
1511
1909
  const inspected = await runtime.inspectEditor();
1512
1910
  const native = options.nativeEditor?.capabilities();
1513
1911
  const publishingAvailable = Boolean(options.projectPublisher && (typeof options.projectPublisher.isAvailable !== "function" || options.projectPublisher.isAvailable()));
1514
1912
  const exportAvailable = Boolean(options.videoExporter?.isAvailable());
1913
+ const backgroundExportAvailable = Boolean(options.backgroundRenderer?.isAvailable());
1515
1914
  const capabilities = withCapabilityFamilies({
1516
1915
  ...inspected.capabilities,
1517
1916
  editor: {
1518
1917
  ...inspected.capabilities.editor,
1519
1918
  artifactPublish: publishingAvailable,
1919
+ artifactPublishMode: publishingAvailable ? "headed-only" : "unavailable",
1520
1920
  ...(publishingAvailable ? {} : { timelinePublishNewProject: false }),
1521
1921
  videoExport: exportAvailable,
1922
+ backgroundRender: backgroundExportAvailable,
1923
+ externalRender: false,
1522
1924
  },
1523
1925
  }, {
1524
1926
  backend: inspected.identity.backend,
@@ -1551,17 +1953,50 @@ async function inspectMcpEditor(runtime, options) {
1551
1953
  publishingBackend: "fcpxml-publisher",
1552
1954
  export: exportAvailable,
1553
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",
1554
1970
  });
1555
1971
  return {
1556
1972
  ...inspected,
1557
1973
  capabilities,
1558
- preflight: createCapabilityPreflight(inspected.identity, capabilities, {
1559
- processMode: options.processMode ?? (native ? "headed" : "headless"),
1560
- nativeWrite: Boolean(native?.selectionEdit),
1561
- }),
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
+ },
1562
1989
  ...(native ? { native } : {}),
1563
1990
  };
1564
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
+ }
1565
2000
  async function requireEditingRoute(runtime, options, operation) {
1566
2001
  const route = resolveEditingRoute({ operation }, await editingRouteContext(runtime, options));
1567
2002
  if (route.status !== "editor-selected") {
@@ -1569,7 +2004,7 @@ async function requireEditingRoute(runtime, options, operation) {
1569
2004
  }
1570
2005
  }
1571
2006
  async function editingRouteContext(runtime, options) {
1572
- const connection = await connectionStatus(options);
2007
+ const connection = await effectiveConnectionStatus(runtime, options);
1573
2008
  let editor;
1574
2009
  try {
1575
2010
  editor = await inspectMcpEditor(runtime, options);