@morshoto/framekit 0.1.6 → 0.1.11

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 (43) 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/background-materialization.js +175 -0
  5. package/dist-package/adapters/final-cut/typescript/src/canonical.js +189 -32
  6. package/dist-package/adapters/final-cut/typescript/src/connection.js +55 -17
  7. package/dist-package/adapters/final-cut/typescript/src/disposable-native.js +33 -7
  8. package/dist-package/adapters/final-cut/typescript/src/fcpxml-console-experiment.js +74 -0
  9. package/dist-package/adapters/final-cut/typescript/src/fcpxml.js +615 -49
  10. package/dist-package/adapters/final-cut/typescript/src/index.js +10 -0
  11. package/dist-package/adapters/final-cut/typescript/src/library-inspection.js +390 -0
  12. package/dist-package/adapters/final-cut/typescript/src/live.js +16 -6
  13. package/dist-package/adapters/final-cut/typescript/src/media.js +151 -0
  14. package/dist-package/adapters/final-cut/typescript/src/native-session.js +412 -0
  15. package/dist-package/adapters/final-cut/typescript/src/native.js +1192 -364
  16. package/dist-package/adapters/final-cut/typescript/src/publisher.js +225 -32
  17. package/dist-package/adapters/final-cut/typescript/src/session.js +163 -17
  18. package/dist-package/adapters/final-cut/typescript/src/shadow-mutation.js +120 -0
  19. package/dist-package/adapters/final-cut/typescript/src/sqlite-inspection.js +433 -0
  20. package/dist-package/adapters/final-cut/typescript/src/timeline-ir-fcpxml.js +372 -0
  21. package/dist-package/adapters/final-cut/typescript/src/unattended-editing.js +66 -0
  22. package/dist-package/apps/mcp-server/src/headless-sessions.js +112 -0
  23. package/dist-package/apps/mcp-server/src/main.js +41 -8
  24. package/dist-package/apps/mcp-server/src/materialization-jobs.js +326 -0
  25. package/dist-package/apps/mcp-server/src/routing.js +227 -39
  26. package/dist-package/apps/mcp-server/src/server.js +642 -97
  27. package/dist-package/apps/mcp-server/src/version.js +109 -1
  28. package/dist-package/packages/runtime/src/application/media-analysis-service.js +1 -3
  29. package/dist-package/packages/runtime/src/application/project-service.js +46 -7
  30. package/dist-package/packages/runtime/src/capabilities.js +55 -7
  31. package/dist-package/packages/runtime/src/context/project-catalog.js +159 -0
  32. package/dist-package/packages/runtime/src/domain/capabilities.js +33 -0
  33. package/dist-package/packages/runtime/src/domain/context.js +14 -1
  34. package/dist-package/packages/runtime/src/domain/index.js +1 -0
  35. package/dist-package/packages/runtime/src/domain/timeline-target.js +217 -0
  36. package/dist-package/packages/runtime/src/editing/edit-service.js +15 -1
  37. package/dist-package/packages/runtime/src/editing/intent.js +178 -2
  38. package/dist-package/packages/runtime/src/index.js +3 -0
  39. package/dist-package/packages/runtime/src/runtime.js +2 -2
  40. package/dist-package/packages/runtime/src/timeline/drift-reconciliation.js +295 -0
  41. package/dist-package/packages/runtime/src/timeline/editing-session.js +490 -0
  42. package/dist-package/packages/testkit/src/in-memory-editor.js +5 -4
  43. package/package.json +12 -6
@@ -1,9 +1,13 @@
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";
9
+ import { EditingSessionRepository } from "./headless-sessions.js";
10
+ import { SessionMaterializationJobs, } from "./materialization-jobs.js";
7
11
  const revisionValueSchema = z.object({
8
12
  id: z.string(),
9
13
  sequence: z.number().int().nonnegative(),
@@ -298,6 +302,10 @@ const artifactPublishInputSchema = z.object({
298
302
  transactionId: z.string().min(1),
299
303
  confirm: z.boolean(),
300
304
  }).strict();
305
+ const artifactTransactionInputSchema = z.object({
306
+ artifactPath: z.string().trim().min(1),
307
+ transactionId: z.string().min(1),
308
+ }).strict();
301
309
  const workflowOperationSchema = z.discriminatedUnion("type", [
302
310
  renameClipSchema,
303
311
  trimClipSchema,
@@ -622,11 +630,98 @@ const nativeEditToolInputSchema = z.object({
622
630
  gainDb: z.number().finite().optional(),
623
631
  duration: z.number().nonnegative().optional(),
624
632
  }).strict();
633
+ const nativeOperationSessionSubmitSchema = z.object({
634
+ operation: z.literal("disposable.rename-clip"),
635
+ previewToken: z.string().trim().min(1),
636
+ projectId: z.string().trim().min(1),
637
+ sequenceId: z.string().trim().min(1),
638
+ targetIdentity: z.string().trim().min(1),
639
+ baseRevision: revisionValueSchema,
640
+ idempotencyKey: z.string().trim().min(1),
641
+ }).strict();
642
+ const nativeOperationSessionJobSchema = {
643
+ jobId: z.string().trim().min(1),
644
+ };
625
645
  function jsonResult(value) {
626
646
  return {
627
647
  content: [{ type: "text", text: JSON.stringify(value) }],
628
648
  };
629
649
  }
650
+ async function sessionResult(action) {
651
+ try {
652
+ return jsonResult(await action());
653
+ }
654
+ catch (error) {
655
+ const message = error instanceof Error ? error.message : String(error);
656
+ return {
657
+ isError: true,
658
+ content: [{
659
+ type: "text",
660
+ text: JSON.stringify({ code: message.split(":", 1)[0] || "SESSION_ERROR", message }),
661
+ }],
662
+ };
663
+ }
664
+ }
665
+ function capabilityErrorResult(operation, capabilityName, capability) {
666
+ return {
667
+ isError: true,
668
+ content: [{
669
+ type: "text",
670
+ text: JSON.stringify({
671
+ code: "CAPABILITY_UNAVAILABLE",
672
+ message: `${operation} requires ${capabilityName}`,
673
+ operation,
674
+ capability: capabilityName,
675
+ available: false,
676
+ backend: capability.backend,
677
+ guarantee: capability.guarantee,
678
+ unavailableReason: capability.unavailableReason,
679
+ }),
680
+ }],
681
+ };
682
+ }
683
+ function nativeMediaImportErrorResult(error) {
684
+ const serialized = serializeNativeFinalCutMediaImportError(error);
685
+ if (serialized) {
686
+ return {
687
+ isError: true,
688
+ content: [{ type: "text", text: JSON.stringify(serialized) }],
689
+ };
690
+ }
691
+ if (!isDirectoryMediaImportError(error))
692
+ throw error;
693
+ return {
694
+ isError: true,
695
+ content: [{
696
+ type: "text",
697
+ text: JSON.stringify({
698
+ code: error.code,
699
+ message: error.message,
700
+ guidance: error.guidance,
701
+ }),
702
+ }],
703
+ };
704
+ }
705
+ function capabilityUnavailableErrorResult(error) {
706
+ const serialized = serializeCapabilityUnavailableError(error);
707
+ if (!serialized)
708
+ throw error;
709
+ return {
710
+ isError: true,
711
+ content: [{ type: "text", text: JSON.stringify(serialized) }],
712
+ };
713
+ }
714
+ function isDirectoryMediaImportError(error) {
715
+ if (!error || typeof error !== "object")
716
+ return false;
717
+ const value = error;
718
+ const guidance = value.guidance;
719
+ return value.code === NATIVE_MEDIA_IMPORT_DIRECTORY_ERROR_CODE
720
+ && Boolean(guidance)
721
+ && typeof guidance === "object"
722
+ && typeof guidance.previewTool === "string"
723
+ && typeof guidance.executeTool === "string";
724
+ }
630
725
  function skillErrorResult(error) {
631
726
  const value = error && typeof error === "object" ? error : {};
632
727
  const message = error instanceof Error ? error.message : String(error);
@@ -665,10 +760,20 @@ function normalizeConnectionStatus(value) {
665
760
  const backend = typeof identity?.backend === "string" ? identity.backend : undefined;
666
761
  return {
667
762
  ...status,
668
- capabilities: withCapabilityFamilies(status.capabilities, {
763
+ capabilities: withCanonicalTimelineMode(withCapabilityFamilies(status.capabilities, {
669
764
  ...(backend ? { backend, connectionBackend: backend } : {}),
670
765
  connection: status.state === "ready",
671
- }),
766
+ })),
767
+ };
768
+ }
769
+ function nativeMediaIntentCapabilities(nativeEditor) {
770
+ const capabilities = nativeEditor?.capabilities();
771
+ return {
772
+ "native.mediaImport": Boolean(capabilities?.mediaImport),
773
+ "native.mediaSelection": Boolean(capabilities?.mediaSelection),
774
+ "native.mediaAppendSelected": Boolean(capabilities?.mediaAppendSelected),
775
+ "native.mediaAppend": Boolean(capabilities?.mediaAppend),
776
+ "native.mediaInsert": Boolean(capabilities?.mediaInsert),
672
777
  };
673
778
  }
674
779
  function isRuntimeCapabilities(value) {
@@ -699,10 +804,103 @@ export function createMcpServer(runtime, options = {}) {
699
804
  runtime.registerBuiltinSkills();
700
805
  const server = new McpServer({ name: "framekit", version: FRAMEKIT_VERSION }, { instructions: EDITOR_FIRST_MCP_INSTRUCTIONS });
701
806
  const nativeTransitionAssets = new Map();
807
+ const sessions = options.sessionDirectory ? new EditingSessionRepository(options.sessionDirectory) : undefined;
808
+ const materializations = sessions && options.materializationDirectory
809
+ ? new SessionMaterializationJobs(options.materializationDirectory, sessions, options.sessionMaterializationPublisher)
810
+ : undefined;
811
+ const requireSessions = () => {
812
+ if (!sessions)
813
+ throw new Error("SESSION_STORAGE_UNAVAILABLE: configure a session directory");
814
+ return sessions;
815
+ };
816
+ const requireMaterializations = () => {
817
+ if (!materializations)
818
+ throw new Error("MATERIALIZATION_STORAGE_UNAVAILABLE: configure a materialization directory");
819
+ return materializations;
820
+ };
821
+ const sessionOperationSchema = z.array(z.unknown());
822
+ server.registerTool("session.create", {
823
+ description: "Create and atomically persist a provider-neutral editing session without mutating Final Cut.",
824
+ inputSchema: {
825
+ sessionId: z.string().min(1).optional(),
826
+ provider: z.object({ id: z.string().min(1), version: z.string().min(1).optional() }).optional(),
827
+ base: z.unknown(),
828
+ },
829
+ }, async ({ sessionId, provider, base }) => sessionResult(async () => requireSessions().create({
830
+ ...(sessionId ? { sessionId } : {}),
831
+ ...(provider ? { provider } : {}),
832
+ base: base,
833
+ })));
834
+ server.registerTool("session.inspect", {
835
+ description: "Inspect a persisted editing session and its exact base and desired Timeline IR.",
836
+ inputSchema: { sessionId: z.string().min(1) },
837
+ }, async ({ sessionId }) => sessionResult(async () => requireSessions().inspect(sessionId)));
838
+ server.registerTool("session.edit.preview", {
839
+ description: "Preview provider-neutral session edits without persisting or mutating Final Cut.",
840
+ inputSchema: {
841
+ sessionId: z.string().min(1),
842
+ expectedRevision: revisionValueSchema.optional(),
843
+ operations: sessionOperationSchema,
844
+ },
845
+ }, async ({ sessionId, expectedRevision, operations }) => sessionResult(async () => requireSessions().preview(sessionId, operations, expectedRevision)));
846
+ server.registerTool("session.edit.execute", {
847
+ description: "Apply edits only to a persisted session's desired Timeline IR.",
848
+ inputSchema: {
849
+ sessionId: z.string().min(1),
850
+ expectedRevision: revisionValueSchema.optional(),
851
+ operations: sessionOperationSchema,
852
+ },
853
+ }, async ({ sessionId, expectedRevision, operations }) => sessionResult(async () => requireSessions().execute(sessionId, operations, expectedRevision)));
854
+ server.registerTool("session.status", {
855
+ description: "Read editing-session readiness, provider binding, and revisions.",
856
+ inputSchema: { sessionId: z.string().min(1) },
857
+ }, async ({ sessionId }) => sessionResult(async () => requireSessions().status(sessionId)));
858
+ server.registerTool("session.reconcile", {
859
+ description: "Reconcile a fresh provider Timeline IR with the session base and desired state.",
860
+ inputSchema: {
861
+ sessionId: z.string().min(1),
862
+ provider: z.object({ id: z.string().min(1), version: z.string().min(1).optional() }),
863
+ providerState: z.unknown(),
864
+ },
865
+ }, async ({ sessionId, provider, providerState }) => sessionResult(async () => requireSessions().reconcile(sessionId, provider, providerState)));
866
+ server.registerTool("session.observe", {
867
+ description: "Bind read-only non-canonical Final Cut SQLite evidence to session freshness.",
868
+ inputSchema: { sessionId: z.string().min(1), sourcePath: z.string().min(1) },
869
+ }, async ({ sessionId, sourcePath }) => sessionResult(async () => {
870
+ if (!options.sqliteObservationProvider) {
871
+ throw new Error("FINAL_CUT_SQLITE_INSPECTION_UNAVAILABLE: no read-only observation provider is configured");
872
+ }
873
+ return requireSessions().observe(sessionId, sourcePath, options.sqliteObservationProvider);
874
+ }));
875
+ const sessionMaterializationTargetSchema = z.object({
876
+ provider: z.literal("final-cut"),
877
+ libraryUid: z.string().min(1),
878
+ eventUid: z.string().min(1),
879
+ projectUid: z.string().min(1),
880
+ sequenceUid: z.string().min(1),
881
+ eventName: z.string().min(1).optional(),
882
+ materialization: z.literal("versioned").optional(),
883
+ }).strict();
884
+ server.registerTool("session.materialize.preview", {
885
+ description: "Preview deterministic versioned FCPXML materialization without staging or publishing it.",
886
+ inputSchema: { sessionId: z.string().min(1), target: sessionMaterializationTargetSchema },
887
+ }, async ({ sessionId, target }) => sessionResult(async () => requireMaterializations().preview(sessionId, target)));
888
+ server.registerTool("session.materialize.execute", {
889
+ description: "Confirm, stage, checkpoint, and request publication of a versioned FCPXML project.",
890
+ inputSchema: { sessionId: z.string().min(1), target: sessionMaterializationTargetSchema, confirm: z.boolean() },
891
+ }, async ({ sessionId, target, confirm }) => sessionResult(async () => requireMaterializations().execute(sessionId, target, confirm)));
892
+ server.registerTool("session.materialize.status", {
893
+ description: "Inspect a persisted materialization job after completion, blockage, or server restart.",
894
+ inputSchema: { jobId: z.string().min(1) },
895
+ }, async ({ jobId }) => sessionResult(async () => requireMaterializations().status(jobId)));
896
+ server.registerTool("session.materialize.retry", {
897
+ description: "Resume a retryable persisted materialization job with its verified immutable artifact.",
898
+ inputSchema: { jobId: z.string().min(1) },
899
+ }, async ({ jobId }) => sessionResult(async () => requireMaterializations().retry(jobId)));
702
900
  server.registerTool("connection.status", {
703
901
  description: "Read Framekit's Final Cut connection state before editor-first capability discovery.",
704
902
  inputSchema: {},
705
- }, async () => jsonResult(normalizeConnectionStatus(await connectionStatus(options))));
903
+ }, async () => jsonResult(await effectiveConnectionStatus(runtime, options)));
706
904
  server.registerTool("skill.list", {
707
905
  description: "List registered versioned Framekit Skills with current capability availability.",
708
906
  inputSchema: {},
@@ -766,22 +964,55 @@ export function createMcpServer(runtime, options = {}) {
766
964
  });
767
965
  server.registerTool("project.inspect", {
768
966
  description: "Read the current canonical project snapshot before editing.route selects a capability-checked path.",
769
- }, async () => jsonResult(await runtime.inspectProject()));
967
+ }, async () => {
968
+ const inspected = await inspectMcpEditor(runtime, options);
969
+ const capability = inspected.capabilities.families.canonicalDocument.read;
970
+ if (!capability.available) {
971
+ return capabilityErrorResult("project.inspect", "canonicalDocument.read", capability);
972
+ }
973
+ try {
974
+ return jsonResult(await runtime.inspectProject());
975
+ }
976
+ catch (error) {
977
+ return capabilityUnavailableErrorResult(error);
978
+ }
979
+ });
770
980
  server.registerTool("artifact.inspect", {
771
- description: "Identify the managed FCPXML artifact used by artifact.edit and artifact.publish.",
981
+ description: "Identify the managed FCPXML artifact used by the background artifact.edit and artifact.publish workflows.",
772
982
  inputSchema: {},
773
983
  }, async () => jsonResult(await runtime.inspectArtifact()));
774
984
  server.registerTool("project.list", {
775
985
  description: "List projects and their stable Final Cut sequence identities, including the active target.",
776
986
  inputSchema: {},
777
- }, async () => jsonResult(await runtime.listProjects()));
987
+ }, async () => {
988
+ try {
989
+ return jsonResult(await runtime.listProjects());
990
+ }
991
+ catch (error) {
992
+ const inspectionError = serializeFinalCutLibraryInspectionError(error);
993
+ if (inspectionError) {
994
+ return {
995
+ isError: true,
996
+ content: [{ type: "text", text: JSON.stringify(inspectionError) }],
997
+ };
998
+ }
999
+ return capabilityUnavailableErrorResult(error);
1000
+ }
1001
+ });
778
1002
  server.registerTool("project.select", {
779
1003
  description: "Select one project and, when it has multiple sequences, one explicit sequence; ambiguous targets fail closed.",
780
1004
  inputSchema: {
781
1005
  projectId: z.string().min(1),
782
1006
  sequenceId: z.string().min(1).optional(),
783
1007
  },
784
- }, async ({ projectId, sequenceId }) => jsonResult(await runtime.selectProject({ projectId, sequenceId })));
1008
+ }, async ({ projectId, sequenceId }) => {
1009
+ try {
1010
+ return jsonResult(await runtime.selectProject({ projectId, sequenceId }));
1011
+ }
1012
+ catch (error) {
1013
+ return capabilityUnavailableErrorResult(error);
1014
+ }
1015
+ });
785
1016
  server.registerTool("editor.inspect", {
786
1017
  description: "Read editor identity and machine-readable capabilities before selecting an editing path.",
787
1018
  }, async () => {
@@ -801,12 +1032,20 @@ export function createMcpServer(runtime, options = {}) {
801
1032
  server.registerTool("editing.intent.resolve", {
802
1033
  description: "Map a supported natural-language editing request to one explicit operation without executing it.",
803
1034
  inputSchema: { request: z.string().trim().min(1) },
804
- }, async ({ request }) => jsonResult(resolveEditingIntent(request)));
1035
+ }, async ({ request }) => jsonResult(resolveEditingIntent(request, {
1036
+ availableCapabilities: nativeMediaIntentCapabilities(options.nativeEditor),
1037
+ })));
805
1038
  server.registerTool("editing.route", {
806
1039
  description: "Resolve an editor-first path after capability checks; never bypass a connected editor, and require explicit external fallback selection.",
807
1040
  inputSchema: {
808
1041
  operation: z.enum([
1042
+ "project.list",
1043
+ "project.select",
1044
+ "project.inspect",
1045
+ "timeline.inspect",
1046
+ "editor.live.inspect",
809
1047
  "timeline.edit",
1048
+ "artifact.edit",
810
1049
  "timeline.mask.add",
811
1050
  "editor.native.edit",
812
1051
  "editor.native.picture-in-picture",
@@ -826,31 +1065,52 @@ export function createMcpServer(runtime, options = {}) {
826
1065
  server.registerTool("editor.native.inspect", {
827
1066
  description: "Inspect the active Final Cut selection/playhead before a native UI edit.",
828
1067
  inputSchema: {},
829
- }, async () => jsonResult(options.nativeEditor
830
- ? await options.nativeEditor.inspect()
1068
+ }, async (_args, extra) => jsonResult(options.nativeEditor
1069
+ ? await options.nativeEditor.inspect({ signal: extra.signal })
831
1070
  : { available: false, error: { code: "CAPABILITY_UNAVAILABLE", message: "Final Cut native writes are not configured" } }));
832
1071
  server.registerTool("editor.native.focus", {
833
1072
  description: "Activate Final Cut Pro and focus its timeline without changing project or timeline content.",
834
1073
  inputSchema: {},
835
- }, async () => jsonResult(options.nativeEditor
836
- ? await options.nativeEditor.focusTimeline()
1074
+ }, async (_args, extra) => jsonResult(options.nativeEditor
1075
+ ? await options.nativeEditor.focusTimeline({ signal: extra.signal })
837
1076
  : { available: false, error: { code: "CAPABILITY_UNAVAILABLE", message: "Final Cut native writes are not configured" } }));
838
1077
  server.registerTool("editor.native.media.import", {
839
1078
  description: "Import one local video or audio file into the active Final Cut Browser and wait for a stable media handle.",
840
1079
  inputSchema: { path: z.string().min(1) },
841
- }, async ({ path }) => {
1080
+ }, async ({ path }, extra) => {
1081
+ if (!options.nativeEditor)
1082
+ throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native media import is not configured");
1083
+ try {
1084
+ return jsonResult(await options.nativeEditor.importMedia(path, { signal: extra.signal }));
1085
+ }
1086
+ catch (error) {
1087
+ return nativeMediaImportErrorResult(error);
1088
+ }
1089
+ });
1090
+ server.registerTool("editor.native.media.directory.preview", {
1091
+ description: "Enumerate supported top-level video files in a local directory without mutating Final Cut and return an expiring import preview.",
1092
+ inputSchema: { path: z.string().trim().min(1) },
1093
+ }, async ({ path }, extra) => {
842
1094
  if (!options.nativeEditor)
843
1095
  throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native media import is not configured");
844
- return jsonResult(await options.nativeEditor.importMedia(path));
1096
+ return jsonResult(await options.nativeEditor.previewImportMediaDirectory(path, { signal: extra.signal }));
1097
+ });
1098
+ server.registerTool("editor.native.media.directory.execute", {
1099
+ description: "Import every file from a directory preview after explicit confirmation and return per-file stable media handles or failures.",
1100
+ inputSchema: { previewToken: z.string().min(1), confirm: z.literal(true) },
1101
+ }, async ({ previewToken, confirm }, extra) => {
1102
+ if (!options.nativeEditor)
1103
+ throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native media import is not configured");
1104
+ return jsonResult(await options.nativeEditor.executeImportMediaDirectory(previewToken, confirm, { signal: extra.signal }));
845
1105
  });
846
1106
  server.registerTool("editor.native.edit", {
847
1107
  description: "Apply a guarded native Final Cut UI edit to the active selection or playhead.",
848
1108
  inputSchema: nativeEditToolInputSchema,
849
- }, async (input) => {
1109
+ }, async (input, extra) => {
850
1110
  if (!options.nativeEditor)
851
1111
  throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native writes are not configured");
852
1112
  const operation = nativeEditSchema.parse(input);
853
- return jsonResult(await options.nativeEditor.edit(operation));
1113
+ return jsonResult(await options.nativeEditor.edit(operation, { signal: extra.signal }));
854
1114
  });
855
1115
  server.registerTool("editor.native.disposable.preview", {
856
1116
  description: "Preview a disposable native Final Cut rename after canonical target, revision, and native preflight checks.",
@@ -863,7 +1123,7 @@ export function createMcpServer(runtime, options = {}) {
863
1123
  server.registerTool("editor.native.disposable.execute", {
864
1124
  description: "Execute a disposable native Final Cut edit and return canonical diff, verification, and rollback state.",
865
1125
  inputSchema: { previewToken: z.string().min(1) },
866
- }, async ({ previewToken }) => {
1126
+ }, async ({ previewToken }, extra) => {
867
1127
  if (!options.disposableNative)
868
1128
  throw new Error("CAPABILITY_UNAVAILABLE: disposable native edit is not configured");
869
1129
  return jsonResult(await options.disposableNative.execute(previewToken));
@@ -876,48 +1136,80 @@ export function createMcpServer(runtime, options = {}) {
876
1136
  throw new Error("CAPABILITY_UNAVAILABLE: disposable native edit is not configured");
877
1137
  return jsonResult(await options.disposableNative.undo(operationId));
878
1138
  });
1139
+ server.registerTool("editor.native.operation.submit", {
1140
+ description: "Accept a previewed native Final Cut operation as a resumable job without waiting for headed readiness.",
1141
+ inputSchema: nativeOperationSessionSubmitSchema,
1142
+ }, async (request) => {
1143
+ if (!options.nativeOperationSession)
1144
+ throw new Error("CAPABILITY_UNAVAILABLE: native operation session is not configured");
1145
+ return jsonResult(await options.nativeOperationSession.submit(request));
1146
+ });
1147
+ server.registerTool("editor.native.operation.status", {
1148
+ description: "Poll a resumable native Final Cut operation for readiness, completion, verification, and restoration evidence.",
1149
+ inputSchema: nativeOperationSessionJobSchema,
1150
+ }, async ({ jobId }) => {
1151
+ if (!options.nativeOperationSession)
1152
+ throw new Error("CAPABILITY_UNAVAILABLE: native operation session is not configured");
1153
+ return jsonResult(options.nativeOperationSession.status(jobId));
1154
+ });
1155
+ server.registerTool("editor.native.operation.retry", {
1156
+ description: "Retry a waiting native Final Cut operation after the required headed session becomes ready.",
1157
+ inputSchema: nativeOperationSessionJobSchema,
1158
+ }, async ({ jobId }) => {
1159
+ if (!options.nativeOperationSession)
1160
+ throw new Error("CAPABILITY_UNAVAILABLE: native operation session is not configured");
1161
+ return jsonResult(await options.nativeOperationSession.retry(jobId));
1162
+ });
1163
+ server.registerTool("editor.native.operation.cancel", {
1164
+ description: "Cancel a pending native Final Cut operation or report recovery when mutation has already started.",
1165
+ inputSchema: nativeOperationSessionJobSchema,
1166
+ }, async ({ jobId }) => {
1167
+ if (!options.nativeOperationSession)
1168
+ throw new Error("CAPABILITY_UNAVAILABLE: native operation session is not configured");
1169
+ return jsonResult(await options.nativeOperationSession.cancel(jobId));
1170
+ });
879
1171
  server.registerTool("editor.native.title.add.preview", {
880
1172
  description: "Preview adding an installed Final Cut title at the live playhead or an explicit timeline range.",
881
1173
  inputSchema: nativeTitlePreviewSchema,
882
- }, async ({ assetId, text, start, duration }) => {
1174
+ }, async ({ assetId, text, start, duration }, extra) => {
883
1175
  if (!options.nativeEditor)
884
1176
  throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native title placement is not configured");
885
1177
  const asset = await resolveNativeTitleAsset(runtime, assetId);
886
- return jsonResult(await options.nativeEditor.previewTitleAdd({ asset, text, start, duration }));
1178
+ return jsonResult(await options.nativeEditor.previewTitleAdd({ asset, text, start, duration }, { signal: extra.signal }));
887
1179
  });
888
1180
  server.registerTool("editor.native.title.add.execute", {
889
1181
  description: "Execute a previously previewed native Final Cut title placement and return its verification and Undo handle.",
890
1182
  inputSchema: { previewToken: z.string().min(1) },
891
- }, async ({ previewToken }) => {
1183
+ }, async ({ previewToken }, extra) => {
892
1184
  if (!options.nativeEditor)
893
1185
  throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native title placement is not configured");
894
- return jsonResult(await options.nativeEditor.executeTitleAdd(previewToken));
1186
+ return jsonResult(await options.nativeEditor.executeTitleAdd(previewToken, { signal: extra.signal }));
895
1187
  });
896
1188
  server.registerTool("editor.native.picture-in-picture.preview", {
897
1189
  description: "Preview connecting selected Final Cut Browser video to a stable timeline occurrence with verified transform properties.",
898
1190
  inputSchema: nativePictureInPicturePreviewSchema,
899
- }, async (request) => {
1191
+ }, async (request, extra) => {
900
1192
  if (!options.nativeEditor)
901
1193
  throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native picture-in-picture placement is not configured");
902
1194
  await requireEditingRoute(runtime, options, "editor.native.picture-in-picture");
903
- return jsonResult(await options.nativeEditor.previewPictureInPicture(request));
1195
+ return jsonResult(await options.nativeEditor.previewPictureInPicture(request, { signal: extra.signal }));
904
1196
  });
905
1197
  server.registerTool("editor.native.picture-in-picture.execute", {
906
1198
  description: "Execute a native Final Cut picture-in-picture preview and return transform readback, revision, and Undo verification.",
907
1199
  inputSchema: { previewToken: z.string().min(1) },
908
- }, async ({ previewToken }) => {
1200
+ }, async ({ previewToken }, extra) => {
909
1201
  if (!options.nativeEditor)
910
1202
  throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native picture-in-picture placement is not configured");
911
1203
  await requireEditingRoute(runtime, options, "editor.native.picture-in-picture");
912
- return jsonResult(await options.nativeEditor.executePictureInPicture(previewToken));
1204
+ return jsonResult(await options.nativeEditor.executePictureInPicture(previewToken, { signal: extra.signal }));
913
1205
  });
914
1206
  server.registerTool("editor.native.transition.search", {
915
1207
  description: "Search the visible Final Cut Transitions browser and return only transitions with stable native identities.",
916
1208
  inputSchema: { query: z.string().trim().min(1) },
917
- }, async ({ query }) => {
1209
+ }, async ({ query }, extra) => {
918
1210
  if (!options.nativeEditor)
919
1211
  throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native transition discovery is not configured");
920
- const matches = await options.nativeEditor.searchTransitions(query);
1212
+ const matches = await options.nativeEditor.searchTransitions(query, { signal: extra.signal });
921
1213
  for (const match of matches) {
922
1214
  nativeTransitionAssets.set(match.id, match);
923
1215
  nativeTransitionAssets.set(`final-cut:transition:${match.identity}`, match);
@@ -927,176 +1219,220 @@ export function createMcpServer(runtime, options = {}) {
927
1219
  server.registerTool("editor.native.transition.add.preview", {
928
1220
  description: "Preview adding a discovered native transition between two adjacent occurrence handles at an exact duration.",
929
1221
  inputSchema: nativeTransitionPreviewSchema,
930
- }, async ({ assetId, beforeOccurrenceHandle, afterOccurrenceHandle, duration }) => {
1222
+ }, async ({ assetId, beforeOccurrenceHandle, afterOccurrenceHandle, duration }, extra) => {
931
1223
  if (!options.nativeEditor)
932
1224
  throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native transition placement is not configured");
933
- const asset = await resolveNativeTransitionAsset(runtime, options.nativeEditor, assetId, nativeTransitionAssets);
1225
+ const asset = await resolveNativeTransitionAsset(runtime, options.nativeEditor, assetId, nativeTransitionAssets, extra.signal);
934
1226
  return jsonResult(await options.nativeEditor.previewTransitionAdd({
935
1227
  asset,
936
1228
  beforeOccurrenceHandle,
937
1229
  afterOccurrenceHandle,
938
1230
  duration,
939
- }));
1231
+ }, { signal: extra.signal }));
940
1232
  });
941
1233
  server.registerTool("editor.native.transition.add.execute", {
942
1234
  description: "Execute a previously previewed native transition placement and return verified revision and Undo state.",
943
1235
  inputSchema: { previewToken: z.string().min(1) },
944
- }, async ({ previewToken }) => {
1236
+ }, async ({ previewToken }, extra) => {
945
1237
  if (!options.nativeEditor)
946
1238
  throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native transition placement is not configured");
947
- return jsonResult(await options.nativeEditor.executeTransitionAdd(previewToken));
1239
+ return jsonResult(await options.nativeEditor.executeTransitionAdd(previewToken, { signal: extra.signal }));
948
1240
  });
949
1241
  server.registerTool("editor.native.mask.preview", {
950
1242
  description: "Preview adding a bounded native Final Cut Draw Mask to one located occurrence without mutating the timeline.",
951
1243
  inputSchema: nativeMaskPreviewSchema,
952
- }, async ({ occurrenceHandle, mask }) => {
1244
+ }, async ({ occurrenceHandle, mask }, extra) => {
953
1245
  if (!options.nativeEditor)
954
1246
  throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native masking is not configured");
955
- return jsonResult(await options.nativeEditor.previewMask({ occurrenceHandle, mask }));
1247
+ return jsonResult(await options.nativeEditor.previewMask({ occurrenceHandle, mask }, { signal: extra.signal }));
956
1248
  });
957
1249
  server.registerTool("editor.native.mask.execute", {
958
1250
  description: "Execute a previously previewed native Draw Mask and return readback verification and native Undo state.",
959
1251
  inputSchema: { previewToken: z.string().trim().min(1) },
960
- }, async ({ previewToken }) => {
1252
+ }, async ({ previewToken }, extra) => {
961
1253
  if (!options.nativeEditor)
962
1254
  throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native masking is not configured");
963
- return jsonResult(await options.nativeEditor.executeMask(previewToken));
1255
+ return jsonResult(await options.nativeEditor.executeMask(previewToken, { signal: extra.signal }));
964
1256
  });
965
1257
  server.registerTool("editor.native.undo", {
966
1258
  description: "Undo a previously accepted native Final Cut UI edit using Final Cut's native Undo command.",
967
1259
  inputSchema: { operationId: z.string().min(1) },
968
- }, async ({ operationId }) => {
1260
+ }, async ({ operationId }, extra) => {
969
1261
  if (!options.nativeEditor)
970
1262
  throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native writes are not configured");
971
- return jsonResult(await options.nativeEditor.undo(operationId));
1263
+ return jsonResult(await options.nativeEditor.undo(operationId, { signal: extra.signal }));
972
1264
  });
973
1265
  server.registerTool("editor.native.media.search", {
974
1266
  description: "Search the active Final Cut Browser for live media and return short-lived media handles.",
975
1267
  inputSchema: { query: z.string().min(1) },
976
- }, async ({ query }) => {
1268
+ }, async ({ query }, extra) => {
977
1269
  if (!options.nativeEditor)
978
1270
  throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native media search is not configured");
979
- return jsonResult(await options.nativeEditor.searchMedia(query));
1271
+ return jsonResult(await options.nativeEditor.searchMedia(query, { signal: extra.signal }));
980
1272
  });
981
1273
  server.registerTool("editor.native.media.select", {
982
1274
  description: "Select one live Final Cut Browser media result using its short-lived handle.",
983
1275
  inputSchema: { mediaHandle: z.string().min(1) },
984
- }, async ({ mediaHandle }) => {
1276
+ }, async ({ mediaHandle }, extra) => {
985
1277
  if (!options.nativeEditor)
986
1278
  throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native media selection is not configured");
987
- return jsonResult(await options.nativeEditor.selectMedia(mediaHandle));
1279
+ return jsonResult(await options.nativeEditor.selectMedia(mediaHandle, { signal: extra.signal }));
988
1280
  });
989
1281
  server.registerTool("editor.native.media.append.preview", {
990
1282
  description: "Preview appending the selected Final Cut Browser media to the end of the active timeline.",
991
1283
  inputSchema: { mediaHandle: z.string().min(1) },
992
- }, async ({ mediaHandle }) => {
1284
+ }, async ({ mediaHandle }, extra) => {
993
1285
  if (!options.nativeEditor)
994
1286
  throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native media append is not configured");
995
- return jsonResult(await options.nativeEditor.previewAppendMedia(mediaHandle));
1287
+ return jsonResult(await options.nativeEditor.previewAppendMedia(mediaHandle, { signal: extra.signal }));
996
1288
  });
997
1289
  server.registerTool("editor.native.media.append.execute", {
998
1290
  description: "Execute a previously previewed append of selected Final Cut Browser media.",
999
1291
  inputSchema: { previewToken: z.string().min(1) },
1000
- }, async ({ previewToken }) => {
1292
+ }, async ({ previewToken }, extra) => {
1001
1293
  if (!options.nativeEditor)
1002
1294
  throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native media append is not configured");
1003
- return jsonResult(await options.nativeEditor.executeAppendMedia(previewToken));
1295
+ return jsonResult(await options.nativeEditor.executeAppendMedia(previewToken, { signal: extra.signal }));
1004
1296
  });
1005
1297
  server.registerTool("editor.native.media.append.selected.preview", {
1006
1298
  description: "Preview appending the currently selected Final Cut Browser media to the end of the active timeline.",
1007
1299
  inputSchema: {},
1008
- }, async () => {
1300
+ }, async (_args, extra) => {
1009
1301
  if (!options.nativeEditor)
1010
1302
  throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native selected-media append is not configured");
1011
- return jsonResult(await options.nativeEditor.previewAppendSelectedMedia());
1303
+ return jsonResult(await options.nativeEditor.previewAppendSelectedMedia({ signal: extra.signal }));
1012
1304
  });
1013
1305
  server.registerTool("editor.native.media.append.selected.execute", {
1014
1306
  description: "Execute a previously previewed append of the currently selected Final Cut Browser media.",
1015
1307
  inputSchema: { previewToken: z.string().min(1) },
1016
- }, async ({ previewToken }) => {
1308
+ }, async ({ previewToken }, extra) => {
1017
1309
  if (!options.nativeEditor)
1018
1310
  throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native selected-media append is not configured");
1019
- return jsonResult(await options.nativeEditor.executeAppendSelectedMedia(previewToken));
1311
+ return jsonResult(await options.nativeEditor.executeAppendSelectedMedia(previewToken, { signal: extra.signal }));
1020
1312
  });
1021
1313
  server.registerTool("editor.native.media.insert.preview", {
1022
1314
  description: "Preview inserting the selected Final Cut Browser media at the current playhead.",
1023
1315
  inputSchema: { mediaHandle: z.string().min(1) },
1024
- }, async ({ mediaHandle }) => {
1316
+ }, async ({ mediaHandle }, extra) => {
1025
1317
  if (!options.nativeEditor)
1026
1318
  throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native media insert is not configured");
1027
- return jsonResult(await options.nativeEditor.previewInsertMedia(mediaHandle));
1319
+ return jsonResult(await options.nativeEditor.previewInsertMedia(mediaHandle, { signal: extra.signal }));
1028
1320
  });
1029
1321
  server.registerTool("editor.native.media.insert.execute", {
1030
1322
  description: "Execute a previously previewed insertion of selected Final Cut Browser media at the playhead.",
1031
1323
  inputSchema: { previewToken: z.string().min(1) },
1032
- }, async ({ previewToken }) => {
1324
+ }, async ({ previewToken }, extra) => {
1033
1325
  if (!options.nativeEditor)
1034
1326
  throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native media insert is not configured");
1035
- return jsonResult(await options.nativeEditor.executeInsertMedia(previewToken));
1327
+ return jsonResult(await options.nativeEditor.executeInsertMedia(previewToken, { signal: extra.signal }));
1036
1328
  });
1037
1329
  server.registerTool("editor.native.timeline.locate", {
1038
1330
  description: "Locate matching occurrences of a live Browser media result in the active Final Cut timeline.",
1039
1331
  inputSchema: { mediaHandle: z.string().min(1) },
1040
- }, async ({ mediaHandle }) => {
1332
+ }, async ({ mediaHandle }, extra) => {
1041
1333
  if (!options.nativeEditor)
1042
1334
  throw new Error("CAPABILITY_UNAVAILABLE: Final Cut timeline occurrence location is not configured");
1043
- return jsonResult(await options.nativeEditor.locateOccurrence(mediaHandle));
1335
+ return jsonResult(await options.nativeEditor.locateOccurrence(mediaHandle, { signal: extra.signal }));
1044
1336
  });
1045
1337
  server.registerTool("editor.native.media.target", {
1046
1338
  description: "Search Final Cut's Browser and target exactly one timeline occurrence with a deterministic live playhead.",
1047
1339
  inputSchema: { query: z.string().min(1) },
1048
- }, async ({ query }) => {
1340
+ }, async ({ query }, extra) => {
1049
1341
  if (!options.nativeEditor)
1050
1342
  throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native media targeting is not configured");
1051
- return jsonResult(await options.nativeEditor.targetMedia(query));
1343
+ return jsonResult(await options.nativeEditor.targetMedia(query, { signal: extra.signal }));
1052
1344
  });
1053
1345
  server.registerTool("editor.native.blade.preview", {
1054
1346
  description: "Prepare a short-lived confirmation token for a Blade-at-playhead operation.",
1055
1347
  inputSchema: { occurrenceHandle: z.string().min(1) },
1056
- }, async ({ occurrenceHandle }) => {
1348
+ }, async ({ occurrenceHandle }, extra) => {
1057
1349
  if (!options.nativeEditor)
1058
1350
  throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native Blade is not configured");
1059
- return jsonResult(await options.nativeEditor.previewBlade(occurrenceHandle));
1351
+ return jsonResult(await options.nativeEditor.previewBlade(occurrenceHandle, { signal: extra.signal }));
1060
1352
  });
1061
1353
  server.registerTool("editor.native.blade.execute", {
1062
1354
  description: "Execute a previously previewed Blade-at-playhead operation in Final Cut Pro.",
1063
1355
  inputSchema: { previewToken: z.string().min(1) },
1064
- }, async ({ previewToken }) => {
1356
+ }, async ({ previewToken }, extra) => {
1065
1357
  if (!options.nativeEditor)
1066
1358
  throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native Blade is not configured");
1067
- return jsonResult(await options.nativeEditor.executeBlade(previewToken));
1359
+ return jsonResult(await options.nativeEditor.executeBlade(previewToken, { signal: extra.signal }));
1068
1360
  });
1069
1361
  server.registerTool("editor.native.delete-range.preview", {
1070
1362
  description: "Preview a destructive ripple-delete of an explicit rational time range from the Final Cut primary storyline.",
1071
1363
  inputSchema: { start: rationalTimeSchema, end: rationalTimeSchema },
1072
- }, async ({ start, end }) => {
1364
+ }, async ({ start, end }, extra) => {
1073
1365
  if (!options.nativeEditor)
1074
1366
  throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native range deletion is not configured");
1075
- return jsonResult(await options.nativeEditor.previewDeleteRange({ start, end }));
1367
+ return jsonResult(await options.nativeEditor.previewDeleteRange({ start, end }, { signal: extra.signal }));
1076
1368
  });
1077
1369
  server.registerTool("editor.native.delete-range.execute", {
1078
1370
  description: "Execute a previously previewed primary-storyline ripple-delete range operation in Final Cut Pro.",
1079
1371
  inputSchema: { previewToken: z.string().min(1) },
1080
- }, async ({ previewToken }) => {
1372
+ }, async ({ previewToken }, extra) => {
1081
1373
  if (!options.nativeEditor)
1082
1374
  throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native range deletion is not configured");
1083
- return jsonResult(await options.nativeEditor.executeDeleteRange(previewToken));
1375
+ return jsonResult(await options.nativeEditor.executeDeleteRange(previewToken, { signal: extra.signal }));
1084
1376
  });
1085
1377
  server.registerTool("editor.native.trim-to-duration.preview", {
1086
1378
  description: "Preview a destructive operation that preserves the beginning of the Final Cut sequence and removes everything after the requested rational duration.",
1087
1379
  inputSchema: { duration: rationalTimeSchema },
1088
- }, async ({ duration }) => {
1380
+ }, async ({ duration }, extra) => {
1089
1381
  if (!options.nativeEditor)
1090
1382
  throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native duration trimming is not configured");
1091
- return jsonResult(await options.nativeEditor.previewTrimToDuration(duration));
1383
+ return jsonResult(await options.nativeEditor.previewTrimToDuration(duration, { signal: extra.signal }));
1092
1384
  });
1093
1385
  server.registerTool("editor.native.trim-to-duration.execute", {
1094
1386
  description: "Execute a previously previewed trim-to-duration operation in Final Cut Pro.",
1095
1387
  inputSchema: { previewToken: z.string().min(1) },
1096
- }, async ({ previewToken }) => {
1388
+ }, async ({ previewToken }, extra) => {
1097
1389
  if (!options.nativeEditor)
1098
1390
  throw new Error("CAPABILITY_UNAVAILABLE: Final Cut native duration trimming is not configured");
1099
- return jsonResult(await options.nativeEditor.executeTrimToDuration(previewToken));
1391
+ return jsonResult(await options.nativeEditor.executeTrimToDuration(previewToken, { signal: extra.signal }));
1392
+ });
1393
+ server.registerTool("artifact.publish.preview", {
1394
+ description: "Prepare a headed-only publish handoff for a verified FCPXML artifact without opening Final Cut.",
1395
+ inputSchema: {
1396
+ artifactPath: z.string().trim().min(1),
1397
+ transactionId: z.string().min(1),
1398
+ },
1399
+ }, async ({ artifactPath, transactionId }) => {
1400
+ if (!options.projectPublisher)
1401
+ throw new Error("CAPABILITY_UNAVAILABLE: Final Cut project publishing requires FRAMEKIT_FCPXML_PATH and native writes");
1402
+ const transaction = runtime.getTransaction(transactionId);
1403
+ if (transaction.target?.kind !== "artifact" || transaction.target.artifactPath !== artifactPath) {
1404
+ throw new Error(`PUBLISH_TARGET_MISMATCH: transaction ${transactionId} is not verified for artifact ${artifactPath}`);
1405
+ }
1406
+ if (!transaction.artifactDigest) {
1407
+ throw new Error(`PUBLISH_SOURCE_CHANGED: transaction ${transactionId} has no immutable artifact digest`);
1408
+ }
1409
+ const verification = await runtime.verifyTransaction(transactionId);
1410
+ if (!verification.passed)
1411
+ throw new Error(`FINAL_CUT_PUBLISH_VALIDATION_FAILED: source transaction ${transactionId} did not pass verification`);
1412
+ return jsonResult(await options.projectPublisher.preparePublish({
1413
+ sourceTransactionId: transactionId,
1414
+ artifactPath,
1415
+ artifactDigest: transaction.artifactDigest,
1416
+ }));
1417
+ });
1418
+ server.registerTool("artifact.publish.execute", {
1419
+ description: "Execute a prepared artifact publish job after explicit confirmation and return only a verified or resumable state.",
1420
+ inputSchema: {
1421
+ jobId: z.string().trim().min(1),
1422
+ confirm: z.literal(true),
1423
+ },
1424
+ }, async ({ jobId, confirm }) => {
1425
+ if (!options.projectPublisher)
1426
+ throw new Error("CAPABILITY_UNAVAILABLE: Final Cut project publishing requires FRAMEKIT_FCPXML_PATH and native writes");
1427
+ return jsonResult(await options.projectPublisher.executePublishJob(jobId, confirm));
1428
+ });
1429
+ server.registerTool("artifact.publish.status", {
1430
+ description: "Read the current state of a prepared artifact publish job without opening Final Cut or retrying it.",
1431
+ inputSchema: { jobId: z.string().trim().min(1) },
1432
+ }, async ({ jobId }) => {
1433
+ if (!options.projectPublisher)
1434
+ throw new Error("CAPABILITY_UNAVAILABLE: Final Cut project publishing requires FRAMEKIT_FCPXML_PATH and native writes");
1435
+ return jsonResult(options.projectPublisher.getPublishJob(jobId));
1100
1436
  });
1101
1437
  server.registerTool("artifact.publish", {
1102
1438
  description: "Import the validated FCPXML artifact as a new Final Cut project without replacing the active project; requires explicit confirmation.",
@@ -1221,9 +1557,21 @@ export function createMcpServer(runtime, options = {}) {
1221
1557
  timestamp: new Date(sequence).toISOString(),
1222
1558
  }, waitMs ?? 0)));
1223
1559
  server.registerTool("editor.live.inspect", {
1224
- description: "Read live Final Cut Workflow Extension state: project, active sequence, playhead, and selected range.",
1560
+ description: "Read observed live Final Cut state without requiring canonical timeline snapshot capability.",
1225
1561
  inputSchema: {},
1226
- }, async () => jsonResult(await runtime.inspectLiveEditor()));
1562
+ }, async () => {
1563
+ const inspected = await inspectMcpEditor(runtime, options);
1564
+ const capability = inspected.capabilities.families.observation.timeline;
1565
+ if (!capability.available) {
1566
+ return capabilityErrorResult("editor.live.inspect", "observation.timeline", capability);
1567
+ }
1568
+ try {
1569
+ return jsonResult(await runtime.inspectLiveEditor());
1570
+ }
1571
+ catch (error) {
1572
+ return capabilityUnavailableErrorResult(error);
1573
+ }
1574
+ });
1227
1575
  server.registerTool("editor.live.changes", {
1228
1576
  description: "Read live Final Cut timeline change events after a revision; optionally wait for new events.",
1229
1577
  inputSchema: {
@@ -1236,8 +1584,20 @@ export function createMcpServer(runtime, options = {}) {
1236
1584
  timestamp: new Date(sequence).toISOString(),
1237
1585
  }, waitMs ?? 0)));
1238
1586
  server.registerTool("timeline.inspect", {
1239
- description: "Read the current canonical timeline snapshot.",
1240
- }, async () => jsonResult(await runtime.inspectTimeline()));
1587
+ description: "Read the current canonical timeline snapshot after canonical capability checks.",
1588
+ }, async () => {
1589
+ const inspected = await inspectMcpEditor(runtime, options);
1590
+ const capability = inspected.capabilities.families.canonicalDocument.read;
1591
+ if (!capability.available) {
1592
+ return capabilityErrorResult("timeline.inspect", "canonicalDocument.read", capability);
1593
+ }
1594
+ try {
1595
+ return jsonResult(await runtime.inspectTimeline());
1596
+ }
1597
+ catch (error) {
1598
+ return capabilityUnavailableErrorResult(error);
1599
+ }
1600
+ });
1241
1601
  server.registerTool("timeline.frame.capture", {
1242
1602
  description: "Capture an image at an exact timeline position with project, sequence, clip, and optional visual-analysis metadata.",
1243
1603
  inputSchema: {
@@ -1252,7 +1612,19 @@ export function createMcpServer(runtime, options = {}) {
1252
1612
  server.registerTool("media.search", {
1253
1613
  description: "Search normalized media references by id or source path.",
1254
1614
  inputSchema: { query: z.string() },
1255
- }, async ({ query }) => jsonResult(await runtime.searchMedia(query)));
1615
+ }, async ({ query }) => {
1616
+ const inspected = await inspectMcpEditor(runtime, options);
1617
+ const capability = inspected.capabilities.families.observation.media;
1618
+ if (!capability.available) {
1619
+ return capabilityErrorResult("media.search", "observation.media", capability);
1620
+ }
1621
+ try {
1622
+ return jsonResult(await runtime.searchMedia(query));
1623
+ }
1624
+ catch (error) {
1625
+ return capabilityUnavailableErrorResult(error);
1626
+ }
1627
+ });
1256
1628
  server.registerTool("media.index", {
1257
1629
  description: "Query analyzed media by semantic properties, source identity, capabilities, and usable ranges.",
1258
1630
  inputSchema: mediaIndexQuerySchema.shape,
@@ -1273,11 +1645,12 @@ export function createMcpServer(runtime, options = {}) {
1273
1645
  inputSchema: roughCutPlanSchema.shape,
1274
1646
  }, async (request) => jsonResult(await runtime.planRoughCut(request)));
1275
1647
  server.registerTool("editor.assets", {
1276
- description: "Search editor-native transitions, effects, titles, generators, and templates.",
1648
+ description: "Search installed transitions, effects, titles, generators, and templates; filesystem discovery is the default and native Browser discovery is explicit.",
1277
1649
  inputSchema: {
1278
1650
  query: z.string().optional(),
1279
1651
  kind: z.enum(["transition", "effect", "title", "generator", "audio-effect", "template"]).optional(),
1280
1652
  vendor: z.string().optional(),
1653
+ discovery: z.enum(["background", "native", "all"]).optional().default("background"),
1281
1654
  },
1282
1655
  }, async (query) => jsonResult(await runtime.listAssets(query)));
1283
1656
  server.registerTool("timeline.changes", {
@@ -1307,16 +1680,19 @@ export function createMcpServer(runtime, options = {}) {
1307
1680
  inputSchema: roughCutConstructionPlanInputSchema,
1308
1681
  }, async (request) => jsonResult(await runtime.previewRoughCutConstruction(request)));
1309
1682
  server.registerTool("artifact.edit", {
1310
- description: "Edit the identified managed FCPXML artifact and return its artifact target, new revision, read-after-write, and diff.",
1683
+ description: "Edit the identified managed FCPXML artifact in the background and return its artifact target, new revision, read-after-write, and diff.",
1311
1684
  inputSchema: artifactEditToolInputSchema,
1312
1685
  }, async (input) => {
1686
+ await requireEditingRoute(runtime, options, "artifact.edit");
1313
1687
  const { artifactPath, verification, ...operation } = input;
1314
- return jsonResult(await runtime.editArtifact(artifactPath, editOperationSchema.parse(operation), verification ?? {}));
1688
+ const transaction = await runtime.editArtifact(artifactPath, editOperationSchema.parse(operation), verification ?? {});
1689
+ return jsonResult({ ...transaction, ...withTransactionProvenance(transaction) });
1315
1690
  });
1316
1691
  server.registerTool("editor.timeline.edit", {
1317
1692
  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
1693
  inputSchema: editorTimelineEditToolInputSchema,
1319
1694
  }, async (input) => {
1695
+ await requireEditingRoute(runtime, options, "timeline.edit");
1320
1696
  const { projectId, sequenceId, verification, ...operation } = input;
1321
1697
  return jsonResult(await runtime.editTimeline({ projectId, sequenceId }, editOperationSchema.parse(operation), verification ?? {}));
1322
1698
  });
@@ -1355,14 +1731,17 @@ export function createMcpServer(runtime, options = {}) {
1355
1731
  }));
1356
1732
  });
1357
1733
  server.registerTool("artifact.edit.preview", {
1358
- description: "Validate and preview an ordered artifact edit against the identified FCPXML artifact without mutating it.",
1734
+ description: "Validate and preview an ordered background FCPXML artifact edit without mutating it or the open Final Cut timeline.",
1359
1735
  inputSchema: {
1360
1736
  artifactPath: z.string().trim().min(1),
1361
1737
  baseRevision: revisionValueSchema,
1362
1738
  operations: workflowOperationsSchema,
1363
1739
  verification: verificationPolicySchema.optional(),
1364
1740
  },
1365
- }, async ({ artifactPath, baseRevision, operations, verification }) => jsonResult(await runtime.previewArtifactEdit(artifactPath, { baseRevision, operations, ...(verification ? { verification } : {}) })));
1741
+ }, async ({ artifactPath, baseRevision, operations, verification }) => {
1742
+ await requireEditingRoute(runtime, options, "artifact.edit");
1743
+ return jsonResult(await runtime.previewArtifactEdit(artifactPath, { baseRevision, operations, ...(verification ? { verification } : {}) }).then(withArtifactPreviewProvenance));
1744
+ });
1366
1745
  server.registerTool("editor.timeline.edit.preview", {
1367
1746
  description: "Validate and preview an ordered live timeline edit against the identified active project and sequence without mutating it.",
1368
1747
  inputSchema: {
@@ -1372,15 +1751,51 @@ export function createMcpServer(runtime, options = {}) {
1372
1751
  operations: workflowOperationsSchema,
1373
1752
  verification: verificationPolicySchema.optional(),
1374
1753
  },
1375
- }, async ({ projectId, sequenceId, baseRevision, operations, verification }) => jsonResult(await runtime.previewTimelineEdit({ projectId, sequenceId }, { baseRevision, operations, ...(verification ? { verification } : {}) })));
1754
+ }, async ({ projectId, sequenceId, baseRevision, operations, verification }) => {
1755
+ await requireEditingRoute(runtime, options, "timeline.edit");
1756
+ return jsonResult(await runtime.previewTimelineEdit({ projectId, sequenceId }, { baseRevision, operations, ...(verification ? { verification } : {}) }));
1757
+ });
1376
1758
  server.registerTool("artifact.edit.execute", {
1377
- description: "Execute one short-lived artifact edit preview token exactly once and verify the artifact transaction.",
1759
+ description: "Execute one short-lived background artifact edit preview token exactly once and verify the FCPXML artifact transaction.",
1378
1760
  inputSchema: { previewToken: z.string().min(1) },
1379
- }, async ({ previewToken }) => jsonResult(await runtime.executeEdit(previewToken)));
1761
+ }, async ({ previewToken }) => {
1762
+ await requireEditingRoute(runtime, options, "artifact.edit");
1763
+ const transaction = await runtime.executeEdit(previewToken);
1764
+ return jsonResult({ ...transaction, ...withTransactionProvenance(transaction) });
1765
+ });
1766
+ server.registerTool("artifact.edit.diff", {
1767
+ description: "Read the deterministic diff for a background FCPXML artifact transaction.",
1768
+ inputSchema: artifactTransactionInputSchema,
1769
+ }, async ({ artifactPath, transactionId }) => {
1770
+ const transaction = requireArtifactTransaction(runtime, transactionId, artifactPath);
1771
+ return jsonResult({ ...runtime.getDiff(transactionId), ...withTransactionProvenance(transaction) });
1772
+ });
1773
+ server.registerTool("artifact.edit.verify", {
1774
+ description: "Read verification checks for a background FCPXML artifact transaction.",
1775
+ inputSchema: artifactTransactionInputSchema,
1776
+ }, async ({ artifactPath, transactionId }) => {
1777
+ const transaction = requireArtifactTransaction(runtime, transactionId, artifactPath);
1778
+ return jsonResult({ ...(await runtime.verifyTransaction(transactionId)), ...withTransactionProvenance(transaction) });
1779
+ });
1780
+ server.registerTool("artifact.edit.undo", {
1781
+ description: "Restore a background FCPXML artifact transaction without changing the open Final Cut timeline.",
1782
+ inputSchema: artifactTransactionInputSchema,
1783
+ }, async ({ artifactPath, transactionId }) => {
1784
+ const transaction = requireArtifactTransaction(runtime, transactionId, artifactPath);
1785
+ const restored = await runtime.undo(transactionId);
1786
+ const artifact = await runtime.inspectArtifact();
1787
+ return jsonResult({
1788
+ ...restored,
1789
+ ...withTransactionProvenance(transaction, restored.revision, artifact.digest),
1790
+ });
1791
+ });
1380
1792
  server.registerTool("editor.timeline.edit.execute", {
1381
1793
  description: "Execute one short-lived live timeline edit preview token exactly once and verify the timeline transaction.",
1382
1794
  inputSchema: { previewToken: z.string().min(1) },
1383
- }, async ({ previewToken }) => jsonResult(await runtime.executeEdit(previewToken)));
1795
+ }, async ({ previewToken }) => {
1796
+ await requireEditingRoute(runtime, options, "timeline.edit");
1797
+ return jsonResult(await runtime.executeEdit(previewToken));
1798
+ });
1384
1799
  server.registerTool("timeline.edit.execute", {
1385
1800
  description: "Execute one short-lived composite edit preview token exactly once after editing.route capability checks, then verify the transaction.",
1386
1801
  inputSchema: { previewToken: z.string().min(1) },
@@ -1448,18 +1863,81 @@ export function createMcpServer(runtime, options = {}) {
1448
1863
  server.registerTool("edit.diff", {
1449
1864
  description: "Read the deterministic diff for a completed edit transaction.",
1450
1865
  inputSchema: { transactionId: z.string().min(1) },
1451
- }, async ({ transactionId }) => jsonResult(runtime.getDiff(transactionId)));
1866
+ }, async ({ transactionId }) => {
1867
+ const transaction = runtime.getTransaction(transactionId);
1868
+ return jsonResult({ ...runtime.getDiff(transactionId), ...withTransactionProvenance(transaction) });
1869
+ });
1452
1870
  server.registerTool("edit.verify", {
1453
1871
  description: "Read verification checks for a completed transaction.",
1454
1872
  inputSchema: { transactionId: z.string().min(1) },
1455
- }, async ({ transactionId }) => jsonResult(await runtime.verifyTransaction(transactionId)));
1873
+ }, async ({ transactionId }) => {
1874
+ const transaction = runtime.getTransaction(transactionId);
1875
+ return jsonResult({ ...(await runtime.verifyTransaction(transactionId)), ...withTransactionProvenance(transaction) });
1876
+ });
1456
1877
  server.registerTool("edit.undo", {
1457
1878
  description: "Restore the pre-edit snapshot for a completed transaction.",
1458
1879
  inputSchema: { transactionId: z.string().min(1) },
1459
- }, async ({ transactionId }) => jsonResult(await runtime.undo(transactionId)));
1880
+ }, async ({ transactionId }) => {
1881
+ const transaction = runtime.getTransaction(transactionId);
1882
+ const restored = await runtime.undo(transactionId);
1883
+ const artifact = transaction.target?.kind === "artifact" ? await runtime.inspectArtifact() : undefined;
1884
+ return jsonResult({
1885
+ ...restored,
1886
+ ...withTransactionProvenance(transaction, restored.revision, artifact?.digest),
1887
+ });
1888
+ });
1460
1889
  installMcpSchemaCompatibility(server);
1461
1890
  return server;
1462
1891
  }
1892
+ function withTransactionProvenance(transaction, revision = transaction.after.revision, digest = transaction.artifactDigest) {
1893
+ const target = transaction.target;
1894
+ const artifact = target?.kind === "artifact"
1895
+ ? {
1896
+ mode: "background-artifact",
1897
+ path: target.artifactPath,
1898
+ revisionScope: "artifact",
1899
+ revision: structuredClone(revision),
1900
+ ...(digest ? { digest } : {}),
1901
+ mutatesOpenTimeline: false,
1902
+ }
1903
+ : undefined;
1904
+ return {
1905
+ ...(target ? { target: structuredClone(target) } : {}),
1906
+ ...(artifact ? { artifact } : {}),
1907
+ provenance: {
1908
+ surface: target?.kind === "artifact" ? "artifact" : "live-timeline",
1909
+ revisionScope: target?.kind === "artifact" ? "artifact" : "live-timeline",
1910
+ revision: structuredClone(revision),
1911
+ ...(target?.kind === "artifact" && digest ? { digest } : {}),
1912
+ mutatesOpenTimeline: target?.kind !== "artifact",
1913
+ },
1914
+ };
1915
+ }
1916
+ function withArtifactPreviewProvenance(preview) {
1917
+ const target = preview.target;
1918
+ if (target.kind !== "artifact") {
1919
+ throw new Error("INVALID_ARTIFACT_TARGET: preview is not bound to an artifact");
1920
+ }
1921
+ const artifact = {
1922
+ mode: "background-artifact",
1923
+ path: target.artifactPath,
1924
+ revisionScope: "artifact",
1925
+ revision: structuredClone(preview.baseRevision),
1926
+ ...(preview.artifactDigest ? { digest: preview.artifactDigest } : {}),
1927
+ mutatesOpenTimeline: false,
1928
+ };
1929
+ return {
1930
+ ...preview,
1931
+ artifact,
1932
+ provenance: {
1933
+ surface: "artifact",
1934
+ revisionScope: "artifact",
1935
+ revision: structuredClone(preview.baseRevision),
1936
+ ...(preview.artifactDigest ? { digest: preview.artifactDigest } : {}),
1937
+ mutatesOpenTimeline: false,
1938
+ },
1939
+ };
1940
+ }
1463
1941
  async function resolveNativeTitleAsset(runtime, assetId) {
1464
1942
  const assets = await runtime.listAssets();
1465
1943
  const asset = assets.find((candidate) => candidate.id === assetId);
@@ -1469,7 +1947,7 @@ async function resolveNativeTitleAsset(runtime, assetId) {
1469
1947
  throw new Error(`TITLE_ASSET_INCOMPATIBLE: ${assetId} is not an installed Final Cut title asset`);
1470
1948
  return asset;
1471
1949
  }
1472
- async function resolveNativeTransitionAsset(runtime, nativeEditor, assetId, nativeTransitionAssets = new Map()) {
1950
+ async function resolveNativeTransitionAsset(runtime, nativeEditor, assetId, nativeTransitionAssets = new Map(), signal) {
1473
1951
  const cachedAsset = nativeTransitionAssets.get(assetId);
1474
1952
  if (cachedAsset)
1475
1953
  return cachedAsset;
@@ -1486,7 +1964,7 @@ async function resolveNativeTransitionAsset(runtime, nativeEditor, assetId, nati
1486
1964
  // transition placement must use the stable identity returned by Final Cut's
1487
1965
  // Transitions browser. Resolve registry assets back through native discovery
1488
1966
  // instead of fabricating a native identity from the registry id.
1489
- const nativeMatches = await nativeEditor.searchTransitions(asset?.name ?? assetId);
1967
+ const nativeMatches = await nativeEditor.searchTransitions(asset?.name ?? assetId, { signal });
1490
1968
  const matchingNativeMatches = asset
1491
1969
  ? nativeMatches.filter((candidate) => candidate.name === asset.name)
1492
1970
  : nativeMatches.filter((candidate) => candidate.id === assetId || candidate.identity === assetId);
@@ -1507,18 +1985,52 @@ async function connectionStatus(options) {
1507
1985
  capabilities: null,
1508
1986
  };
1509
1987
  }
1988
+ async function effectiveConnectionStatus(runtime, options) {
1989
+ const status = await connectionStatus(options);
1990
+ const hasConnectionCapabilities = isRuntimeCapabilities(status.capabilities);
1991
+ if (status.state !== "ready" || (options.connectionStatus && !hasConnectionCapabilities)) {
1992
+ return normalizeConnectionStatus(status);
1993
+ }
1994
+ try {
1995
+ const inspected = await inspectMcpEditor(runtime, options);
1996
+ return {
1997
+ ...status,
1998
+ identity: inspected.identity,
1999
+ capabilities: inspected.capabilities,
2000
+ preflight: inspected.preflight,
2001
+ };
2002
+ }
2003
+ catch (error) {
2004
+ const message = error instanceof Error ? error.message : String(error);
2005
+ return normalizeConnectionStatus({
2006
+ ...status,
2007
+ state: "unavailable",
2008
+ lastError: {
2009
+ code: "CAPABILITY_UNAVAILABLE",
2010
+ message: `effective runtime capability inspection failed: ${message}`,
2011
+ },
2012
+ identity: undefined,
2013
+ capabilities: undefined,
2014
+ preflight: undefined,
2015
+ });
2016
+ }
2017
+ }
1510
2018
  async function inspectMcpEditor(runtime, options) {
1511
2019
  const inspected = await runtime.inspectEditor();
1512
2020
  const native = options.nativeEditor?.capabilities();
1513
2021
  const publishingAvailable = Boolean(options.projectPublisher && (typeof options.projectPublisher.isAvailable !== "function" || options.projectPublisher.isAvailable()));
1514
2022
  const exportAvailable = Boolean(options.videoExporter?.isAvailable());
2023
+ const backgroundExportAvailable = Boolean(options.backgroundRenderer?.isAvailable());
1515
2024
  const capabilities = withCapabilityFamilies({
1516
2025
  ...inspected.capabilities,
1517
2026
  editor: {
1518
2027
  ...inspected.capabilities.editor,
1519
2028
  artifactPublish: publishingAvailable,
2029
+ artifactPublishMode: publishingAvailable ? "headed-only" : "unavailable",
1520
2030
  ...(publishingAvailable ? {} : { timelinePublishNewProject: false }),
1521
2031
  videoExport: exportAvailable,
2032
+ backgroundRender: backgroundExportAvailable,
2033
+ externalRender: false,
1522
2034
  },
1523
2035
  }, {
1524
2036
  backend: inspected.identity.backend,
@@ -1551,17 +2063,50 @@ async function inspectMcpEditor(runtime, options) {
1551
2063
  publishingBackend: "fcpxml-publisher",
1552
2064
  export: exportAvailable,
1553
2065
  exportBackend: "final-cut-native-export",
2066
+ backgroundExport: {
2067
+ available: backgroundExportAvailable,
2068
+ backend: "external-renderer",
2069
+ guarantee: backgroundExportAvailable ? "verified" : "none",
2070
+ ...(backgroundExportAvailable ? { evidenceTier: "artifact-rendered" } : { unavailableReason: "background rendering is unavailable" }),
2071
+ },
2072
+ backgroundExportBackend: "external-renderer",
2073
+ externalExport: {
2074
+ available: false,
2075
+ backend: "external-renderer",
2076
+ guarantee: "none",
2077
+ unavailableReason: "external rendering is unavailable",
2078
+ },
2079
+ externalExportBackend: "external-renderer",
1554
2080
  });
1555
2081
  return {
1556
2082
  ...inspected,
1557
2083
  capabilities,
1558
- preflight: createCapabilityPreflight(inspected.identity, capabilities, {
1559
- processMode: options.processMode ?? (native ? "headed" : "headless"),
1560
- nativeWrite: Boolean(native?.selectionEdit),
1561
- }),
2084
+ workflows: {
2085
+ artifact: {
2086
+ mode: "background-artifact",
2087
+ tools: [...BACKGROUND_ARTIFACT_WORKFLOW],
2088
+ requiresFinalCutFrontmost: false,
2089
+ changesOpenTimeline: false,
2090
+ },
2091
+ },
2092
+ preflight: {
2093
+ ...createCapabilityPreflight(inspected.identity, capabilities, {
2094
+ processMode: options.processMode ?? (native ? "headed" : "headless"),
2095
+ nativeWrite: Boolean(native?.selectionEdit),
2096
+ }),
2097
+ fingerprint: options.buildFingerprint ?? FRAMEKIT_BUILD_FINGERPRINT,
2098
+ },
1562
2099
  ...(native ? { native } : {}),
1563
2100
  };
1564
2101
  }
2102
+ function requireArtifactTransaction(runtime, transactionId, artifactPath) {
2103
+ const transaction = runtime.getTransaction(transactionId);
2104
+ const target = transaction.target;
2105
+ if (target?.kind !== "artifact" || resolvePath(target.artifactPath) !== resolvePath(artifactPath.trim())) {
2106
+ throw new Error(`TARGET_MISMATCH: transaction ${transactionId} is not bound to artifact ${artifactPath}`);
2107
+ }
2108
+ return transaction;
2109
+ }
1565
2110
  async function requireEditingRoute(runtime, options, operation) {
1566
2111
  const route = resolveEditingRoute({ operation }, await editingRouteContext(runtime, options));
1567
2112
  if (route.status !== "editor-selected") {
@@ -1569,7 +2114,7 @@ async function requireEditingRoute(runtime, options, operation) {
1569
2114
  }
1570
2115
  }
1571
2116
  async function editingRouteContext(runtime, options) {
1572
- const connection = await connectionStatus(options);
2117
+ const connection = await effectiveConnectionStatus(runtime, options);
1573
2118
  let editor;
1574
2119
  try {
1575
2120
  editor = await inspectMcpEditor(runtime, options);